OpenAgents

Commit

Plan the port of Pierre's code surfaces

819a54005e33 · AtlantisPleb · · parent 27e5b79cc603 

Plan the port of Pierre's code surfaces

`pierrecomputer/pierre` is the open-source part of Pierre's stack, Apache 2.0:
the UI libraries behind Code.Storage, which itself stays proprietary. Four of
its components map onto surfaces a code host needs and we either lack or
render badly.

This doc says what those are, what "porting" means here -- almost none of the
code survives, since `packages/diffs/src/components` alone is 14,627 lines of
React and vanilla TypeScript over Shiki and a virtualizer, and what transfers
is the model and the layout decisions -- and what we are deliberately not
taking: the virtualizer, the editor, the highlighting worker, and their theme.

The work list at the bottom is the tracker. Four items, ranked: a single file's
diff, a numbered and addressable blob, the repository tree, and the multi-file
compare view. One open decision is recorded rather than assumed: server-side
highlighting needs `{:lumis, "~> 0.1"}` through mdex, and the first components
ship unhighlighted because structure is worth more than colour and is the
harder half to add later.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0149rBWy7br1Z7bbz9NrQhEr
Co-Authored-By
Claude Opus 5 (1M context) <noreply@anthropic.com>

Deploy story

What this commit did to the running system — joined from the forge receipt chain, the part a commit page elsewhere cannot show.

Not deployed through the forge lane

No push, promotion, build, or deploy receipt references this commit (receipts are scanned over a bounded recent window). Changes shipped by full node replacement carry their proof in the release gate receipt instead.

Changed files

  • added docs/2026-08-20-pierre-code-surfaces-port.md

Diff

1 file changed, +135 -0

docs/2026-08-20-pierre-code-surfaces-port.md added +135

@@ -0,0 +1,135 @@

1 
# Porting Pierre's code surfaces
2
3 
*2026-08-20*
4
5 
This doc explains what Pierre's libraries are, which parts are worth adapting
6 
into `OpenAgentsWeb.UI`, which parts are deliberately not, and what still needs
7 
doing. **The work list at the bottom is the tracker for this effort** — update
8 
it in the same change that lands the work, not afterwards.
9
10 
## What Pierre is
11
12 
[`pierrecomputer/pierre`][pierre] is the open-source part of Pierre's stack.
13 
Code.Storage, their product, stays proprietary; what is published are the UI
14 
libraries behind it, under **Apache 2.0**. Read at `ba7d51d2` (2026-08-19),
15 
synced through `~/work/projects/manifest.txt` to
16 
`~/work/projects/repos/pierre`.
17
18 
The packages that matter to us:
19
20 
| Package | npm | What it is |
21 
| --- | --- | --- |
22 
| `packages/diffs` | `@pierre/diffs` 1.3.5 | `CodeView`, `FileDiff`, `File`, and virtualized variants |
23 
| `packages/trees` | `@pierre/trees` 1.0.0-beta.6 | `FileTree`, a path-first file tree |
24 
| `packages/theme` | `@pierre/theme` 2.0.0 | Pierre's colour themes, including Shiki grammars |
25
26 
The components, in their own words:
27
28 
- **`CodeView`** is the multi-file scroller: one viewport holding mixed file and
29 
  diff items, sticky headers, virtualization, line selection, optional edit
30 
  mode.
31 
- **`FileDiff`** is a single file's split or stacked diff, with Shiki
32 
  highlighting, annotations, and accept/reject hunks.
33 
- **`File`** is a non-diff code view of one blob.
34 
- **`FileTree`** is the sidebar tree, not a blob viewer.
35
36 
## What "porting" means here
37
38 
Almost none of the code survives. `packages/diffs/src/components` alone is
39 
**14,627 lines of TypeScript**, and it is React and vanilla TS built on Shiki, a
40 
streaming worker, and a virtualizer. What we take is the **model and the layout
41 
decisions**: how a diff is decomposed into files, hunks, and lines carrying two
42 
line numbers; what a file header holds; how a multi-file view keeps its place.
43 
Those are the expensive parts to get right and they transfer intact.
44
45 
Apache 2.0 requires the copyright notice be retained where code is used. Since
46 
this is adaptation rather than copying, attribution lives in the moduledoc of
47 
each ported component and here.
48
49 
Two standing decisions, the same ones taken for the Launch UI adaptation:
50
51 
- **Our tokens, not their theme.** Pierre ships its own palette and Shiki
52 
  themes. Adopting them would put a second colour system beside the one every
53 
  other surface uses. Every ported value resolves to an existing token.
54 
- **No JavaScript where the server can do it.** These surfaces render from data
55 
  we already have on the server. A diff is decomposed in Elixir and rendered as
56 
  HTML; collapsing uses native `<details>`.
57
58 
## Where we are starting from
59
60 
The data layer mostly exists. The presentation does not.
61
62 
| Surface | Today |
63 
| --- | --- |
64 
| Commit (`/OpenAgentsInc/:repo/commit/:sha`) | The whole unified diff in one `<pre>`. No per-file split, no hunk headers, no add/remove colour, no line numbers. |
65 
| Blob (`/OpenAgentsInc/:repo/blob/:ref/*path`) | File contents in one `<pre><code>`. No line numbers, no line anchors, no highlighting. |
66 
| Repo (`/OpenAgentsInc/:repo`) | Commit list. No file tree, although `Browse.tree/3` already returns `[%{name, kind, size}]`. |
67 
| Compare / pull request | Does not exist. |
68
69 
`OpenAgents.Forge.Browse` already provides what the first items need:
70 
`diff/2` shells `git diff-tree -p -M --no-color` and caps the output, and
71 
`tree/3` lists a directory at a ref.
72
73 
## What we are not porting
74
75 
Stated so nobody re-litigates it later:
76
77 
- **The virtualizer.** `Virtualizer` (722 lines), `VirtualizedFile` (1,156),
78 
  and `VirtualizedFileDiff` (2,182) are about four thousand lines solving a
79 
  problem we solve server-side by bounding the diff before it is rendered.
80 
- **Edit mode and the editor.** We are building a code *host*, not an editor.
81 
- **`shiki-stream` and the highlighting worker.** Highlighting belongs on the
82 
  server here; see the open decision below.
83 
- **`packages/theme`.** We have a token ladder.
84 
- **`packages/path-store` and `packages/pipes`.** A tree data store we do not
85 
  need, and an unrelated 3D demo.
86
87 
## Open decision: syntax highlighting
88
89 
Highlighting is the one item that needs a dependency. `mdex`, already a
90 
dependency, supports server-side highlighting but requires `{:lumis, "~> 0.1"}`
91 
and raises a clear error naming it when absent. That would give highlighted
92 
diffs and blobs with no JavaScript and no Shiki.
93
94 
Not yet taken. Diff and blob rendering ship unhighlighted first, because the
95 
structure is worth far more than the colour and it is a smaller change to add
96 
highlighting to a correct structure than the reverse.
97
98 
## Work list
99
100 
Status is one of **done**, **next**, or **planned**.
101
102 
### 1. `diff_file/1` — a single file's diff — **next**
103
104 
Adapted from `FileDiff`. Decomposes a unified diff into files, hunks, and lines
105 
carrying old and new numbers, and renders it with a file header, hunk headers,
106 
add/remove tinting, and per-line anchors. Collapsible per file through native
107 
`<details>`.
108
109 
Lands as a parser plus a component, catalogued and demoed, and replaces the
110 
raw `<pre>` on the commit page.
111
112 
### 2. `code_file/1` — one blob, numbered and addressable — **planned**
113
114 
Adapted from `File`. Line numbers, line anchors and ranges (`#L12`,
115 
`#L12-L20`), a sticky filename header, copy and raw actions. Replaces the
116 
blob page's bare `<pre><code>`.
117
118 
The line-anchor model is the valuable part: a line number that is a link, and a
119 
range that survives being pasted into an issue.
120
121 
### 3. `file_tree/1` — the repository sidebar — **planned**
122
123 
Adapted from `@pierre/trees`. Path-first: the tree is built from a list of
124 
paths rather than from nested directory objects, which is what makes it cheap
125 
to render a subtree at a ref. `Browse.tree/3` already supplies the data, and
126 
native `<details>` gives collapsing without script.
127
128 
### 4. `diff_list/1` — many files in one view — **planned**
129
130 
Adapted from `CodeView`, minus virtualization. Composes `diff_file/1` items
131 
with sticky per-file headers and a "files changed, +N −M" summary bar. This is
132 
the compare and pull-request surface, and it is mostly composition once item 1
133 
exists.
134
135 
[pierre]: https://github.com/pierrecomputer/pierre

This page updates live while a promote is in flight · changelog