pierre-guard

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.ts files)
• Integration point: packages/review-editor/components/DiffViewer.tsx
• Current version: check packages/review-editor/package.json for 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.ts files to confirm prop names and types haven't changed
• Check if renderHoverUtility is still supported (it's deprecated — may be removed)
• Verify DiffLineAnnotation still uses side: 'deletions' | 'additions' (not 'old' | 'new')
• Confirm SelectedLineRange shape: { start, end, side? }

Shadow DOM Selectors

• Grep the upstream source for each data-* attribute we target in unsafeCSS
• If upgrading the package version, diff the old and new CSS/HTML output for renamed attributes
• Test both split and unified views — 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 !important is still needed (Pierre may change specificity)

Theme Compliance

• New UI elements must use theme tokens (bg-border, bg-primary, etc.), not hardcoded colors like bg-blue-500
• The existing ResizeHandle component in packages/ui/components/ResizeHandle.tsx sets the visual convention — match it

Build & Runtime

• Run bun run dev:review and 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

1. Check the upstream changelog / commit history at https://github.com/pierrecomputer/pierre
2. Diff the .d.ts files 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
   

3. Search for renamed/removed data attributes in the new version
4. Run through the full verification checklist above
5. Test the resizable split pane — it depends on grid layout internals