domma-cms 1.8.32 → 1.8.34

package/plugins/docs/admin/views/editor.js

@@ -0,0 +1,978 @@
+/**
+ * Docs - one document (#/plugins/docs/d/<id>).
+ *
+ * The page, its toolbar, an Outline, and everything done to the document:
+ * save and autosave, the edit lock, sharing, export, send to, version
+ * history, focus mode. Home is admin/views/docs.js.
+ *
+ * The edit lock: opening a document you may edit takes its lock and keeps it
+ * with a heartbeat; anyone else opening it reads, sees who is editing, and is
+ * offered Edit now when the lock is free. The owner can take over; the editor
+ * who lost it has their unsaved work saved as a copy rather than thrown away.
+ *
+ * Unsaved work is never lost silently: autosave, Ctrl+S, a leave guard on the
+ * router, a draft kept in this browser, and the browser's own prompt on close.
+ *
+ * @module docs/admin/views/editor
+ */
+
+import {docsApi, HOME, docHref, esc, icon, loadKit, loadExtensions, newSession, unlockOnUnload, allowDocAttrs, setContentFilter, promptWith} from '/plugins/docs/admin/lib/api.js';
+import {DocEditor} from '/plugins/docs/admin/lib/editor.js';
+import {draftKey, legacyDraftKey, normaliseDraft, makeDraft, draftDiffers, draftQuestion, copyTitle} from '/plugins/docs/admin/lib/drafts.js';
+import {VersionHistory} from '/plugins/docs/admin/lib/versions.js';
+import {DocumentTemplates} from '/plugins/docs/admin/lib/templates.js';
+import {FindReplace} from '/plugins/docs/admin/lib/find-replace.js';
+import {FolderManager} from '/plugins/docs/admin/lib/folders.js';
+import {exportItems, openSendEmail, sendToPage, sendToBlog} from '/plugins/docs/admin/lib/send.js';
+import {openShare} from '/plugins/docs/admin/lib/share.js';
+import {mountPdfViewer, pdfFacts, pdfExportItems, downloadPdf, replacePdf} from '/plugins/docs/admin/lib/pdf-view.js';
+
+const SCREEN = /^\/plugins\/docs\/d\/[^/?#]+\/?(\?.*)?$/;
+const pathOf = (p) => String(p || '').split('?')[0].replace(/\/$/, '');
+const HEARTBEAT_MS = 30000;
+const POLL_MS = 15000;
+
+const OUTLINE_ROW = `<button type="button" class="{{cls}}" data-heading="{{index}}" title="{{text}}">{{text}}</button>`;
+
+const PREFS_KEY = 'docs.editor';
+export function normaliseEditorPrefs(raw) {
+    const r = raw && typeof raw === 'object' ? raw : {};
+    return {outlineOpen: r.outlineOpen !== false};
+}
+
+/** A draft kept in this browser for unsaved work on leaving (admin/lib/drafts.js has the rules). */
+// Drafts are per signed-in person (a shared browser, a shared document): the key carries the user id.
+const signedIn = () => { try { const u = S.get('auth_user'); return String((typeof u === 'string' ? JSON.parse(u) : u)?.id || ''); } catch { return ''; } };
+const dropKey = (key) => { try { S.remove?.(key); S.set?.(key, null); } catch { /* storage blocked */ } };
+function readDraft(id) {
+    try {
+        // 2.9's owner-less draft: whose it is cannot be known, so it is removed, never offered.
+        if (S.get(legacyDraftKey(id)) != null) dropKey(legacyDraftKey(id));
+        const me = signedIn();
+        return me ? normaliseDraft(S.get(draftKey(id, me)), me) : null;
+    } catch { return null; }
+}
+function writeDraft(id, draft) {
+    const me = signedIn();
+    if (!me || draft?.owner !== me) return;   // signed out (or someone else now): keep nothing
+    try { S.set(draftKey(id, me), draft); } catch { /* storage blocked */ }
+}
+function clearDraft(id) { const me = signedIn(); if (me) dropKey(draftKey(id, me)); }
+
+/**
+ * E.confirm, and a way to answer it Cancel from code - Domma's dialog has no
+ * close(). The dialog is built synchronously, so its Cancel button is the last
+ * one in the page when E.confirm returns. A screen that goes while it asks
+ * dismisses it: Cancel is always the keeping answer, so nothing is lost.
+ */
+function askDismissable(message, options) {
+    // Domma answers OK on Enter anywhere in the page, and OK is "Throw away" here: Enter
+    // is swallowed while it asks, and focus starts on the keeping answer.
+    const swallowEnter = (e) => { if (e.key === 'Enter') { e.preventDefault(); e.stopImmediatePropagation(); } };
+    window.addEventListener('keydown', swallowEnter, true);
+    const answer = E.confirm(message, options);
+    const cancel = [...document.querySelectorAll('.dm-dialog-cancel')].at(-1) || null;
+    setTimeout(() => { try { cancel?.focus(); } catch { /* gone */ } }, 80);
+    answer.finally(() => window.removeEventListener('keydown', swallowEnter, true));
+    return {answer, dismiss: () => { if (cancel?.isConnected) cancel.click(); }};
+}
+
+// ---- One open document at a time, reachable from the router ----
+
+/** {path, dirty(), dispose()} of the mounted editor. */
+let active = null;
+let routerWired = false;
+
+function wireRouter() {
+    if (routerWired || !window.R?.use) return;
+    routerWired = true;
+    R.use((to, from, next) => {
+        const fromPath = pathOf(from?.path);
+        const leaving = SCREEN.test(from?.path || '') && pathOf(to?.path) !== fromPath;
+        if (!leaving || !active?.dirty()) return next();
+        const a = active;
+        return E.confirm('This document has changes that are not saved yet. Save them and leave?', {
+            title: 'Unsaved changes', confirmText: 'Save and leave', cancelText: 'Stay'
+        }).then(async (ok) => {
+            if (ok && await a.saveNow()) next();
+            else history.replaceState(null, '', `#${from.path}`);   // the hash has already moved
+        });
+    });
+    M.subscribe('router:afterChange', ({to} = {}) => {
+        if (active && pathOf(to?.path) !== active.path) { const a = active; active = null; a.dispose(); }
+    });
+}
+
+export const docsEditorView = {
+    templateUrl: '/plugins/docs/admin/templates/editor.html',
+
+    async onMount($container) {
+        wireRouter();
+        if (active) { const a = active; active = null; a.dispose(); }
+        const root = $container.get(0);
+        const m = /^#\/plugins\/docs\/d\/([^/?#]+)/.exec(location.hash);
+        const id = m ? decodeURIComponent(m[1]) : '';
+        const path = `/plugins/docs/d/${m ? m[1] : ''}`;
+        const session = newSession();
+        const cleanups = [];
+        let disposed = false;
+        let lockHeld = false;
+        // Filled in once the editor exists; the router can reach this view from the first await on.
+        let isDirty = () => false;
+        let saveNow = async () => true;
+        let keepDraft = () => {};
+        const onDispose = (fn) => { if (disposed) { try { fn?.(); } catch { /* gone */ } } else cleanups.push(fn); };
+        active = {
+            path,
+            dirty: () => isDirty(),
+            saveNow: () => saveNow(),
+            dispose() {
+                if (disposed) return;
+                // Left with unsaved work (the guard was passed some other way): keep a draft.
+                try { if (isDirty()) keepDraft(); } catch { /* best effort */ }
+                disposed = true;
+                if (lockHeld) docsApi.unlock(id, session).catch(() => {});
+                lockHeld = false;
+                cleanups.splice(0).reverse().forEach(fn => { try { fn?.(); } catch { /* gone */ } });
+            }
+        };
+        const kit = await loadKit();
+        if (disposed) return;
+        const prefsStore = kit.settingsStore(PREFS_KEY, normaliseEditorPrefs);
+        const recount = () => kit.sidebarCount(HOME);
+
+        /**
+         * The document has gone (deleted, or no longer shared) but this browser
+         * still holds unsaved work on it: ask, and keep it as a new document
+         * of the person's own unless they throw it away. Leaving while asked
+         * keeps the draft for next time.
+         */
+        async function offerOrphanDraft(draft) {
+            const q = draftQuestion(draft, null);
+            const asked = askDismissable(q.text, q.options);
+            onDispose(asked.dismiss);
+            const throwAway = await asked.answer;
+            if (disposed) return;
+            if (throwAway) { clearDraft(id); location.hash = HOME; return; }
+            try {
+                const made = await docsApi.create({title: copyTitle(draft), content: draft.content});
+                clearDraft(id);
+                recount();
+                E.toast(`Your unsaved changes are now a document of your own: ${made.title}`, {type: 'success', duration: 8000});
+                if (!disposed) location.hash = docHref(made.id);
+            } catch (err) {
+                E.toast(`${err.message || 'Could not make a new document'} - your changes are still kept in this browser.`, {type: 'error'});
+                if (!disposed) location.hash = HOME;
+            }
+        }
+
+        // ---- Load ----
+        // The page shows a skeleton while the document is fetched; the editor's
+        // chips and buttons stay hidden (static `hidden`) until bound.
+        const loadingSlot = root.querySelector('.docs-ed__loading');
+        let site = {};
+        let doc;
+        try {
+            const loads = Promise.all([docsApi.settings.get().catch(() => ({})), docsApi.get(id, session)]);
+            const loader = await import('/admin/js/lib/loading.js').catch(() => null);
+            [site, doc] = loader?.whileLoading && loadingSlot
+                ? await loader.whileLoading(loadingSlot, loads, loader.SHAPES.rows)
+                : await loads;
+        } catch (err) {
+            if (disposed) return;
+            if (loadingSlot) loadingSlot.hidden = true;
+            // Gone, with work of ours on it still in this browser: offer it back as a new document.
+            const draft = /not found/i.test(err.message || '') ? readDraft(id) : null;
+            if (draft) { await offerOrphanDraft(draft); return; }
+            E.toast(err.message || 'That document could not be opened', {type: 'error'});
+            location.hash = HOME;
+            return;
+        }
+        if (loadingSlot) loadingSlot.hidden = true;
+        if (disposed || location.hash.indexOf(`#${path}`) !== 0) return;   // left while loading
+        // A PDF document (2.13) is a file: its body is never edited here, and only add-ons that declare
+        // they understand PDF documents are installed in its screen.
+        const pdf = doc.format === 'pdf';
+        const extensions = (await loadExtensions(site.extensions)).filter(e => !pdf || (Array.isArray(e.kinds) && e.kinds.includes('pdf')));
+        if (disposed) return;
+
+        // ---- State ----
+        const current = M.observable(doc);
+        const title = M.observable(doc.title || '');
+        const savedTitle = M.observable(doc.title || '');
+        const contentDirty = M.observable(false);
+        const saving = M.observable(false);
+        const savedAt = M.observable(null);
+        const failed = M.observable(false);
+        // 'editing' - this tab holds the lock; 'locked' - someone else does;
+        // 'free' - nobody does but we are reading; 'view' - viewer or in Trash.
+        const mode = M.observable('view');
+        const lockedBy = M.observable('');
+        const takeOverAllowed = M.observable(false);
+        const lockMine = M.observable(false);      // the lock is ours, from another tab
+        const me = (() => { try { const u = S.get('auth_user'); return (typeof u === 'string' ? JSON.parse(u) : u)?.id || ''; } catch { return ''; } })();
+        /** Note who holds the lock. */
+        const holder = (lock) => {
+            lockMine.value = Boolean(lock && lock.userId && lock.userId === me);
+            lockedBy.value = lock?.name || 'Someone';
+        };
+        const starred = M.observable(Boolean(doc.starred));
+        const prefs = M.observable(prefsStore.read());
+        const outlineOpen = M.observable(prefs.peek().outlineOpen && window.innerWidth > 900);
+        const focus = M.observable(false);
+        const sideOpen = M.observable(false);
+        const stats = M.observable({words: 0, chars: 0});
+        const outlineRows = M.observable([]);
+        onDispose(M.effect(() => prefsStore.write({outlineOpen: outlineOpen.value})));
+
+        const access = () => current.peek().access;
+        // A Suggester edits too - in suggesting mode, which an add-on (Docs Pro) provides and the server checks (2.5).
+        const suggests = () => access() === 'suggester' && Boolean(site.suggestions);
+        // 2.12: an add-on may freeze it for this person (a protected wiki page) - read only, the reason in a chip.
+        const mayEdit = () => !pdf && (access() === 'owner' || access() === 'editor' || suggests()) && !current.peek().trashedAt && !current.peek().frozen;
+        const editorRights = () => access() === 'owner' || access() === 'editor';
+        let changeSeq = 0;
+        // The version the unsaved edits began from: the stored one - or, for a draft
+        // picked back up, that draft's own `was` until it is saved.
+        let pickedWas = '';
+        const editWas = () => pickedWas || current.peek().updatedAt || '';
+        // The owner is whoever opened this editor - never whoever is signed in by the time it is written.
+        const draftNow = () => makeDraft({owner: me, title: title.peek(), content: editor.getValue(), was: editWas()});
+        // Panels opened from here close with the screen; one that is still opening checks this.
+        const panelLife = {
+            alive: () => !disposed,
+            add(fn) { onDispose(fn); return () => { const at = cleanups.indexOf(fn); if (at !== -1) cleanups.splice(at, 1); }; }
+        };
+
+        // Titles compare as the server stores them: spaces collapsed, "Untitled" when empty.
+        const normTitle = (t) => String(t ?? '').replace(/\s+/g, ' ').trim() || 'Untitled';
+        const dirty = M.computed(() => mode.value === 'editing' && (contentDirty.value || normTitle(title.value) !== normTitle(savedTitle.value)));
+        const readOnly = M.computed(() => mode.value !== 'editing');
+        const titleLocked = M.computed(() => mode.value !== 'editing' || current.value.access === 'suggester');
+
+        const data = {
+            title, starred, lockedBy, outlineOpen, focus, sideOpen, outlineRows, readOnly, titleLocked,
+            isPdf: M.computed(() => current.value.format === 'pdf'),
+            pdfText: M.computed(() => (current.value.format === 'pdf' ? `PDF${pdfFacts(current.value.file) ? ` · ${pdfFacts(current.value.file)}` : ''}` : '')),
+            pdfName: M.computed(() => String(current.value.file?.name || '')),
+            edClass: M.computed(() => `docs-ed${readOnly.value ? ' is-readonly' : ''}${outlineOpen.value && !pdf ? ' has-outline' : ''}${sideOpen.value ? ' has-side' : ''}${pdf ? ' is-pdf' : ''}`),
+            starTitle: M.computed(() => (starred.value ? 'Remove star' : 'Star')),
+            whereText: M.computed(() => {
+                const d = current.value;
+                const owner = d.access === 'owner' ? 'My documents' : `${d.ownerName}'s document`;
+                return d.shares?.length || d.publicLink ? `${owner} · shared` : owner;
+            }),
+            saveState: M.computed(() => {
+                if (mode.value !== 'editing') return '';
+                if (saving.value) return 'Saving…';
+                if (failed.value) return 'Not saved';
+                if (dirty.value) return 'Unsaved changes';
+                return savedAt.value ? `Saved ${D(savedAt.value).format('HH:mm')}` : 'All changes saved';
+            }),
+            saveClass: M.computed(() => `docs-ed__save${failed.value ? ' is-failed' : dirty.value ? ' is-dirty' : ''}`),
+            lockText: M.computed(() => (!lockedBy.value ? '' : lockMine.value ? 'Open for editing in another tab' : `${lockedBy.value} is editing`)),
+            takeOverText: M.computed(() => (lockMine.value ? 'Edit here' : 'Take over')),
+            canTakeOver: M.computed(() => mode.value === 'locked' && takeOverAllowed.value),
+            canEditNow: M.computed(() => mode.value === 'free'),
+            viewOnly: M.computed(() => mode.value === 'view' && !current.value.trashedAt && !current.value.frozen && current.value.format !== 'pdf'),
+            frozenText: M.computed(() => (current.value.trashedAt ? '' : String(current.value.frozen || ''))),
+            inTrash: M.computed(() => Boolean(current.value.trashedAt)),
+            canRestore: M.computed(() => Boolean(current.value.trashedAt) && current.value.access === 'owner'),
+            // 2.11: no Share for access that comes only through an add-on (the Wiki's editors).
+            canShare: M.computed(() => (current.value.access === 'owner' || current.value.access === 'editor') && !current.value.trashedAt
+                && !(current.value.outwardRefusal && current.value.access !== 'owner')),
+            statsText: M.computed(() => {
+                if (current.value.format === 'pdf') return [pdfFacts(current.value.file), current.value.file?.name].filter(Boolean).join(' · ') || 'PDF';
+                const {words, chars} = stats.value;
+                const mins = Math.max(1, Math.round(words / 230));
+                return `${words.toLocaleString()} word${words === 1 ? '' : 's'} · ${chars.toLocaleString()} characters · ${words ? `${mins} min read` : 'empty'}`;
+            }),
+            editedText: M.computed(() => {
+                const d = current.value;
+                return d.updatedAt ? `Last edited ${D(d.updatedAt).fromNow()}` : '';
+            })
+        };
+
+        // ---- The page ----
+        root.querySelector('.docs-outline__list').innerHTML = OUTLINE_ROW;
+        const pageEl = root.querySelector('.docs-page');
+        // For a PDF the editor runs on a page nobody sees (its save, lock and outline paths stay inert) and the viewer has the real one.
+        const page = pdf ? document.createElement('div') : pageEl;
+        const toolbarHost = root.querySelector('.docs-ed__toolbar');
+        let pdfView = null;
+        const editor = new DocEditor(page, toolbarHost, {
+            pickImage: async () => {
+                const mp = await import('/admin/js/lib/media-picker.js').catch(() => null);
+                if (mp?.pickMedia) return mp.pickMedia({title: 'Insert an image'});
+                return E.prompt('Image address', {title: 'Insert image', inputPlaceholder: 'https://… or /media/…'});
+            },
+            uploadImage: async (file) => {
+                const mod = await import('/admin/js/api.js').catch(() => null);
+                if (!mod?.api?.media?.upload) throw new Error('Images cannot be uploaded from here - use Insert image.');
+                const form = new FormData();
+                form.append('file', file, file.name || 'pasted-image.png');
+                const saved = await mod.api.media.upload(form);
+                const one = Array.isArray(saved) ? saved[0] : saved;
+                return one?.url || (one?.name ? `/media/${one.name}` : null);
+            }
+        });
+        editor.init();
+        onDispose(() => editor.destroy());
+
+        const findReplace = new FindReplace().setEditor(editor);
+        const versionHistory = new VersionHistory();
+        const templates = new DocumentTemplates();
+
+        // Outline and counts follow the content, a moment after typing stops.
+        let outlineTimer = null;
+        let headingEls = [];
+        function refreshOutline() {
+            headingEls = editor.headings();
+            outlineRows.value = headingEls.map((h, i) => ({
+                key: `${i}:${h.tagName}:${h.textContent.slice(0, 40)}`, index: i,
+                text: h.textContent.replace(/\s+/g, ' ').trim() || 'Untitled heading',
+                cls: `docs-outline__item docs-outline__item--${h.tagName.toLowerCase()}`
+            })).filter(r => r.text);
+            const text = editor.text().trim();
+            stats.value = {words: text ? text.split(/\s+/).length : 0, chars: text.length};
+        }
+        refreshOutline();
+        onDispose(() => clearTimeout(outlineTimer));
+
+        // ---- Saving ----
+        let autosaveTimer = null;
+        onDispose(() => clearTimeout(autosaveTimer));
+        function scheduleAutosave() {
+            const interval = Number(site.autoSaveInterval ?? 30000);
+            clearTimeout(autosaveTimer);
+            if (!interval) return;
+            autosaveTimer = setTimeout(() => save({silent: true}), interval);
+        }
+
+        editor.onChange(() => {
+            if (mode.peek() !== 'editing') return;
+            changeSeq++;
+            contentDirty.value = true;
+            failed.value = false;
+            scheduleAutosave();
+            clearTimeout(outlineTimer);
+            outlineTimer = setTimeout(refreshOutline, 400);
+        });
+        onDispose(M.effect(() => {
+            if (normTitle(title.value) !== normTitle(savedTitle.peek()) && mode.peek() === 'editing') scheduleAutosave();
+        }));
+
+        let inflight = null;
+        /**
+         * Save, waiting for one already running first ("Save and leave"
+         * during an autosave must not just give up).
+         *
+         * @returns {Promise<boolean>} true when everything is saved
+         */
+        async function save(opts = {}) {
+            while (inflight) await inflight.catch(() => false);
+            if (disposed) return !dirty.peek();
+            inflight = doSave(opts);
+            try { return await inflight; } finally { inflight = null; }
+        }
+
+        async function doSave({silent = false} = {}) {
+            if (mode.peek() !== 'editing') return !dirty.peek();
+            if (!dirty.peek()) return true;
+            clearTimeout(autosaveTimer);
+            saving.value = true;
+            const seq = changeSeq;
+            // An untitled document takes its first line as its title, once.
+            if (normTitle(title.peek()) === 'Untitled' && normTitle(savedTitle.peek()) === 'Untitled') {
+                const first = editor.text().split('\n').map(l => l.trim()).find(Boolean);
+                if (first) title.value = first.slice(0, 80);
+            }
+            const sentTitle = normTitle(title.peek());
+            try {
+                const updated = await docsApi.update(id, {title: sentTitle, content: editor.getValue(),
+                    baseUpdatedAt: current.peek().updatedAt}, session);
+                savedTitle.value = updated.title;
+                // Show the title as stored, unless it was edited while saving.
+                if (normTitle(title.peek()) === sentTitle && title.peek() !== updated.title && document.activeElement?.id !== 'docs-ed-title') title.value = updated.title;
+                // Only what was sent counts as saved: typing during the request is still unsaved.
+                if (changeSeq === seq) contentDirty.value = false;
+                current.value = {...current.peek(), ...updated};
+                pickedWas = '';
+                savedAt.value = new Date().toISOString();
+                failed.value = false;
+                if (!dirty.peek() && !draftPending) clearDraft(id);
+                if (!silent) E.toast('Saved', {type: 'success'});
+                return !dirty.peek();
+            } catch (err) {
+                const msg = err.message || '';
+                if (/is editing/i.test(msg)) { await lostLock(); return false; }
+                if (/saved by someone else/i.test(msg)) { await conflict(); return false; }
+                if (/not found|not edit|permission|forbidden/i.test(msg)) { await lostAccess(msg); return false; }
+                failed.value = true;
+                E.toast(msg || 'Could not save', {type: 'error'});
+                return false;
+            } finally {
+                saving.value = false;
+            }
+        }
+
+        /** Keep unsaved work as the user's own copy; fall back to a draft in this browser. */
+        async function keepAsCopy() {
+            const content = editor.getValue();
+            try {
+                return await docsApi.duplicate(id, {title: `${normTitle(title.peek())} (your unsaved changes)`, content});
+            } catch {
+                writeDraft(id, draftNow());
+                return null;
+            }
+        }
+
+        /** The document was saved by someone else since this editor loaded it. */
+        async function conflict() {
+            const unsaved = dirty.peek();
+            if (unsaved) {
+                const copy = await keepAsCopy();
+                if (copy) recount();
+                E.toast(copy
+                    ? `This document was saved by someone else while you worked. Your version is in a copy: ${copy.title}.`
+                    : 'This document was saved by someone else while you worked. Your version is kept in this browser.', {type: 'warning', duration: 12000});
+            }
+            contentDirty.value = false;
+            await refreshFromServer(true, {replace: true});
+        }
+
+        /** Access taken away (or the document deleted) while editing. */
+        async function lostAccess(msg) {
+            if (dirty.peek()) writeDraft(id, draftNow());
+            contentDirty.value = false;
+            title.value = savedTitle.peek();
+            lockHeld = false;
+            setMode('view');
+            E.toast(`You can no longer edit this document${/not found/i.test(msg) ? '' : ` (${msg})`}. Anything unsaved is kept in this browser.`, {type: 'warning', duration: 10000});
+        }
+
+        // ---- The edit lock ----
+        let heartbeat = null;
+        let poll = null;
+        onDispose(() => { clearInterval(heartbeat); clearInterval(poll); });
+
+        function setMode(next) {
+            if (disposed) return;
+            mode.value = next;
+            lockHeld = next === 'editing';
+            editor.setReadOnly(next !== 'editing');
+            clearInterval(heartbeat);
+            clearInterval(poll);
+            if (next === 'editing') heartbeat = setInterval(beat, HEARTBEAT_MS);
+            else poll = setInterval(() => refreshFromServer(false, {poll: true}), next === 'view' ? POLL_MS * 2 : POLL_MS);
+        }
+
+        async function acquire(force = false) {
+            try {
+                const r = await docsApi.lock(id, session, force);
+                if (r.ok) { lockedBy.value = ''; lockMine.value = false; return r; }
+                holder(r.lock);
+                takeOverAllowed.value = Boolean(r.canTakeOver);
+                return null;
+            } catch (err) {
+                E.toast(err.message || 'Could not start editing', {type: 'error'});
+                return null;
+            }
+        }
+
+        async function beat() {
+            if (disposed || mode.peek() !== 'editing') return;
+            let r;
+            try {
+                r = await docsApi.lock(id, session);
+            } catch (err) {
+                if (/not found|forbidden|permission/i.test(err.message || '')) await lostAccess(err.message || '');
+                return;   // otherwise offline for a moment - the next beat tries again
+            }
+            if (disposed || mode.peek() !== 'editing') return;
+            if (!r.ok) {
+                holder(r.lock);
+                takeOverAllowed.value = Boolean(r.canTakeOver);
+                await lostLock(r.lock);
+            } else if (r.updatedAt && r.updatedAt !== current.peek().updatedAt && !saving.peek()) {
+                // Our lock lapsed (a sleeping laptop) and someone saved in between.
+                await conflict();
+            }
+        }
+
+        /** Someone took the document over: keep what we had as a copy, then read their version. */
+        async function lostLock(lock) {
+            if (mode.peek() !== 'editing') return;
+            if (lock) holder(lock);
+            const who = lockMine.peek() ? 'Your other tab' : (lockedBy.peek() || 'Someone');
+            const unsaved = dirty.peek();
+            if (unsaved) {
+                const copy = await keepAsCopy();
+                if (copy) recount();
+                setMode('locked');
+                E.toast(copy
+                    ? `${who} took over editing. What you had not saved is in a copy: ${copy.title}.`
+                    : `${who} took over editing. Your unsaved changes are kept in this browser.`, {type: 'warning', duration: 10000});
+            } else {
+                setMode('locked');
+                E.toast(`${who} is editing this document now.`, {type: 'info'});
+            }
+            contentDirty.value = false;
+            title.value = savedTitle.peek();
+            await refreshFromServer(true);
+        }
+
+        /** Put a server copy into the page, keeping the reader's scroll position. */
+        function showContent(fresh) {
+            if (pdf) {
+                // A new file (replaced, or a version restored): the viewer reloads; the title and facts follow the record.
+                // `_before` is the record as it was (refreshFromServer has already put the new one in `current`).
+                const before = fresh._before || {};
+                title.value = fresh.title || '';
+                savedTitle.value = fresh.title || '';
+                if (pdfView && (fresh.file?.sha256 !== before.file?.sha256 || fresh.file?.uploadedAt !== before.file?.uploadedAt)) pdfView.reload();
+                return;
+            }
+            const y = page.parentElement?.scrollTop || 0;
+            editor.setValue(fresh.content || '');
+            editor._syncEmpty?.();
+            pickedWas = '';   // the server's copy is in the page now: later edits begin from it
+            title.value = fresh.title || '';
+            savedTitle.value = fresh.title || '';
+            contentDirty.value = false;
+            changeSeq++;
+            if (page.parentElement) page.parentElement.scrollTop = y;
+            refreshOutline();
+        }
+
+        /**
+         * The latest saved version. Readers poll this; `replace` also puts it
+         * into the page while editing (after a restore, or after a conflict).
+         */
+        async function refreshFromServer(force = false, {replace = false, poll = false} = {}) {
+            if (disposed) return;
+            try {
+                const fresh = await docsApi.get(id, session, {poll});
+                if (disposed) return;
+                const changed = force || fresh.updatedAt !== current.peek().updatedAt || fresh.content !== current.peek().content;
+                const before = current.peek();
+                current.value = fresh;
+                starred.value = Boolean(fresh.starred);
+                if (changed && (mode.peek() !== 'editing' || replace)) showContent(pdf ? {...fresh, _before: before} : fresh);
+                if (fresh.lock && !fresh.lock.mine && mode.peek() !== 'editing') {
+                    holder(fresh.lock);
+                    takeOverAllowed.value = fresh.access === 'owner' || fresh.lock.userId === me || (['owner', 'editor'].includes(fresh.access) && Boolean(fresh.lock.suggester));
+                }
+                if (mode.peek() === 'locked' && !fresh.lock) { lockedBy.value = ''; setMode(mayEdit() ? 'free' : 'view'); }
+                else if (mode.peek() === 'free' && fresh.lock && !fresh.lock.mine) setMode('locked');
+            } catch (err) {
+                if (/not found/i.test(err.message || '')) {
+                    E.toast('This document is no longer available to you.', {type: 'warning'});
+                    location.hash = HOME;
+                }
+            }
+        }
+
+        async function startEditing(force = false) {
+            if (disposed) return;
+            if (!mayEdit()) { setMode('view'); return; }
+            const r = await acquire(force);
+            if (disposed) { if (r) docsApi.unlock(id, session).catch(() => {}); return; }
+            if (r) {
+                // Take whatever was saved while we waited (or since this page loaded), then edit.
+                if (force || mode.peek() !== 'view' || (r.updatedAt && r.updatedAt !== current.peek().updatedAt)) {
+                    await refreshFromServer(true, {replace: true});
+                }
+                if (disposed) return;
+                setMode('editing');
+                // Work left here last time is offered back once this tab can edit (not while someone else does).
+                await offerDraft();
+            } else {
+                setMode('locked');
+            }
+        }
+
+        /**
+         * Work left unsaved here last time, offered back once - when this tab
+         * can edit. OK throws it away; Cancel, Escape or the backdrop put it
+         * back (admin/lib/drafts.js draftQuestion). The draft is removed only
+         * after an answer: leaving while asked dismisses the question and
+         * keeps it. A picked-up draft keeps its own `was` until it is saved.
+         */
+        let draftAsked = false;
+        let draftPending = false;   // asking: no save may clear the draft meanwhile
+        async function offerDraft() {
+            if (draftAsked || disposed || mode.peek() !== 'editing') return;
+            const draft = readDraft(id);
+            if (!draft) return;
+            draftAsked = true;
+            if (!draftDiffers(draft, current.peek())) { clearDraft(id); return; }
+            const q = draftQuestion(draft, current.peek());
+            // The page is locked while it asks: typing now would race the answer.
+            draftPending = true;
+            root.inert = true;
+            const asked = askDismissable(q.text, q.options);
+            onDispose(asked.dismiss);
+            let throwAway;
+            try { throwAway = await asked.answer; } finally { draftPending = false; root.inert = false; }
+            if (disposed) return;
+            if (throwAway) { clearDraft(id); return; }
+            // Lost the lock while asking: ask again once this tab edits.
+            if (mode.peek() !== 'editing') { draftAsked = false; return; }
+            editor.setValue(draft.content);
+            editor._syncEmpty?.();
+            if (draft.title) title.value = draft.title;
+            pickedWas = draft.was;
+            contentDirty.value = true;
+            changeSeq++;
+            refreshOutline();
+            scheduleAutosave();
+        }
+
+        // ---- Actions ----
+        const back = () => { location.hash = HOME; };
+
+        async function toggleStar() {
+            try {
+                await docsApi.star(id, !starred.peek());
+                starred.value = !starred.peek();
+            } catch (err) { E.toast(err.message || 'Could not change the star', {type: 'error'}); }
+        }
+
+        async function takeOver() {
+            if (lockMine.peek()) { await startEditing(true); return; }
+            const ok = await E.confirm(`Take over editing from <strong>${esc(lockedBy.peek())}</strong>? Anything they have not saved is kept for them as a copy.`,
+                {title: 'Take over editing', confirmText: 'Take over'});
+            if (ok) await startEditing(true);
+        }
+
+        async function share() {
+            if (dirty.peek()) await save({silent: true});
+            if (disposed) return;
+            await openShare({doc: current.peek(), kit, life: panelLife, sections: shareSections, suggestions: Boolean(site.suggestions), onChange: (next) => { current.value = {...current.peek(), ...next}; }});
+        }
+
+        // One Version history at a time; it closes with the screen.
+        let historyOpen = false;
+        async function showHistory() {
+            if (historyOpen) return;
+            historyOpen = true;
+            let modal = null;
+            try {
+                if (dirty.peek()) await save({silent: true});
+                if (disposed) return;
+                modal = await versionHistory.show(id, {session, canRestore: pdf ? editorRights() && !current.peek().trashedAt && !current.peek().frozen : mode.peek() === 'editing' && access() !== 'suggester'});
+                if (!modal) return;
+                if (disposed) { modal.close(); return; }
+                const off = panelLife.add(() => { try { modal.close(); } catch { /* gone */ } });
+                modal.element.addEventListener('close', async () => {
+                    historyOpen = false;
+                    off();
+                    if (!disposed && versionHistory.restored) await refreshFromServer(true, {replace: true});
+                }, {once: true});
+            } finally {
+                if (!modal || disposed) historyOpen = false;
+            }
+        }
+
+        async function rename() {
+            const name = await promptWith('Document title', {title: 'Rename document'}, title.peek());
+            if (disposed || name === null || name === undefined || !String(name).trim()) return;
+            if (pdf) {
+                // No editing mode for a PDF: the title is saved on its own.
+                try {
+                    const updated = await docsApi.update(id, {title: String(name).trim()}, session);
+                    if (disposed) return;
+                    current.value = {...current.peek(), ...updated};
+                    title.value = updated.title;
+                    savedTitle.value = updated.title;
+                } catch (err) { E.toast(err.message || 'Could not rename', {type: 'error'}); }
+                return;
+            }
+            title.value = String(name).trim();
+            await save({silent: true});
+        }
+
+        async function makeCopy() {
+            if (dirty.peek()) await save({silent: true});
+            if (disposed) return;
+            try {
+                const c = await docsApi.duplicate(id);
+                recount();
+                if (disposed) { E.toast(`Copy made: ${c.title}`, {type: 'success'}); return; }
+                const ok = await E.confirm(`Copy made: <strong>${esc(c.title)}</strong>. Open it?`, {title: 'Copy made', confirmText: 'Open copy', cancelText: 'Stay here'});
+                if (ok && !disposed) location.hash = docHref(c.id);
+            } catch (err) { E.toast(err.message || 'Could not copy', {type: 'error'}); }
+        }
+
+        async function moveTo(folderId) {
+            try {
+                const updated = await docsApi.update(id, {folderId}, session);
+                if (disposed) return;
+                current.value = {...current.peek(), ...updated};
+                E.toast('Moved', {type: 'success'});
+            } catch (err) { E.toast(err.message || 'Could not move', {type: 'error'}); }
+        }
+
+        async function trash() {
+            const ok = await E.confirm('Move this document to Trash? You can restore it from Trash.', {title: 'Move to Trash', confirmText: 'Move to Trash'});
+            if (!ok || disposed) return;
+            try {
+                contentDirty.value = false;
+                title.value = savedTitle.peek();
+                await docsApi.trash(id);
+                recount();
+                E.toast('Moved to Trash', {type: 'success'});
+                if (!disposed) location.hash = HOME;
+            } catch (err) { E.toast(err.message || 'Could not move to Trash', {type: 'error'}); }
+        }
+
+        async function restoreFromTrash() {
+            try {
+                await docsApi.restore(id);
+                recount();
+                E.toast('Restored', {type: 'success'});
+                if (disposed) return;
+                await refreshFromServer(true);
+                await startEditing();
+            } catch (err) { E.toast(err.message || 'Could not restore', {type: 'error'}); }
+        }
+
+        const snapshot = async () => {
+            if (dirty.peek()) await save({silent: true});
+            return {...current.peek(), title: title.peek() || 'Untitled', content: editor.getValue()};
+        };
+
+        let folderManager = null;
+        async function moveItems() {
+            if (!folderManager) { folderManager = new FolderManager(); await folderManager.load(); }
+            const here = current.peek().folderId || null;
+            return [{id: null, name: 'My documents (no folder)', depth: 0}, ...folderManager.rows().filter(f => f.id !== null)].map(f => ({
+                label: `${'  '.repeat(f.depth)}${f.name}`, icon: f.id === null ? 'folder-open' : 'folder',
+                disabled: f.id === here, action: () => moveTo(f.id)
+            }));
+        }
+        let folderItems = [];
+
+        /** Everything you can do to a PDF document (2.13): there is no text, so no save, template, print or page. */
+        function pdfMenu() {
+            const d = current.peek();
+            const owner = d.access === 'owner';
+            const rights = editorRights() && !d.trashedAt && !d.frozen;
+            const items = [];
+            if (rights) items.push({label: 'Rename…', icon: 'edit-3', action: rename});
+            items.push({label: 'Make a copy', icon: 'copy', action: makeCopy});
+            if (owner && !d.trashedAt && folderItems.length) items.push({label: 'Move to', icon: 'folder', submenu: folderItems});
+            items.push({type: 'divider'});
+            items.push({label: 'Download PDF', icon: 'download', action: () => downloadPdf(d)});
+            if (rights) items.push({label: 'Replace the PDF…', icon: 'upload', action: async () => {
+                const updated = await replacePdf(d, {session, host: pageEl});
+                if (updated && !disposed) { const before = current.peek(); current.value = {...before, ...updated}; showContent({...updated, _before: before}); recount(); }
+            }});
+            if (rights && !d.outwardRefusal && site.allowSend !== false) {
+                items.push({label: 'Send to', icon: 'send', submenu: [{label: 'Email…', icon: 'mail', action: () => openSendEmail({doc: d, kit, life: panelLife, publicLinksAllowed: site.publicLinks !== false})}]});
+            }
+            if (editorRights()) items.push({label: 'Version history', icon: 'clock', action: showHistory});
+            for (const fn of extMenus) {
+                try { const extra = fn({doc: d, view: 'editor', editable: false}); if (Array.isArray(extra) && extra.length) items.push({type: 'divider'}, ...extra); } catch { /* an add-on's problem */ }
+            }
+            if (owner && !d.trashedAt) items.push({type: 'divider'}, {label: 'Move to Trash', icon: 'trash', danger: true, action: trash});
+            return items;
+        }
+
+        function moreMenu() {
+            if (pdf) return pdfMenu();
+            const d = current.peek();
+            const owner = d.access === 'owner';
+            const editable = mode.peek() === 'editing';
+            const editorRights = owner || d.access === 'editor';
+            const items = [];
+            if (editable) items.push({label: 'Save (Ctrl+S)', icon: 'save', action: () => save()});
+            if (owner && !d.trashedAt) items.push({label: 'Rename…', icon: 'edit-3', action: rename});
+            items.push({label: 'Make a copy', icon: 'copy', action: makeCopy});
+            if (owner && !d.trashedAt && folderItems.length) items.push({label: 'Move to', icon: 'folder', submenu: folderItems});
+            items.push({label: 'Save as template…', icon: 'layout', action: async () => templates.saveAsTemplate(editor.getValue())});
+            items.push({type: 'divider'});
+            items.push({label: 'Download', icon: 'download', submenu: exportItems(snapshot)});
+            items.push({label: 'Print or save as PDF…', icon: 'printer', action: () => exportItems(snapshot).at(-1).action()});
+            // 2.11: nothing goes out of a document that may not leave Docs now (outwardRefusal).
+            if (editorRights && !d.trashedAt && !d.outwardRefusal) {
+                items.push({label: 'Send to', icon: 'send', submenu: [
+                    ...(site.allowSend === false ? [] : [{label: 'Email…', icon: 'mail', action: async () => { const d = await snapshot(); if (!disposed) openSendEmail({doc: d, kit, life: panelLife, publicLinksAllowed: site.publicLinks !== false}); }}]),
+                    {label: 'A new page…', icon: 'file-text', action: async () => sendToPage(await snapshot())},
+                    {label: 'A new blog post…', icon: 'feather', action: async () => sendToBlog(await snapshot())}
+                ]});
+            }
+            // History is the editors' (2.8.1): the server answers 403 to anyone else.
+            if (editorRights) items.push({label: 'Version history', icon: 'clock', action: showHistory});
+            for (const fn of extMenus) {
+                try { const extra = fn({doc: current.peek(), view: 'editor', editable}); if (Array.isArray(extra) && extra.length) items.push({type: 'divider'}, ...extra); } catch { /* an add-on's problem */ }
+            }
+            if (owner && !d.trashedAt) items.push({type: 'divider'}, {label: 'Move to Trash', icon: 'trash', danger: true, action: trash});
+            return items;
+        }
+
+        function setFocus(on) {
+            focus.value = on;
+            document.body.classList.toggle('docs-focus', on);
+        }
+        onDispose(() => document.body.classList.remove('docs-focus'));
+
+
+        // ---- Add-ons ----
+        // Only add-ons that understand this document's kind were kept above (2.13), so nothing here needs filtering.
+        const extMenus = [];
+        const shareSections = [];
+        const side = root.querySelector('.docs-ed__side');
+        const host = {
+            view: 'editor', api: docsApi, kit, esc, icon, editor, session,
+            doc: () => current.peek(),
+            isEditing: () => mode.peek() === 'editing',
+            reload: () => refreshFromServer(true),
+            save: () => save({silent: true}),
+            addDocMenu(fn) { if (typeof fn === 'function') extMenus.push(fn); },
+            addShareSection(fn) { if (typeof fn === 'function') shareSections.push(fn); },
+            /** Show a panel on the right; returns the element to fill. */
+            openSide(titleText) {
+                side.replaceChildren();
+                const head = document.createElement('div');
+                head.className = 'docs-ed__side-head';
+                const h = document.createElement('span');
+                h.textContent = titleText || '';
+                const x = document.createElement('button');
+                x.type = 'button';
+                x.className = 'btn btn-xs btn-ghost';
+                x.setAttribute('aria-label', 'Close panel');
+                x.innerHTML = icon('x', 14);
+                x.addEventListener('click', () => { sideOpen.value = false; side.replaceChildren(); });
+                head.append(h, x);
+                const body = document.createElement('div');
+                body.className = 'docs-ed__side-body';
+                side.append(head, body);
+                sideOpen.value = true;
+                return body;
+            },
+            closeSide() { sideOpen.value = false; side.replaceChildren(); },
+            /** Keep more data-* attributes through the admin's sanitiser (2.4) - e.g. comment anchors. */
+            allowAttrs: (list) => allowDocAttrs(list),
+            /** Filter the body on its way out - downloads, print, Send to (2.5). Keyed: installing again replaces it. */
+            setContentFilter: (key, fn) => setContentFilter(key, fn),
+            /** Whether the site offers suggestions, and the viewer's access (2.5). */
+            suggestions: Boolean(site.suggestions),
+            /** A chip beside the lock and Trash chips; returns the element to fill (2.1). */
+            addChip() {
+                const chip = document.createElement('span');
+                chip.hidden = true;
+                root.querySelector('.docs-ed__status-chips')?.appendChild(chip);
+                return chip;
+            },
+            /** Call fn with the document now and whenever it changes - a save, a reload (2.1). */
+            watchDoc(fn) { if (typeof fn === 'function') onDispose(M.effect(() => { const d = current.value; try { fn(d); } catch { /* an add-on's problem */ } })); },
+            onDispose
+        };
+        for (const ext of extensions) {
+            try { await ext.mod.install?.(host); } catch (err) { console.warn('[docs] add-on install failed', ext.owner, err); }
+        }
+        if (disposed) return;
+
+        // ---- Bindings ----
+        onDispose(kit.helpPopovers(root, {position: 'bottom'}));
+        const more = root.querySelector('.docs-ed__more');
+        const outlineList = root.querySelector('.docs-outline__list');
+        const bindings = M.applyBindings(data, root, {
+            methods: {
+                back, toggleStar, takeOver, share, restoreFromTrash,
+                editNow: () => startEditing(),
+                toggleOutline: () => { outlineOpen.value = !outlineOpen.peek(); },
+                toggleFocus: () => setFocus(!focus.peek()),
+                find: () => findReplace.show(root.querySelector('.docs-ed__canvas')),
+                history: showHistory
+            }
+        });
+        onDispose(() => bindings.dispose());
+
+        const menus = [
+            E.contextMenu(more, {cursor: 'glyph', inherit: false, density: 'compact', items: moreMenu}),
+            // Right-click in a table: rows, columns, delete. Anywhere else keeps the browser's own menu (spelling).
+            E.contextMenu(page, {
+                cursor: 'glyph', match: 'td, th', inherit: false, density: 'compact',
+                items: (cell) => editor.tableMenu(cell)
+            })
+        ];
+        onDispose(() => menus.forEach(mn => mn?.destroy?.()));
+        more.addEventListener('click', async () => {
+            if (current.peek().access === 'owner' && !folderItems.length) folderItems = await moveItems().catch(() => []);
+            if (!disposed) kit.openMenuAt(more);
+        });
+        outlineList.addEventListener('click', (e) => {
+            const b = e.target.closest('[data-heading]');
+            const h = b && headingEls[Number(b.dataset.heading)];
+            if (h) {
+                h.scrollIntoView({behavior: 'smooth', block: 'start'});
+                if (window.innerWidth < 900) outlineOpen.value = false;
+            }
+        });
+
+        // Keys: Ctrl+S saves, Ctrl+F finds, Ctrl+Shift+F focus mode, Escape leaves focus mode.
+        const onKey = (e) => {
+            const k = e.key.toLowerCase();
+            if ((e.ctrlKey || e.metaKey) && !e.shiftKey && k === 's') {
+                e.preventDefault();
+                save();
+            } else if ((e.ctrlKey || e.metaKey) && !e.shiftKey && k === 'f' && root.contains(e.target) && !pdf) {
+                e.preventDefault();
+                findReplace.show(root.querySelector('.docs-ed__canvas'));
+            } else if ((e.ctrlKey || e.metaKey) && e.shiftKey && k === 'f') {
+                e.preventDefault();
+                setFocus(!focus.peek());
+            } else if (e.key === 'Escape' && focus.peek() && !document.querySelector('.dm-modal.is-open, .dm-slideover.is-open')) {
+                setFocus(false);
+            }
+        };
+        document.addEventListener('keydown', onKey);
+        onDispose(() => document.removeEventListener('keydown', onKey));
+
+        // Title: Enter goes into the page.
+        root.querySelector('#docs-ed-title').addEventListener('keydown', (e) => {
+            if (e.key === 'Enter') { e.preventDefault(); editor.focus(); }
+        });
+
+        // Closing the tab: the browser's own prompt for unsaved work, a draft, and the lock let go.
+        const onBeforeUnload = (e) => {
+            // A save still on its way counts too (2.9): closing then would lose it.
+            if (saving.peek() && !dirty.peek()) { e.preventDefault(); e.returnValue = ''; return; }
+            if (!dirty.peek()) return;
+            writeDraft(id, draftNow());
+            e.preventDefault();
+            e.returnValue = '';
+        };
+        const onPageHide = () => { if (lockHeld) unlockOnUnload(id, session); };
+        window.addEventListener('beforeunload', onBeforeUnload);
+        window.addEventListener('pagehide', onPageHide);
+        onDispose(() => { window.removeEventListener('beforeunload', onBeforeUnload); window.removeEventListener('pagehide', onPageHide); });
+
+        Domma.icons.scan(root);
+
+        // The document goes in only now, after bindings, help popovers and icon
+        // scans: none of them may act on markup inside a person's document.
+        if (pdf) {
+            // The file, in the browser's own viewer (admin/lib/pdf-view.js); the editor keeps its detached page.
+            pdfView = mountPdfViewer(pageEl, {id, title: () => title.peek() || 'Untitled', ticket: () => current.peek().fileTicket || ''});
+            onDispose(() => pdfView?.dispose());
+        } else {
+            editor.setValue(doc.content || '');
+            editor._syncEmpty?.();
+            refreshOutline();
+        }
+
+        // ---- Hand the router the real state, then start ----
+        isDirty = () => dirty.peek();
+        saveNow = () => save({silent: true});
+        keepDraft = () => writeDraft(id, draftNow());
+
+        // Editing starts here - and offers back a draft from last time (offerDraft).
+        await startEditing();
+        if (disposed) return;
+        if (mode.peek() === 'editing' && !editor.text().trim()) editor.focus();
+    }
+};