Files
PaperClipAI/ui
95ba0a7de6 fix(ui): keep translated pages from crashing on React DOM updates (#22463)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - The board UI is a React app, and the browser error monitor reports
render failures from its route error boundary
> - Some people read the board with browser page translation (Chrome or
Google Translate) turned on
> - Translation replaces React-owned text nodes, or moves them into
`<font>` wrappers. React does not support this (facebook/react#11538)
> - The next React commit that removes such a node, or inserts before
it, gets `NotFoundError` from `removeChild` or `insertBefore`. The route
error boundary then replaces the page
> - Three production error reports show this exact shape. Each has the
existing `translation_marker: true` diagnostic, so the cause is
confirmed and not a guess
> - This pull request adds a narrow DOM guard that does what React asked
for only on a translated page
> - The benefit is that translated pages stay usable, and real DOM
errors still reach the error monitor

## Linked Issues or Issue Description

Refs facebook/react#11538

**What happened?**
A person used the board with browser page translation turned on (locale
`es-419`). After the page changed, the route error boundary showed an
error. The error monitor recorded `NotFoundError: Failed to execute
'removeChild' on 'Node': The node to be removed is not a child of this
node.` A second report from the same kind of session recorded the
`insertBefore` form of the same error.

**Steps to reproduce**
1. Open a board page that updates its text, for example a task whose
status changes.
2. Use the browser to translate the page into another language.
3. Let the page update so that React removes or moves a translated text
node.
4. The route error boundary replaces the page.

**Expected behavior**
The page keeps working while it is translated.

**Environment**
Hosted board, production build, Chrome page translation active
(`translated-ltr` class on `<html>`).

## What Changed

- Add `ui/src/lib/translation-dom-guard.ts`. It wraps
`Node.prototype.removeChild` and `Node.prototype.insertBefore`. The
wrapper acts only when both conditions are true: the page has the
translation marker class, and the node is detached or is still inside
the parent. In that case it removes the node from its real parent, or
inserts before the translation wrapper. A `MutationObserver` records
which `<font>` replaced each detached text node. For a `replaceChild`,
that is the added `<font>`. For an insert followed by a remove, it is
the `<font>` inserted next to that text node. The guard uses it only if
it is still next to the removed text, so it never takes a neighbor's
translation. When React removes a detached text node, the guard also
removes that translated replacement, so the old text does not stay on
the page. When React inserts before a detached node, the guard inserts
before its replacement, or appends if there is none. All other calls go
to the native method without change.
- Install the guard in `ui/src/main.tsx` before the first render. Only
the first call installs it, and its stop function restores the native
methods.
- Move the translation-marker check in `browser-error-context.ts` into
an exported `hasPageTranslationMarker()` helper. The guard and the error
diagnostic now read the same signal. The diagnostic output does not
change.
- Add `translation-dom-guard.test.tsx`. It renders real React in jsdom
and does what translation does to a text node. This includes a replace
in one step, an insert followed by a remove, and two adjacent text nodes
translated right to left and left to right.

## Verification

- Red: with a no-op guard, the new tests fail with the same
`NotFoundError` that production recorded. Against the first version of
this guard, the three replacement tests fail (the translated text stayed
on the page). Against the second version, the right-to-left two-node
test fails (the neighbor's translation was deleted).
- Green: `cd ui && npx vitest run src/lib/translation-dom-guard.test.tsx
src/lib/browser-error-context.test.ts src/lib/sentry.test.ts
src/lib/sentry-package-version.test.ts` passes (4 files, 66 tests).
- The tests also prove that the native errors stay on a page that is not
translated, and for a node outside the parent on a translated page.
- `tsc --noEmit -p ui/tsconfig.json` shows no errors in the changed
files. The local run had only the UI dependencies installed, so
unrelated packages that were not built (plugin SDK, runner protocol)
showed errors that were already there. Required CI does the full
typecheck, test, and build.
- I did not run a real Chrome translation session. The jsdom test makes
the same DOM change that translation makes.

## Risks

- The guard changes two global DOM methods. Untranslated pages pay one
extra property comparison per call. The translation check runs only when
the parent does not match.
- The `MutationObserver` watches child-list changes on the whole
document. Its callback only checks records that remove one text node,
and it keeps replacements in a `WeakMap`, so detached nodes can still be
garbage collected.
- On a translated page, a real bug that removes a detached node, or that
inserts before a node inside a nested element, is no longer reported.
This is limited to translated pages, which already showed this crash.
- If translation detaches a node without a `<font>` replacement that the
observer saw, removal leaves the page as it is, and an insert goes at
the end of the parent. The page does not crash.

## Model Used

- Claude Opus 5.5 (`claude-opus-5-5`), with tool use and code execution
in an agent workspace.

## Checklist

- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [ ] All Paperclip CI gates are green
- [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: paperclipbugbot <356415228+paperclipbugbot@users.noreply.github.com>
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-21 03:57:16 -08:00
..
…

@paperclipai/ui

Published static assets for the Paperclip board UI.

What gets published

The npm package contains the production build under dist/. It does not ship the UI source tree or workspace-only dependencies.

Storybook

Storybook config, stories, and fixtures live under ui/storybook/.

pnpm --filter @paperclipai/ui storybook
pnpm --filter @paperclipai/ui build-storybook

Typical use

Install the package, then serve or copy the built files from node_modules/@paperclipai/ui/dist.

Editor dependency identity

Keep the root and workspace overrides for @codemirror/state, @codemirror/view, and @lezer/common aligned. CodeMirror requires shared extension identity, while Lezer parsers and syntax highlighters require shared NodeProp IDs. Multiple Lezer copies can crash code-block highlighting with tags is not iterable. src/lib/codemirror-single-instance.test.ts checks the installed dependency graph and highlights sample code through the editor's real language dependencies. GitHub Actions owns regeneration of pnpm-lock.yaml.