@richscripts/richtexteditor 2.4.0 → 2.4.2

package/richtexteditor/CHANGELOG.md

@@ -1,6 +1,331 @@
 # RichTextEditor Changelog
 
-## Version 2.3.0 — Block types, equation editor, bookmark cards, spell check, drag-handles, smart chips, email export (Pass 64)
+## Version 2.4.0 — Long-document authoring, real document export, security and accessibility (Pass 65)
+
+Twenty-nine plugins, no `rte.js` core changes. The theme of the release is
+closing the gaps that competitors gate behind paid tiers, and fixing three
+things about our own product that were not true.
+
+### Security (three real holes, found by testing rather than by review)
+- **`plugins/sanitizer.js`** — allowlist content filter on input, output **and
+  the live DOM**. Unknown elements are unwrapped rather than deleted, so a
+  user's words are never silently lost. Parses with `DOMParser` (never
+  `innerHTML` on a live node, which fires `<img onerror>` before the filter
+  runs) and re-parses until stable to defeat mutation XSS.
+  - **Stored XSS:** `<iframe srcdoc="<script>…">` survived the core filter into
+    saved HTML and executed when that HTML was rendered downstream. "Nothing
+    executes in the editor" was the wrong bar.
+  - **Transient XSS:** the first version cleaned up *after* the paste — measured
+    execution at +70 ms. Paste is now intercepted in the capture phase and only
+    when the clipboard HTML actually executes on insertion, so ordinary Word
+    pastes still reach the editor's own Word cleanup untouched.
+  - **Collaborator XSS:** a CRDT applies remote edits by writing nodes straight
+    into the live document, bypassing both paste and `setHTMLCode`. Any
+    participant could run script in every other participant's browser, and the
+    payload replicated onward. Closed by a live-DOM guard
+    (`sanitizerGuardLiveDom`, on by default) that only engages when an inserted
+    node or attribute is executable, so typing costs nothing.
+- **`plugins/restrictedediting.js`** — Word-style protected documents: content
+  is read-only except regions tagged `data-rte-editable="true"`.
+
+### Accessibility
+- **`plugins/keyboarda11y.js`** — an audit of the running editor found four open
+  issues, three of them WCAG Level A: a **keyboard trap** (focus could enter the
+  editing area and never leave), `aria-pressed` missing on every toggle button,
+  `aria-expanded` missing on every menu button, and 53 toolbar tab stops.
+  `Escape` now leaves the editing area (Tab keeps its editing meaning), toggle
+  state is mirrored from the existing active class so announced state cannot
+  disagree with the highlight, and each toolbar has a single roving tab stop.
+- **`plugins/accessibilitychecker.js`** — flags and one-click repairs missing
+  alt text, missing table headers, empty or non-descriptive links, and skipped
+  heading levels. Header repair emits `<th scope="col">`, which is what the
+  tagged PDF and .docx exports then consume.
+
+### Document export and import
+- **`plugins/pdfexport.js`** — PDF written by hand, with **selectable text** and
+  a full accessibility tag tree (H1–H6, P, L/LI, Table/TH/TD, Figure; decoration
+  emitted as artifacts), so the output passes a Section 508 / EN 301 549 review
+  rather than only a copy-paste test. The raster html2pdf path is kept for cases
+  where pixel fidelity matters more.
+- **`plugins/docxexport.js`** — a genuine OOXML package built in the browser via
+  `CompressionStream`: no library, no server, no upload. Emits exactly what
+  `documentimport.js` reads, so HTML → .docx → HTML round-trips.
+- **`plugins/documentimport.js`** — .docx import completeness: text boxes,
+  endnotes as well as footnotes, equations (OMML ↔ LaTeX), SmartArt diagrams and
+  WMF placeholders. Nothing is dropped silently; what HTML cannot represent
+  degrades visibly.
+- **`plugins/wordexport.js`** — Word-compatible HTML export (library-free).
+
+### Long-document authoring
+- **`plugins/pagination.js`** — print-layout page view. CKEditor and Tiptap both
+  sell this as a paid add-on.
+- **`plugins/multilevellist.js`** — legal numbering (1, 1.1, 1.1.1) via CSS
+  counters.
+- **`plugins/footnotes.js`** — inline markers with an auto-renumbering notes
+  section.
+- **`plugins/crossreference.js`** — references that keep pointing at the right
+  target after the document is edited around them.
+- **`plugins/tableofcontents.js`** — self-updating contents block from the
+  document's headings. Premium in both majors.
+- **`plugins/linenumbers.js`** — margin line numbers for pleadings, statutes and
+  transcripts.
+- **`plugins/documentoutline.js`**, **`plugins/contentminimap.js`** — navigation
+  for long documents.
+- **`plugins/watermark.js`** — DRAFT / CONFIDENTIAL marking behind the content.
+
+### Editing and productivity
+- **`plugins/formatpainter.js`** — the clipboard-brush interaction, premium in
+  both majors.
+- **`plugins/changecase.js`** — UPPERCASE / lowercase / Title / Sentence /
+  tOGGLE. CKEditor gates this behind a plan.
+- **`plugins/autocorrect.js`** — typo fixes, sentence capitalisation, smart
+  quotes and dashes as you type.
+- **`plugins/permanentpen.js`** — a fixed format applied to everything typed
+  until switched off.
+- **`plugins/draghandle.js`** — grab a block by its grip and drop it elsewhere.
+- **`plugins/tabletools.js`** — column sorting and row numbering; TinyMCE sells
+  both as premium "Enhanced Tables".
+- **`plugins/mergefields.js`** — placeholders that turn a document into a
+  template for mail merge and invoice runs.
+- **`plugins/linkchecker.js`** — finds broken, unsafe, misleading, or
+  assistive-technology-unreachable links, with a host-supplied resolver so no
+  vendor infrastructure is required. TinyMCE's equivalent is premium *and*
+  requires their service.
+- **`plugins/formattingmarks.js`** — Word's ¶ button, including the invisible
+  non-breaking and zero-width characters that cause mysterious layout bugs.
+- **`plugins/charlimit.js`** — enforces a maximum (the built-in statistics
+  readout only displays counts).
+- **`plugins/readabilitystats.js`** — local Flesch / Flesch-Kincaid readout, no
+  API call.
+
+### Right-to-left
+- **`plugins/textdirection.js`** — direction commands, toolbar items and
+  language strings for Arabic, Hebrew, Persian and Urdu, which the editor
+  previously had no way to express at all.
+- **`plugins/rtlui.js`** — flips the editor chrome (toolbar, dropdowns, menus,
+  dialogs) so an RTL user is not typing right-to-left inside a left-to-right
+  frame.
+
+### Build
+- `build-bundle.ps1` now searches several locations for esbuild and fails hard
+  when it finds none. It previously looked at one hardcoded path and, when that
+  path was pruned, silently skipped minification while still exiting 0 — so a
+  stale `all_plugins.min.js` was mirrored to every tier for several builds.
+
+## Version 2.3.0 — Block types, equation editor, bookmark cards, spell check, drag-handles, smart chips, email export, inline Markdown, Mermaid diagrams, read-aloud, emoji autocomplete, task lists, auto-embed, foldable headings, typewriter & focus modes, Markdown export, local-draft recovery, AI ghost-text autocomplete (Pass 64)
+
+**New plugin: `plugins/ghostcomplete.js` — AI ghost-text autocomplete**
+- GitHub-Copilot / Notion-AI-style inline completion: after a typing pause a
+  greyed suggestion appears after the caret continuing your sentence; **Tab**
+  accepts it, **Esc** (or simply continuing to type) dismisses it. Ambient and
+  hands-free — distinct from the command-driven AI Toolkit.
+- **Bring-your-own-key**: supply `config.ghostTextResolver({before, after, full})`
+  returning a string (or Promise). No model ships and no network call is made
+  without it; the feature is inert until both `config.ghostText` and a resolver
+  are set. Tunables: `delayMs` (default 600), `minChars` (3), `maxContext` (2000).
+- **Serialization-safe**: the suggestion is a `contenteditable="false"`
+  `<span class="rte-ghost">` decoration that is never part of the saved content —
+  the caret is kept *before* it so typing/saving behave normally, and
+  `getHTMLCode` / `getJSON` are wrapped to strip any ghost span. Accept goes
+  through `execCommand("insertText")` so one Ctrl+Z reverts it. Stale-request
+  tokens prevent races while typing. API: `editor.requestGhostText()` /
+  `acceptGhostText()` / `dismissGhostText()` / `hasGhostText()` /
+  `setGhostTextResolver(fn)`; slash `/ai complete`. No core `rte.js` changes.
+  Verified live (ghost shows, Tab + API accept inserts undoable text with clean
+  serialize, Esc / typing / mousedown / API dismiss, ghost never leaks into saved
+  HTML).
+
+**New plugin: `plugins/localdraft.js` — local draft autosave & crash recovery**
+- Complements the server-oriented core `config.autoSave` with offline resilience:
+  persists the document to `localStorage` as you type (debounced) and, on the
+  next load, offers to restore the unsaved draft via an unobtrusive bar
+  ("An unsaved draft from 3 min ago was found — Restore / Discard"). Gmail /
+  Notion style "never lose your work".
+- Opt-in via `config.localDraft = true` or an options object (`key`,
+  `intervalMs`, `ttlMs`, `promptRestore`). Safe by design: the draft is **never
+  auto-applied** (the server content shows until the user clicks Restore),
+  empty/unchanged docs aren't persisted, and stale drafts past the TTL (default
+  14 days) are pruned. Also saves on `beforeunload`/`pagehide`. API:
+  `editor.saveLocalDraft()` / `hasLocalDraft()` / `getLocalDraft()` /
+  `restoreLocalDraft()` / `clearLocalDraft()` (call `clear` after a real save).
+  Verified live (autosave→reload→restore-bar→Restore round-trip) + 11 logic
+  assertions (TTL prune, blank/baseline skip, restore, clear).
+
+**New plugin: `plugins/markdownexport.js` — Copy / Download as Markdown**
+- Surfaces the core HTML→Markdown engine (`editor.toMarkdown()`) as a
+  discoverable export, the way Notion "Copy as Markdown" / Obsidian do. Slash
+  commands `/copy as markdown` and `/download as markdown`, plus the API
+  `editor.getMarkdown()`, `editor.copyAsMarkdown()` (clipboard, with an
+  execCommand fallback for older browsers) and `editor.downloadMarkdown(name?)`
+  (saves a `.md` Blob; the filename is derived from the first heading when not
+  given). Read-only — nothing in the document changes. Toggle with
+  `config.markdownExportEnabled`. Verified live (Markdown output for headings /
+  bold / italic / lists, clipboard receives the correct text, download filename
+  derivation + custom name keep the `.md` extension).
+
+**New plugin: `plugins/dialoga11y.js` — dialog accessibility**
+- The editor's dialog popups (`<rte-dropdown-panel>` with an `<rte-dialog-header>`)
+  shipped without `role`/`aria-label`, and their fields without programmatic
+  labels — so a screen reader announced an unnamed "menu" with unlabeled inputs
+  (WCAG 4.1.2 / 1.3.1 / 3.3.2). This plugin adds the missing metadata, deriving
+  every name from the editor's OWN markup (never guessing): the dialog name is the
+  header text ("Insert Link", "Insert Table"), the role is corrected from `menu`
+  to `dialog` on titled form popups, and each field is labelled from its
+  `<rte-dialog-line-URL/-TEXT/-TARGET>` wrapper. Natively-labelled fields are left
+  untouched, and plain dropdowns (color/font pickers, no header) are deliberately
+  skipped so they aren't mislabelled. No core changes; opt out with
+  `config.dialogA11y = false`. Verified live on the link/table dialogs (role,
+  name, and field labels all correct; native `<label>`s preserved).
+
+**New plugin: `plugins/a11yenhance.js` — accessibility metadata**
+- Closes the most common WCAG 2.2 findings for an iframe-based editor by emitting
+  the assistive-technology metadata the editing surface needs: the editor iframe
+  gets a `title` (WCAG 2.4.1 / 4.1.2), the editing region gets `role="textbox"` +
+  `aria-multiline="true"` + an `aria-label` (4.1.2), and the editing document gets
+  a `lang` attribute (3.1.1 / 3.1.2). Re-applied on every document remount so the
+  metadata survives `setHTMLCode`. Configurable via `config.contentAriaLabel`,
+  `config.contentLang` (defaults to the host page `<html lang>` or `en`), and
+  `config.a11yEnhance = false` to opt out; API `editor.applyAccessibilityMetadata()`.
+  Verified live (iframe title, role, aria-multiline, aria-label, document lang all
+  present and surviving remount).
+
+**New plugin: `plugins/typewriter.js` — typewriter scrolling + focus mode**
+- Two distraction-free writing modes, both purely presentational (no content or
+  DOM mutation — nothing to serialize):
+  - **Typewriter mode** keeps the caret line pinned to a fixed vertical anchor
+    (default: the middle of the viewport) by scrolling the editable as you type,
+    the way iA Writer / Typora / Ulysses do — the text rises to meet a steady
+    caret instead of the caret marching down the page. Anchor is configurable
+    via `config.typewriterAnchor` (0.15–0.85 fraction of viewport height).
+  - **Focus mode** dims every block except the paragraph / heading / list-item
+    the caret is in (Notion / iA Writer "focus" behaviour), so the current
+    sentence stands out.
+- Toggle either independently: slash `/typewriter` + `/focus mode`, or the API
+  `editor.toggleTypewriterMode()` / `editor.toggleFocusMode()` (plus
+  `set…`/`is…` variants). Off by default; opt in with `config.typewriterModeEnabled`
+  / `config.focusModeEnabled`.
+- **Serialization-safe**: focus mode toggles a single class on the editable
+  (`rte-focus-active`) and a transient class on the active block
+  (`rte-focus-current`); typewriter mode only scrolls. `getHTMLCode` / `getJSON`
+  are wrapped to strip the transient class around the call, so saved markup is
+  always clean even if a save fires mid-keystroke. No core `rte.js` changes.
+  Verified live (focus dimming current=1.0 / dimmed=0.28 opacity, typewriter
+  scroll pulls the caret line to the anchor, serialization clean) + 19 logic
+  assertions.
+
+**New plugin: `plugins/foldheadings.js` — collapsible heading sections**
+- Obsidian / Notion / Word-style section folding: hover a heading and click the
+  gutter chevron (or call the API) to collapse every block beneath it, up to the
+  next heading of the same or higher level. Great for navigating long structured
+  documents; pairs with the existing document-outline panel. API:
+  `editor.toggleHeadingFold(h)`, `editor.foldAtCaret()`, `editor.unfoldAll()`;
+  slash `/fold section` and `/unfold all`. Toggle with `config.foldHeadingsEnabled`.
+- **Serialization-safe by design**: the fold state lives ONLY in runtime CSS
+  classes (`rte-fold-collapsed` / `rte-fold-hidden`) and the chevron is a CSS
+  `::before` pseudo-element &mdash; nothing is injected into the content.
+  `getHTMLCode` / `getJSON` / `getHTMLContent` are wrapped to strip those classes
+  around the call, so **saved markup is always clean and folded content is never
+  lost**. Caret safety: folding a section that contains the caret moves the caret
+  to the heading so it is never stuck in hidden content. No core `rte.js` changes.
+  Verified live (14 checks: level-aware folds, serialization clean + content
+  preserved + restored, caret safety, gutter-click vs text-click).
+
+**New plugin: `plugins/autoembed.js` — auto-embed media URLs on paste**
+- Paste a bare YouTube or Vimeo URL on its own line (collapsed caret) and it
+  becomes a responsive 16:9 embed &mdash; the Notion / Medium behaviour.
+  Complements the command-driven Insert Video dialog and the bookmark-card plugin
+  (which makes a link-preview card from any URL). Also exposed programmatically as
+  `editor.embedUrl(url)`.
+- **Injection-safe by construction**: the iframe `src` is NEVER the raw pasted
+  string. The video id is extracted with a strict whitelist regex, constrained to
+  `[A-Za-z0-9_-]` / digits, and a trusted provider embed URL is built from a
+  template (verified against `youtube.com.evil.com`, `javascript:`,
+  `"><script>`, wrong-domain and non-numeric inputs). Mid-paragraph and
+  text-selected pastes are left untouched (they stay links). Extend providers via
+  `config.autoEmbedResolver(url)` (must return an `https://` embed URL); toggle
+  with `config.autoEmbedEnabled` (default true). No core `rte.js` changes.
+- Robust paste hook: the listener attaches to the iframe **document** and
+  re-attaches on `ready` / `aftersethtml` (the editor recreates the editable body
+  after init, which would orphan a body-level listener). Verified live (13 checks
+  + 14 resolver/security unit tests).
+
+**New plugin: `plugins/todolist.js` — interactive to-do / task lists**
+- `editor.execCommand("inserttodolist")` (slash `/to-do`, toolbar) inserts a
+  checklist whose items each carry a clickable checkbox; clicking toggles the item
+  between open and done (a check + strike-through). Notion / GitHub / Google-Docs
+  style. Closes a real gap &mdash; the editor shipped an orphan `inserttodolist`
+  toolbar icon (`svgCode_inserttodolist`) with no command behind it.
+- Checkboxes are styled `contenteditable="false"` spans (not `<input>`s, which
+  misbehave in contenteditable); the done state lives in `data-checked`, so the
+  list round-trips through `getHTMLCode` / `getJSON` and re-binds on load via
+  click delegation (works for pasted/loaded lists). New items created with Enter
+  are auto-normalized to include a checkbox and an open state. CSS injected at
+  insert time. No core `rte.js` changes. Verified live (10 checks: insert,
+  click-toggle both ways, text-click no-op, style injection, Enter-item
+  normalization, round-trip).
+
+**New plugin: `plugins/emojiautocomplete.js` — emoji `:shortcode:` autocomplete**
+- GitHub / Slack / Discord-style inline emoji entry, no picker needed. Two
+  behaviours: (1) typing a complete `:shortcode:` (closing colon) replaces it with
+  the emoji (`:fire:` → 🔥, `:+1:` → 👍, `:tada:` → 🎉); (2) typing `:` + a partial
+  query shows a popup of matches — Arrow keys move, Enter/Tab insert, Esc dismisses.
+- Curated built-in shortcode map (~140 common emoji, what people actually type);
+  extend or replace via `config.emojiShortcodes`. Toggle with
+  `config.emojiAutocompleteEnabled` (default true). Word-boundary gated (a colon
+  mid-identifier like `path:fire:` is ignored), inert inside `<code>`/`<pre>`.
+  Complements the existing emoji picker (insertemoji) with keyboard-only entry.
+  No core `rte.js` changes. Verified live (12 checks: immediate replace, unknown-
+  code passthrough, popup matches, Enter-commit, Arrow-nav, mid-word guard,
+  code-inert).
+
+**New plugin: `plugins/readaloud.js` — read-aloud (text-to-speech)**
+- `editor.execCommand("readaloud")` (slash `/read aloud`, toolbar) opens a small
+  non-modal control bar (play/pause, stop, voice, rate) and reads the current
+  selection — or the whole document if nothing is selected — aloud, sentence by
+  sentence, **highlighting each sentence as it is spoken** (via the native
+  selection, so document content is never modified). The speech-OUT complement
+  to the dictation plugin's speech-IN, and an accessibility win alongside the
+  accessibility checker.
+- Browser-native via the Web Speech API (`window.speechSynthesis`) — **no library
+  bundled, no backend, no API key**. Reads cross-paragraph content correctly
+  (offset→DOM-range mapping). Public API: `editor.readAloud({ rate, voice })` /
+  `editor.stopReadAloud()`. `config.readAloudRate` (default 1.0) and
+  `config.readAloudHighlight` (default true). Gracefully detects browsers without
+  a synthesizer. Stops on page-hide; pauses on tab-hide. No core `rte.js` changes.
+  Verified live (8 checks: sentence split, cross-node highlight, selection-only
+  read, control bar, auto-start, toggle-close, stop-restores-caret, API surface).
+
+**New plugin: `plugins/mermaiddiagram.js` — Mermaid diagrams (diagrams-as-code)**
+- `editor.execCommand("insertdiagram")` (slash `/diagram`, toolbar) opens a dialog
+  to author Mermaid text (flowchart, sequence, gantt, pie, class, state…) with a
+  live preview, and renders it to SVG. Closes the diagrams-as-code gap vs GitHub /
+  GitLab / Notion / Obsidian. Double-click a block to edit it in place.
+- No renderer is bundled (Mermaid is ~2 MB). Three tiers, mirroring the equation
+  editor's "host supplies KaTeX/MathJax" model: (1) `config.diagramResolver(source)`
+  → `Promise<{svg}|{imageUrl}>` for server-side render (e.g. Kroki); (2) a
+  `window.mermaid` instance loaded by the host page; (3) neither — the source is
+  stored and shown as a `<pre>` fallback, re-renderable later via
+  `editor.renderDiagrams()`. The Mermaid source always round-trips in
+  `data-diagram`, so blocks stay editable regardless of how they were rendered.
+- Mermaid source is HTML-escaped into the attribute and the fallback `<pre>`;
+  blocks are `contenteditable="false"`. CSS injected at insert time. No core
+  `rte.js` changes. Verified live (14 checks: render via host renderer, BYOK
+  resolver, no-renderer fallback, injection-safety, `renderDiagrams()`, round-trip).
+
+**Inline Markdown autoformat (core)**
+- Typing the closing delimiter of an inline Markdown span now converts it in
+  place: `**bold**` / `__bold__` → `<strong>`, `*italic*` / `_italic_` → `<em>`,
+  `` `code` `` → `<code>`, `~~strike~~` → `<s>`. Completes the Markdown story —
+  the editor already had block shortcuts (`# `, `> `, `- `, `1. `, `---`); this
+  adds the inline half that Notion / Slack / GitHub / Typora users expect.
+- The opening delimiter must sit at a **word boundary**, so `2*3*` (math),
+  `*.txt*` is reduced, `snake_case_` and intraword `a*b*` are left untouched.
+  Inert inside `<code>` / `<pre>` / links. Output uses the editor's own semantic
+  tags (`<strong>`/`<em>`), so it round-trips with the existing Markdown
+  import/export. Undoable with Ctrl+Z. Toggle with `config.markdownInlineEnabled`
+  (default `true`). No new toolbar/command surface — pure typing UX. Verified
+  live (14 checks: 8 conversions, 4 false-positive guards, code-inert, end-to-end
+  typing).
 
 **New plugin: `plugins/emailtoolkit.js` — email inline-style export**
 - `editor.getEmailHTML(options?)` returns email-client-safe HTML: a curated set