[diffs] Custom Header Feature

[amadeus]

This branch adds custom header rendering to diffs/files and refactors theming so host-level styles are applied more reliably across SSR, hydration, and re-renders.

Ultimately this is a bit of a sidequest for the proper CodeViewer component, coming soon-ish.

What Changed

• Added renderCustomHeader support across vanilla + React diff/file APIs, so consumers can fully replace the built-in header content.
  • Kept renderHeaderPrefix and renderHeaderMetadata for partial customization of the default header layout.
• Simplified diff header callback signatures to receive FileDiffMetadata directly (instead of wrapper objects with optional fields).
• Reworked theme style handling to host-scoped style injection (data-theme-css) instead of relying on inline theme styles on wrappers.
  • Added a new CSS layer structure (base, theme, rendered, unsafe) and a theme CSS wrapper utility to improve layering consistency.
  • Improved render/hydration behavior by caching applied theme/unsafe CSS and avoiding unnecessary style node churn on re-render.
• Updated docs and examples (including a richer custom-header demo) to cover prefix/metadata/custom-header usage and callback argument expectations.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
pierrejs-diff-demo	Ready	Preview	Mar 26, 2026 7:52am
pierrejs-docs	Ready	Preview	Mar 26, 2026 7:52am

[Copilot]

Pull request overview

Adds a “custom header” rendering mode to the diffs package and refactors theming so highlighter theme CSS is applied at the shadow-host level (instead of inline styles / data attributes), with corresponding SSR + React wrapper updates.

Changes:

• Introduces renderCustomHeader / headerRenderMode plumbing across core renderers, components, SSR helpers, and React wrappers.
• Moves theme application from per-node inline styles / data-theme-type to a host-scoped <style data-theme-css> node (plus new CSS layer ordering).
• Updates docs/demo examples and snapshot tests to match the new header + theming output.

Reviewed changes

Copilot reviewed 43 out of 43 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
packages/diffs/test/createFileHeaderElement.test.ts	Adds snapshot coverage for default vs custom header AST.
packages/diffs/test/snapshots/patchFileRender.test.ts.snap	Updates snapshots for removed inline theme attrs/styles and new data-diffs-header value.
packages/diffs/test/snapshots/createFileHeaderElement.test.ts.snap	New snapshots for createFileHeaderElement default/custom modes.
packages/diffs/test/snapshots/DiffHunksRendererVirtualization.test.ts.snap	Snapshot updates for theming/header attribute changes.
packages/diffs/test/snapshots/DiffHunksRender.test.ts.snap	Snapshot updates for theming/header attribute changes.
packages/diffs/src/utils/setWrapperNodeProps.ts	Removes theme-related inline styles and data-theme-type from <pre>.
packages/diffs/src/utils/renderFileWithHighlighter.ts	Stops returning baseThemeType; returns { code, themeStyles }.
packages/diffs/src/utils/renderDiffWithHighlighter.ts	Stops returning baseThemeType; returns { code, themeStyles }.
packages/diffs/src/utils/hostTheme.ts	Adds helpers to upsert/remove the host-scoped theme <style> node.
packages/diffs/src/utils/cssWrappers.ts	Adds wrapThemeCSS() and updates layer order to include rendered.
packages/diffs/src/utils/createStyleElement.ts	Adds createThemeStyleElement() for SSR/AST style injection.
packages/diffs/src/utils/createPreElement.ts	Removes theme props from pre AST; only sets line-number width CSS var inline.
packages/diffs/src/utils/createFileHeaderElement.ts	Adds mode and custom-header slot rendering.
packages/diffs/src/utils/arePrePropertiesEqual.ts	Removes theme props from pre equality comparison.
packages/diffs/src/types.ts	Introduces FileHeaderRenderMode, updates header callback signatures, adds theme style cache type.
packages/diffs/src/style.css	Updates layering, removes data-theme-type styling paths, scopes header styling to default mode.
packages/diffs/src/ssr/preloadFile.ts	SSR now emits <style data-theme-css> and sets header mode based on renderCustomHeader.
packages/diffs/src/ssr/preloadDiffs.ts	SSR now emits <style data-theme-css> and sets header mode based on renderCustomHeader.
packages/diffs/src/renderers/UnresolvedFileHunksRenderer.ts	Aligns unresolved renderer option types with new DiffHunksRendererOptions.
packages/diffs/src/renderers/FileRenderer.ts	Adds headerRenderMode, removes baseThemeType handling, makes mergeOptions public.
packages/diffs/src/renderers/DiffHunksRenderer.ts	Adds headerRenderMode to renderer options/defaults; removes baseThemeType handling.
packages/diffs/src/react/utils/useUnresolvedFileInstance.ts	Threads hasCustomHeader and forces slot presence via noop render hook.
packages/diffs/src/react/utils/useFileInstance.ts	Threads hasCustomHeader and forces slot presence via noop render hook.
packages/diffs/src/react/utils/useFileDiffInstance.ts	Uses parsed fileDiff directly; threads hasCustomHeader and forces slot presence via noop render hook.
packages/diffs/src/react/utils/renderFileChildren.tsx	Adds React slot rendering for renderCustomHeader.
packages/diffs/src/react/utils/renderDiffChildren.tsx	Adds React slot rendering for renderCustomHeader and simplifies header callback args.
packages/diffs/src/react/types.ts	Adds renderCustomHeader and updates header callback signatures to accept FileDiffMetadata.
packages/diffs/src/react/UnresolvedFile.tsx	Wires renderCustomHeader through to children + instance options.
packages/diffs/src/react/PatchDiff.tsx	Wires renderCustomHeader through to children + instance options.
packages/diffs/src/react/MultiFileDiff.tsx	Parses fileDiff via parseDiffFromFile and wires renderCustomHeader.
packages/diffs/src/react/FileDiff.tsx	Wires renderCustomHeader through to children + instance options.
packages/diffs/src/react/File.tsx	Wires renderCustomHeader through to children + instance options.
packages/diffs/src/constants.ts	Adds CUSTOM_HEADER_SLOT_ID and THEME_CSS_ATTRIBUTE.
packages/diffs/src/components/UnresolvedFile.ts	Fixes return undefined; to return; in void methods.
packages/diffs/src/components/FileStream.ts	Applies theme via host-scoped style node and caches theme state.
packages/diffs/src/components/FileDiff.ts	Applies theme via host-scoped style node; adds custom header slot handling + caching.
packages/diffs/src/components/File.ts	Applies theme via host-scoped style node; adds custom header slot handling + caching.
apps/docs/app/page.tsx	Small refactor in docs page rendering for custom header section.
apps/docs/app/docs/VanillaAPI/constants.ts	Updates example header callback signature usage.
apps/docs/app/docs/ReactAPI/constants.ts	Updates example header callback signature usage.
apps/docs/app/diff-examples/CustomHeader/constants.ts	Simplifies custom header example setup and options.
apps/docs/app/diff-examples/CustomHeader/CustomHeader.tsx	Updates docs example to toggle between metadata vs fully custom header mode.
apps/demo/src/main.ts	Simplifies theme toggling across all instance collections.

Comments suppressed due to low confidence (1)

packages/diffs/src/style.css:1367

• Header container styling is now scoped to [data-diffs-header='default']. In custom header mode, the header element will not receive the shared header shell behavior (positioning, padding, z-index, min-height, etc.), which likely breaks sticky header/layout expectations for custom headers. If custom headers are meant to render inside the same shell, consider applying the container-level styles to [data-diffs-header] and only keeping the metadata/additions/deletions sub-rules scoped to 'default'.

  [data-diffs-header='default'] {
    position: relative;
    display: flex;
    flex-direction: row;
    justify-content: space-between;
    align-items: center;
    gap: var(--diffs-gap-inline, var(--diffs-gap-fallback));
    min-height: calc(
      1lh + (var(--diffs-gap-block, var(--diffs-gap-fallback)) * 3)
    );
    padding-inline: 16px;
    top: 0;
    z-index: 2;
  }

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.