Graph updates; readme updates

2 files changed, 16 insertions, 3 deletions

diff --git a/graph/README.md b/graph/README.md
index f7037548..8d3850e7 100644
--- a/graph/README.md
+++ b/graph/README.md
@@ -156,6 +156,18 @@ This keeps both graphs side by side in the chapter README. Chapter 10a's
 [load-after-store example](../chapter10a/README.md#local-memory-optimizations)
 uses this format to isolate a single rewrite.
 
+Choose how much control to show according to the lesson. Keep it when teaching
+control construction, branch elimination, loop nesting, or `break`/`continue`.
+For a value rewrite inside an otherwise obvious branch or loop, omit the
+routine CFG and its predicate-only computations, while preserving Phi data
+inputs and their order. Chapter 5's arithmetic/Phi examples and Chapter 9's
+optimization examples use this convention. Detached True/False projections
+can identify important gates, including the two Returns in Chapter 9's first
+GVN example. Describe omitted context in the caption or surrounding text.
+If a snapshot omits a Loop, retain `"backedge": true` on its Phis' backedge
+inputs so layout still puts the loop header values above their updates. This
+is a documentation layout hint; live snapshots derive it from the Loop node.
+
 The memory diagrams in 10a, 10b, and 11 also use viewer snapshots, with definitions
 above uses (apart from loop backedges) and arrows from use to definition.
 They omit control-flow context, including Regions and their Phi bindings,
diff --git a/graph/web/layout.js b/graph/web/layout.js
index 04d6f338..bd164854 100644
--- a/graph/web/layout.js
+++ b/graph/web/layout.js
@@ -155,9 +155,10 @@ class GraphLayout {
         const bundle = e.refs.length > 1;
         const id = bundle ? `b${use.id}d${e.def}` : "e" + e.orig.use + "i" + e.orig.idx;
         const reg = byId.get(use.edges[0]?.def)?.n;
-        const back = !use.fold && e.idx === 2 && (use.kind === "LOOP" ||
-          (use.kind === "PHI" && reg?.kind === "LOOP"));
-        const loop = back ? (use.kind === "LOOP" ? use.id : reg.id) : 0;
+        // Focused documentation can omit the Loop but retain its backedge cue.
+        const back = !use.fold && (e.backedge === true || (e.idx === 2 &&
+          (use.kind === "LOOP" || (use.kind === "PHI" && reg?.kind === "LOOP"))));
+        const loop = back ? (use.kind === "LOOP" ? use.id : (reg?.kind === "LOOP" ? reg.id : 0)) : 0;
         const wrap = loop && view.groups.has(loop) && !raw.get(loop).fold ? loop : 0;
         if (wrap) backs.set(wrap, (backs.get(wrap) || 0) + 1);
         edges.push({id, use: use.id, def: e.def, idx: e.orig.idx, orig: e.orig, refs: e.refs, bundle, role: e.role, label: e.label,