ep_hljs 0.1.1

package/.eslintrc.cjs

@@ -0,0 +1,10 @@
+'use strict';
+
+// This is a workaround for https://github.com/eslint/eslint/issues/3458
+require('eslint-config-etherpad/patch/modern-module-resolution');
+
+module.exports = {
+  root: true,
+  extends: 'etherpad/plugin',
+  ignorePatterns: ['node_modules', 'static/css/themes', 'static/js/vendor', 'static/tests/frontend-new'],
+};

package/.github/workflows/automerge.yml

@@ -0,0 +1,45 @@
+name: Dependabot Automerge
+permissions:
+  contents: write
+  pull-requests: write
+  # `actions: write` lets the post-merge step kick off Node.js Package on
+  # the default branch via `gh workflow run`. Without this, automerge'd
+  # PRs land on main but the on-push release job never fires (GitHub
+  # Actions intentionally suppresses on:push triggers when the push is
+  # authenticated with GITHUB_TOKEN).
+  actions: write
+on:
+  workflow_run:
+    workflows:
+      - Node.js Package
+    types:
+      - completed
+
+jobs:
+  automerge:
+    if: >
+      github.event.workflow_run.conclusion == 'success' &&
+      github.event.workflow_run.event == 'push' &&
+      github.event.workflow_run.actor.login == 'dependabot[bot]'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Automerge
+        id: automerge
+        uses: "pascalgn/automerge-action@v0.16.4"
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          MERGE_METHOD: squash
+          MERGE_LABELS: ""
+          MERGE_RETRY_SLEEP: "100000"
+
+      - name: Trigger release on default branch
+        # `pascalgn/automerge-action` exits 0 whether or not it merged. Skip
+        # the dispatch when nothing was actually merged so we don't kick a
+        # phantom release run on every Dependabot Automerge invocation.
+        if: steps.automerge.outputs.mergeResult == 'merged'
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: gh workflow run test-and-release.yml --ref ${{ github.event.repository.default_branch }}

package/.github/workflows/backend-tests.yml

@@ -0,0 +1,75 @@
+name: Backend Tests
+
+# any branch is useful for testing before a PR is submitted
+on:
+  workflow_call:
+
+jobs:
+  withplugins:
+    # run on pushes to any branch
+    # run on PRs from external forks
+    if: |
+      (github.event_name != 'pull_request')
+      || (github.event.pull_request.head.repo.id != github.event.pull_request.base.repo.id)
+    name: with Plugins
+    runs-on: ubuntu-latest
+    steps:
+      -
+        name: Install libreoffice
+        uses: awalsh128/cache-apt-pkgs-action@v1.6.0
+        with:
+          packages: libreoffice libreoffice-pdfimport
+          version: 1.0
+      -
+        name: Install etherpad core
+        uses: actions/checkout@v6
+        with:
+          repository: ether/etherpad-lite
+          path: etherpad-lite
+      - uses: actions/setup-node@v6
+        name: Install Node.js
+        with:
+          node-version: 22
+      - uses: pnpm/action-setup@v6
+        name: Install pnpm
+        with:
+          version: 10
+          run_install: false
+      - name: Get pnpm store directory
+        shell: bash
+        run: |
+          echo "STORE_PATH=$(pnpm store path --silent)" >> $GITHUB_ENV
+      - uses: actions/cache@v5
+        name: Setup pnpm cache
+        with:
+          path: ${{ env.STORE_PATH }}
+          key: ${{ runner.os }}-pnpm-store-${{ hashFiles('**/pnpm-lock.yaml') }}
+          restore-keys: |
+            ${{ runner.os }}-pnpm-store-
+      -
+        name: Checkout plugin repository
+        uses: actions/checkout@v6
+        with:
+          path: plugin
+      - name: Remove tests
+        working-directory: ./etherpad-lite
+        run: rm -rf ./src/tests/backend/specs
+      -
+        name: Install Etherpad core dependencies
+        working-directory: ./etherpad-lite
+        run: bin/installDeps.sh
+      - name: Install plugin
+        working-directory: ./etherpad-lite
+        run: |
+          pnpm run plugins i --path  ../../plugin
+      -
+        name: Run the backend tests
+        working-directory: ./etherpad-lite/src
+        run: |
+          shopt -s globstar
+          res=$(find ./plugin_packages -path "*/static/tests/backend/specs/*" 2>/dev/null | wc -l)
+          if [ $res -eq 0 ]; then
+          echo "No backend tests found"
+          else
+          npx cross-env NODE_ENV=production mocha --import=tsx --timeout 120000 --recursive node_modules/ep_*/static/tests/backend/specs/**
+          fi

package/.github/workflows/codeql.yml

@@ -0,0 +1,41 @@
+name: "CodeQL"
+
+on:
+  push:
+    branches: [ "main" ]
+  pull_request:
+    branches: [ "main" ]
+  schedule:
+    - cron: "26 5 * * 2"
+
+jobs:
+  analyze:
+    name: Analyze
+    runs-on: ubuntu-latest
+    permissions:
+      actions: read
+      contents: read
+      security-events: write
+
+    strategy:
+      fail-fast: false
+      matrix:
+        language: [ javascript ]
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Initialize CodeQL
+        uses: github/codeql-action/init@v4
+        with:
+          languages: ${{ matrix.language }}
+          queries: +security-and-quality
+
+      - name: Autobuild
+        uses: github/codeql-action/autobuild@v4
+
+      - name: Perform CodeQL Analysis
+        uses: github/codeql-action/analyze@v4
+        with:
+          category: "/language:${{ matrix.language }}"

package/.github/workflows/frontend-tests.yml

@@ -0,0 +1,72 @@
+# Publicly credit Sauce Labs because they generously support open source
+# projects.
+name: Frontend Tests
+
+on:
+  workflow_call:
+
+jobs:
+  test-frontend:
+    runs-on: ubuntu-latest
+
+    steps:
+      -
+        name: Check out Etherpad core
+        uses: actions/checkout@v6
+        with:
+          repository: ether/etherpad-lite
+          path: etherpad-lite
+      - uses: actions/setup-node@v6
+        name: Install Node.js
+        with:
+          node-version: 22
+      - uses: pnpm/action-setup@v6
+        name: Install pnpm
+        with:
+          version: 10
+          run_install: false
+      - name: Get pnpm store directory
+        shell: bash
+        run: |
+          echo "STORE_PATH=$(pnpm store path --silent)" >> $GITHUB_ENV
+      - uses: actions/cache@v5
+        name: Setup pnpm cache
+        with:
+          path: ${{ env.STORE_PATH }}
+          key: ${{ runner.os }}-pnpm-store-${{ hashFiles('**/pnpm-lock.yaml') }}
+          restore-keys: |
+            ${{ runner.os }}-pnpm-store-
+      -
+        name: Checkout plugin repository
+        uses: actions/checkout@v6
+        with:
+          path: plugin
+      -
+        name: Install Etherpad core dependencies
+        working-directory: ./etherpad-lite
+        run: bin/installDeps.sh
+      - name: Install plugin
+        working-directory: ./etherpad-lite
+        run: |
+          pnpm run plugins i --path ../../plugin
+      - name: Create settings.json
+        working-directory: ./etherpad-lite
+        run: cp ./src/tests/settings.json settings.json
+      - name: Run the frontend tests
+        working-directory: ./etherpad-lite
+        shell: bash
+        run: |
+          pnpm run dev &
+          connected=false
+          can_connect() {
+            curl -sSfo /dev/null http://localhost:9001/ || return 1
+            connected=true
+          }
+          now() { date +%s; }
+          start=$(now)
+          while [ $(($(now) - $start)) -le 30 ] && ! can_connect; do
+            sleep 1
+          done
+          cd src
+          pnpm exec playwright install chromium --with-deps
+          pnpm run test-ui --project=chromium

package/.github/workflows/npmpublish.yml

@@ -0,0 +1,124 @@
+# This workflow will run tests using node and then publish a package to the npm registry when a release is created
+# For more information see: https://help.github.com/actions/language-and-framework-guides/publishing-nodejs-packages
+#
+# Publishing uses npm Trusted Publishing (OIDC) — no NPM_TOKEN secret is
+# required. Each package must have a trusted publisher configured on npmjs.com
+# pointing at this workflow file. See:
+# https://docs.npmjs.com/trusted-publishers
+
+name: Node.js Package
+
+on:
+  workflow_call:
+
+jobs:
+  publish-npm:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write   # for the atomic version-bump push (branch + tag)
+      id-token: write   # for npm OIDC trusted publishing
+    steps:
+      - uses: actions/setup-node@v6
+        with:
+          # OIDC trusted publishing needs npm >= 11.5.1, which requires
+          # Node >= 20.17.0. setup-node's `20` resolves to the latest
+          # 20.x, which satisfies that.
+          node-version: 20
+          registry-url: https://registry.npmjs.org/
+      - name: Upgrade npm to >=11.5.1 (required for trusted publishing)
+        run: npm install -g npm@latest
+      - name: Check out Etherpad core
+        uses: actions/checkout@v6
+        with:
+          repository: ether/etherpad-lite
+      - uses: pnpm/action-setup@v6
+        name: Install pnpm
+        with:
+          # No `version:` here — defer to packageManager in package.json so
+          # we don't clash with etherpad-lite's pnpm version pin (the
+          # checkout above puts its package.json at cwd). See
+          # pnpm/action-setup#225.
+          run_install: false
+      - name: Get pnpm store directory
+        shell: bash
+        run: |
+          echo "STORE_PATH=$(pnpm store path --silent)" >> $GITHUB_ENV
+      - uses: actions/cache@v5
+        name: Setup pnpm cache
+        with:
+          path: ${{ env.STORE_PATH }}
+          key: ${{ runner.os }}-pnpm-store-${{ hashFiles('**/pnpm-lock.yaml') }}
+          restore-keys: |
+            ${{ runner.os }}-pnpm-store-
+      -
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+      -
+        name: Bump version (patch)
+        id: bump
+        run: |
+          LATEST_TAG=$(git describe --tags --abbrev=0) || exit 1
+          NEW_COMMITS=$(git rev-list --count "${LATEST_TAG}"..) || exit 1
+          # No new commits since the last tag → nothing to publish.
+          # Setting `bumped=false` lets the publish step below skip
+          # itself instead of trying to republish the existing version
+          # (which fails with "cannot publish over previously published
+          # versions"). Only manual `gh workflow run` invocations on a
+          # tag-current branch hit this path; on:push always sees ≥1
+          # new commit because the push event is what triggered us.
+          if [ "${NEW_COMMITS}" -le 0 ]; then
+            echo "bumped=false" >> "${GITHUB_OUTPUT}"
+            exit 0
+          fi
+          git config user.name 'github-actions[bot]'
+          git config user.email '41898282+github-actions[bot]@users.noreply.github.com'
+          pnpm i --frozen-lockfile
+          # `pnpm version patch` bumps package.json, makes a commit, and creates
+          # a `v<new-version>` tag. Capture the new tag name from package.json
+          # rather than parsing pnpm's output, which has historically varied.
+          # Bump the patch component directly with Node. pnpm/action-setup@v6
+          # sometimes installs pnpm 11 pre-releases even when version: 10.x is
+          # requested (pnpm/action-setup#225); those pre-releases either skip
+          # the git commit/tag or reject --no-git-tag-version as unknown.
+          # Doing the bump in Node sidesteps both failure modes.
+          NEW_VERSION=$(node -e "const fs=require('fs');const p=require('./package.json');const v=p.version.split('.');v[2]=String(Number(v[2])+1);p.version=v.join('.');fs.writeFileSync('./package.json',JSON.stringify(p,null,2)+'\n');console.log(p.version);")
+          NEW_TAG="v${NEW_VERSION}"
+          git add package.json
+          git commit -m "${NEW_TAG}"
+          git tag -a "${NEW_TAG}" -m "${NEW_TAG}"
+          # CRITICAL: use --atomic so the branch update and the tag update
+          # succeed (or fail) as a single transaction on the server. The old
+          # `git push --follow-tags` was non-atomic per ref: if a concurrent
+          # publish run won the race, the branch fast-forward would be rejected
+          # but the tag push would still land — leaving a dangling tag with no
+          # matching commit on the branch. Subsequent runs would then forever
+          # try to bump to the same already-existing tag and fail with
+          # `tag 'vN+1' already exists`. With --atomic, a rejected branch push
+          # rejects the tag push too, and the next workflow tick can retry
+          # cleanly against the up-to-date refs.
+          git push --atomic origin "${GITHUB_REF_NAME}" "${NEW_TAG}"
+          echo "bumped=true" >> "${GITHUB_OUTPUT}"
+      # This is required if the package has a prepare script that uses something
+      # in dependencies or devDependencies.
+      -
+        if: steps.bump.outputs.bumped == 'true'
+        run: pnpm i
+      # `npm publish` must come after `git push` otherwise there is a race
+      # condition: If two PRs are merged back-to-back then master/main will be
+      # updated with the commits from the second PR before the first PR's
+      # workflow has a chance to push the commit generated by `npm version
+      # patch`. This causes the first PR's `git push` step to fail after the
+      # package has already been published, which in turn will cause all future
+      # workflow runs to fail because they will all attempt to use the same
+      # already-used version number. By running `npm publish` after `git push`,
+      # back-to-back merges will cause the first merge's workflow to fail but
+      # the second's will succeed.
+      #
+      # Use `npm publish` directly (not `pnpm publish`) because OIDC trusted
+      # publishing requires npm CLI >= 11.5.1 and `pnpm publish` shells out to
+      # whichever `npm` is on PATH; calling `npm` directly avoids any shim
+      # ambiguity.
+      - name: Publish to npm via OIDC
+        if: steps.bump.outputs.bumped == 'true'
+        run: npm publish --provenance --access public

package/.github/workflows/test-and-release.yml

@@ -0,0 +1,32 @@
+name: Node.js Package
+on:
+  push:
+  # Invoked by automerge.yml after a Dependabot PR is merged. GitHub
+  # Actions doesn't fire on:push when the push is authored by GITHUB_TOKEN
+  # (the automerge action's only available identity), so without this
+  # dispatch trigger the release job never runs after auto-merges.
+  workflow_dispatch:
+
+# id-token: write must be granted here so the reusable npmpublish workflow
+# can request an OIDC token for npm trusted publishing.
+permissions:
+  contents: write
+  id-token: write
+
+jobs:
+  backend:
+    uses: ./.github/workflows/backend-tests.yml
+    secrets: inherit
+  frontend:
+    uses: ./.github/workflows/frontend-tests.yml
+    secrets: inherit
+  release:
+    if: ${{ github.ref == 'refs/heads/master' || github.ref == 'refs/heads/main' }}
+    needs:
+      - backend
+      - frontend
+    permissions:
+      contents: write   # for the version bump push
+      id-token: write   # for npm OIDC trusted publishing
+    uses: ./.github/workflows/npmpublish.yml
+    secrets: inherit

package/CLAUDE.md

@@ -0,0 +1,141 @@
+# Claude Code Guidelines for `ep_hljs`
+
+Whole-pad syntax highlighting for Etherpad, powered by highlight.js, painted via the **CSS Custom Highlights API**. This file is the architectural reference for anyone (Claude or human) extending the plugin.
+
+## Architecture in one paragraph
+
+Tokens are computed at render time and painted by the browser via `CSS.highlights` Range registration — **the DOM Etherpad's Ace owns is never mutated**. On every line render (`acePostWriteDomLineHTML`) and every text mutation (`MutationObserver`), the renderer reads `node.textContent`, runs `hljs.highlight(text, {language})` (cached in an LRU keyed by `language:text`), turns the resulting `<span>`-soup into `{start, end, cls}` token ranges, then builds DOM `Range` objects pointing into the line's existing text nodes and adds them to `CSS.highlights.get('hljs-keyword')` etc. The browser composites the paint via `::highlight(hljs-…)` rules in `editor.css`. No `splitText`, no injected `<span>`s, no Easysync attribute broadcast.
+
+## Files
+
+| Path | Role |
+|---|---|
+| `static/js/syntaxRenderer.js` | Orchestrator: state, LRU cache, auto-detect timer, `acePostWriteDomLineHTML` hook, MutationObserver, repaintAllLines |
+| `static/js/highlightRegistry.js` | Wraps `CSS.highlights`. `setLineRanges(lineEl, [{start,end,cls}])` / `removeLineRanges(lineEl)` / `clearAll()` |
+| `static/js/hljsAdapter.js` | `tokenize(text, lang) -> ranges \| null`, `detect(text) -> language \| null`, `parseHljsHtml(html) -> ranges` |
+| `static/js/codeIndent.js` | `aceKeyEvent` handler: Enter inherits/extends indent, Tab/Shift+Tab indent/de-indent in code mode |
+| `static/js/lruCache.js` | Map-backed LRU |
+| `static/js/index.js` | Client postAceInit: dynamically injects `vendor/hljs.min.js`, wires socketio + padToggle.init + syntaxRenderer.start + codeIndent.start |
+| `static/js/themeBridge.js` | Light/dark theme detection (no longer swaps stylesheets — `editor.css` carries both palettes) |
+| `static/js/domOverlay.js` | "Highlighting paused" badge for MAX_LINES kill switch |
+| `static/css/editor.css` | `::highlight(hljs-…)` rules. Light + dark palettes scoped via `.super-dark-editor` |
+| `static/css/themes/{github,github-dark}.css` | Vendored hljs themes — used **only by export pipeline**, not by the live editor |
+| `index.js` (server) | loadSettings, clientVars (lang + indentSize), socketio (setLanguage), eejsBlock_*, getLineHTMLForExport, stylesForExport |
+| `lib/padLanguageStore.js` | `{language, autoDetect}` per pad |
+| `lib/exportRenderer.js` | HTML/PDF export: hljs.highlight() emits real `<span>`s + theme CSS inlined |
+
+## How rendering actually flows
+
+```
+keystroke / paste / remote changeset
+    │
+    ▼
+Etherpad updates inner-iframe DOM
+    │
+    ├─ acePostWriteDomLineHTML hook fires (full line re-renders only)
+    │       └─ syntaxRenderer.renderLine(lineDiv)
+    │
+    └─ MutationObserver fires (every text mutation, including incremental typing)
+            └─ syntaxRenderer.renderLine(dirtyLine)
+                    │
+                    ▼
+              tokenize(text, language)  ←  LRU cache
+                    │
+                    ▼
+              setLineRanges(lineEl, ranges)
+                    │
+                    ├─ removeLineRanges(lineEl)  // strip old Highlight refs
+                    ├─ buildSegments(lineEl)      // walk text nodes
+                    ├─ buildRange(...) per token  // Range with setStart/setEnd
+                    └─ CSS.highlights.get(cls).add(range)
+                    │
+                    ▼
+              browser paints ::highlight(cls) rules
+```
+
+## Hard-won lessons (read before changing the render path)
+
+### 1. Don't mutate the DOM Ace owns
+v0.1 stored tokens as Easysync attributes — `setAttributesOnRange` moved the caret to the start of the range on the active line. v0.2 wrapped text nodes via `splitText`/`insertBefore` — fought Etherpad's `_magicdom_dirtiness.knownHTML` bookkeeping; lying about `knownHTML` to break the feedback loop broke remote changeset application. **CSS Custom Highlights is the answer:** observation only, no DOM modification, no fights with Ace.
+
+### 2. `acePostWriteDomLineHTML` only fires on FULL line re-renders
+Etherpad does incremental DOM updates on single-character typing (modifies `textNode.nodeValue` in place). The hook is only called when a line is fully written: paste, language change, line split, undo/redo. To catch every text mutation, install a `MutationObserver` on the inner doc body (`{childList: true, subtree: true, characterData: true}`) and walk up to the magicdomid line div. Etherpad sometimes swaps a line div wholesale on edit — `m.target` becomes `innerdocbody` and the new line is in `m.addedNodes`, so iterate both `m.target` and `m.addedNodes` when finding line ancestors.
+
+### 3. The cache must not poison
+`tokenize()` returns `null` (not `[]`) when `window.hljs` isn't loaded. `renderLine` defers — does not cache, does not strip existing highlights. If you cache `[]` from a missing-hljs render, every future render for that key is empty.
+
+### 4. `CSS.highlights` is per-document
+The editor lives in a nested iframe (`ace_outer` → `ace_inner`). Range objects must be created on the inner document and Highlights registered with the inner window's `CSS.highlights`. Using the outer window's `Highlight` constructor or `CSS.highlights` produces silent no-ops. `highlightRegistry.setLineRanges` resolves the right window via `lineEl.ownerDocument.defaultView`.
+
+### 5. Multi-class hljs spans need splitting
+hljs sometimes emits `<span class="hljs-meta hljs-string">@foo</span>`. CSS `<custom-ident>` doesn't allow spaces, so registering a Highlight named `"hljs-meta hljs-string"` is invisible. `parseHljsHtml` splits on whitespace and emits one range per class.
+
+### 6. Etherpad applies `super-dark-editor` to the inner `<html>`, not `<body>`
+Per `ace.ts:266`. Our dark-mode CSS uses `.super-dark-editor ::highlight(…)` (descendant-selector) so it matches whether the class is on `html`, `body`, or any ancestor.
+
+### 7. `padToggle` exposes `init({onChange})`, not `subscribe`
+The helper's eejs templates render `<input type="checkbox">` with NO `checked` attribute. Without calling `init()` on the client, the checkbox stays unchecked even when `defaultEnabled: true`. The flow is server-renders-empty → client-init-binds-state.
+
+### 8. `acePostWriteDomLineHTML` fires BEFORE `postAceInit` for the initial render
+For pads with persisted language, the initial line renders happen before `loadHljs()` resolves and before `syntaxRenderer.start()` sets state. The hook short-circuits on auto/missing-hljs and leaves them un-tokenized. Fix: schedule a `setTimeout(repaintAllLines, 100)` from `start()` to catch lines that rendered too early.
+
+### 9. Auto-detect is per-client, no broadcast (yet)
+Each client runs `hljs.highlightAuto(padText)` on a 2s idle interval. Convergence relies on `hljs.highlightAuto` being deterministic (same content → same language). If divergence is reported, add a jittered `setLanguage` broadcast with cancel-on-incoming so first-fire wins (sketched but not landed; see git stash `v0.2-task6-wip-archive` for the broadcast variant).
+
+### 10. The `padShortcutEnabled.tab` Etherpad setting affects Tab interception
+`codeIndent.handleKey` returns `true` and `evt.preventDefault()` to suppress Etherpad's default Tab. Test before assuming this works for a given keystroke — `aceKeyEvent` hook ordering means `outsideKeyPress` runs *before* the hook for Enter on Chrome (`isTypeForSpecialKey && keyCode === 13` branch in `ace2_inner.ts`). Backend unit tests are reliable; some Playwright tests for keystroke interaction are flaky and `test.fixme`'d.
+
+## Settings (server-side)
+
+```json
+"ep_hljs": {
+  "indentSize": 2
+}
+```
+
+`indentSize` is admin-configurable in `settings.json` (clamped to `1..16`, default `2`). A pad-level UI picker (TOC-style) is a deferred follow-up.
+
+## i18n
+
+All user-facing strings have `data-l10n-id` and a fallback English string. Keys live in `locales/en.json`:
+
+| Key | Where |
+|---|---|
+| `ep_hljs.label` | toolbar dropdown aria-label |
+| `ep_hljs.auto` | dropdown "Auto-detect" option |
+| `ep_hljs.off` | dropdown "Off" option |
+| `ep_hljs.paused` | "Highlighting paused" badge |
+| `ep_hljs.user_enable` | padToggle checkbox label |
+
+Programming language names (`JavaScript`, `Python`, etc.) are intentionally **not** translated — they're proper nouns / fixed identifiers in the hljs grammar registry.
+
+## Accessibility
+
+- The toolbar `<select>` exposes `aria-label` (via `data-l10n-attr="aria-label"`).
+- Toggle checkboxes get `<label for="...">` from the padToggle helper.
+- `Ctrl/Alt/Meta + Tab` is **not** intercepted by `codeIndent` — keyboard navigation escape hatch.
+- `Shift+Tab` defers to Etherpad's default when there's no leading whitespace to remove (so list-mode Shift+Tab still works).
+- **Color contrast trade-off:** the light-mode operator color (`#3b82f6` against white) is ~3.7:1 — passes WCAG AA for large/bold text only. The string color (`#1d4ed8`) passes AA at 7:1. Users with low-vision needs should use the dark skin variant which has high-contrast brights (`#79c0ff` etc., > 7:1 on the dark BG).
+
+## Tests
+
+```bash
+# Backend (jsdom + mocha)
+cd etherpad-lite/src && npx cross-env NODE_ENV=production mocha --import=tsx --timeout 30000 \
+  $(find plugin_packages -path '*ep_hljs*/static/tests/backend/specs/*.test.js' | tr '\n' ' ')
+
+# Frontend (Playwright)
+cd etherpad-lite/src && CI=true pnpm exec playwright test --project=chromium --reporter=line --workers=1 --retries=0 \
+  $(find plugin_packages -path '*ep_hljs*/static/tests/frontend-new/specs/*.spec.ts' | tr '\n' ' ')
+```
+
+Backend (38 cases): `lruCache`, `highlightRegistry` (jsdom Range building), `codeIndent` (Enter/Tab/Shift+Tab logic with mocked rep+editorInfo), `hljsAdapter` (parseHljsHtml multi-class + entities), `padLanguageStore`, `socket`, `export`.
+
+Frontend (~21 cases, ~3 fixme'd): `caret-stability`, `collaboration`, `content-sync`, `dark-mode` (CSS rule presence), `export`, `initial-paint`, `language-picker`, `large-pad`, `lifecycle`, `multi-user-caret`, `single-line-while`, `code-indent` (mostly fixme — see lesson #10).
+
+## Known issues / follow-ups
+
+- Pad-level indent size picker (currently admin-only via `settings.json`).
+- Auto-detect divergence between collaborators is theoretically possible; broadcast-with-jitter pattern designed but not landed (see git stash).
+- `code-indent.spec.ts` Enter/Tab/Shift+Tab Playwright cases are `test.fixme` — manual testing + backend unit tests cover the logic.
+- `caret-stability.spec.ts` and `multi-user-caret.spec.ts` repro 2 are intermittently flaky on the niceSelect dropdown click — UI timing race, not a code bug.