# Start Here

> The Pierre monorepo hosts two production-grade open source UI libraries — @pierre/diffs for pixel-perfect, virtualized code diffs and @pierre/trees for high-performance file trees — plus the documentation site that showcases them. This page gives the 30-minute orientation: what matters, entry points to open first, vocabulary, and recommended first files.

- Repository: pierrecomputer/pierre
- GitHub: https://github.com/pierrecomputer/pierre
- Human wiki: https://grok-wiki.com/public/wiki/pierrecomputer-pierre-fac2c554b845
- Complete Markdown: https://grok-wiki.com/public/wiki/pierrecomputer-pierre-fac2c554b845/llms-full.txt

## Source Files

- `README`
- `package.json`
- `AGENTS.md`
- `apps/docs/package.json`
- `scripts/wt.ts`

---

<details>
<summary>Relevant source files</summary>
The following files were used as context for generating this wiki page:
- [README](README)
- [package.json](package.json)
- [AGENTS.md](AGENTS.md)
- [apps/docs/package.json](apps/docs/package.json)
- [scripts/wt.ts](scripts/wt.ts)
- [packages/diffs/package.json](packages/diffs/package.json)
- [packages/diffs/README.md](packages/diffs/README.md)
- [packages/diffs/src/index.ts](packages/diffs/src/index.ts)
- [packages/diffs/src/components/Virtualizer.ts](packages/diffs/src/components/Virtualizer.ts)
- [packages/trees/package.json](packages/trees/package.json)
- [packages/trees/README.md](packages/trees/README.md)
- [tsconfig.json](tsconfig.json)
- [apps/docs/lib/product-config.ts](apps/docs/lib/product-config.ts)
</details>

# Start Here

This page orients anyone opening the `pierrecomputer/pierre` repository for the first time. In under 30 minutes you will know what the monorepo contains, which two published UI libraries are the reason it exists, how to run its code, and which files reward reading first. Everything else—internal packages, scripts, and the docs site—exists to support those two libraries and the documentation that showcases them.

The repository is a Bun-based TypeScript monorepo that ships `@pierre/diffs` (a Shiki-powered library for rendering code files and diffs) and `@pierre/trees` (a path-first, shadow-DOM file tree component). A single Next.js application in `apps/docs` serves the public documentation sites for both libraries plus an internal “diffshub” variant. Strict monorepo rules (catalog dependencies, root-only lint/format, worktree port isolation, project references) keep the published packages small and consistent.

## The Two Published Libraries

### @pierre/diffs
A production diff and code-file rendering library. It accepts raw patches, two versions of a file, or arbitrary text, then produces split or unified views with syntax highlighting, inline annotations, line selection, and accept/reject UI. Rendering is virtualized for large files; theming reuses Shiki themes (including CSS variable themes) and automatically follows light/dark.

Public entry points (from package.json):
- `@pierre/diffs` – core components and highlighter APIs
- `@pierre/diffs/react` – React wrappers
- `@pierre/diffs/ssr` – server-side rendering helpers
- `@pierre/diffs/worker` – off-main-thread diff computation

Key source modules include `VirtualizedFileDiff`, `Virtualizer`, `FileDiff`, `CodeView`, and the Shiki language/theme resolvers. The package depends on `diff`, `shiki`, and the internal `@pierre/theme` package.

Sources: [packages/diffs/package.json:20-50](), [packages/diffs/README.md:1-35](), [packages/diffs/src/index.ts:1-45](), [packages/diffs/src/components/Virtualizer.ts:1-15]()

### @pierre/trees
A high-performance file tree that stores all public state by canonical path strings rather than numeric IDs. The implementation lives in one place and is exposed through four entry points so the same model works in vanilla JS, React, SSR, and web components. The tree renders inside a shadow root, supports search, git status badges, custom icons, keyboard navigation, and context menus. Large trees use a prepared-input path that avoids re-sorting on every render.

Public entry points:
- `@pierre/trees` – `FileTree` model class and `prepare*Input` helpers
- `@pierre/trees/react` – `useFileTree`, `FileTree` component, selection/search hooks
- `@pierre/trees/ssr` – `preloadFileTree` for declarative shadow DOM
- `@pierre/trees/web-components` – side-effect registration

The tree depends on the internal `@pierre/path-store` workspace package for its efficient model. The package ships extensive benchmarks and Playwright E2E tests that specifically cover sticky-header drift and scroll performance.

Sources: [packages/trees/package.json:1-70](), [packages/trees/README.md:1-60]()

## Documentation and Demo Sites

`apps/docs` is a Next.js 16 application that builds the three published packages (`diffs`, `trees`, `truncate`) on every dev and prod build. It then serves three distinct sites from the same binary, switched by the `NEXT_PUBLIC_SITE` environment variable:

- `diffs` → diffs.com (or local :3690)
- `trees` → trees.software (or local :3691)
- `diffshub` → internal hub (or local :3692)

The site uses route groups `(diffs)`, `(trees)`, and `(diffshub)` plus a shared component library and MDX documentation. `apps/demo` exists for quick local Vite-based experiments (primarily path-store and tree visuals).

Sources: [apps/docs/package.json:5-35](), [apps/docs/lib/product-config.ts:1-30](), [apps/docs/app/layout.tsx:1-30]()

## Monorepo Layout and Entry Points

```
.
├── packages/
│   ├── diffs/          # published @pierre/diffs (tsdown → dist/)
│   ├── trees/          # published @pierre/trees (depends on path-store)
│   ├── truncate/       # small published utility, used by docs
│   ├── path-store/     # internal model for trees + benchmarks
│   └── ...
├── apps/
│   ├── docs/           # Next.js multi-site docs (builds the libs first)
│   └── demo/           # Vite playground
├── scripts/
│   ├── wt.ts           # worktree + port-offset manager
│   ├── ws.ts           # workspace script runner (“bun ws <pkg> <task>”)
│   └── run-dev.sh      # port-cleaner used by all dev scripts
├── package.json        # catalog + root scripts only
└── tsconfig.json       # project references to every package/app
```

All TypeScript projects answer to `bun run tsc`. The root `tsconfig.json` wires project references so editor and `tsgo` type-checking stay fast and accurate.

Sources: [tsconfig.json:1-15](), [package.json:3-20]()

## Development Workflow (AGENTS.md Rules)

You must follow these conventions; they are enforced by CI and by every maintainer.

- **Always use Bun.** Never `npm`, `pnpm`, or `npx` inside the repo.
- **Catalog dependencies only.** Add a version once in the root `package.json` under `workspaces.catalog`, then reference it as `"foo": "catalog:"` in any package. Never run `bun add` inside a package directory.
- **Lint and format from the root only.** `bun run lint`, `bun run format`, `bun run lint:css`. After any code change you are not done until these pass plus the relevant `bun run tsc`.
- **AGENT=1 for tests.** `export AGENT=1` before `bun test` so Bun’s runner emits AI-friendly output.
- **No O(n²) loops.** Calculate expensive values once before the loop; scan backwards when you only need the last interesting index.
- **Helper comments.** Every non-trivial function gets a one-sentence plain-English comment above its declaration explaining what data it transforms and why it exists.
- **Worktrees for parallel work.** `bun run wt new <slug>` creates an isolated checkout at `~/pierre/pierre-worktrees/<slug>` with its own port offset. All dev servers (3690/3691/4174/9222 etc.) are shifted so multiple agents or branches never collide. Always run `bun run wt clean` before you finish.

Sources: [AGENTS.md:1-30](), [AGENTS.md:80-120](), [scripts/wt.ts:1-60]()

## Most Useful Root Scripts

| Command                  | Purpose                                      |
|--------------------------|----------------------------------------------|
| `bun run wt new <slug>`  | Create isolated worktree + port offset       |
| `bun run wt clean`       | Kill stale processes on all managed ports    |
| `bun run lint && bun run format` | Required after any edit               |
| `bun run tsc`            | Type-check every package (uses tsgo)         |
| `bun ws <pkg> <task>`    | Run a script inside one workspace package    |
| `bun run docs:build`     | Build docs + all three published libs        |
| `bun run icons:sprite`   | Regenerate SVG sprite used by diffs          |

Sources: [package.json:60-85]()

## Recommended First 30-Minute Reading Order

1. [packages/diffs/README.md](packages/diffs/README.md) and [packages/trees/README.md](packages/trees/README.md) – the public contract and examples.
2. The `exports` block of each package’s `package.json` – exactly what consumers can import.
3. [AGENTS.md](AGENTS.md) (first 60 lines) – the non-negotiable rules.
4. [apps/docs/lib/product-config.ts](apps/docs/lib/product-config.ts) – how the same Next.js app becomes three different sites.
5. One source file from each library, e.g. `packages/diffs/src/components/Virtualizer.ts` and the `FileTree` constructor in trees, to see the performance focus in practice.
6. [scripts/wt.ts](scripts/wt.ts) header comments – why the worktree/port system exists.

After those six files you will understand the product, the constraints, and the exact commands you will type every day.

## Quick Vocabulary

- **catalog:** – Bun workspace dependency indirection defined once at the root.
- **preparedInput** – Trees optimization: pre-sort and pre-build the tree model once, then hand the result to `FileTree`.
- **Virtualizer / VirtualizedFileDiff** – Diffs windowing layer that only renders the visible scroll window.
- **port offset** – Integer added to every well-known port when you are inside a worktree so 3690, 9222, etc. never conflict.
- **tsgo** – The fast native TypeScript checker used by most `tsc` scripts.
- **shadow root** – Trees renders its DOM inside an open shadow root for style encapsulation.
- **ws / wt** – The two custom Bun scripts (`scripts/ws.ts`, `scripts/wt.ts`) that replace `npm --workspace` and `git worktree` ergonomics.

## Summary

The repository’s only public deliverables are two small, well-tested, Apache-2.0 UI libraries plus the documentation that proves they work. Everything else—worktree tooling, catalog discipline, root-only quality gates, and the multi-site docs build—is infrastructure that keeps those two packages reliable and pleasant to maintain. Read the two READMEs, the AGENTS rules, and the package.json exports blocks first; you will then know exactly where to look for any subsequent question.

Sources: [packages/trees/README.md:1-25](), [AGENTS.md:10-45](), [package.json:60-80]()