`. Its only class is hashed by
the CSS modules, so nothing outside the bundle can name it. Giving it a stable class, the way
`.auth-button`, `.auth-submit`, `.comment-actions` and `.sort-picker` are kept outside the
modules for this reason, is what makes the counter assertable in a browser
Two others are already reachable and simply have no browser case written yet, which is a smaller
job than it looked:
- `spinner` renders `clsx('spinner', styles.root, …)` and is still open. It is the *between-pages*
indicator at `profile.tsx:162-165`, shown in place of the Load more button once a page is being
fetched, so it is reachable only when `comments` is not null. The profile's initial load and its
failure are a different element, the `Preloader` at `profile.tsx:221`, and that one is covered by
`TestProfile_LoadingAndFailureStates`; the two are easy to conflate and are not the same thing
- **done for the telegram panel.** `preloader` renders `clsx('preloader', className)`, asserted
by `TestTelegramSub_ThePanelSaysItIsWorking`
- **done.** `comment-actions-additional` carries a stable class, and the order is asserted by
`TestComment_AdminActionsKeepTheirOrder`
## Transient states nothing waits on
- **done.** buttons disabled while a vote request is in flight, `TestVote_BothButtonsAreDisabledWhileTheVoteIsInFlight`
- **done.** the loading indicator in the telegram subscription panel
- **done.** the profile's loading and error states
- the preloader that must not reappear after a load-more click
Each needs a browser case that holds the request open, which the suite already knows how to do:
`TestVote_FailureShowsAnErrorAndRestoresTheScore` blocks a route and asserts the optimistic state
before releasing it.
## Absence with no positive control
The browser suite asserts what appears far more readily than what does not. Cases kept for this:
- **done.** the Reply action gone in a read-only thread, now asserted in
`TestComment_ReadOnlyThreadTakesTheFormAway`, which posts a comment first so the assertion has
something to be about
- **done.** Hide absent on a reader's own comment, Delete absent on another reader's,
`TestComment_ActionsDependOnWhoseCommentItIs`
- **done.** the verification icon absent before an admin verifies
- the auth dropdown starting closed
## Configurations no instance runs
- **done.** `email_notifications` and `telegram_notifications` off, each instance being the
other's negative case
- upvote-only voting, and voting hidden altogether
- the controversy tooltip, which needs a comment with controversy in it
## Values inside an element, where the browser case only waits for the element
- **done.** the edit countdown's value, `TestComment_EditCountdownCountsDown`
- the telegram link's full `https://t.me/
/?start=`, where the browser helper parses out
the `start` parameter and never looks at the host or the bot name
## Error branches that are not the one the browser drives
- the generic fallback message for an unrecognised code. The browser suite fulfils a 409 and
asserts the catalogued string, which never enters that branch
- **done.** a failed check or unsubscribe cleared by a later success, driven separately because
the two handlers clear their own error
## What is not worth moving
Call counts and call arguments (`api.telegramSubscribe` called once, `getUserComments` called with
a page size) assert how a client method was used, not what a reader gets. The browser suite asserts
the request and the response instead, which is the better test of the same thing, so these stay in
jest or go away on their own when the code changes.
## What the static build would settle on its own
Thirty-four of the cases still in jest exist because of the build rather than because of the
behaviour: eighteen assert a hashed css-module class and sixteen select by a `data-testid` the
production bundle strips. With static css there is no hash to pin and the class in the source is
the class in the browser, so those assertions have nothing left to say and the browser can select
what ships. Covering them now would mean writing browser cases whose purpose disappears with the
build, which is why they are left here rather than done.
---
### Backlog Public Widget Contract Docs And Types (`docs/backlog/public-widget-contract-docs-and-types.md`)
---
worth: yes
where: site/content/docs/configuration/frontend/_index.md, frontend/apps/remark42/app/typings/global.d.ts
added: 2026-08-21
---
# The public embed contract has no reference page and no shippable type declaration
Discussion #1714 asked for a description of `window.REMARK42` and TypeScript types, in December 2023.
The contract was written out in a reply on 2026-08-20, but a discussion comment is not documentation,
and the two halves of the request are still open.
## The docs half
The pieces exist and are scattered. `configuration/frontend/_index.md:81` documents `changeTheme` only,
in a section about theming. `configuration/frontend/spa.md` shows `createInstance`, `destroy` and the
`REMARK42::ready` event, but as a single-page-app recipe rather than as a reference. The Astro and
Gatsby manuals repeat fragments again. There is no page that states the surface once.
Three behaviours are documented nowhere and will bite anyone building against it, all in `app/embed.ts`:
- `createInstance` throws rather than returning an error in three cases: no element with id `remark42`,
`window.remark_config` undefined, or `site_id` unset
- those checks read the **global** `window.remark_config`, while the rest of the function reads the
object passed as the argument, so passing a config does not remove the need for a valid global
- `createInstance` reuses a direct-child iframe carrying `data-remark42-iframe` rather than creating one,
and the config passed to that second call is ignored, so calling it again without a `destroy` silently
does nothing. The reuse also leaves the first instance's `message`, `hashchange` and `click` listeners
installed, so each call adds another set
Also undocumented: the embed script creates an instance *before* dispatching `REMARK42::ready`, so the
event means the global is safe to touch rather than that nothing is mounted; and `__colors__` reaches
the iframe through `window.name` (`templates/iframe.ejs:42-44`) rather than the URL, so it is read once
at boot and is not a runtime API.
## The types half, and the open decision
`app/typings/global.d.ts` is internal: it imports `jest-fetch-mock` and `common/types`, so it cannot be
shipped as-is. A public declaration would be a standalone file with `Theme`, `RemarkConfig` and the
`window.REMARK42` surface and no internal imports. That part is easy.
**How it reaches a consumer is not decided.** `tsc` picks up types from `node_modules`, and npm is the
direction we have just moved away from: #1715 declined packaging the widgets and #2172 removed
`@remark42/api`. Options, in the order I would rank them:
1. Publish the file on the site as a copy-paste block, with no package. Zero infrastructure, works
today, and consumers paste it into their own `global.d.ts`. This is what the Astro and Gatsby
manuals need, since both currently declare `REMARK42: any` and `remark_config: any`
(`integration-with-astro/index.md:150`, `integration-with-gatsby/index.md:109`), which is our own
documentation admitting the gap.
2. A types-only npm package. Note this does not contradict #1715: that was declined because shipping
*widget code* through npm puts the widget in the host origin and breaks OAuth. A package containing
no runtime code has none of that problem. It does add a publish step and a version to keep in sync.
Option 1 clears the reported need. Option 2 only pays off if we want `npm i -D` ergonomics, which is a
separate call.
Whatever is chosen, fixing the two integration manuals to stop using `any` is the visible win, and
#1714 should get the pull request linked when it lands, as promised there.
---
### Backlog Site Checks Do Not Gate Merge (`docs/backlog/site-checks-do-not-gate-merge.md`)
---
worth: yes
where: repository settings, not a file
added: 2026-08-21
---
# nothing on master is a required status check
`master` is protected, but `required_status_checks` is `{"checks": [], "contexts": [], "enforcement_level": "off"}`,
and the only ruleset on the branch ("Copilot review for default branch", id 15225632) carries just
`deletion`, `non_fast_forward` and `copilot_code_review`. Verified with
`gh api repos/umputun/remark42/branches/master`.
Every workflow in the repository is therefore advisory. A red X on any backend, frontend or site job
shows in the checks list and does not stop the merge button, so a pull request that fails CI can still
be merged by anyone who does not read the list.
Fix: configure required status checks on `master` for the jobs that should block. Worth deciding
deliberately rather than by default, since it also governs what happens to Dependabot pull requests
and to any job that turns out to be flaky.
---
### Plans 2026 08 19 Frontend Simplification (`docs/plans/2026-08-19-frontend-simplification.md`)
# Frontend simplification: shipping the widget as static HTML, CSS and JavaScript
The goal is a widget that ships without npm: no installed dependency tree, no bundler, no node in
the build, and static HTML, CSS and JavaScript as the output. This document plans that and nothing
else.
Two subjects that earlier revisions carried have been taken out. The server-rendered direction of
#825 is a different proposal and is not costed here; removing it from this document does not decide
against it. Multi-domain hosting is an authentication question that constrains this work at exactly
one point, noted in its place below, and is tracked separately so that a backend decision does not
block a build decision.
## Where this stands
The direction is settled. What was open was whether the verification could survive the move, and
that is now half answered.
The test suite has split in two. Pure logic, meaning anything that is a function over strings,
objects and dates, runs under `node --test` directly from source with nothing installed, and its CI
job installs nothing so that a test reaching for a dependency fails. What remains on jest is the
half that renders components into jsdom.
That retires the earlier framing, which held that dropping npm drops the whole unit suite and that
the only route was to close every gap in the e2e suite first. The question is now specifically about
DOM-rendering cases, and each has three possible answers: move the subject's logic out and test it
under node, cover the behaviour in the e2e suite, or accept the loss.
It also settles, by precedent, a question earlier revisions listed as open. Dependency-free node
scripts may stay, so the translation tooling written against node built-ins does not have to be
ported to Go to satisfy the goal.
### The extraction pattern
Value imports in the node layer write the extension in full and use a relative path, never the
`common/…` alias, because node resolves neither. Type-only imports erase and keep the ordinary
style. This is recorded in both `CLAUDE.md` files; it is repeated here because it decides whether a
given jest case can move at all. A case whose subject imports through the alias cannot move until
the subject does, which is why the split extracted the pure half of each module first.
The pattern is the reusable part. Pull the logic out of the module that touches the DOM, test that
half under node, and leave the thin DOM half to jest or to the e2e suite. It found several defects
on its first pass, which is the argument for continuing it.
## Standing requirement: the language must be selectable per page
The locale is read once from `remark_config.locale` and resolved to one catalogue. There is no
runtime switcher and no locale entry in the postMessage contract, so the language cannot change
during an instance's life, and a site with several language versions embeds each page with its own
locale.
Must survive any build change:
- `remark_config.locale` keeps selecting the language per instance
- every supported language keeps working. Adding one is not catalogue-only today: the language goes
into a registry file, and generation then rewrites the loader from it. Preserve that
registry-plus-generation shape or replace it deliberately
- the translation completeness check survives in some form
- date and time rendering keeps resolving in the viewer's timezone. The locale is not the viewer's,
since it is configured and the server knows it too. Only the timezone is genuinely client-side, so
the carve-out is timezone-local rendering and not a whole date-formatting layer
## Sequence: parity first, changes second, CSS excepted
The build change must reproduce current behaviour exactly, with no feature change, no markup change
and no visible difference, so that any regression it causes is attributable to the build and to
nothing else. Interleaving a rendering bug with a deliberate redesign in one diff is expensive to
untangle, and the widget's most stateful code is the composer and authentication, which is where it
is most expensive.
CSS is the exception and has to be correct on the first pass. Reproducing the hashed class names
exactly would freeze an accidental surface as though it had been designed, and renaming later breaks
every override written against the first set. Public names ship once, and #5 has been open since
2018 asking for stable ones.
One piece of work in flight collides with this: #2128 rewrites the CSS layer on the assumption that
hashed names stay. Settling the class-name direction first is what stops that work being redone.
## What replaces each npm gate
| gate | replacement | state |
|---|---|---|
| dependency-free unit tests | none needed | in place |
| jest | extract logic into the node layer, cover the rest in the e2e suite, accept the remainder | in progress |
| type checking | undecided | open |
| lint and style lint | undecided, and an accepted loss is a real option | open |
| size budgets | a Go test over the embedded filesystem | designed |
| translation completeness | only message extraction is bound to npm; everything downstream of it is already node built-ins | narrowed |
Type checking is the hard one, and the only gate with no route. Dropping the bundler without
answering it means either shipping untyped source or finding a checker that is not npm, and there is
no third option that keeps the current guarantee.
The translation failure mode is worth carrying forward because it is silent. Extraction matches the
identifiers the widget calls, not an import source, so moving strings into Go templates would
extract nothing with a zero exit code, after which generation deletes them from every catalogue.
## What the bundler still does
The list any no-bundler proposal has to answer for.
- transpiles TypeScript and JSX
- CSS modules, with nesting and with one `composes` that crosses a file boundary. That one has no
plain-CSS equivalent and has to be flattened instead of translated
- code-splits the locale catalogues and the emoji data
- runs an autoprefixer pass against a browserslist query. Without a transpiler that query becomes the
literal browser floor and source syntax ships as written
- builds the HTML entry pages, including the fallback page a reader is offered when the widget
detects a third-party context with storage unavailable. This is the one point where multi-domain
hosting constrains this work: that page went unbuilt from the January 2021 rewrite until #2197
restored it, so it returned 404 for four years in exactly the configuration that needs it, and
nothing in the e2e suite pins it. Any replacement build has to keep emitting it
- derives asset URLs. Since #2197 the public path is computed at runtime from the URL the bundle was
loaded from, so a sub-path install resolves its own assets. A build with no bundler inherits that
requirement instead of the fix, and #2224 is what it costs when it goes wrong
- strips test-only attributes through a local plugin, which nothing else replicates
- minifies
- substitutes build-time constants. The instance URL was the one with teeth, and #2198 moved that
substitution to serve time in the Go file server, so a build with no bundler inherits a working
mechanism and not a broken one
## What is already out
Worth stating because the widget build is now the last npm consumer in the repository.
- the documentation site is a Go static generator since #2179 and has no manifest at all
- the e2e suite has been a Go module since #2180. Its browser driver fetches a node runtime at test
time, which is a fetched runtime and not a tracked dependency, so it survives whatever happens here
- the published API package and the shared frontend packages went with #2172
- static assets needing no processing are embedded in the Go binary since #2181, which is the working
proof that the no-build serving path carries real files
- since #2197 there is one manifest and one lockfile. The release pipeline still runs pnpm to build
the widget, and that step goes when the widget build does
## Still open
Each of these can move the answer.
- **A definition of done.** Which files and jobs actually go: the node stages in the image build, the
remaining npm CI jobs, the pnpm steps in the release pipeline, and the git hooks. For each, the
replacement or the accepted loss
- **Type checking**, the one gate with no route yet
- **A runtime-dependency inventory.** For every package the widget actually ships with: whether a
usable ESM build exists, the licence, and whether it is vendored or dropped. Vendoring the custom
elements understates them, because they mutate the textarea selection, emit their own events and
lazily load data, so rendering the tags is not the same as the behaviour working
- **A build-output acceptance matrix.** The generated pages, the catalogue and emoji payloads, the
copied images, the stripped attributes and the size budgets are today the emergent result of
separate bundler rules and plugins. Without a statement of what the output must contain, a
replacement cannot be checked against anything
- **The integrator contract.** The documented `/web` URLs, the component loader, and the legacy `.js`
names, which must stay module-free. `/web` is an overlay: a `--web-root` file wins and only a
missing name falls through to the embedded assets, so moving a page between the two sources
silently changes whether an operator can override it
- **The development loop.** The dev server goes with npm, and `make rundev` with `--web-root`
replaces it
- **Message-channel hardening**, available and not done. Both ends post with `'*'` and check the
sender instead of the target. The parent builds the iframe URL itself, so it knows the widget
origin and could pass it as `targetOrigin` and compare the origin alongside the source
## Rejected
- **A full vanilla rewrite**: the render layer becomes an unowned in-house framework
- **lit, alpine, solid, petite-vue**: none removes more tooling than this path, and each trades a
known small library for a less-known one
- **preact with htm over native ESM**: dropping the JSX transpile drops type-checked markup, since
the JSX pragma is what types templates today and tagged literals are opaque to the type checker.
Unbundling every source file and locale chunk into individually fetched modules also multiplies a
cold load's request count against the rate limit the file server applies, and the cache headers
revalidate each one
- **Packaging the widget for npm (#1715)**: it must run in an iframe on the remark42 origin for OAuth
popups, so importing it into a host bundle breaks authentication. A types-only package is a
separate question
---
### Plans Completed 2026 02 24 Bem To Css Modules Batch1 (`docs/plans/completed/2026-02-24-bem-to-css-modules-batch1.md`)
# BEM → CSS Modules migration, batch 1: leaf components
## Overview
- Migrate 4 leaf BEM components to CSS Modules: **button**, **dropdown**, **thread**, **auth-panel**
- Consolidates 19 BEM CSS files into 4 CSS module files
- Cleans up dead CSS classes and unused props discovered during analysis
- Follows the pattern established in PR #2013 (batch 0: dropdown-item, list-comments, subscribe-by-rss, settings)
## Context
- PR #2013 migrated 4 small components with zero visual regression (verified pixel-by-pixel on built artefacts)
- Key learning from batch 0: `mix` is pure string concatenation — parent and child can be migrated independently in any order
- These 4 "leaf" components are migrated first because they have no inward `mix` coupling with unmigrated parents (or the coupling is dead)
- Batch 2 (comment-form, subscribe-by-email, comment, root) follows after this lands
## Development Approach
- **Testing approach**: Regular (run existing tests after each change; no new tests needed as these are CSS-only changes with no logic)
- Complete each task fully before moving to the next
- Make small, focused changes
- Run `cd frontend && pnpm lint` and `cd frontend && pnpm test` after each task
## Progress Tracking
- Mark completed items with `[x]` immediately when done
- Add newly discovered tasks with ➕ prefix
- Document issues/blockers with ⚠️ prefix
## Implementation Steps
### Task 1: Migrate `button` to CSS Modules
7 BEM CSS files → 1 `button.module.css`. Uses lookup objects for dynamic kind/size/theme props.
**Files to modify:**
- `frontend/apps/remark42/app/components/button/button.tsx`
- `frontend/apps/remark42/app/components/button/index.ts`
**Files to create:**
- `frontend/apps/remark42/app/components/button/button.module.css`
**Files to delete (7):**
- `button/button.css`
- `button/_kind/_link/button_kind_link.css` + parent dirs
- `button/_kind/_primary/button_kind_primary.css` + parent dirs
- `button/_kind/_secondary/button_kind_secondary.css` + parent dirs
- `button/_size/_large/button_size_large.css` + parent dirs
- `button/_size/_middle/button_size_middle.css` + parent dirs
- `button/_theme/_dark/button_theme_dark.css` + parent dirs
**Steps:**
- [x] Create `button.module.css` consolidating all 7 CSS files:
```css
.root {
background: none;
border: 0;
padding: 0;
margin: 0;
border-radius: 4px;
font-family: inherit;
font-size: inherit;
cursor: pointer;
white-space: nowrap;
&:focus {
box-shadow: 0 0 0 2px var(--color47);
outline: none;
}
&:disabled {
opacity: 0.6;
cursor: default;
}
}
.kindLink {
background: transparent;
font-weight: 600;
color: var(--color9);
&:hover { color: var(--color33); }
&:disabled, &:hover:disabled { color: var(--color9); }
}
.kindPrimary {
background: var(--color15);
color: var(--color6);
&:hover { background: var(--color33); }
&:hover:disabled { background: var(--color15); }
}
.kindSecondary {
background: var(--color6);
color: inherit;
&:hover { box-shadow: inset 0 0 0 2px var(--color33); }
}
.sizeMiddle {
height: 2rem;
padding: 0 12px;
}
.sizeLarge {
height: 36px;
padding: 0 12px;
font-size: 16px;
}
.themeDark {
&.kindSecondary {
background: var(--color8);
color: var(--color20);
}
&.kindLink {
&:disabled, &:hover:disabled { color: var(--color6); }
}
}
```
- [x] Update `button.tsx`:
- Remove `import b, { Mods, Mix } from 'bem-react-helper'`
- Add `import styles from './button.module.css'`
- Add lookup objects:
```tsx
const kindStyles: Record = {
primary: styles.kindPrimary,
secondary: styles.kindSecondary,
link: styles.kindLink,
};
const sizeStyles: Record = {
middle: styles.sizeMiddle,
large: styles.sizeLarge,
};
```
- Remove `mods` from `ButtonProps` type and destructuring (never passed by any caller)
- Change `Mix` type import to plain `string | string[]` for `mix` prop
- Change className to: `clsx(styles.root, kind && kindStyles[kind], size && sizeStyles[size], theme === 'dark' && styles.themeDark, mix, className)`
- [x] Update `index.ts`: remove all 7 CSS imports, keep only `export { Button } from './button'`
- [x] Delete all 7 old CSS files and their BEM directories
- [x] Run `cd frontend && pnpm lint && pnpm test` — must pass before next task
### Task 2: Migrate `dropdown` to CSS Modules
7 BEM CSS files → 1 `dropdown.module.css`. Replaces 3 DOM class queries with refs and `data-dropdown` attribute. Removes dead `heading` prop (no callers) and dead `dropdown__heading` class (no CSS). Updates already-migrated `dropdown-item.module.css`.
**Files to modify:**
- `frontend/apps/remark42/app/components/dropdown/dropdown.tsx`
- `frontend/apps/remark42/app/components/dropdown/index.ts`
- `frontend/apps/remark42/app/components/dropdown/__item/dropdown-item.module.css` (change `:global(.dropdown)` → `[data-dropdown]`)
**Files to create:**
- `frontend/apps/remark42/app/components/dropdown/dropdown.module.css`
**Files to delete (7):**
- `dropdown/dropdown.css`
- `dropdown/__content/dropdown__content.css` + dir
- `dropdown/__items/dropdown__items.css` + dir
- `dropdown/__title/dropdown__title.css` + dir
- `dropdown/_active/dropdown_active.css` + dir
- `dropdown/_theme/_dark/dropdown_theme_dark.css` + dirs
- `dropdown/_theme/_light/dropdown_theme_light.css` + dirs
**Steps:**
- [x] Create `dropdown.module.css` consolidating all 7 CSS files:
```css
.root {
display: inline-block;
position: relative;
}
.content {
position: absolute;
z-index: 20;
outline-width: 0;
display: none;
top: 100%;
left: 0;
transform: translate(-0.5em, 5px);
min-width: 120px;
max-width: 260px;
border: 2px solid var(--color15);
border-radius: 3px;
padding: 0 0 5px;
}
.items {
padding: 5px 0;
&:last-child { padding-bottom: 0; }
}
.title {
&::after {
content: '\25BE';
margin-left: 2px;
}
}
.active > .content {
display: block;
}
.themeDark > .content {
background-color: var(--color8);
}
.themeLight > .content {
background-color: var(--color6);
}
```
- [x] Update `dropdown.tsx`:
- Replace `import b from 'bem-react-helper'` with `import clsx from 'clsx'` and `import styles from './dropdown.module.css'`
- Add `contentRef = createRef()` alongside existing `rootNode` ref
- Add `data-dropdown` attribute to root div (for nested dropdown detection by parent traversal)
- Replace 3 DOM queries with ref:
- Line 78: `parent.classList.contains('dropdown')` → `parent.hasAttribute('data-dropdown')`
- Line 95: `Array.from(...).find(c => c.classList.contains('dropdown__content'))` → `this.contentRef.current`
- Line 118: `this.rootNode.current.querySelector('.dropdown__content')` → `this.contentRef.current`
- Root div: `className={clsx(styles.root, isActive && styles.active, theme === 'dark' ? styles.themeDark : styles.themeLight, mix)}`
- Content div: `className={styles.content}` with `ref={this.contentRef}`
- Items div: `className={styles.items}`
- Button mix: `mix={[styles.title, titleClass]}` (clsx in Button handles arrays)
- Remove dead `heading` prop from Props type and the heading div from JSX (prop is never passed by any caller, class has no CSS)
- [x] Update `dropdown-item.module.css`: change `& > :global(.dropdown)` to `& > [data-dropdown]`
- [x] Update `index.ts`: remove all 7 CSS imports, keep `export { Dropdown }` and `export { DropdownItem }`
- [x] Delete all 7 old CSS files and their BEM directories
- [x] Run `cd frontend && pnpm lint && pnpm test` — must pass before next task
### Task 3: Migrate `thread` to CSS Modules
3 BEM CSS files → 1 `thread.module.css`. Levels 0-5 had no CSS rules — only level 6 matters. The `mix` prop (receives `"root__thread"` from root component) is passed through as a plain class string.
**Files to modify:**
- `frontend/apps/remark42/app/components/thread/thread.tsx`
- `frontend/apps/remark42/app/components/thread/index.ts`
**Files to create:**
- `frontend/apps/remark42/app/components/thread/thread.module.css`
**Files to delete (3):**
- `thread/thread.css`
- `thread/__collapse/thread__collapse.css` + dir
- `thread/_theme_dark/thread_theme_dark.css` + dir
**Steps:**
- [x] Create `thread.module.css` consolidating all 3 CSS files:
```css
.root {
position: relative;
}
.indented {
margin-left: 17px;
}
.level6 .level6 {
margin-left: 0;
}
.collapse {
height: calc(100% - 50px);
width: 11px;
position: absolute;
top: 50px;
left: -4px;
cursor: pointer;
&::after {
display: block;
content: '';
position: absolute;
left: 5px;
top: 0;
border-left: 1px dotted var(--color35);
height: 100%;
}
&:hover::after {
transform: translateX(-1px);
border-left: 3px solid var(--color10);
z-index: 10;
}
}
.collapsed {
composes: collapse;
width: 18px;
height: 18px;
top: 12px;
left: 0;
display: flex;
text-align: center;
opacity: 0.8;
border-radius: 2px;
border: 1px solid;
&::after { display: none; }
&:hover { opacity: 1; }
&:hover::after { transform: translateX(0); }
& > div {
position: relative;
top: 6px;
left: 3px;
width: 12px;
height: 2px;
border-bottom: 2px solid;
&::before, &::after {
content: '';
width: 100%;
height: 2px;
border-bottom: 2px solid;
position: absolute;
top: -4px;
left: 0;
}
&::after { top: 4px !important; }
}
}
.themeDark {
& .collapse {
&::after { border-color: var(--color36); }
&:hover::after { border-color: var(--color6); }
}
}
```
- [x] Update `thread.tsx`:
- Replace `import b from 'bem-react-helper'` with `import clsx from 'clsx'` and `import styles from './thread.module.css'`
- Root div: `className={clsx(styles.root, indented && styles.indented, level === 6 && styles.level6, theme === 'dark' && styles.themeDark, mix)}`
- Collapse div: `className={collapsed ? styles.collapsed : styles.collapse}`
- [x] Update `index.ts`: remove all 3 CSS imports, keep only `export { Thread } from './thread'`
- [x] Delete all 3 old CSS files and their BEM directories
- [x] Run `cd frontend && pnpm lint && pnpm test` — must pass before next task
### Task 4: Migrate `auth-panel` BEM remnants to CSS Modules
2 BEM CSS files → merge into existing `auth-panel.module.css`. Removes dead global class strings alongside module classes. Has test file to update.
**Dead code to clean up:**
- `auth-panel__pseudo-link` — no CSS rules, remove from JSX
- `auth-panel_loggedIn` / `auth-panel_theme_*` — dead mods from `b()`, no CSS rules
- `clsx('user', styles.user)` etc. — bare global strings (`'user'`, `'user-profile-button'`, `'user-avatar'`, `'user-logout-button'`) have no CSS; remove from `clsx()`
**Files to modify:**
- `frontend/apps/remark42/app/components/auth-panel/auth-panel.tsx`
- `frontend/apps/remark42/app/components/auth-panel/auth-panel.module.css`
- `frontend/apps/remark42/app/components/auth-panel/auth-panel.test.tsx`
- `frontend/apps/remark42/app/components/auth-panel/index.ts`
**Files to delete (2):**
- `auth-panel/auth-panel.css`
- `auth-panel/__column/auth-panel__column.css` + dir
**Steps:**
- [x] Merge BEM styles into existing `auth-panel.module.css` — add these classes after existing ones:
```css
.root {
display: flex;
justify-content: space-between;
font-size: 14px;
line-height: 16px;
align-items: center;
}
.column:last-child {
margin-left: 8px;
text-align: right;
}
.columnSeparated > * + * {
position: relative;
display: inline-block;
margin-left: 20px;
&::before {
position: absolute;
left: -15px;
display: inline-block;
width: 10px;
text-align: center;
content: '•';
}
}
.adminAction { }
```
- [x] Update `auth-panel.tsx`:
- Remove `import b from 'bem-react-helper'`
- Root div: `className={styles.root}` (drop dead `theme`/`loggedIn` mods)
- Column divs: `className={styles.column}`
- Separated column: `className={clsx(styles.column, styles.columnSeparated)}`
- Remove `className="auth-panel__pseudo-link"` from `` (dead class, no CSS)
- Clean up dual class patterns: `clsx('user', styles.user)` → `styles.user`, same for userButton/userAvatar/userLogoutButton
- Change `mix="auth-panel__admin-action"` → `className={styles.adminAction}` on both Button calls
- [x] Update `auth-panel.test.tsx`:
- Add `import styles from './auth-panel.module.css'`
- `.find('.auth-panel__admin-action')` → `` .find(`.${styles.adminAction}`) ``
- `.find('.auth-panel__column')` → `` .find(`.${styles.column}`) ``
- [x] Update `index.ts`: remove 2 CSS imports, keep `export * from './auth-panel'`
- [x] Delete `auth-panel.css` and `__column/` directory
- [x] Run `cd frontend && pnpm lint && pnpm test` — must pass before next task
### Task 5: Verify acceptance criteria
- [x] Verify all 4 components use CSS Modules (no remaining `b()` calls in migrated files)
- [x] Run full frontend test suite: `cd frontend && pnpm test`
- [x] Run frontend linter: `cd frontend && pnpm lint`
- [x] Grep for old BEM class names to verify no remaining references to deleted CSS files
- [x] Verify `bem-react-helper` is no longer imported in any of the 4 migrated components
## Technical Details
### Class naming convention
- BEM block → `root`
- BEM element → camelCase of element name (`dropdown__content` → `content`, `auth-panel__column` → `column`)
- BEM modifier → camelCase (`button_kind_primary` → `kindPrimary`, `thread_theme_dark` → `themeDark`)
- Combined modifier → compound `&.` nesting (`button_theme_dark.button_kind_secondary` → `.themeDark { &.kindSecondary { ... } }`)
### Button `mix` prop after migration
- Type changes from `Mix` (bem-react-helper) to `string | string[] | undefined`
- Passed directly to `clsx()` which handles all these types
- Callers in batch 2 (not yet migrated) continue passing BEM strings — works fine
- Already-migrated callers pass module hashes — works fine
### Dropdown DOM query replacements
| Before | After |
|---|---|
| `classList.contains('dropdown')` | `hasAttribute('data-dropdown')` |
| `querySelector('.dropdown__content')` | `this.contentRef.current` |
| `Array.from(...).find(c => c.classList.contains('dropdown__content'))` | `this.contentRef.current` |
### Files to delete (total: 19 CSS files + BEM directories)
- Button: 7 CSS files
- Dropdown: 7 CSS files
- Thread: 3 CSS files
- Auth-panel: 2 CSS files
## Post-Completion
- Visual smoke test: `cd frontend && pnpm dev:app`, verify button variants, dropdown open/close, thread collapse/expand, auth-panel admin actions in both light and dark themes
- Built artefact comparison: build docker image from branch, compare against master (same method as PR #2013)
- Batch 2 (comment-form, subscribe-by-email, comment, root) as follow-up
---
### Site Content Docs Configuration Frontend Spa (`site/content/docs/configuration/frontend/spa.md`)
---
title: API for Single-Page Application
---
Add the following JavaScript to your `index.html`, which in this case, it is identical to ``
```js
;(function () {
var host = 'https://demo.remark42.com' // Your remark42 host
var components = ['embed'] // Your choice of remark42 components
for (var i = 0; i < components.length; i++) {
var d = document
var s = d.createElement('script')
s.src = host + '/web/' + components[i] + '.mjs'
s.type = 'module'
s.defer = true
;(d.head || d.body).appendChild(s)
}
})()
```
Created `remark42Instance` when the `div` containing remark42 has appeared, usually at `mounted` or `componentDidMount` of the SPA lifecycle. Destroy the previous instance first, if necessary.
```ts
initRemark42() {
if (window.REMARK42) {
if (this.remark42Instance) {
this.remark42Instance.destroy()
}
this.remark42Instance = window.REMARK42.createInstance({
node: this.$refs.remark42 as HTMLElement,
...remark42_config // See
})
}
}
mounted() {
if (window.REMARK42) {
this.initRemark42()
} else {
window.addEventListener('REMARK42::ready', () => {
this.initRemark42()
})
}
}
```
- Ensure that this is called every time route changes
```ts
@Watch('$route.path')
onRouteChange() {
this.initRemark42()
}
```
- And, destroyed before routeLeave
```ts
beforeRouteLeave() {
if (this.remark42Instance) {
this.remark42Instance.destroy()
}
}
```
---
--- METRICS ---
- Files Extracted: 45
- Estimated Token Budget: ~52992 tokens
- Canonical Reference: https://codewiki.google/github.com/umputun/remark42