forked from bchanot/claude
feat(explain-diff): explain a diff as one self-contained HTML page
Adapted from Geoffrey Litt's explain-diff gist: background, intuition, grouped code walkthrough, 5-question quiz, saved outside the repo. Bundled template, components catalog and checker with its test suite. Row reflect; profiles full, max, dev.
This commit is contained in:
1 parent
6f0deb489d
commit
b353fac2ba
14 files changed
+1266
No files matched your search
@@ -0,0 +1,187 @@
|
||||
# Components for an explain-diff page
|
||||
|
||||
Every snippet below is styled by `assets/template.html`. Copy, then replace
|
||||
the sample content. Keep the class names: the stylesheet and the checker
|
||||
know them. Sample text is in English; write yours in the page language.
|
||||
|
||||
## Skippable deep background
|
||||
|
||||
The newcomer's tour of the system goes in a collapsible block, so a reader
|
||||
who knows it can jump straight to the narrow background.
|
||||
|
||||
```html
|
||||
<details class="deep">
|
||||
<summary>How the hint service works <span class="hint">(skip if you
|
||||
know it)</span></summary>
|
||||
<p>…</p>
|
||||
</details>
|
||||
```
|
||||
|
||||
## Callouts
|
||||
|
||||
Three kinds: `concept` (a definition or key idea), `edge` (an edge case
|
||||
worth remembering), `risk` (what can still go wrong, or a follow-up).
|
||||
|
||||
```html
|
||||
<aside class="callout concept">
|
||||
<p class="callout-title">Lazy guest</p>
|
||||
<p>A visitor who has not played yet has no session row …</p>
|
||||
</aside>
|
||||
<aside class="callout edge">
|
||||
<p class="callout-title">Edge case: session creation fails</p>
|
||||
<p>…</p>
|
||||
</aside>
|
||||
<aside class="callout risk">
|
||||
<p class="callout-title">Not covered by this change</p>
|
||||
<p>…</p>
|
||||
</aside>
|
||||
```
|
||||
|
||||
## Flow of components
|
||||
|
||||
Nodes left to right, an edge between each pair. The edge label carries the
|
||||
example data that travels (a call, a payload, a return value). `hl` marks
|
||||
the component the change touches. On a phone the flow turns vertical.
|
||||
|
||||
```html
|
||||
<figure class="diagram">
|
||||
<div class="flow">
|
||||
<div class="node"><span class="node-title">Browser</span>
|
||||
<span class="node-sub">guest g-42, no session</span></div>
|
||||
<div class="edge">ensureGuest()</div>
|
||||
<div class="node hl"><span class="node-title">fetchHint</span>
|
||||
<span class="node-sub">new: session first</span></div>
|
||||
<div class="edge">rpc hint(day=12)</div>
|
||||
<div class="node"><span class="node-title">Database</span>
|
||||
<span class="node-sub">auth-gated RPC</span></div>
|
||||
</div>
|
||||
<figcaption>After the fix: the session exists before the hint call.
|
||||
</figcaption>
|
||||
</figure>
|
||||
```
|
||||
|
||||
A return value travels back through the label of the same edge
|
||||
(`hint(day=12) → "starts with B"`) or through a second flow below.
|
||||
|
||||
## Row of states
|
||||
|
||||
Same markup with `state` nodes; `hl` marks the state the change adds.
|
||||
|
||||
```html
|
||||
<div class="flow">
|
||||
<div class="node state"><span class="node-title">running</span></div>
|
||||
<div class="edge">crash ×3</div>
|
||||
<div class="node state hl"><span class="node-title">stopped</span>
|
||||
<span class="node-sub">new: final</span></div>
|
||||
</div>
|
||||
```
|
||||
|
||||
## Before and after
|
||||
|
||||
```html
|
||||
<div class="compare">
|
||||
<div class="pane before">
|
||||
<p class="pane-label">Before</p>
|
||||
<p>…</p>
|
||||
</div>
|
||||
<div class="pane after">
|
||||
<p class="pane-label">After</p>
|
||||
<p>…</p>
|
||||
</div>
|
||||
</div>
|
||||
```
|
||||
|
||||
## Simplified UI mock
|
||||
|
||||
For UI changes: draw only what the user sees that matters, as boxes.
|
||||
`mark` outlines the element the change affects. Put two mocks inside the
|
||||
panes of a `compare` block for a before and after view.
|
||||
|
||||
```html
|
||||
<div class="mock">
|
||||
<div class="mock-bar">Daily puzzle · day 12</div>
|
||||
<div class="mock-body">
|
||||
<p>Find the word in 6 tries.</p>
|
||||
<div class="mock-field">B _ _ _ _</div>
|
||||
<div class="mock-button">Hint</div>
|
||||
<div class="mock-alert mark">Hint unavailable</div>
|
||||
</div>
|
||||
</div>
|
||||
```
|
||||
|
||||
`mock-alert ok` gives the success colour.
|
||||
|
||||
## Toy data
|
||||
|
||||
```html
|
||||
<div class="table-wrap">
|
||||
<table class="data">
|
||||
<thead><tr><th>Visitor</th><th>Session</th><th>Hint</th></tr></thead>
|
||||
<tbody>
|
||||
<tr><td>g-42</td><td>none</td><td>refused</td></tr>
|
||||
</tbody>
|
||||
</table>
|
||||
</div>
|
||||
```
|
||||
|
||||
## Code excerpt and diff
|
||||
|
||||
Show only the lines that matter, with the `path:line` above. Escape `<`,
|
||||
`>` and `&` in every code block.
|
||||
|
||||
```html
|
||||
<figure>
|
||||
<span class="path">apps/web/src/game/daily.ts:31</span>
|
||||
<pre><code>export async function fetchDailyHint(day: number) {
|
||||
const ok = await ensureGuestSession();
|
||||
if (!ok) return null;
|
||||
}</code></pre>
|
||||
<figcaption>The session comes first; a failure ends in null.</figcaption>
|
||||
</figure>
|
||||
```
|
||||
|
||||
A diff block holds raw unified-diff lines; the template's script colours
|
||||
the `+`, `-` and `@@` lines. Keep the leading `+` / `-` / space.
|
||||
|
||||
```html
|
||||
<figure>
|
||||
<span class="path">apps/web/src/game/daily.ts</span>
|
||||
<pre class="diff">@@ -28,6 +28,9 @@ export async function fetchDailyHint
|
||||
export async function fetchDailyHint(day: number) {
|
||||
+ const ok = await ensureGuestSession();
|
||||
+ if (!ok) return null;
|
||||
return rpc("hint", { day });</pre>
|
||||
</figure>
|
||||
```
|
||||
|
||||
## Quiz data
|
||||
|
||||
The template renders the quiz from the JSON block `quiz-data`. Five
|
||||
questions, three or four options each, exactly one `"correct": true`, and a
|
||||
`why` on every option. Backticks in any string render as inline code. Plain
|
||||
text only, no HTML; write `<\/` for any `</` inside a string.
|
||||
|
||||
```json
|
||||
[
|
||||
{
|
||||
"q": "A guest with no session asks for a hint. What runs first?",
|
||||
"options": [
|
||||
{"text": "The hint RPC", "correct": false,
|
||||
"why": "That was the bug: the RPC refused a caller with no session."},
|
||||
{"text": "`ensureGuestSession()`", "correct": true,
|
||||
"why": "The fetcher now creates the session, then calls the RPC."},
|
||||
{"text": "A page reload", "correct": false,
|
||||
"why": "Nothing reloads; the fix stays inside the fetcher."}
|
||||
]
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
Labels on `#quiz-root` follow the page language. `{n}` and `{total}` in the
|
||||
score label are filled by the script.
|
||||
|
||||
| Placeholder | English | French |
|
||||
|---|---|---|
|
||||
| `{{QUIZ_RIGHT}}` | Right. | Exact. |
|
||||
| `{{QUIZ_WRONG}}` | Not quite. | Pas tout à fait. |
|
||||
| `{{QUIZ_SCORE}}` | Score: {n} out of {total} | Score : {n} sur {total} |
|
||||
Reference in new issue
Block a user