domma-cms 1.8.32 → 1.8.34

package/plugins/docs/CLAUDE.md

@@ -0,0 +1,318 @@
+# Docs - AI Assistant Guide
+
+A document editor in the admin (2.0): Home and a per-document editor, sharing with people, public
+links, import/export, send to page/blog/email, an edit lock, trash, stars, version history, templates.
+Free (2.14.0; paid and closed source until then). Plan and phases (with Docs Pro): `dcms-marketplace/docs/docs-plan.md`.
+
+## Files
+
+| File | What |
+|---|---|
+| `plugin.js` | the admin API (`/api/plugins/docs`) |
+| `plugin.public.js` | the public link page `GET /docs/s/:token` (`?download=md|html|txt`), via `renderBlogPage` + `templates/public-doc.html` |
+| `lib/store.js` | storage, `accessOf`, user state (stars/recent), the edit lock table, link index, `sanitizeDoc`, `selectRows`, `purgeTrash`. Shared by both halves: its module state (`runtime.config`, locks, caches) is one copy. |
+| `lib/importer.js` | `.md` (CMS `marked`, GFM task lists -> checklists), `.html`, `.txt` -> sanitised HTML |
+| `lib/pdf.js`, `lib/pdf-worker.js` | 2.13: `inspectPdf` (the checks a PDF passes before it is kept), `extractPdfText` (pdfjs-dist in a worker thread with a time budget), `extractToHtml`, `contentDisposition` |
+| `admin/lib/pdf-view.js` | 2.13: the PDF screen's parts - the viewer frame, facts, download, replace, the PDF download menu |
+| `lib/extensions.js` | the registry `globalThis[Symbol.for('domma.docs')]` for Docs Pro |
+| `admin/lib/convert.js` | pure, DOM-free: `parseHtml`, `htmlToMarkdown`, `htmlToText`, `countWords`, `preview`, `outline`, `standaloneHtml`, `startsWithTitle`. Used by server AND browser. |
+| `admin/lib/shortcuts.js` | pure: Markdown typing shortcuts |
+| `admin/lib/editor.js` | `DocEditor` - contenteditable + execCommand, toolbar, shortcuts as DOM work, checklists, tables, image paste/upload |
+| `admin/lib/api.js` | `docsApi` (through `H`), `loadKit`, `loadExtensions`, `sanitizeHtml`, download/print helpers |
+| `admin/lib/share.js`, `send.js`, `settings.js`, `versions.js`, `folders.js`, `templates.js`, `find-replace.js` | panels and helpers |
+| `admin/views/docs.js` | Home (`#/plugins/docs`) |
+| `admin/views/editor.js` | the editor (`#/plugins/docs/d/:id`) |
+
+## Storage - files only
+
+| Path | Holds |
+|---|---|
+| `data/documents/<id>.json` | `id, title, content (HTML), format:'html', folderId, tags, userId (owner), shares:[{userId, role:'viewer'|'editor', addedAt, addedBy}], publicLink:{token, createdAt, createdBy}|null, trashedAt, trashedBy, wordCount, createdAt, updatedAt, updatedBy` |
+| `data/versions/<id>/<n>.json` | `num, title, content, createdAt, savedBy, replacedBy` |
+| `data/user-state.json` | `{[userId]: {starred:[id], recent:[{id, at}]}}` |
+| `data/folders.json`, `data/templates.json` | through `_lib/dataStore` (per user) |
+| `data/.backup-markdown/` | originals of documents converted from the old Markdown editor |
+| `data/files/<id>.pdf` | 2.13: a PDF document's file; `data/versions/<id>/<n>.pdf` is the file an earlier version was |
+
+Document writes are atomic (tmp + rename) and serialised per document. **Every route that changes an
+existing document uses `mutateDoc(id, fn)`**, which re-reads inside the per-document write chain (a
+share saved while an autosave lands must not write back a stale body). Single process only. There is
+no MongoDB mode. Tests set `DOCS_DATA_DIR` (tests/_env.js, imported first) to a temp dir.
+
+## Rules that matter
+
+- **HTML is the only stored format.** Every body goes through `sanitizeDoc` (sanitize-html allowlist:
+  document tags, a few inline styles, `data-type` on ul, `data-checked` on li; http/https/mailto/tel
+  links, data: only for img) on create, update, import, restore and template save; `full()` and the
+  public page sanitise again on the way out. `editorMode` was removed in 2.0. `migrateLegacy` (onReady)
+  upgrades every document/template without `format` once, per document: no HTML tags = Markdown ->
+  `marked`, otherwise sanitised (1.x stored bodies raw). Versions are upgraded on restore. Backups in
+  `data/.backup-markdown/`.
+- **The admin sanitises with DOMPurify directly** (`api.js sanitizeHtml`): `ALLOW_DATA_ATTR:false` plus
+  only `data-type`/`data-checked` (`allowDocAttrs` for add-ons). Domma.sanitize drops all `data-*`
+  (checklists became bullets); allowing all would let a body's `data-on-click`/`data-help` reach the
+  admin's bindings. The editor also sets the body only AFTER applyBindings/helpPopovers/icons.scan.
+  No DOMPurify -> text only.
+- **Lost updates:** the editor sends `baseUpdatedAt`; a text save from a stale copy -> 409 `{conflict}`
+  and the editor keeps its text as a copy. The heartbeat compares the lock's `updatedAt` too (a lock
+  that lapsed while a laptop slept).
+- **Versions:** one person's saves within 10 minutes of their last save add none (`shouldSnapshot`);
+  restores always snapshot.
+- **Trash** belongs to the owner: sharees get 404, send/shares/link -> 409, Trash view and Empty Trash
+  are the user's own docs only (even an admin with `scope:'all'`).
+- **Email:** `allowSend` site setting; 50 addresses per person per day (in memory) on top of 10 per send
+  and 10 sends / 10 min.
+- **Known gap:** the public page renders through the site template, so site analytics / injected
+  scripts on that page can see the token in `location.href`.
+- **Access** (`accessOf`): owner > shares (editor/viewer) > `scope:'all'` (everyone reads, admins are
+  owners). No access -> 404; a viewer asking to edit -> 403. Owner only: move, trash/restore/delete,
+  removing editors (an editor may add people, never remove an editor). Duplicates are always the
+  copier's own, unshared, without a link.
+- **Edit lock** (in memory, per browser tab `session`, TTL 90s, heartbeat 30s): `POST /lock` answers
+  200 `{ok:false, lock, canTakeOver}` when held elsewhere (never 423 - the admin's `H` hides error
+  bodies). `PUT` of title/content from another session -> 423. `force` only for the owner or the same
+  user. The editor that loses the lock saves its unsaved content as "<title> (your unsaved changes)"
+  via `POST /duplicate {title, content}`.
+- **Protected links fail closed (2.3):** `doc.linkGuarded` (set by Docs Pro through `setLinkGuard`) means the public page
+  answers 404 unless an extension with a `publicGate` is registered (`registry.hasGate()`) - a lapsed Docs Pro never
+  opens a password-protected or expired link.
+- **Public links:** a random 18-byte token; `docByToken` returns null when the site setting
+  `publicLinks` is false or the document is trashed. Rate-limited 60/min, `noindex`, `no-store`,
+  `no-referrer`. Turning a link off and on makes a new token.
+- **Send to page/blog** is done in the browser through the core `/api/pages` and Blog `/api/plugins/blog/posts`
+  with the user's own token (Markdown body, drafts) - Docs grants nothing.
+
+## Routes (`/api/plugins/docs`)
+
+- `GET /count` (2.7) - sidebar badge: documents you own (Trash left out), `inventory: true`; details rows Yours / Shared with you / Starred / In Trash. Cached a minute per user (a Map; entries older than 60 s are dropped), keyed to a write generation bumped in `onResponse` for every non-GET request - a count stores its answer only if no write finished while it read
+- `GET/PUT /settings` (`autoSaveInterval, maxVersions, publicLinks, allowSend, trashDays`; `scope` read-only; `extensions`)
+- `GET /people` - share picker (id, name; email for admins), filtered to roles holding `docs.read`
+- `GET /documents?view=mine|recent|starred|shared|all|trash&folder=&q=` - rows with `excerpt`, no body
+- `POST /documents`, `POST /documents/import {name, text, folderId}` (5 MB)
+- `GET/PUT/DELETE /documents/:id` (`GET ?poll=1` = a reader's refresh, not recorded as opened; `PUT
+  baseUpdatedAt`) (DELETE = Trash; `?permanent=1` from Trash only), `POST .../restore`, `POST /trash/empty`
+- `POST .../duplicate {title?, content?}`, `POST .../star {on}`
+- `POST/DELETE .../lock` (`session`), `PUT .../shares {shares, notify, message}`, `POST/DELETE .../link`
+- `POST .../send {to, message, mode:'inline'|'link'}` - max 10, 10 per 10 min
+- `GET .../versions`, `GET .../versions/:num`, `POST .../versions/:num/restore`
+- `GET/POST /folders`, `PUT/DELETE /folders/:id`, `GET/POST /templates`, `DELETE /templates/:id`
+
+## Extension registry (for Docs Pro)
+
+`docsRegistry()` - `register(owner, {label, admin, markup, publicGate, linkInfo, on})`, `services`
+(readDoc, writeDoc, listDocs, accessOf, sanitizeDoc, allowMarkup, siteBase, people, config, htmlToText,
+and since 2.1 `listFolders`, `isAdmin` - Docs Pro's Spaces are folders; since 2.2 `convert` {standaloneHtml,
+htmlToMarkdown, htmlToText, fileName, startsWithTitle, parseHtml (2.4)} - Docs Pro's cloud copies and Word files; since 2.3 `setLinkGuard(docId, on)`;
+since 2.4 `createDoc({title, content, folderId}, user)` - sanitised, folder checked with `usableFolder`, into Recent),
+`gate()`, `linkInfo()`, `emit('saved'|'trashed'|'deleted'|'linkRemoved')`. Register from `onReady`.
+The admin screens import each `admin` module and call `install(host)`; the host offers
+`addDocMenu(fn)`, `addShareSection(fn)`, Home `addPlace({key,label,icon,render})`, editor
+`openSide(title)`/`closeSide()`, `doc()`, `reload()`, `save()`, `onDispose`, and since 2.1 `addChip()` (an
+element beside the lock/Trash chips) and `watchDoc(fn)` (called with the document now and on every change).
+Home hides search, sort and grid/list while an add-on place is open (2.1).
+Since 2.4: Home `addImporter({ext: ['.docx'], accept, label, import(file, {folderId}) => doc})` (New > Import and drop
+use it for matching files; extends the file input's `accept`), both screens `allowAttrs([...])` (more attributes kept by the
+admin's DOMPurify - Pro's `data-comment`; the SERVER side is the registry's `markup`), and the editor's DocEditor
+`saveRange()`, `restoreRange(r)`, `selectedText(r)`, `insertHtml(html, r)`, `applyNamed(name, r)` (2.8 - a named
+toolbar action at a saved selection: bold/italic/underline/strike/highlight/inlineCode/link/clearFormat/bulletList/
+numberedList/checklist/quote; refused read-only and while suggesting), `wrapSelection({data-*}, r)` (a span; across
+blocks keeps the first block's part), `unwrap(selector)`. "Use a template" sets `sessionStorage['docs:fill-next']='1'` when
+the template holds `{{...}}` - Pro's merge fields open their fill-in panel.
+
+## Admin traps met here
+
+- `data-each` templates are set in JS; whole class lists are one `{{cls}}` (whitespace next to
+  `{{…}}` is dropped); a select's value is set after render.
+- Markdown shortcuts are DOM work: `execCommand('insertUnorderedList')` in a freshly emptied `<p>`
+  nests the list inside the `<p>`.
+- Headless tests: one browser context per user (a shared context shares localStorage and so the
+  sign-in); Domma keeps a hidden `.dm-dialog-confirm` - click the visible one.
+
+## Tests
+
+`tests/plugin.test.js` (API: settings, versions, permissions, sanitising, sharing, notify, lock, trash,
+star/recent, public links + page, import, send, people - mail and users are injected via
+`options.mailer` / `options.listUsers`), `tests/convert.test.js`, `tests/shortcuts.test.js`. Run from
+the CMS: `cd cms && node --test --test-concurrency=1 ../dcms-marketplace/plugins/docs/tests/*.test.js`.
+
+## Suggesters (2.5)
+
+Share role `suggester` - `accessOf` answers it; `canEdit` is false. While an extension registers `suggest: {check}` (Docs Pro,
+`registry.hasSuggest()`), a Suggester may take the edit lock and PUT the body: title/tags ignored, folder refused, the lock
+REQUIRED (423 without it), and the body stored is `registry.checkSuggestion(stored, sent, user)` (null -> 403
+`suggestOnly`). Without Pro a Suggester is a Viewer everywhere (no lock, no save) and the share role is kept as it was
+(new ones cannot be given). `/settings` answers `suggestions`. Admin: share panel offers "Suggester" when
+`site.suggestions` (or someone already has it); the editor treats a Suggester as able to edit (then Pro forces
+suggesting mode), title read-only, no version restore. DocEditor `setSuggesting(on)` switches off the toolbar, Markdown
+shortcuts, Tab, Enter-in-checklist, checklist ticks, the table menu, Docs' paste/drop handling and find-and-replace's
+Replace - so an add-on can track every change from `beforeinput`.
+
+**What leaves Docs** goes through add-ons' filters: server `registry.publicHtml(html)` (public page and its downloads,
+email "inline") and admin `outgoing(html)` (`setContentFilter(key, fn)` on both screens' host; downloads, print, Send
+to Page / Blog). Docs Pro uses them to strip comment marks and show pending suggestions as not made.
+
+## Ready-made templates (2.6)
+
+An extension's `templates()` (registry) lists read-only templates: `GET /templates` answers the user's own first, then
+`{id: 'x-<owner>-<id>', name, description, category, content (sanitised), builtIn: true, source: <label>}`. Home shows
+"<category> · <source>" and no Delete. (admin/lib/templates.js `showPicker` is not wired to anything - its built-in
+branch only matters if it is revived.) DELETE on one is a 404
+(they are not in templates.json).
+
+## 2.8.1 (2026-10-13): trusted email links; history for editors
+
+- `siteBase()` is the Site URL (or old `site.url`) only; `linkBase(req)` (async, in the registry's services) is what
+  emails and the share panel's link use: the Site URL, else core's `trustedOrigin` (an address someone has really
+  signed in on, as password resets do). Never the request's Host header - an insider could send colleagues a link to a
+  lookalike host. With no trusted address the share email names the path and the log warns.
+- `GET .../versions` and `.../versions/:num` answer 403 to anyone who cannot edit (viewers, suggesters, `scope:'all'`
+  readers): a version may hold text the owner removed before sharing. The editor menu shows Version history to
+  editors and owners only.
+
+## The Tool Upgrade (2.9.0, 2026-10-14)
+
+- **Home banner:** New (+, the New menu is bound to that button) and Import beside the cog. The rail's own New button is
+  hidden when the banner exists (kept for a core without the chrome). A help mark beside the list title explains the places.
+- **Shift+F10** on a focused document card, template card or folder opens its menu; every Home menu has a header.
+- **Sidebar badge:** `recount()` (kit.sidebarCount - added to loadKit) after create, import, copy, trash, restore,
+  delete for good and Empty Trash.
+- **Unsaved work:** the editor's existing `beforeunload` (draft + browser prompt when dirty) now also asks while a save is
+  on its way. Share, Email and Settings ask before closing with a change (`admin/lib/panel-guard.js` guardClose, applied
+  AFTER kit.onceClosed - otherwise onceClosed's wrapper tears the panel down whatever the question answered).
+- **The editor keeps its own top bar** for Outline, Find, History, Focus, Share and More - Focus mode hides the admin
+  banner (`body.docs-focus .dm-plugin-banner`), so document actions in the banner would vanish exactly when writing.
+- Prompts with a starting value use `promptWith(message, options, value)` (api.js), never E.prompt's `inputValue`: Domma
+  sanitises that into `value="…"` and turns `&quot;` back into a bare quote, so a title with `"` opened cut short (escaping
+  it does not help). The value is set as a property on the dialog's input, which exists as soon as E.prompt returns.
+
+## 2.10.0 (2026-10-15 Tool Upgrade, second pass)
+
+- Drafts: `admin/lib/drafts.js` (pure, tested), stored as `docs.draft.<userId>.<docId>` = `{owner, title, content, at,
+  was}`. Another person's draft is never read back; 2.9's drafts with no owner are dropped. Restore question: OK throws
+  away, Cancel/Escape put back, or make a new document "<title> (your unsaved changes)" if the original is gone. Enter
+  is ignored and the page locked while it asks; a draft goes only after an answer.
+- `panel-guard.js`: `claimPanel` (one of a kind), `tieToScreen`, `guardClose(..., busy)`. Share and Settings keep values
+  typed during a slow save; Email ignores close while sending.
+- `/count` answers `places` {starred, shared, mine (top level), trash} for the rail. Its cache generation is
+  `runtime.writeGen` in lib/store.js, bumped by EVERY store write (Docs Pro writes through services, not Docs' routes).
+- Menus on Share people and Version history rows.
+
+## 2.11.0 (2026-10-15): the Wiki's hooks
+
+- Registry `access: (doc, user) => 'editor' | 'viewer' | null` (synchronous) - `extraAccess()` gives the strongest any
+  extension grants. `store.accessOf` takes the stronger of the share/site-wide role and the extension's (owner stays
+  owner). The Wiki makes `wiki.update` holders editors of every wiki page.
+- `onlyThroughExtension(doc, user)`: a document reached ONLY through an extension (not owned, not shared, not
+  site-wide) is in no Home place but Starred (when starred) and Recent (when opened) - it was never shared with them.
+- Services: `mutateDoc(id, fn)`, `publicHtml(html)` (= `registry.publicHtml(withoutSuggestions(sanitizeDoc(html)))`,
+  what the public sees), `lockOf(id)` (the lock as `publicLock` shows it to nobody's session, or null).
+- Access ONLY through an extension is for editing and history: `outwardRefusal(doc, user)` - PUT shares, POST/DELETE
+  link and send answer 403; the editor hides Share and Send to, Home hides Share/Email (`row.outward`).
+- Registry `restrict: (doc) => null | {reason}` (`restrictionOf`, a throwing one restricts): for EVERYONE, owner
+  included - POST link and send refused (403, the reason in `outwardRefusal`), the public page `/docs/s/:token` 404s
+  (an existing link stops working while restricted, and works again after), the share panel shows the reason instead
+  of the link switch, Send to is hidden. PUT shares refuses (403) any change that ADDS someone, owner included -
+  existing shares keep working and removing people is allowed; the share panel hides Add people and says why (`restricted` on the document). The Wiki restricts its pages
+  while it is members-only. (Send to page/blog is browser-side through core APIs: hidden, not enforced.)
+- Events `restored(doc, user, num)` after a version restore, `untrashed(doc, user)` after a restore from Trash.
+- Tested through the Wiki's API tests (`plugins/wiki/tests/api.test.js`) with real Docs underneath.
+
+## 2.12.0 (2026-10-15): freeze - protection that reaches Docs' editor
+
+- Registry `freeze: (doc, user) => null | {reason}` (synchronous; `frozenFor(doc, user)` - the first reason, a throwing
+  one freezes) and `store.frozenFor()`. For EVERYONE, owner included: PUT of title/content -> 403 `{error: reason,
+  frozen: true}` (folder, tags still allowed), `POST /lock` -> `{ok: false, readOnly: true, frozen}`, version restore
+  and DELETE (Trash or permanent) -> 403. Reading, history, duplicating and the rest are untouched. `full()` answers
+  `frozen` (the reason, '' when not); the editor treats a frozen document as not editable (`mayEdit`) and shows a
+  "Protected" chip with the reason as its title.
+- The Wiki (0.2) registers it from its add-ons' `canEdit` (Wiki Pro's protection, locks and a wiki's editor roles).
+  `typeof registry.frozenFor === 'function'` is how a consumer detects 2.12 (the Wiki's `/status.protectable`).
+- A frozen document also refuses `POST .../restore` (out of Trash), and `POST /trash/empty` leaves it in Trash.
+- Service `outwardRefusal(doc, user)` - why this person may not share, link, send or publish it ('' = they may);
+  Docs Pro 0.9.1 refuses to publish such a document to a Space.
+- Credited saves (for Wiki Pro's approved suggestions): service `snapshotVersion(doc, by)` keeps what a change replaces
+  as a version, as a save does. A document's `creditName` + `creditAt` (equal to its `updatedAt`) names who that save
+  is credited to ("Sam (visitor)"): the version made of it carries `savedByName`, and `shouldSnapshot` never folds a
+  credited save into the next one. Both apply only while `creditAt === updatedAt` - the next ordinary save ends it.
+
+## 2.13.0 (2026-10-20): PDF documents
+
+A document can be a file. `format: 'pdf'` + `file: {name, size, pages, sha256, encrypted, uploadedAt, uploadedBy}`
+(`fileRecord()`, whitelisted); the bytes at `data/files/<id>.pdf`; `content` is the TEXT READ OUT OF THE FILE as
+`<p>` HTML (`extractToHtml`, sanitised), so search, the card excerpt and `wordCount` work unchanged. `kindOf(doc)` -
+`'pdf' | 'html'` - is the one question; everything that renders, exports or edits a body asks it. Docs never rewrites
+a PDF: it is kept whole or refused.
+
+- **Checks (`lib/pdf.js inspectPdf`)**: 20 MB cap (`MAX_PDF_BYTES`), `%PDF-` in the first KB, then every name in
+  `REFUSED_NAMES` (JavaScript, JS, Launch, EmbeddedFile(s), RichMedia, XFA, GoToE, SubmitForm, ImportData) searched in
+  the raw bytes AND every FlateDecode stream inflated (per-stream and total caps - a bomb is skipped, not followed), with
+  `#xx` name escapes undone first. Refused with the plain reason, never stripped. `/OpenAction` is NOT refused (a plain
+  "open at page 1" is in every LaTeX export; a script behind it is caught by /JS). Encrypted files are kept (no extract).
+- **Text extract**: `extractPdfText` runs pdfjs-dist (`pdfjs-dist/legacy/build/pdf.mjs`, an OPTIONAL dependency of the
+  CMS - `extractCapability()` resolves it without loading) in a `worker_threads` Worker with scripting off, no fonts,
+  300 pages / 200k chars, and a 20 s budget - over time it is terminated and the document stored without an extract.
+  `GET /settings` answers `pdf: {maxBytes, search, reason}`. Tests skip the extract test where pdfjs is absent.
+- **Routes**: `POST /documents/upload {name, data: base64, folderId, title?}` (the same road as Docs Pro's Word import -
+  no multipart dependency), `GET /documents/:id/file` (inline; `?download=1` saves; anyone who may read),
+  `PUT /documents/:id/file {name, data}` (editors; ALWAYS a version - a new upload is a real change; 409 in Trash, 423
+  while another session holds the lock, 403 frozen), `GET /documents/:id/versions/:num/file` (editors, as history is),
+  `GET /documents/:id/view?t=<ticket>` (below). PUT of `content` on a PDF -> 400; title/folder/tags still save and keep
+  `format`. Duplicate copies the file BEFORE the record is written. Restore of a PDF version copies `<n>.pdf` back.
+  `removeDoc` removes the file; the version trim removes `<n>.pdf` with `<n>.json`. Send "inline" attaches the PDF.
+- **The file goes out** (`sendPdf`) with `application/pdf`, `Content-Disposition` from the TITLE (never the uploaded
+  name), `X-Content-Type-Options: nosniff`, `Cache-Control: private, no-store`, `Content-Security-Policy: default-src
+  'none'; sandbox`, `X-Robots-Tag: noindex`. The public page frames `/docs/s/<token>?file=1` and offers `?download=pdf`;
+  `?download=md|html|txt` on a PDF answers the PDF (nothing else is derived from it). `public-doc.html` takes its action
+  links as `{{actions}}` now.
+- **View tickets - why the admin frame is not a blob**. The admin's CSP has `frame-src 'self' …`: a `blob:` frame is
+  REFUSED (the first build failed exactly there). An `<iframe>` carries no bearer header either. So `full()` answers
+  `fileTicket` for a PDF - HMAC-SHA256 of `{d: docId, u: userId, a: admin, e: expiry}` under a key made at boot
+  (`viewKey`), 20 minutes - and the frame's address is `/view?t=…` (no `authenticate`; the ticket names the person
+  and the route checks `accessOf` for them again). The editor polls every 30 s, so `current.fileTicket` is always
+  fresh; a restart ends every ticket and the next poll hands out new ones.
+- **No `sandbox` ATTRIBUTE on the frame**: Chrome's PDF viewer will not open in a sandboxed iframe (`chrome-error://`
+  instead - measured). The CSP `sandbox` header on the response is fine (the viewer loads, measured too).
+- **Registry `kinds`** (`register(owner, {kinds: ['html', 'pdf']})`, default `['html']`): an add-on written before PDF
+  documents sees none of them - `emit()` skips it for a PDF (first arg with `format`), `adminModules()` carries `kinds`,
+  Home tags each add-on's `addDocMenu`/`addShareSection` function with the installing add-on's kinds (`forKind`) and the
+  editor installs only add-ons declaring `'pdf'` in a PDF's screen. `registry.handles(ext, doc)`. SERVICES ARE NOT
+  FILTERED: Docs Pro < 0.10 that lists documents itself (Spaces' folder publish, cloud "every save" runs through
+  `on.saved` - skipped; but `listDocs` in a Space) sees the text extract as the body. Docs Pro 0.10 branches on `kindOf`.
+  Services added: `kindOf`, `readFile(docId)`, `writeFile(docId, buf, user, {name})` (= PUT .../file), `pdfCapability()`.
+- **Admin**: Home routes `.pdf` files (`isPdfFile`) to `uploadPdf` (`readBase64`), cards say `PDF · n pages · size`
+  (`pdfFacts`) with a PDF chip, Download offers the PDF only (`pdfExportItems`). The editor for a PDF: the DocEditor
+  runs on a DETACHED element (its save/lock/outline paths stay inert) and `mountPdfViewer` has the real `.docs-page`;
+  `mayEdit()` is false (mode `view`, no lock, no drafts), the title is renamed from the menu (saved on its own),
+  `pdfMenu()` replaces `moreMenu()` (Rename, copy, move, Download PDF, Replace the PDF…, Send to > Email, history,
+  add-ons, Trash). `showContent()` for a PDF reloads the viewer when `file.sha256`/`uploadedAt` changed
+  (`fresh._before` carries the record as it was). Version history rows/preview show facts + Download this version.
+  `.docs-ed.is-pdf` hides the toolbar, outline, Outline and Find buttons (CSS).
+- Tests: `tests/pdf.test.js` (lib), four `2.13:` tests in `tests/plugin.test.js`; `tests/_pdf.js` makes real PDFs
+  (xref correct, optional FlateDecode, extra objects for the refusals). Browser-checked headlessly: upload -> editor ->
+  viewer loads (Chrome's PDF viewer frame present) -> replace -> history -> Home card -> public page.
+
+## 2.13.1 (2026-10-20): `services.createPdfDoc`
+
+`createPdfDoc({title, buf, name, folderId}, user)` - a PDF document from bytes, as the upload route makes one (checked
+by `inspectPdf`, text read, filed where the person may file, into their Recent). Throws `{status, message}`. Docs Pro
+0.11's "take pages out" is the caller.
+
+## 2.13.2 (2026-10-20): review fixes
+
+- **The name scan inflates every stream** (`lib/pdf.js searchableText`): no dictionary is parsed to decide - the first build
+  read the innermost `<<` before `stream`, so any stream whose dictionary held a nested one (every object stream with
+  /DecodeParms) was never inflated and a /JavaScript or /EmbeddedFile inside it passed. Each body that starts with a zlib
+  header is inflated, again while the output still looks deflated (double /FlateDecode, 3 deep), and a stream past the cap
+  (32 MB a stream, 160 MB in all) makes the file UNCHECKABLE and refused ("too large to check"), not skipped.
+- **Restoring the oldest PDF version at the history cap** read its file after the restore's own snapshot had trimmed it:
+  the version's bytes are read BEFORE the snapshot now, and written with `writeFileBytes`.
+- `POST /documents` passes only title/content/folderId/tags to `newDoc` - a record saying `format: 'pdf'` with no file
+  behind it can no longer be made there.
+- `GET /documents/:id/view` re-checks that the ticket's person still exists, is active and holds a role with `docs.read`
+  (or level 0) - a ticket no longer outlives the permission for its 20 minutes.
+
+## 2.14.0 (2026-10-21): free
+
+`tier: free`, no `closedSource` - no licence is needed or checked any more (the engine only checks a
+`closedSource` plugin). Included in every hosted plan and free to self-host; not `bundle: false`, so the next
+`make sync-free-tier` ships it in the engine. Docs Pro and Wiki Pro stay paid and still `requires: ["docs"]`.