Pierre Integration Guard
Plannotator's code review UI wraps @pierre/diffs — an open-source diff renderer that uses Shadow DOM. The integration is concentrated in a single file but relies on undocumented internals (shadow DOM selectors, CSS variable names, grid layout assumptions). This skill helps verify changes don't break that contract.
Source of Truth
- Upstream repo: https://github.com/pierrecomputer/pierre/tree/main/packages/diffs
- Local types:
node_modules/@pierre/diffs/dist/(.d.tsfiles) - Integration point:
packages/review-editor/components/DiffViewer.tsx - Current version: check
packages/review-editor/package.jsonfor the pinned version
Always verify against the upstream repo or local .d.ts files — don't rely on memory of the API shape.
What We Import
import { FileDiff } from '@pierre/diffs/react';
import { getSingularPatch, processFile } from '@pierre/diffs';These are the only three imports. DiffViewer.tsx is the only file that touches Pierre.
API Surface to Guard
1. Component Props (FileDiff)
Read the current prop types from node_modules/@pierre/diffs/dist/react/index.d.ts or the upstream source. The props we use:
| Prop | Type | Notes | |
|---|---|---|---|
fileDiff | FileDiffMetadata | From getSingularPatch() or processFile() | |
options | FileDiffOptions<T> | See options table below | |
lineAnnotations | DiffLineAnnotation<T>[] | {side, lineNumber, metadata} | |
selectedLines | `SelectedLineRange \ | null` | {start, end, side} |
renderAnnotation | (ann) => ReactNode | Custom inline annotation renderer | |
renderHoverUtility | (getHoveredLine) => ReactNode | The + button on hover (deprecated upstream — watch for removal) |
2. Options Object
| Option | Value We Pass | Risk | |
|---|---|---|---|
themeType | `'dark' \ | 'light'` | Low — standard enum |
unsafeCSS | CSS string | High — targets internal selectors | |
diffStyle | `'split' \ | 'unified'` | Low — standard enum |
diffIndicators | 'bars' | Low | |
hunkSeparators | 'line-info' | Low | |
enableLineSelection | true | Low | |
enableHoverUtility | true | Medium — deprecated prop | |
onLineSelectionEnd | callback | Medium — signature could change |
3. Shadow DOM Selectors (via unsafeCSS)
These are the selectors we inject CSS rules against. They target data-* attributes inside Pierre's shadow DOM. If Pierre renames or removes any of these, our styling breaks silently.
Currently used:
:host— shadow root[data-diff]— root diff container[data-file]— file wrapper[data-diffs-header]— header bar[data-error-wrapper]— error display[data-virtualizer-buffer]— virtual scroll buffer[data-file-info]— file metadata row[data-column-number]— line number gutter[data-diffs-header] [data-title]— title (we hide it)[data-diff-type='split']— split layout mode[data-overflow='scroll']/[data-overflow='wrap']— overflow mode
4. CSS Variables We Override
We override these --diffs-* variables to theme Pierre:
--diffs-bg,--diffs-fg— base colors--diffs-dark-bg,--diffs-light-bg— theme-specific backgrounds--diffs-dark,--diffs-light— theme-specific foregrounds
5. CSS Variables We Inject (Custom)
We set these on a wrapper div outside the shadow DOM, relying on CSS custom property inheritance:
--split-left,--split-right— control the split pane grid ratio
The unsafeCSS grid override references these: grid-template-columns: var(--split-left, 1fr) var(--split-right, 1fr). The 1fr fallback ensures the layout is safe if the variables aren't set.
6. Grid Layout Assumption
Pierre's split view uses CSS Grid with grid-template-columns: 1fr 1fr. We override this for the resizable split pane. If Pierre changes its layout engine (e.g., to flexbox or a different grid structure), the override will stop working.
How to verify: In the upstream source, search for grid-template-columns in the diff component styles.
Verification Checklist
When reviewing changes that touch the Pierre integration, check:
Props & Types
- Read the current
.d.tsfiles to confirm prop names and types haven't changed - Check if
renderHoverUtilityis still supported (it's deprecated — may be removed) - Verify
DiffLineAnnotationstill usesside: 'deletions' | 'additions'(not'old' | 'new') - Confirm
SelectedLineRangeshape:{start, end, side?}
Shadow DOM Selectors
- Grep the upstream source for each
data-*attribute we target inunsafeCSS - If upgrading the package version, diff the old and new CSS/HTML output for renamed attributes
- Test both
splitandunifiedviews — selectors are layout-dependent
CSS Variables
- Grep upstream for
--diffs-bg,--diffs-fg, and other variables we override - Verify the variable names haven't been renamed or removed
- Check that
!importantis still needed (Pierre may change specificity)
Theme Compliance
- New UI elements must use theme tokens (
bg-border,bg-primary, etc.), not hardcoded colors likebg-blue-500 - The existing
ResizeHandlecomponent inpackages/ui/components/ResizeHandle.tsxsets the visual convention — match it
Build & Runtime
- Run
bun run dev:reviewand verify the diff renders in both split and unified modes - Check the browser console for Pierre warnings (e.g.,
parseLineType: Invalid firstChar) - Test with add-only and delete-only files (Pierre doesn't render split grid for these)
- If changing UI code, remember build order:
bun run --cwd apps/review build && bun run build:hook
When Upgrading @pierre/diffs
- Check the upstream changelog / commit history at https://github.com/pierrecomputer/pierre
- Diff the
.d.tsfiles between old and new versions:# Before upgrading, snapshot current types cp -r node_modules/@pierre/diffs/dist /tmp/pierre-old # After upgrading diff -r /tmp/pierre-old node_modules/@pierre/diffs/dist - Search for renamed/removed data attributes in the new version
- Run through the full verification checklist above
- Test the resizable split pane — it depends on grid layout internals