diff --git a/lib/tests/explain-diff-check.test.sh b/lib/tests/explain-diff-check.test.sh index d64f8fb..67571fd 100755 --- a/lib/tests/explain-diff-check.test.sh +++ b/lib/tests/explain-diff-check.test.sh @@ -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 "}, + {"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 `@` 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 "" 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))