fix(explain-diff): arrow class no longer collides with edge callout; bundle fill_template.py

Eval iteration 1: the callout 'edge' variant picked up the diagram connector styles, and all three skill runs hand-wrote a template filler. fill_template.py takes values.json with @fragment files, escapes </ in the quiz; suite 21 checks.
This commit is contained in:
bchanot committed 2026-10-17 13:10:37 +02:00
1 parent b353fac2ba
commit faedb98699
5 files changed
+112 -19

No files matched your search

+25
View File
@@ -97,5 +97,30 @@ out=$(python3 "$CHECK" "$D-dash.html")
check T15-fail-line-names-check "$(printf '%s\n' "$out" \
| grep -c '^FAIL em-dash:')" 1
# fill_template.py: a valid values file builds a page the checker passes;
# a missing placeholder is refused (rc 1).
FILL="$SKILL/scripts/fill_template.py"
python3 -I - "$SKILL/assets/template.html" "$WORK/values.json" <<'PY'
import json, re, sys
keys = set(re.findall(r"\{\{([A-Z_]+)\}\}", open(sys.argv[1]).read()))
values = {k: "x" for k in keys}
values.update(LANG="en", BACKGROUND_BODY="@bg.html", QUIZ_JSON=[
{"q": "Q?", "options": [
{"text": "a", "correct": True, "why": "yes </script>"},
{"text": "b", "correct": False, "why": "no"},
{"text": "c", "correct": False, "why": "no"}]}] * 5)
json.dump(values, open(sys.argv[2], "w"))
PY
echo '<p>Fragment.</p>' > "$WORK/bg.html"
python3 "$FILL" "$WORK/values.json" "$D-filled.html" >/dev/null
check T16-filled-page-passes "$(rc "$D-filled.html")" 0
check T17-fragment-inlined "$(grep -c '<p>Fragment.</p>' "$D-filled.html")" 1
check T18-script-close-escaped "$(grep -c 'yes </script>' "$D-filled.html")" 0
python3 -I -c 'import json, sys
d = json.load(open(sys.argv[1])); d.pop("LANG")
json.dump(d, open(sys.argv[2], "w"))' "$WORK/values.json" "$WORK/bad.json"
python3 "$FILL" "$WORK/bad.json" "$D-bad.html" >/dev/null 2>&1
check T19-missing-placeholder-refused "$?" 1
printf 'explain-diff checker: %d pass, %d fail\n' "$pass" "$fail"
[ "$fail" -eq 0 ]
+12 -5
View File
@@ -113,11 +113,18 @@ less than three styled boxes.
The skill folder is `$HOME/.claude/skills/explain-diff/`.
1. Read `references/components.md` (the snippet catalog), then start from
a copy of `assets/template.html`.
2. Replace every `{{…}}` placeholder. Section ids stay `background`,
`intuition`, `code` and `quiz`: the table of contents and the checker
rely on them.
1. Read `references/components.md` (the snippet catalog) and the
placeholders of `assets/template.html`.
2. Write each section body as its own HTML fragment file, the quiz as a
JSON list, and a `values.json` mapping every placeholder to its text or
to `@<fragment file>`. Keep these working files in a temporary folder,
never in the repo. Then build the page:
```bash
python3 "$HOME/.claude/skills/explain-diff/scripts/fill_template.py" values.json <file>
```
It refuses a missing or unknown placeholder. Section ids stay
`background`, `intuition`, `code` and `quiz`: the table of contents and
the checker rely on them.
3. Code goes in `<pre>` blocks, HTML-escaped (`<` as `&lt;`, `>` as `&gt;`,
`&` as `&amp;`). An unescaped `<T>` generic or JSX tag silently swallows
the code that follows it.
+9 -9
View File
@@ -200,7 +200,7 @@ details.deep[open] > summary {
border-bottom: 1px solid var(--line);
}
/* Diagrams: flow and states */
/* Diagrams: flow and states (.arrow links two nodes) */
.flow { display: flex; align-items: stretch; }
.node {
flex: 1 1 0;
@@ -215,17 +215,17 @@ details.deep[open] > summary {
.node.state { border-radius: 999px; text-align: center; }
.node-title { display: block; font-weight: 650; }
.node-sub { display: block; font-size: 0.82rem; color: var(--muted); }
.edge {
.arrow {
position: relative;
flex: 0 0 7rem;
flex: 0 0 9rem;
align-self: center;
padding: 0 0.6rem 0.7rem;
font: 0.75rem/1.3 var(--mono);
color: var(--muted);
text-align: center;
overflow-wrap: anywhere;
overflow-wrap: break-word;
}
.edge::before {
.arrow::before {
content: "";
position: absolute;
left: 0.3rem;
@@ -233,7 +233,7 @@ details.deep[open] > summary {
bottom: 0.3rem;
border-top: 1.5px solid var(--muted);
}
.edge::after {
.arrow::after {
content: "";
position: absolute;
right: 0.3rem;
@@ -360,13 +360,13 @@ table.data th { font-weight: 650; color: var(--muted); }
h2 { margin-top: 3.5rem; }
.compare { grid-template-columns: 1fr; }
.flow { flex-direction: column; }
.edge {
.arrow {
flex-basis: auto;
align-self: flex-start;
padding: 0.55rem 0 0.75rem 1.5rem;
text-align: left;
}
.edge::before {
.arrow::before {
top: 0;
bottom: 0.2rem;
left: 0.65rem;
@@ -374,7 +374,7 @@ table.data th { font-weight: 650; color: var(--muted); }
border-top: 0;
border-left: 1.5px solid var(--muted);
}
.edge::after {
.arrow::after {
right: auto;
bottom: 0;
left: calc(0.65rem - 4.25px);
+5 -5
View File
@@ -39,7 +39,7 @@ worth remembering), `risk` (what can still go wrong, or a follow-up).
## Flow of components
Nodes left to right, an edge between each pair. The edge label carries the
Nodes left to right, an `arrow` between each pair. Its 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.
@@ -48,10 +48,10 @@ the component the change touches. On a phone the flow turns vertical.
<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="arrow">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="arrow">rpc hint(day=12)</div>
<div class="node"><span class="node-title">Database</span>
<span class="node-sub">auth-gated RPC</span></div>
</div>
@@ -60,7 +60,7 @@ the component the change touches. On a phone the flow turns vertical.
</figure>
```
A return value travels back through the label of the same edge
A return value travels back through the label of the same arrow
(`hint(day=12) → "starts with B"`) or through a second flow below.
## Row of states
@@ -70,7 +70,7 @@ 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="arrow">crash ×3</div>
<div class="node state hl"><span class="node-title">stopped</span>
<span class="node-sub">new: final</span></div>
</div>
+61
View File
@@ -0,0 +1,61 @@
#!/usr/bin/env python3
"""Fill the explain-diff template: fill_template.py <values.json> <out.html>.
values.json maps each placeholder name (without braces) to its content.
A value starting with "@" names a file whose content is used instead, so
long HTML bodies can live in their own fragment files. QUIZ_JSON may be a
JSON list: it is serialised here, with "</" escaped for the script block.
Exit 1 when a placeholder is missing or unknown.
"""
import json
import re
import sys
from pathlib import Path
TEMPLATE = Path(__file__).resolve().parent.parent / "assets/template.html"
PLACEHOLDER = re.compile(r"\{\{([A-Z_]+)\}\}")
def resolve(value, base):
if isinstance(value, str) and value.startswith("@"):
return (base / value[1:]).read_text(encoding="utf-8")
return value
def quiz_text(value):
if isinstance(value, str):
value = json.loads(value)
return json.dumps(value, ensure_ascii=False, indent=1).replace(
"</", "<\\/")
def fill(template, values):
wanted = set(PLACEHOLDER.findall(template))
missing, unknown = wanted - set(values), set(values) - wanted
if missing or unknown:
raise KeyError(f"missing: {sorted(missing)}, "
f"unknown: {sorted(unknown)}")
return PLACEHOLDER.sub(lambda m: values[m.group(1)], template)
def main(argv):
if len(argv) != 3:
print(__doc__.strip())
return 2
values_path = Path(argv[1]).expanduser()
raw = json.loads(values_path.read_text(encoding="utf-8"))
values = {k: resolve(v, values_path.parent) for k, v in raw.items()}
if "QUIZ_JSON" in values:
values["QUIZ_JSON"] = quiz_text(values["QUIZ_JSON"])
try:
page = fill(TEMPLATE.read_text(encoding="utf-8"), values)
except KeyError as err:
print(f"ERROR {err}")
return 1
Path(argv[2]).expanduser().write_text(page, encoding="utf-8")
print(f"wrote {argv[2]}")
return 0
if __name__ == "__main__":
sys.exit(main(sys.argv))