# After 30 Minutes — Next Reads & Tasks

> You now understand the monorepo shape, the two libraries, the contributor contract (bun only, catalog, root lint+format, worktree cleanup), and the performance invariants (no nested loops, pre-calculate before iteration). This page lists the exact next files and commands: run a package test, study visible-tree-projection or UniversalRenderingManager, add a small feature, and the living glossary of Pierre terms (catalog:, PIERRE_PORT_OFFSET, prepareFileTreeInput, DiffHunksRenderer, oxfmt, AGENT=1, visible projection, worktree).

- 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

- `AGENTS.md`
- `packages/diffs/src/managers/UniversalRenderingManager.ts`
- `packages/path-store/src/visible-tree-projection.ts`
- `packages/trees/TESTING.md`
- `packages/diffs/scripts/benchmarkParseMergeConflictDiffFromFile.ts`
- `packages/path-store/scripts/benchmark.ts`
- `CLAUDE.md`

---

<details>
<summary>Relevant source files</summary>
The following files were used as context for generating this wiki page:
- [AGENTS.md](AGENTS.md)
- [CLAUDE.md](CLAUDE.md)
- [packages/diffs/src/managers/UniversalRenderingManager.ts](packages/diffs/src/managers/UniversalRenderingManager.ts)
- [packages/path-store/src/visible-tree-projection.ts](packages/path-store/src/visible-tree-projection.ts)
- [packages/trees/test/TESTING.md](packages/trees/test/TESTING.md)
- [packages/diffs/scripts/benchmarkParseMergeConflictDiffFromFile.ts](packages/diffs/scripts/benchmarkParseMergeConflictDiffFromFile.ts)
- [packages/path-store/scripts/benchmark.ts](packages/path-store/scripts/benchmark.ts)
- [package.json](package.json)
- [packages/trees/src/preparedInput.ts](packages/trees/src/preparedInput.ts)
- [packages/diffs/src/renderers/DiffHunksRenderer.ts](packages/diffs/src/renderers/DiffHunksRenderer.ts)
- [scripts/wt.ts](scripts/wt.ts)
- [packages/diffs/src/index.ts](packages/diffs/src/index.ts)
- [packages/trees/src/index.ts](packages/trees/src/index.ts)
- [packages/path-store/src/index.ts](packages/path-store/src/index.ts)
</details>

# After 30 Minutes — Next Reads & Tasks

After your first 30 minutes in the pierrecomputer/pierre monorepo, you have seen the high-level shape: a Bun-based TypeScript monorepo with two primary libraries (`diffs` for rich diff rendering and `trees`/`path-store` for high-performance file tree state and UI), plus supporting packages (`truncate`, `storage-elements`, test data). You have internalized the contributor contract from the agent instructions and the performance culture that keeps hot paths fast.

This page gives you the exact next files, commands, and a living glossary so you can move from orientation to useful work without violating invariants (bun-only, catalog dependencies, root-only lint/format, worktree cleanup, no nested loops).

## The Two Libraries at a Glance

- **diffs** (`packages/diffs`): Renders diffs as virtualized HAST trees with syntax highlighting (Shiki), hunk expansion, annotations, and split/unified views. Key export: `DiffHunksRenderer`.
- **trees + path-store** (`packages/trees`, `packages/path-store`): `PathStore` + `prepareFileTreeInput` feed a virtualized file tree; `createVisibleTreeProjection` builds ARIA-aware sibling metadata using typed arrays instead of maps.

Everything else (apps, scripts, test fixtures) exists to exercise these two libraries under realistic Git-scale loads.

Sources: [packages/diffs/src/index.ts:1-50](), [packages/trees/src/index.ts:1-30](), [packages/path-store/src/index.ts:1-30]()

## Recommended Next Reads (Study These Immediately)

### 1. `packages/path-store/src/visible-tree-projection.ts`
The clearest example of the performance contract in action. It builds a preorder projection of visible rows using `Int32Array` for parent indices, child counts, and last-row-at-depth tracking, then lazily materializes the `visibleIndexByPath` map only when needed.

```ts
// Calculate once upfront, typed arrays, no per-iteration Maps
const parentRowIndex = new Int32Array(rowCount);
// ...
lastRowAtDepth = ensureDepthCapacity(lastRowAtDepth, depth);
```

Read the whole 115-line file. Then look at its callers in `projection.ts` and the benchmark in `packages/path-store/scripts/benchmarkVisibleTreeProjection.ts`.

Sources: [packages/path-store/src/visible-tree-projection.ts:19-115](), [packages/path-store/src/visible-tree-projection.ts:27-43]()

### 2. `packages/diffs/src/managers/UniversalRenderingManager.ts`
A tiny (37-line) rAF batching utility with a self-deprecating TODO. It is the shared render scheduler used by diff components to coalesce updates. Even though small, it demonstrates the "universal" rendering concerns that cross the virtualized components.

Sources: [packages/diffs/src/managers/UniversalRenderingManager.ts:1-37]()

### 3. The benchmark scripts
- `packages/diffs/scripts/benchmarkParseMergeConflictDiffFromFile.ts` (340 lines) — shows how the diffs team measures parse + render cost across `maxContextLines` cases.
- `packages/path-store/scripts/benchmark.ts` (thousands of lines of workloads) — the canonical place to see what "fast for real Git repos" means.

Running or reading these tells you where the team actually spends profiling time.

Sources: [packages/diffs/scripts/benchmarkParseMergeConflictDiffFromFile.ts:29-60]()

### 4. Test strategy documents
- [packages/trees/test/TESTING.md](packages/trees/test/TESTING.md) (and the matching section in AGENTS.md) — explicit rules: unit first, Playwright only for computed styles / shadow DOM / CSS custom properties, no broad snapshots.

Sources: [packages/trees/test/TESTING.md:1-46](), [AGENTS.md:206-258]()

## Run a Real Package Test (Do This Now)

```bash
export AGENT=1
# From repo root (preferred)
bun ws diffs test
# Or inside the package
cd packages/diffs && bun test
```

For the tree package (includes E2E):
```bash
bun ws trees test
bun ws trees test:e2e   # builds dist, installs Chromium if needed, runs Playwright
```

Always run from the package directory or via `bun ws` when the task is package-scoped. After any code change you must also run (from root):
```bash
bun run format
bun run lint
bun run tsc   # or the package's bun run tsc
```

Sources: [AGENTS.md:8-10](), [AGENTS.md:226-241](), [packages/trees/test/TESTING.md:36-39]()

## Add a Small Feature — Minimal Contract-Compliant Path

1. Pick a leaf: a new option on `DiffHunksRenderer`, a tiny helper in `path-store`, or a missing icon preset in `trees`.
2. Implement the helper with a one-line comment above it explaining what data it transforms and why (see AGENTS readability rules).
3. Add or extend a unit test (never a broad snapshot).
4. From the package dir: `bun test`.
5. From repo root: `bun run format && bun run lint && bun run tsc`.
6. If you touched anything that starts a dev server or browser fixture, run `bun run wt clean` (or `bun run wt clean <slug>`) before you finish.
7. If you added a dependency: first edit root `package.json` `workspaces.catalog`, then reference it as `"catalog:"` in the package `package.json`. Never `bun add` inside a package.

Sources: [AGENTS.md:131-188](), [AGENTS.md:62-68]()

## Living Glossary of Pierre Terms

| Term                    | Meaning & Where It Lives                                                                 | Why It Matters |
|-------------------------|------------------------------------------------------------------------------------------|--------------|
| `catalog:`              | Dependency reference in every sub `package.json` (root `workspaces.catalog` holds the real version). Never put a version number in a package's own file. | Eliminates drift across 8+ packages. |
| `PIERRE_PORT_OFFSET`    | Integer written by `scripts/wt.ts` into each worktree's `.env.worktree`; read by `ws.ts`, Playwright config, and dev scripts. | Prevents port collisions when multiple agents run dev servers or Chrome debuggers in parallel worktrees. |
| `prepareFileTreeInput`  | `packages/trees/src/preparedInput.ts:15` — thin wrapper around `PathStore.prepareInput` that returns an opaque `FileTreePreparedInput` token. | Guarantees the expensive normalization/sort work has already happened before the tree component sees the data. |
| `DiffHunksRenderer`     | `packages/diffs/src/renderers/DiffHunksRenderer.ts` (exported from `diffs/index.ts`). Class that turns hunk data into themed HAST rows for virtualized rendering. | The single place that knows split vs unified, annotation injection, and Shiki tokenization. |
| `oxfmt`                 | Root formatter invoked via `bun run format` / `bun run format:check`. | One canonical style for the whole monorepo; must be run from root after every edit. |
| `AGENT=1`               | Environment variable that makes Bun's test runner emit AI-friendly, non-interactive output. | Required at the top of any terminal session before `bun test`. |
| Visible projection      | `createVisibleTreeProjection` in `path-store/src/visible-tree-projection.ts`. Returns `{ rows, getParentIndex, visibleIndexByPath }` built with `Int32Array`s and a lazy Map. | Powers ARIA sibling calculations and expansion state without O(n) path reparsing on every render. |
| Worktree                | Git worktree managed by `bun run wt new <slug>` (creates `~/pierre/pierre-worktrees/<slug>/` + offset). Scripts: `wt rm`, `wt clean`, `wt ps`. | The official way to run multiple isolated dev environments; agents must clean up ports on exit. |

Sources: [package.json:workspaces.catalog](), [scripts/wt.ts:164-373](), [packages/trees/src/preparedInput.ts:15-32](), [packages/diffs/src/renderers/DiffHunksRenderer.ts:1-30](), [AGENTS.md:5-10](), [AGENTS.md:38-68](), [packages/path-store/src/visible-tree-projection.ts:19-50]()

## Quick Command Cheat Sheet

```bash
export AGENT=1
bun run lint && bun run format          # after any edit (from root)
bun ws <pkg> test                       # diffs, trees, truncate, ...
bun ws trees test:e2e                   # Playwright only when jsdom is insufficient
bun run wt clean                        # before you log off or switch worktrees
bun run tsc                             # typecheck everything via project references
```

## Closing Summary

The monorepo's power comes from ruthless consistency: one package manager, one linter/formatter invocation point, one dependency catalog, typed-array projections instead of nested loops, and an explicit cleanup contract for parallel work. Read the two projection and renderer files, run one package's test suite under `AGENT=1`, and you will be ready to make a contract-compliant contribution on your next turn.

Sources: [AGENTS.md:145-188]()