C.E.L_Slide_test2/docs/architecture/IMP-18-SVG-GAP-REPORT.md

IMP-18 — Phase Z SVG Coordinate Pre-compute Gap Report

Status: documented (reference-only, dormant) Scope: doc-only. No runtime surface modified. Related issue: #18 Soft dependency: IMP-04 (frame_partials registration) — IMP-18 activates only when a SVG-bearing partial lands under templates/phase_z2/.

---

A1 — Phase R' source pattern (read-only reference)

Phase R' implements SVG coordinate pre-compute as a renderer hook. References (do not modify):

• src/renderer.py:169-207 — _preprocess_svg_data(block_type, block_data) — mutates block_data with computed coordinates when block_type ∈ SVG_BLOCKS; warns and falls back on exception.
• src/renderer.py:175 — SVG_BLOCKS = {"venn-diagram", "relationship"} — exhaustive type allow-list.
• src/renderer.py:321 — call site inside render_multi_page() (block_data = _preprocess_svg_data(block_type, block_data)), right before _resolve_template_path lookup.
• src/svg_calculator.py:15-156 — five helpers:
  • L15 calc_circle_positions(n, center_x, center_y, radius) — 12 o'clock clockwise N-element layout.
  • L47 calc_item_radius(n, base_radius=75.0) — auto-shrink small-circle radius for crowding.
  • L59 calc_orbit_radius(n, base_orbit=120.0) — auto-expand orbit for crowding.
  • L70 calc_outer_radius(n, orbit_radius, item_radius) — outer enclosing circle, 40 px margin.
  • L77 prepare_venn_data(items, center_label, center_sub, description, viewbox_width=600.0, viewbox_height=550.0) — top-level entry; mutates items[*].cx/cy/r and returns outer_r/center_x/center_y/viewbox_width/viewbox_height.

A2 — Phase Z partial SVG inventory (gap)

Phase Z active partials surface:

• templates/phase_z2/families/*.html — 13 files.
• templates/phase_z2/frames/*.html — 2 files.
• Total surface = 15 partials.

SVG usage scan (evidence): rg "<svg|viewBox" templates/phase_z2/ → 0 matches (exit 1).

Closest geometric candidate is templates/phase_z2/families/construction_goals_three_circle_intersection.html (frame_id 1171281189, "cycle-3way-intersection" intent), but it renders three intersecting circles via HTML/CSS — border-radius:50% + linear-gradient + ::before outer ring — not SVG. The Figma source's six accent kanji circles, six side labels, three decorative rects, and three arcs are explicitly NOT PROMOTED at the partial header (compact MDX-mapped focus). No partial currently demands the pre-computed items[*].cx/cy/r contract.

A3 — IMP-04 activation gate (soft dependency)

IMP-18 has no Phase Z runtime consumer today. Re-activation triggers:

1. IMP-04 (frame_partials registration) lands an SVG-bearing partial under templates/phase_z2/ (e.g., a venn-diagram or relationship frame promoted from Figma).
2. The partial declares slots that consume items[*].cx/cy/r + outer_r + viewbox_* (the prepare_venn_data return contract).

Until both conditions hold, IMP-18 stays dormant and this gap report is the sole deliverable.

A4 — Phase R' guardrail (read-only lock)

Per CLAUDE.md Phase R' regression prevention rules and the Stage 1/2 exit reports:

• src/renderer.py — read-only. No edit to _preprocess_svg_data body, SVG_BLOCKS set, or render_multi_page call site.
• src/svg_calculator.py — read-only. No edit to the five helpers or their public signatures.
• templates/phase_z2/families/*.html (13) + templates/phase_z2/frames/*.html (2) — no <svg> / viewBox insertion in IMP-18 scope. SVG-bearing partial onboarding is owned by IMP-04.
• F12 construction_goals_three_circle_intersection.html HTML/CSS → SVG migration is out of scope (separate post-IMP-04 issue).
• No hardcoded SVG coordinates in Phase Z templates — when IMP-18 re-activates, coordinates must be derived from svg_calculator helpers (or equivalent forward-port into phase_z2_renderer), not hand-copied.

---

Re-activation checklist (future)

When IMP-04 introduces the first SVG-bearing Phase Z partial:

• Identify partial(s) consuming items[*].cx/cy/r + outer_r + viewbox_*.
• Decide port target — extend phase_z2_renderer with a _preprocess_svg_data analog, or reuse src/svg_calculator.py directly.
• Keep Phase R' references untouched.
• Add anchor SHA bump only if runtime source surface changes.