[ihordubas99]

Ticket

https://community.openproject.org/wp/COMMS-1057

What are you trying to accomplish?

Documents now support math formulas through @blocknote/math-block. Users can insert a block equation or an inline equation from the slash menu (/math, /equation, /latex) and edit the LaTeX source in a popup. The stored markdown keeps the LaTeX, with $$…$$ for block equations and $…$ for inline ones. The menu texts follow the user's locale.

Screenshots

What approach did you choose and why?

Editor. The math block and inline math specs from @blocknote/math-block (0.54.2, matching our BlockNote version) are added to the schema in OpBlockNoteEditor. Their slash menu items are merged into the "Advanced" group with combineByGroup, and the math dictionary of the same locale is merged into the editor dictionary.

Markdown in hocuspocus. The markdown is produced by hocuspocus from its own schema. Without math in that schema, every formula was silently dropped from the stored description. The package's own specs cannot run there, for two reasons. Its entry point imports KaTeX's CSS, which Node cannot load. Its React rendering also leaves work scheduled after ServerBlockNoteEditor tears down its DOM, and that crashes the process. Instead, mathSpecs.ts defines static twins with the same type, content and code meta, like the existing static work package specs. They render a <math> element with an application/x-tex annotation, which BlockNote's markdown exporter turns into $$/$ notation.

KaTeX stylesheet. KaTeX renders every formula twice in the editor, once as HTML and once as MathML for assistive technology, and only its stylesheet hides the MathML copy. Without the stylesheet in the shadow root, the formula shows up twice. Chromium also ignores @font-face rules declared inside a shadow root, so the KaTeX fonts only load when the stylesheet is in the document too. That is why katex.min.css goes into the global styles bundle, which is linked into both the document and the editor's shadow root, instead of the shadow-root-only blocknote bundle. It adds about 23 KB of CSS to every page. The fonts are only fetched where a formula is shown. katex is a direct dependency now, deduped with the version math-block uses.

Left out. Two optional parts of the BlockNote docs are not included.

• The "Equation" entry in the formatting toolbar's block type select. The toolbar lives in op-blocknote-extensions and cannot take extra items, so this would need a change in the library.
• LaTeX syntax highlighting in the source popup. It comes with @blocknote/code-block, which COMMS-1058 adds for code block highlighting in a follow-up PR. The math specs already declare latex as their language, so they pick it up without further changes.

Tests

• hocuspocus unit tests pin the stored markdown for block and inline math.
• A frontend unit test covers the merged locale.
• Two feature specs insert both kinds of equation via the slash menu, check that the KaTeX stylesheet applies inside the shadow root, and check the stored markdown. The stylesheet assertion was verified red without the angular.json entry.

Merge checklist

• Added/updated tests
• Added/updated documentation in Lookbook (patterns, previews, etc)
• Tested major browsers (Chrome, Firefox, Edge, ...)

[github-actions]

Dependency Review

The following issues were found:

• ❌ 1 vulnerable package(s)
• ✅ 0 package(s) with incompatible licenses
• ✅ 0 package(s) with invalid SPDX license definitions
• ✅ 0 package(s) with unknown licenses.

See the Details below.

Vulnerabilities

frontend/package-lock.json

Name	Version	Vulnerability	Severity
katex	0.16.47	KaTeX: Existing prototype pollution can bypass trust restrictions	low

OpenSSF Scorecard

Package	Version	Score	Details
npm/katex	0.16.47	🟢 4.3	Details Check Score Reason Code-Review 🟢 5 Found 11/21 approved changesets -- score normalized to 5 Maintained 🟢 10 30 commit(s) and 16 issue activity found in the last 90 days -- score normalized to 10 Security-Policy 🟢 10 security policy file detected Dangerous-Workflow ⚠️ 0 dangerous workflow patterns detected Token-Permissions ⚠️ 0 detected GitHub workflow tokens with excessive permissions Binary-Artifacts 🟢 10 no binaries found in the repo CII-Best-Practices ⚠️ 0 no effort to earn an OpenSSF best practices badge detected Packaging ⚠️ -1 packaging workflow not detected License 🟢 10 license file detected Fuzzing ⚠️ 0 project is not fuzzed Pinned-Dependencies ⚠️ 0 dependency not pinned by hash detected -- score normalized to 0 Signed-Releases ⚠️ 0 Project has not signed or included provenance with any releases. Branch-Protection ⚠️ -1 internal error: error during branchesHandler.setup: internal error: some github tokens can't read classic branch protection rules: https://github.com/ossf/scorecard-action/blob/main/docs/authentication/fine-grained-auth-token.md SAST 🟢 10 SAST tool is run on all commits
npm/@blocknote/math-block	0.54.2	Unknown	Unknown
npm/commander	8.3.0	🟢 7.4	Details Check Score Reason Maintained 🟢 8 0 commit(s) and 10 issue activity found in the last 90 days -- score normalized to 8 Security-Policy 🟢 10 security policy file detected Token-Permissions 🟢 9 detected GitHub workflow tokens with excessive permissions Code-Review 🟢 9 Found 20/22 approved changesets -- score normalized to 9 Binary-Artifacts 🟢 10 no binaries found in the repo Dangerous-Workflow 🟢 10 no dangerous workflow patterns detected Packaging ⚠️ -1 packaging workflow not detected Pinned-Dependencies 🟢 10 all dependencies are pinned CII-Best-Practices ⚠️ 0 no effort to earn an OpenSSF best practices badge detected License 🟢 10 license file detected Fuzzing ⚠️ 0 project is not fuzzed Branch-Protection ⚠️ 0 branch protection not enabled on development/release branches Signed-Releases ⚠️ -1 no releases found SAST 🟢 8 SAST tool detected but not run on all commits

Scanned Files

• frontend/package-lock.json

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

An organization owner can choose the repository organization as the billing source for reviews requested by members with a paid Copilot license. Learn about Copilot code review billing. Review the Copilot code review billing settings.

[github-actions]

Warning

Flaky specs

• rspec ./spec/features/components/lookbook_accessibility_spec.rb[1:14:1]

🤖 Ask Copilot to investigate

Copy the prompt below into a new comment on this PR to delegate the investigation to GitHub Copilot. It will look into the flakiness and open a separate pull request with you as reviewer.

@copilot The following spec(s) are flaky in CI (first seen on PR #26049, linked for reference only):

- `rspec ./spec/features/components/lookbook_accessibility_spec.rb[1:14:1]`

Treat this as a standalone task, unrelated to PR #26049. Create a new branch from origin/dev and open a new pull request targeting dev — do not stack it on PR #26049 or reuse that branch.

Follow the playbook in docs/development/testing/handling-flaky-tests/README.md to find the root cause and fix the underlying race — do not skip, delete, or weaken the spec to make it pass; disabling is a last resort per the playbook, and only with a bug ticket. Verify the fix by running the spec(s) repeatedly (e.g. `script/bulk_run_rspec --run-count 10`).

If you cannot reproduce the flake or are not confident in a fix after reasonable investigation, do not fabricate a change or skip the spec to force CI green. Instead, leave the pull request in draft and document what you tried, the suspected cause, and any leads in its description, then assign @ihordubas99 to take over.

Once the fix is verified, title the PR after the spec(s) it fixes, and use the PR description to explain the root cause, how the change resolves it, and the before/after results. Label the PR `flaky-spec`, assign @ihordubas99, and request a review from @ihordubas99.
On every commit, set @ihordubas99 as the sole co-author with a `Co-authored-by:` trailer (use their GitHub no-reply email so it links to their account), so it is traceable who dispatched the fix.

[github-actions]

Caution

The provided work package version does not match the core version

Details:

• Work package URL: https://community.openproject.org/wp/COMMS-1057
• Work package version: not set
• Core version: 18.0.0

Please make sure that:

• The work package version OR your pull request target branch is correct

[github-actions]

Caution

The Enterprise plan field is not set on the work package

Details:

• Work package URL: https://community.openproject.org/wp/COMMS-1057

Please make sure that:

• The work package Enterprise plan field is set

[github-actions]

Warning

Flaky specs

• rspec ./spec/features/work_packages/table/delete_work_packages_with_descendants_spec.rb[1:1:1]

🤖 Ask Copilot to investigate

Copy the prompt below into a new comment on this PR to delegate the investigation to GitHub Copilot. It will look into the flakiness and open a separate pull request with you as reviewer.

@copilot The following spec(s) are flaky in CI (first seen on PR #26049, linked for reference only):

- `rspec ./spec/features/work_packages/table/delete_work_packages_with_descendants_spec.rb[1:1:1]`

Treat this as a standalone task, unrelated to PR #26049. Create a new branch from origin/dev and open a new pull request targeting dev — do not stack it on PR #26049 or reuse that branch.

Follow the playbook in docs/development/testing/handling-flaky-tests/README.md to find the root cause and fix the underlying race — do not skip, delete, or weaken the spec to make it pass; disabling is a last resort per the playbook, and only with a bug ticket. Verify the fix by running the spec(s) repeatedly (e.g. `script/bulk_run_rspec --run-count 10`).

If you cannot reproduce the flake or are not confident in a fix after reasonable investigation, do not fabricate a change or skip the spec to force CI green. Instead, leave the pull request in draft and document what you tried, the suspected cause, and any leads in its description, then assign @ihordubas99 to take over.

Once the fix is verified, title the PR after the spec(s) it fixes, and use the PR description to explain the root cause, how the change resolves it, and the before/after results. Label the PR `flaky-spec`, assign @ihordubas99, and request a review from @ihordubas99.
On every commit, set @ihordubas99 as the sole co-author with a `Co-authored-by:` trailer (use their GitHub no-reply email so it links to their account), so it is traceable who dispatched the fix.

[Copilot]

🟡 Changes recommended

The KaTeX override forces a deprecated breaking release outside math-block’s declared dependency range.

1 open issue

• KaTeX override uses breaking 0.18.11 outside supported dependency range · New

1 file not reviewed

• frontend/package-lock.json: Generated file

_{Review effort: Balanced}

[judithroth]

Huh, this is again more complex than I hoped for.

Please add a drift guard to the hocuspocus tests:

• Install @blocknote/math-block as a devDependency.
• Assert that createMathBlockConfig() and mathInlineContentConfig deep-equal the server specs' configs (type, content, propSchema) that we added

This should prevent (silent) problems on Updates of BlockNote, if they somehow change the config.

I am also unsure about the esbuild addition, but I have to leave now, so you get this as early feedback so far.

Otherwise its quite cool. Saving as Markdown and also copy+paste works 🤩

[judithroth]

I think we should report this as a bug. Or at least ask in an issue at BlockNote if they regard it as a bug.

[ihordubas99]

Agreed, I reported it: TypeCellOS/BlockNote#3228 and TypeCellOS/BlockNote#3230.

While writing the issues I re-checked it on BlockNote 0.54.2, 0.55.0 and 0.56.0 in a clean project, and it turned out to be two separate problems. The stylesheet import keeps @blocknote/math-block from loading in Node at all, in any mode. The crash after an export is not specific to math-block. It happens with any React custom block in ServerBlockNoteEditor, and only with React's development build, so it would not hit our Docker image (which runs with NODE_ENV=production), but it would hit bin/dev and CI. I made the comment in mathSpecs.ts more precise about that.

[judithroth]

Please add a drift guard to the hocuspocus tests:

• Install @blocknote/math-block as a devDependency.
• Assert that createMathBlockConfig() and mathInlineContentConfig deep-equal the server specs' configs (type, content, propSchema).

To ensure that we don't run into inconsistencies on future updates of BlockNote.

[ihordubas99]

Done. @blocknote/math-block is now a hocuspocus devDependency, and the math tests check that the static specs match its configs and code/defining/isolating meta. They fail as soon as the specs differ. I'll add the same guard to the diagrams PR (#26157).

[github-actions]

Warning

Flaky specs

• rspec ./spec/features/work_packages/cancel_editing_spec.rb[1:5]

🤖 Ask Copilot to investigate

Copy the prompt below into a new comment on this PR to delegate the investigation to GitHub Copilot. It will look into the flakiness and open a separate pull request with you as reviewer.

@copilot The following spec(s) are flaky in CI (first seen on PR #26049, linked for reference only):

- `rspec ./spec/features/work_packages/cancel_editing_spec.rb[1:5]`

Treat this as a standalone task, unrelated to PR #26049. Create a new branch from origin/dev and open a new pull request targeting dev — do not stack it on PR #26049 or reuse that branch.

Follow the playbook in docs/development/testing/handling-flaky-tests/README.md to find the root cause and fix the underlying race — do not skip, delete, or weaken the spec to make it pass; disabling is a last resort per the playbook, and only with a bug ticket. Verify the fix by running the spec(s) repeatedly (e.g. `script/bulk_run_rspec --run-count 10`).

If you cannot reproduce the flake or are not confident in a fix after reasonable investigation, do not fabricate a change or skip the spec to force CI green. Instead, leave the pull request in draft and document what you tried, the suspected cause, and any leads in its description, then assign @ihordubas99 to take over.

Once the fix is verified, title the PR after the spec(s) it fixes, and use the PR description to explain the root cause, how the change resolves it, and the before/after results. Label the PR `flaky-spec`, assign @ihordubas99, and request a review from @ihordubas99.
On every commit, set @ihordubas99 as the sole co-author with a `Co-authored-by:` trailer (use their GitHub no-reply email so it links to their account), so it is traceable who dispatched the fix.