From faedb9869992abbf1a3e1a59db4ac1e70af6c6f9 Mon Sep 17 00:00:00 2001 From: bchanot Date: Sat, 17 Oct 2026 13:10:37 +0200 Subject: [PATCH] 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 "}, + {"text": "b", "correct": False, "why": "no"}, + {"text": "c", "correct": False, "why": "no"}]}] * 5) +json.dump(values, open(sys.argv[2], "w")) +PY +echo '

Fragment.

' > "$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 '

Fragment.

' "$D-filled.html")" 1 +check T18-script-close-escaped "$(grep -c 'yes ' "$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 ] diff --git a/skills/explain-diff/SKILL.md b/skills/explain-diff/SKILL.md index b712c4c..62e20ac 100644 --- a/skills/explain-diff/SKILL.md +++ b/skills/explain-diff/SKILL.md @@ -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 `@`. 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 + ``` + 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 `
` blocks, HTML-escaped (`<` as `<`, `>` as `>`,
    `&` as `&`). An unescaped `` generic or JSX tag silently swallows
    the code that follows it.
diff --git a/skills/explain-diff/assets/template.html b/skills/explain-diff/assets/template.html
index 574056d..14317f9 100644
--- a/skills/explain-diff/assets/template.html
+++ b/skills/explain-diff/assets/template.html
@@ -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);
diff --git a/skills/explain-diff/references/components.md b/skills/explain-diff/references/components.md
index 03424c1..7aac4b9 100644
--- a/skills/explain-diff/references/components.md
+++ b/skills/explain-diff/references/components.md
@@ -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.
   
Browser guest g-42, no session
-
ensureGuest()
+
ensureGuest()
fetchHint new: session first
-
rpc hint(day=12)
+
rpc hint(day=12)
Database auth-gated RPC
@@ -60,7 +60,7 @@ the component the change touches. On a phone the flow turns vertical. ``` -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
running
-
crash ×3
+
crash ×3
stopped new: final
diff --git a/skills/explain-diff/scripts/fill_template.py b/skills/explain-diff/scripts/fill_template.py new file mode 100755 index 0000000..ab6a5b5 --- /dev/null +++ b/skills/explain-diff/scripts/fill_template.py @@ -0,0 +1,61 @@ +#!/usr/bin/env python3 +"""Fill the explain-diff template: fill_template.py . + +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 "