domma-cms 1.8.32 → 1.8.34

package/plugins/docs/config.js

@@ -0,0 +1,24 @@
+/**
+ * Docs plugin defaults.
+ *
+ * The admin screen reads these through GET /api/plugins/docs/settings, which
+ * whitelists what it needs. Adding a secret here does not leak it.
+ *
+ * `editorMode` is gone (2.0): documents are always HTML. A site that was set
+ * to 'markdown' has its documents converted once at boot (see plugin.js).
+ */
+export default {
+    // 'all' lets every signed-in user read every document (and admins change
+    // them); 'user' keeps documents private unless shared with people.
+    scope: 'user',
+    autoSaveInterval: 30000, // ms, 0 to disable
+    maxVersions: 50,
+    // Whether "Anyone with the link" can be switched on for a document.
+    publicLinks: true,
+    // Whether documents can be emailed from Docs (Send to > Email). Each
+    // person may email up to 50 addresses a day either way.
+    allowSend: true,
+    // Days a document stays in Trash before it is deleted for good.
+    trashDays: 30
+    // No `storage` key: Docs keeps everything as JSON files under data/.
+};

package/plugins/docs/docs/guide.md

@@ -0,0 +1,270 @@
+---
+title: Guide
+order: 1
+---
+
+Docs is a document editor inside the admin. Write, share with the people you work with, publish a read-only link, download or print, and send a document on as a page, a blog post or an email.
+
+## What it does
+
+- **Home** lists your documents as cards or a list: Recent, Starred, Shared with me, My documents (with your folders), Templates and Trash.
+- Each document opens in its own **editor**, with a page to write on, a formatting toolbar, an Outline of its headings, and a word count.
+- **Markdown shortcuts** while you type: `#` and a space for a heading, `-` for a list, `[]` for a checklist, and more (below).
+- **Share** with other people on the site as Viewers or Editors, and optionally email them.
+- **Public link**: "Anyone with the link can view" gives a read-only web page for the document.
+- **Import** `.md`, `.html` and `.txt` files. **Download** as Markdown, a web page or plain text, or **print / save as PDF**.
+- **PDF documents**: add a PDF and it is kept exactly as it is - filed, shared, linked, emailed and versioned like any document, and shown in your browser's own PDF viewer.
+- **Send to** a new page, a new blog post, or an email.
+- **One editor at a time**: while someone is editing, everyone else sees the document read only, with their name.
+- **Version history** with a preview of every earlier version, and restore.
+- **Trash**: deleted documents can be restored for 30 days (a setting).
+
+Documents are private to whoever made them until they are shared.
+
+## Getting started
+
+1. Open [Docs](#/plugins/docs) from the admin sidebar.
+2. Click **New** (the **+** in the Docs banner at the top) and choose **Blank document**.
+3. Start typing. Type `# ` (a hash and a space) to make the first line a heading.
+4. The document saves by itself shortly after you stop typing. Ctrl+S saves at once.
+5. An untitled document takes its first line as its title when it first saves. Click the title at the top to change it.
+6. Click the arrow at the top left to go back to Home.
+
+## Home
+
+- **New** (the **+** in the banner): **Blank document**, **From a template...**, **Import a file...**, **Upload a PDF...** or **New folder...**.
+  **Import** (the upload arrow beside it) goes straight to choosing files.
+- Right-click a document, template or folder - or use its **⋮**, or select it and press **Shift+F10** - for everything you can do to it.
+- The places on the left:
+  - **Recent**: documents you have opened or edited.
+  - **Starred**: click the star on a card, or in the editor, to keep a document here.
+  - **Shared with me**: other people's documents they have shared with you.
+  - **My documents**: your own. Your folders are listed under **Folders**.
+  - **Templates**: click one to start a new document from it.
+  - **Trash**.
+- **Search** matches titles and text in the place you are looking at. Press `/` to jump to it.
+- Sort by **Last modified**, **Last opened by me**, **Title** or **Created**. Switch between **grid** and **list** with the buttons on the right.
+- Hide the left panel with the panel button next to the title.
+- **Drag files** from your computer onto the list to import them.
+- The Share, Email and Docs settings panels ask before closing if you have changed something and not saved or sent it.
+  Closing the browser tab while a document has unsaved changes asks too.
+- Right-click a document, or click its three-dot button, for:
+  - **Open**
+  - **Open in a new tab**
+  - **Star** or **Remove star**
+  - **Rename...** (owner)
+  - **Make a copy**
+  - **Move to** (owner)
+  - **Share...** (owner and editors)
+  - **Download**
+  - **Email...**
+  - **Move to Trash** (owner)
+- A card shows **Shared**, **Public link**, or who is editing it right now. A PDF's card says **PDF**, with its pages and size where a written document shows its word count.
+
+### Folders
+
+- Folders are yours alone. Documents shared with you appear under **Shared with me**, never in your folders.
+- Right-click a folder (or use its three-dot button) for **New subfolder...**, **Rename...** and **Delete folder...**.
+- Deleting a folder never deletes documents. They, and any subfolders, move up a level.
+
+### Trash
+
+- **Move to Trash** takes a document out of every list, including for the people it was shared with. Its public link stops working while it is there.
+- In Trash, right-click a document for **Restore** or **Delete for good...**. **Empty Trash** deletes everything in it.
+- Documents are deleted for good after the number of days set in Docs settings (30 by default).
+
+## The editor
+
+The top bar holds:
+
+- the **back** arrow
+- the **title**
+- where the document lives, and whether it is shared
+- the save state: **Unsaved changes**, **Saving...**, **Saved 14:05**, or **Not saved** in red when a save failed
+- the **star**
+- **Outline**, **Find and replace** (Ctrl+F), **Version history** and **Focus mode**
+- **Share**
+- the three-dot menu
+
+### Toolbar
+
+| Control | Does |
+|---|---|
+| Text style | Normal text, Heading 1 to 4, Code block, Quote |
+| Undo, Redo | Ctrl+Z, Ctrl+Y |
+| Bold, Italic, Underline, Strikethrough | Ctrl+B, Ctrl+I, Ctrl+U |
+| Highlight | Marks the selection in yellow. Click again to remove. |
+| Inline code | Monospaced text for commands and names |
+| Align left, Centre, Align right | The paragraph's alignment |
+| Bulleted list, Numbered list | Tab indents a list item, Shift+Tab outdents it |
+| Checklist | A list with tick boxes. Click a box to tick it. |
+| Quote | An indented quotation |
+| Link | Ctrl+K. Ctrl+click a link to open it. |
+| Image | Choose a picture from Media, or upload one. You can also paste or drop an image into the page. It is saved to Media. |
+| Table | Enter the size, e.g. `3x4` (columns x rows). Right-click a cell to add or delete rows and columns, or delete the table. Tab moves to the next cell. |
+| Horizontal line | A divider |
+| Clear formatting | Removes bold, colours and so on from the selection |
+
+### Markdown shortcuts
+
+Type these at the start of an empty line, then a space:
+
+| Type | Get |
+|---|---|
+| `#`, `##`, `###`, `####` | Heading 1 to 4 |
+| `-`, `*` or `+` | Bulleted list |
+| `1.` or `1)` | Numbered list |
+| `[]` or `[ ]` | Checklist |
+| `>` | Quote |
+| ```` ``` ```` | Code block |
+
+Type `---` and press Enter for a horizontal line.
+
+### Outline
+
+The **Outline** button shows the document's headings on the left. Click one to jump to it.
+
+### Focus mode
+
+The **Focus mode** button (or Ctrl+Shift+F) hides the admin around the document. Press Escape or click the button again to leave.
+
+### The three-dot menu
+
+- **Save** (Ctrl+S)
+- **Rename...**
+- **Make a copy**
+- **Move to**
+- **Save as template...**
+- **Download**: **Markdown (.md)**, **Web page (.html)**, **Plain text (.txt)**, or **Print or save as PDF...**. In the print dialog, choose "Save as PDF" as the printer to get a PDF.
+- **Print or save as PDF...**
+- **Send to**:
+  - **Email...**
+  - **A new page...**
+  - **A new blog post...**
+- **Version history**
+- **Move to Trash**
+
+## Sharing
+
+1. Click **Share** in the editor, or **Share...** on a document's menu on Home.
+2. Under **Add people**, type a name and pick the person. Only people whose role includes Docs are listed.
+3. Choose **Viewer** or **Editor** (or **Suggester**, with Docs Pro) next to their name.
+4. Leave **Email the people I've added** ticked to tell them, and add a message if you like.
+5. Click **Save access**.
+
+| Who | Can |
+|---|---|
+| Owner | Everything, including Move to, Rename, removing editors and Move to Trash |
+| Editor | Edit, share with more people, turn the public link on or off, email the document, see Version history |
+| Suggester (with Docs Pro) | What a Viewer can, and suggest changes for the owner or an editor to accept or reject. Without Docs Pro, a Viewer |
+| Viewer | Read, make their own copy, download and print (not the Version history - that is the editors') |
+
+To stop sharing with someone, click the **x** next to their name and **Save access**.
+### Public link
+
+1. In the Share panel, tick **Anyone with the link can view**.
+2. Click **Copy** and send the address to whoever needs it.
+
+- The address is long and unguessable. Anyone who has it can read the document, and download it as Markdown, HTML or text, without signing in.
+- The page uses your site's look, and search engines are told not to list it.
+- Untick the box and the address stops working at once. Ticking it again makes a new address.
+- An administrator can switch public links off for the whole site in **Docs settings**. That stops every existing link.
+
+## One editor at a time
+
+- When you open a document you may edit, you are its editor until you leave it.
+- Anyone else who opens it sees it **read only**, with "*name* is editing" at the top. Their screen refreshes by itself to show the latest saved version.
+- When the editor leaves, **Edit now** appears.
+- The owner can click **Take over**. Whatever the other person had not saved is kept for them as a copy called "*title* (your unsaved changes)", in their My documents.
+- If you open a document you are already editing in another tab, you see **Open for editing in another tab**. Click **Edit here** to move editing to this tab.
+- If your computer sleeps long enough for someone else to start editing and save, your next save is not written over theirs: your version is kept as a copy called "*title* (your unsaved changes)" and the page shows theirs.
+
+## Never losing work
+
+- Autosave saves shortly after you stop typing (the delay is a setting).
+- Leaving a document with unsaved changes asks you to **Save and leave** or **Stay**.
+- Closing the browser tab with unsaved changes asks the browser to confirm, and keeps a draft in this browser.
+- Next time you open the document, you are asked whether to **Put them back**.
+
+## Send to
+
+- **Email...**: up to 10 addresses at a time, and 50 a day per person. Send **The document, in the email** (a copy as it is now) or **A link to read it online**, which turns on the public link if it is not on already. The site's email settings are used.
+- **A new page...**: makes a draft page at an address you choose, converted to Markdown, and offers to open it in the page editor. Your role needs permission to create pages.
+- **A new blog post...**: makes a draft post in the Blog, when the Blog is switched on and your role may write posts.
+
+## Import
+
+- **New > Import a file...**, or drag files onto Home.
+- `.md` / `.markdown`:
+  - Headings, lists, task lists, tables, links, images and code come across.
+  - Front matter at the top is ignored.
+- `.html` / `.htm`: the body is kept, scripts and styles are removed.
+- `.txt`: each block of lines becomes a paragraph.
+- A first-level heading at the very top becomes the title. Otherwise the file name is used.
+- Up to 4 MB per file.
+- With **Docs Pro**, Word documents (`.docx`) too - see the Docs Pro guide.
+- A `.pdf` is not converted: it becomes a **PDF document** (below).
+
+## PDF documents
+
+A PDF you add is a document in Docs that happens to be a file. Docs never changes the file.
+
+- **Add one**: **New > Upload a PDF...**, **Import**, or drop it on the list - up to 20 MB. Its name becomes the title.
+- **Open it** and the PDF shows in your browser's own viewer, with the viewer's zoom, search, print and save. There is no
+  toolbar or outline: there is nothing to type into. The chip beside the title says **PDF**, its pages and size.
+- The text inside the PDF is read when it is added, so **search** on Home finds words in it and its card shows the first
+  lines. A scanned PDF (pictures of pages) and a password-protected one have no text to read; they are kept all the same.
+  (On a server without the optional `pdfjs-dist` package, nothing inside PDFs is read - the title is still searched.)
+- Everything else works as for any document: **Star**, **Rename**, **Make a copy** (the copy has its own file), **Move to**,
+  **Share** (Viewers and Editors see the same viewer), the **public link** (a web page framing the PDF, with **Download
+  PDF**), **Email** (the PDF is attached, or a link is sent), **Trash**.
+- **Replace the PDF...** (owner and editors, in the **⋮** menu) uploads a new file. The one it had is kept in **Version
+  history**, where each version shows its pages and size, can be downloaded, and can be restored.
+- **Download PDF** is in the **⋮** menu and under **Download** on Home.
+- A PDF is **checked before it is kept**: one that contains JavaScript, can start programs, has files attached inside it,
+  holds rich media or is an XFA form is refused with the reason. Nothing is stripped out - the file is either kept whole
+  or not at all.
+- Docs Pro features that work on a document's text (Spaces, signatures, Word files, comments, suggestions, merge fields)
+  do not apply to PDF documents yet.
+
+## Version history
+
+1. Click the clock in the editor, or **Version history** on the menu.
+2. Pick a version on the left to see it on the right, with when and who saved it.
+3. Click **Restore this version**. What the document says now is kept as a version first, so a restore can itself be undone.
+
+- A version is kept whenever a save changes the text - except that one person's saves within ten minutes of each other count as one editing session, so autosave does not fill the history.
+- The oldest go once there are more than the number set in **Docs settings** (50 by default).
+- You can restore only while you are the editor.
+
+## Templates
+
+- Open a document and choose **Save as template...** from its menu.
+- Start from one with **New > From a template...**, or click it under **Templates**.
+- Right-click a template to delete it. Documents made from it are not affected.
+- With **Docs Pro**, ready-made templates (letters, quotes, agreements, policies and more) are listed after your own. They are marked with their category and cannot be deleted.
+
+## Wiki pages
+
+With the **Wiki** switched on, a document can be a wiki page (the owner adds it from its menu). People who edit the wiki can then edit the page here too, and see its history - but they cannot share it, give it a public link or send it, because they reach it through the wiki. While a wiki is for members only, nobody - its owner included - can share its pages with anyone new, link them publicly or send them. A page protected or locked in the Wiki shows a **Protected** chip and opens read only, for its owner too; hover the chip to see why.
+
+## Settings
+
+The cog on the banner opens **Docs settings**. **For everyone on this site** needs an administrator:
+
+- **Autosave**: Off, or 10 seconds to 5 minutes after you stop typing.
+- **Versions kept per document**: 5 to 500.
+- **Days in Trash**: 1 to 365.
+- **Allow public links**.
+- **Allow emailing documents**: Send to > Email. Each person can email up to 50 addresses a day.
+- **Who sees documents** is shown but not changed here. **Private, unless shared** is the default. **Everyone with Docs** lets every Docs user read every document and administrators change them. It is set in the plugin's configuration.
+
+**Just for you** (this browser):
+
+- **Show word counts on documents**.
+
+## Tips
+
+- Ctrl+S saves, Ctrl+F finds, Ctrl+K adds a link, Ctrl+Shift+F is focus mode, and `/` on Home jumps to search.
+- Right-click inside a table for the table tools. Anywhere else, right-click gives your browser's own menu (spelling suggestions).
+- A Viewer who wants to change a document can **Make a copy**. The copy is theirs.

package/plugins/docs/lib/extensions.js

@@ -0,0 +1,213 @@
+/**
+ * Docs' door for extensions - how Docs Pro adds signing, protected links and
+ * the rest without replacing Docs.
+ *
+ * On `globalThis` under a registered symbol, so an extension reaches it
+ * without importing a file from this plugin (plugins load in one process, in
+ * no promised order). An extension registers from its `onReady` hook:
+ *
+ *   const docs = globalThis[Symbol.for('domma.docs')];
+ *   if (docs?.version >= 1) docs.register('docs-pro', {
+ *       label: 'Docs Pro',
+ *       admin: '/plugins/docs-pro/admin/docs-extension.js',  // imported by the Docs screens
+ *       markup: {tags: [...], attributes: {span: ['data-comment']}},
+ *       publicGate: async ({doc, request, reply}) => null | {handled: true},
+ *       linkInfo: (doc) => ({expiresAt, protected}),
+ *       on: {saved(doc, user), trashed(doc, user), deleted(doc), restored(doc, user, num)},
+ *       // 2.5: suggested edits. check() gets the stored body and what a Suggester
+ *       // sent; it answers the body to store, or null to refuse. publicHtml()
+ *       // filters a body before it leaves Docs (public page, downloads, email).
+ *       suggest: {check(beforeHtml, afterHtml, user) => string|null},
+ *       publicHtml: (html) => html,
+ *       // 2.6: ready-made templates, listed after the user's own, read only.
+ *       templates: () => [{id, name, description, category, content}],
+ *       // 2.11: access to documents the add-on looks after (the Wiki's pages), on
+ *       // top of owner and shares. Synchronous; 'editor' | 'viewer' | null.
+ *       access: (doc, user) => 'editor' | 'viewer' | null,
+ *       // 2.11: documents that must not leave Docs right now (a members-only wiki's
+ *       // pages): no public link (an existing one stops working), no sending.
+ *       restrict: (doc) => null | {reason},
+ *       // 2.12: documents this person may not change right now (a protected or locked
+ *       // wiki page) - owner included. Synchronous. Refuses the text and title, the
+ *       // edit lock, version restore and Trash; reading, history and the rest stay.
+ *       freeze: (doc, user) => null | {reason},
+ *       // 2.13: the kinds of document this extension understands - 'html' (a body
+ *       // written in the editor) and/or 'pdf' (a file). Default ['html']: an add-on
+ *       // written before PDF documents existed sees none of them - its menu items,
+ *       // chips, share sections and events (`emit`) skip PDF documents, and its admin
+ *       // module is not installed in a PDF document's screen. Services are not
+ *       // filtered: an add-on that lists documents itself should check `kindOf(doc)`.
+ *       kinds: ['html']
+ *   });
+ *
+ * and uses `docs.services` (readDoc, writeDoc, accessOf, sanitizeDoc, ...) to
+ * work on documents the way Docs does. When Pro's licence lapses it never
+ * registers, and Docs carries on alone.
+ *
+ * @module docs/lib/extensions
+ */
+
+export const KEY = Symbol.for('domma.docs');
+export const VERSION = 1;
+
+/** The registry, made once per process. */
+export function docsRegistry() {
+    if (globalThis[KEY]?.version === VERSION) return globalThis[KEY];
+    const extensions = new Map();
+    const reg = {
+        version: VERSION,
+        services: {},
+
+        register(owner, ext = {}) {
+            if (!/^[a-z0-9-]{2,60}$/.test(String(owner))) throw new Error('An extension needs its plugin name.');
+            extensions.set(owner, {
+                owner,
+                label: String(ext.label || owner),
+                admin: typeof ext.admin === 'string' && ext.admin.startsWith('/plugins/') ? ext.admin : '',
+                publicGate: typeof ext.publicGate === 'function' ? ext.publicGate : null,
+                linkInfo: typeof ext.linkInfo === 'function' ? ext.linkInfo : null,
+                on: ext.on || {},
+                suggest: ext.suggest && typeof ext.suggest.check === 'function' ? ext.suggest : null,
+                publicHtml: typeof ext.publicHtml === 'function' ? ext.publicHtml : null,
+                templates: typeof ext.templates === 'function' ? ext.templates : null,
+                access: typeof ext.access === 'function' ? ext.access : null,
+                restrict: typeof ext.restrict === 'function' ? ext.restrict : null,
+                freeze: typeof ext.freeze === 'function' ? ext.freeze : null,
+                kinds: Array.isArray(ext.kinds) && ext.kinds.length ? ext.kinds.map(String).filter(k => k === 'html' || k === 'pdf') : ['html'],
+                order: Number(ext.order) || 0
+            });
+            if (ext.markup && typeof reg.services.allowMarkup === 'function') reg.services.allowMarkup(ext.markup);
+        },
+
+        unregister(owner) { extensions.delete(owner); },
+
+        list() { return [...extensions.values()].sort((a, b) => a.order - b.order); },
+
+        /** Admin modules the Docs screens import, in order - with the kinds of document each understands (2.13). */
+        adminModules() {
+            return reg.list().filter(e => e.admin).map(e => ({owner: e.owner, label: e.label, module: e.admin, kinds: e.kinds}));
+        },
+
+        /** Does this extension understand this document (2.13)? Extensions written before PDF documents understand HTML ones only. */
+        handles(ext, doc) {
+            const kind = doc?.format === 'pdf' ? 'pdf' : 'html';
+            return (ext?.kinds || ['html']).includes(kind);
+        },
+
+        /**
+         * Ask each extension whether it answers a public-link request itself
+         * (a password form, an expired link). The first that handles it wins.
+         */
+        async gate(ctx) {
+            for (const ext of reg.list()) {
+                if (!ext.publicGate) continue;
+                try {
+                    const r = await ext.publicGate(ctx);
+                    if (r?.handled) return r;
+                } catch (err) {
+                    ctx.request?.log?.error?.({err}, `[docs] ${ext.owner} publicGate failed`);
+                    return {handled: true, error: true};
+                }
+            }
+            return null;
+        },
+
+        /** Is any extension able to answer for a protected link? (2.3) */
+        hasGate() { return reg.list().some(e => e.publicGate); },
+
+        /** Extra facts about a document's public link (expiry, password), merged. */
+        linkInfo(doc) {
+            return Object.assign({}, ...reg.list().map((e) => {
+                try { return e.linkInfo ? e.linkInfo(doc) || {} : {}; } catch { return {}; }
+            }));
+        },
+
+        /** Does an extension let Suggesters suggest? (2.5) Without one a Suggester is a Viewer. */
+        hasSuggest() { return reg.list().some(e => e.suggest); },
+
+        /**
+         * A Suggester's save: the first extension's answer - the body to store, or
+         * null (refused). Refused when none is there, or when it throws.
+         */
+        checkSuggestion(before, after, user) {
+            const ext = reg.list().find(e => e.suggest);
+            if (!ext) return null;
+            try { const r = ext.suggest.check(before, after, user); return typeof r === 'string' ? r : null; } catch { return null; }
+        },
+
+        /** Extensions' ready-made templates (2.6): [{owner, label, ...template}]. Never throws. */
+        builtInTemplates() {
+            const out = [];
+            for (const ext of reg.list()) {
+                if (!ext.templates) continue;
+                try {
+                    for (const t of ext.templates() || []) if (t && /^[a-z0-9-]{1,60}$/.test(String(t.id))) out.push({...t, owner: ext.owner, label: ext.label});
+                } catch { /* an extension's problem */ }
+            }
+            return out;
+        },
+
+        /**
+         * The strongest access any extension gives this user on this document (2.11):
+         * 'editor', 'viewer' or null. Never throws - an extension that fails gives none.
+         */
+        extraAccess(doc, user) {
+            let best = null;
+            for (const ext of extensions.values()) {
+                if (!ext.access) continue;
+                let r = null;
+                try { r = ext.access(doc, user); } catch { r = null; }
+                if (r === 'editor') return 'editor';
+                if (r === 'viewer') best = 'viewer';
+            }
+            return best;
+        },
+
+        /**
+         * Why this document may not leave Docs now (2.11) - a reason, or '' when it may.
+         * An extension that throws restricts (fail closed while it is there).
+         */
+        restrictionOf(doc) {
+            for (const ext of extensions.values()) {
+                if (!ext.restrict) continue;
+                try { const r = ext.restrict(doc); if (r) return String(r.reason || `${ext.label} keeps this document private.`); } catch { return `${ext.label} keeps this document private.`; }
+            }
+            return '';
+        },
+
+        /**
+         * Why this person may not change this document now (2.12) - a reason, or '' when
+         * they may. An extension that throws freezes it (fail closed while it is there).
+         */
+        frozenFor(doc, user) {
+            for (const ext of extensions.values()) {
+                if (!ext.freeze) continue;
+                try { const r = ext.freeze(doc, user); if (r) return String(r.reason || `${ext.label} keeps this document from being changed.`).slice(0, 300); } catch { return `${ext.label} keeps this document from being changed.`; }
+            }
+            return '';
+        },
+
+        /** A body as the outside world sees it (2.5): every extension's publicHtml in turn. */
+        publicHtml(html) {
+            let out = String(html ?? '');
+            for (const ext of reg.list()) {
+                if (!ext.publicHtml) continue;
+                try { const r = ext.publicHtml(out); if (typeof r === 'string') out = r; } catch { /* keep what we had */ }
+            }
+            return out;
+        },
+
+        /** Tell every extension that understands the document (2.13: a PDF document reaches only those declaring 'pdf'). Never throws and never waits. */
+        emit(event, ...args) {
+            const doc = args[0] && typeof args[0] === 'object' && 'format' in args[0] ? args[0] : null;
+            for (const ext of reg.list()) {
+                const fn = ext.on?.[event];
+                if (typeof fn !== 'function') continue;
+                if (doc && !reg.handles(ext, doc)) continue;
+                Promise.resolve().then(() => fn(...args)).catch(() => { /* an extension's problem */ });
+            }
+        }
+    };
+    globalThis[KEY] = reg;
+    return reg;
+}

package/plugins/docs/lib/importer.js

@@ -0,0 +1,72 @@
+/**
+ * Files into documents: Markdown, HTML and plain text.
+ *
+ * Markdown goes through the CMS's own `marked` (GitHub-flavoured, so tables
+ * and task lists come across). Whatever the source, the result is sanitised
+ * like any other document body before it is stored.
+ *
+ * @module docs/lib/importer
+ */
+
+import {marked} from 'marked';
+import {escapeHtml, parseHtml} from '../admin/lib/convert.js';
+import {sanitizeDoc} from './store.js';
+
+export const IMPORTABLE = ['md', 'markdown', 'html', 'htm', 'txt'];
+
+/**
+ * @param   {string} name  the file name, for its extension and a fallback title
+ * @returns {string|null} 'md' | 'html' | 'txt', or null when not importable
+ */
+export function kindOf(name) {
+    const ext = String(name || '').toLowerCase().split('.').pop();
+    if (ext === 'md' || ext === 'markdown') return 'md';
+    if (ext === 'html' || ext === 'htm') return 'html';
+    if (ext === 'txt') return 'txt';
+    return null;
+}
+
+/** GFM task list items come out of marked as disabled checkboxes; Docs has its own checklist. */
+function checklists(html) {
+    return html.replace(/<ul>(\s*<li><input (?:checked="" )?disabled="" type="checkbox">[\s\S]*?)<\/ul>/g, (m, body) => {
+        const items = body.replace(/<li><input (checked="" )?disabled="" type="checkbox">\s*/g,
+            (x, on) => `<li data-checked="${on ? 'true' : 'false'}">`);
+        return `<ul data-type="checklist">${items}</ul>`;
+    });
+}
+
+/**
+ * Take the first top-level heading as the title when there is one and no
+ * better title was given; it comes out of the body so it is not doubled.
+ */
+function splitTitle(html) {
+    const m = /^\s*<h1[^>]*>([\s\S]*?)<\/h1>\s*/i.exec(html);
+    if (!m) return {title: null, html};
+    const text = m[1].replace(/<[^>]+>/g, '').replace(/\s+/g, ' ').trim();
+    return text ? {title: parseHtml(text).children.map(c => c.text || '').join(''), html: html.slice(m[0].length)} : {title: null, html};
+}
+
+/**
+ * @param   {{name:string, text:string}} file
+ * @returns {{title:string, content:string}|null}
+ */
+export function importFile({name, text}) {
+    const kind = kindOf(name);
+    if (!kind) return null;
+    const src = String(text ?? '').replace(/^/, '');
+    let html;
+    if (kind === 'md') {
+        // Front matter is metadata, not document.
+        const body = src.replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n/, '');
+        html = checklists(marked.parse(body, {gfm: true, breaks: false, async: false}));
+    } else if (kind === 'html') {
+        const body = /<body[^>]*>([\s\S]*)<\/body>/i.exec(src);
+        html = body ? body[1] : src;
+    } else {
+        html = src.split(/\r?\n\s*\r?\n/).map(p => p.trim()).filter(Boolean)
+            .map(p => `<p>${escapeHtml(p).replace(/\r?\n/g, '<br>')}</p>`).join('');
+    }
+    const base = String(name || '').replace(/\.[^.]+$/, '').trim();
+    const split = splitTitle(html);
+    return {title: split.title || base || 'Imported document', content: sanitizeDoc(split.html)};
+}

package/plugins/docs/lib/pdf-worker.js

@@ -0,0 +1,48 @@
+/**
+ * The PDF text reader, in its own thread (lib/pdf.js starts and stops it).
+ *
+ * pdfjs-dist does the reading with scripting off and no fonts loaded - only
+ * the text is wanted. The parent gives it a time budget and ends it when
+ * that runs out, so a file built to stall never holds the server.
+ *
+ * @module docs/lib/pdf-worker
+ */
+
+import {parentPort, workerData} from 'worker_threads';
+
+async function run() {
+    const {data, maxPages, maxChars} = workerData;
+    const pdfjs = await import('pdfjs-dist/legacy/build/pdf.mjs');
+    const task = pdfjs.getDocument({
+        data: new Uint8Array(data),
+        isEvalSupported: false,
+        disableFontFace: true,
+        useSystemFonts: false,
+        verbosity: 0,
+        stopAtErrors: false
+    });
+    const doc = await task.promise;
+    const pages = doc.numPages;
+    const out = [];
+    let chars = 0;
+    for (let i = 1; i <= Math.min(pages, maxPages) && chars < maxChars; i++) {
+        let page;
+        try { page = await doc.getPage(i); } catch { continue; }
+        const content = await page.getTextContent({includeMarkedContent: false});
+        let line = '';
+        const lines = [];
+        for (const item of content.items) {
+            if (typeof item.str !== 'string') continue;
+            line += item.str;
+            if (item.hasEOL) { lines.push(line); line = ''; } else if (item.str && !/\s$/.test(item.str)) line += ' ';
+        }
+        if (line.trim()) lines.push(line);
+        const text = lines.map(l => l.replace(/\s+/g, ' ').trim()).filter(Boolean).join('\n');
+        if (text) { out.push(text); chars += text.length; }
+        page.cleanup();
+    }
+    await task.destroy();
+    parentPort.postMessage({pages, text: out.join('\n\n').slice(0, maxChars)});
+}
+
+run().catch((err) => parentPort.postMessage({pages: 0, text: null, error: String(err && err.message || err)}));