pierrecomputer/pierre

The @pierre/diffs library is an open source diff and file rendering library built on Shiki. It is available as vanilla JavaScript and React components. Key features include:

• Diff file versions, patches, and arbitrary files
• Split or stacked layout
• Automatic adaptation to Shiki themes
• Support for light and dark mode
• Options for diff highlight styles, in-line highlighting, wrapping, line numbers, and more
• Support for custom fonts and font-feature-settings
• Flexible annotation framework for injecting comments and annotations
• Custom UI for accept/reject changes
• Line selection and highlighting

Diffs is a library designed for rendering code and diffs on the web. It leverages Shiki for syntax highlighting, providing extensive theme and language support.

Key architectural features:

• HTML-centric: Lower-level APIs render raw HTML strings for high performance and flexibility.
• Rendering modes: Higher-order components consume these strings to render into Shadow DOM and CSS grid layouts.
• Framework support: Currently provides components for both vanilla JavaScript and React (React components are equivalents to the vanilla versions).

Trees uses a path-first identity model across all runtimes (React, vanilla, and SSR). Canonical path strings serve as the public identity for all tree items. You should use paths for:

• Selection values
• Focused-item lookups
• Search matches
• Rename and drag-and-drop events
• Git status attachment
• Row annotations

Note that files and directories share the same identity space; the APIs will specify the item kind when necessary.

The Pierre Theme is available in several variants for different accessibility needs and environments:

Standard Variants:

• Pierre Light
• Pierre Dark
• Pierre Light Soft
• Pierre Dark Soft
• Pierre Light Protanopia & Deuteranopia
• Pierre Dark Protanopia & Deuteranopia
• Pierre Light Tritanopia
• Pierre Dark Tritanopia

Web-use only variants:

• Pierre Light Vibrant
• Pierre Dark Vibrant

The library uses three distinct concepts for themes:

1. theme name: A stable, serializable string (e.g., pierre-dark) used as a key for catalogs, resolvers, and storage. This is what you should keep in application state.
2. theme descriptor: A catalog entry containing the name, optional metadata (displayName, collection, colorScheme), and a lazy load() function. Descriptors allow listing themes without loading their JSON.
3. resolved theme object: The actual theme object returned by a loader. It is a Shiki/VS Code-like object containing colors, fg, bg, type, and name after normalization.

Recommendation: Keep the theme name in state/storage, use descriptors for UI menus/metadata, and use the resolved theme object only when coloring the UI or passing it to Shiki.

The Pierre ecosystem uses a layered approach for themes and rendering:

1. @pierre/theme: The foundation. It supplies the raw theme objects.
2. @pierre/theming: The logic layer. It selects, resolves, and maps the theme objects provided by @pierre/theme.
3. @pierre/diffs and @pierre/trees: The consumer layer. These packages use the themes selected/resolved by the theming layer to render code and file trees.

CVD themes in Pierre are engineered using four core principles to ensure accessibility without losing the brand identity:

1. Identical chrome: The base light/dark roles for bg, fg, and border are used verbatim. Only chromatic roles (accent, states, syntax, ansi) change.
2. Signals ride the preserved axis: Meaningful colors are re-mapped to the hue axis preserved by the deficiency:
   • Protan/Deutan: Positive/added $\rightarrow$ blue; Negative/deleted $\rightarrow$ orange.
   • Tritan: Positive/added $\rightarrow$ teal/cyan; Negative/deleted $\rightarrow$ red/vermillion.
3. Luminance as a backup: When multiple roles must share a hue pole, they are separated by luminance (different palette stops).
4. Palette reuse: All colors are sourced from existing scales in src/palettes.ts (e.g., blue, orange, teal, vermillion).

Select an API based on your specific requirement for theme management:

• Collections API: Use this to create a collection, catalog, descriptor, or bundled theme set.
• Resolver API: Use this to register, load, seed, or cache theme objects.
• Controller API: Use this to track the color mode and selected light and dark themes.
• Colors API: Use this to normalize workbench colors or derive colors.
• React API: Use this to read controller state within a React application.

CodeView is a high-level API for rendering a single large scroll region containing a mixed list of file and diff items. It manages virtualization, measured layout reconciliation, sticky headers, selection, and scrollTo targeting.

Core Data Model

• Stable IDs: Every item must have a unique id for reconciliation and targeting.
• Item Types: Items are either { type: 'file', file } or { type: 'diff', fileDiff }.
• Versioning: If you change an item's content or annotations while keeping the same id, you must increment the version property to trigger efficient updates.
• Selection: Selection is viewer-wide. The payload shape is { id, range }.
• Collapsed State: Use the collapsed property to show/hide content. Update version when toggling this.
• Edit Mode: Use the edit property to enable editing for an item.

The Pierre theme package provides two distinct variants:

• Pierre Light: A light theme featuring warm orange accents.
• Pierre Dark: A dark theme featuring warm orange accents.

To add the agent skill for this package using the Skills CLI, run:

npx skills add pierrecomputer/pierre --skill trees