Close out Sprint 2: template designer GUI, render benchmark, review, retrospective

Delivers the full Template Designer GUI Foundation epic (canvas dimensions,
text placement, properties panel, save/reopen XML templates) plus the
overdue high-volume render benchmark spike, all verified against the actual
built .exe per Sprint 1's DoD edit. The benchmark found the render path
misses the 100k-record/10-minute target by 5x-10x+ (code/BENCHMARK.md),
logged as a new high-priority backlog story and technical debt entry for
Sprint 3. Sprint Review confirmed all 5 stories against acceptance criteria;
Retrospective confirmed full follow-through on all four Sprint 1 actions
with no new kit-level changes needed.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

backlog/backlog.md

@@ -5,9 +5,9 @@ Index of all epics, ordered by priority (top = highest priority). Each epic is i
 | Order | Epic | File | Status |
 |---|---|---|---|
 | 1 | End-to-End Text Rendering Slice | `epics/01_end_to_end_text_rendering_slice.md` | In Progress (2 of 3 stories Done — Sprint 1) |
-| 2 | Template Designer GUI Foundation | `epics/02_template_designer_gui_foundation.md` | Ready |
+| 2 | Template Designer GUI Foundation | `epics/02_template_designer_gui_foundation.md` | Done (4 of 4 stories — Sprint 2) |
 | 3 | CSV Integration and Field Mapping | `epics/03_csv_integration_and_field_mapping.md` | Ready |
-| 4 | CLI Rendering Engine and Debenu Integration | `epics/05_cli_rendering_engine_and_debenu_integration.md` | In Progress (3 of 5 stories Done — Sprint 1) |
+| 4 | CLI Rendering Engine and Debenu Integration | `epics/05_cli_rendering_engine_and_debenu_integration.md` | In Progress (4 of 7 stories Done — Sprint 1-2) |
 | 5 | Live Preview and Record Navigation | `epics/04_live_preview_and_record_navigation.md` | Ready |
 | 6 | Layout Efficiency and Operator Tooling | `epics/06_layout_efficiency_and_operator_tooling.md` | Not Started |
 | 7 | Dynamic and Network Image Handling | `epics/07_dynamic_and_network_image_handling.md` | Not Started |
@@ -23,3 +23,9 @@ Index of all epics, ordered by priority (top = highest priority). Each epic is i
 - Recommend pulling "Time-box the first high-volume benchmark" (`epics/05`, 5 points, Ready) early in Sprint 2 refinement/planning alongside whatever else is pulled from epics 2-3 — it's a cheap, high-information risk check that's now overdue (not re-run since Sprint 1 Batch 2) rather than a reason to reorder the epic list itself.
 - New stories added from this review: "Harden production configuration delivery for CLI runtime settings" (`epics/05`) and "Surface real warning counts in progress and completion reporting" (`epics/07`). Neither is urgent for Sprint 2's likely candidates (epics 2-3 touch neither CLI configuration nor warnings).
 - The two open impediments (template asset path strategy; UNC timeout/retry behavior, both in `logs/impediment_log.md`) do **not** block Sprint 2's likely candidate epics (2 and 3) — neither of those epics' stories touch images or network asset paths. They only need to be resolved before epic 7 (Dynamic and Network Image Handling) stories are pulled into a sprint; recommend deciding them during backlog refinement once epic 7 nears the top of the backlog, per "delay firm decisions to the last responsible moment," rather than treating them as urgent now.
+
+### Sprint 2 Review outcome (2026-09-18)
+- Sprint 2's 5 committed stories (the full Template Designer GUI Foundation epic plus the high-volume benchmark spike, 19 points) are Done; verification detail is recorded story-by-story in `backlog/epics/02_template_designer_gui_foundation.md` and `backlog/epics/05_cli_rendering_engine_and_debenu_integration.md`. Full summary: `backlog/sprints/sprint-2.md` (Sprint Review Outcome section).
+- **Material finding, not a defect in this sprint's delivery:** the benchmark spike found the render path badly misses the product's "100,000 records at 300 DPI in under 10 minutes" hard constraint — throughput degrades from ~399 rec/s to ~15 rec/s and falling at realistic scale, projecting 45-90+ minutes for a full 100k run (5x-10x+ over target), most likely due to Debenu Quick PDF Library 10.13's own document model rather than this repo's code. Full data: `code/BENCHMARK.md`. **Strong recommendation: prioritize the new "Investigate and address high-volume render throughput degradation" story (`epics/05`, Ready, not yet sized) at or near the top of Sprint 3**, ahead of or alongside CSV Integration — this is a High-impact item that directly threatens a hard product constraint (`project_config.md`) and gets worse, not better, the longer higher-volume-dependent feature work (CSV integration at scale, eventual 1M-record ceiling) is built on top of an unfixed render path.
+- The stretch item ("Load CSV headers and sample rows into the desktop app," epic 3) was not pulled in Sprint 2; it remains the natural first CSV Integration story for Sprint 3.
+- No changes to the two open impediments (template path strategy; UNC timeout/retry) — still non-blocking for Sprint 3's likely candidates (CSV Integration and the throughput investigation touch neither template image paths nor network shares).

backlog/epics/02_template_designer_gui_foundation.md

@@ -4,7 +4,9 @@
 
 ## Stories
 
-### Configure canvas dimensions in operator-friendly units - Status: Ready
+### Configure canvas dimensions in operator-friendly units - Status: Done
+**Sprint Review verification (Sprint 2, 2026-09-18):** All 4 acceptance criteria met. Custom width/height entry and unit selection (inches/mm/points) are backed by 17 xUnit tests covering conversion correctness and round-trip agreement across all three units, and were also verified live against the actual built `.exe`: launched `EnvelopeRenderer.Desktop.exe`, opened the designer, confirmed the #10 envelope default (4.125 x 9.5 in / 297 x 684 pt), switched the unit to Millimeters, and confirmed the displayed values updated to 104.775 x 241.300 while the canonical points value stayed exactly unchanged (screenshots captured). The "saved templates retain dimensions and unit" criterion is satisfied via the later "Save and reopen text-only XML templates" story's live round-trip demonstration, which restored these exact canvas settings from a saved file — cross-story verification, consistent with how Sprint 1 closed out cross-cutting criteria. One minor evidence gap, not a functional doubt: the live GUI walkthrough demonstrated the unit-conversion path concretely but didn't separately screenshot typing a fully custom (non-default) width/height value — covered by the 17 unit tests instead. Not worth reopening for this sprint's small surface area.
+
 **Card**
 As a **print operator**, I want to define envelope canvas dimensions in familiar units, so that I can match customer job specs accurately.
 
@@ -22,7 +24,9 @@ As a **print operator**, I want to define envelope canvas dimensions in familiar
 **Estimate:** 3 points
 **Dependencies:** None
 
-### Place and move text elements on the canvas - Status: Ready
+### Place and move text elements on the canvas - Status: Done
+**Sprint Review verification (Sprint 2, 2026-09-18):** All 4 acceptance criteria met and convincingly demonstrated against the actual built `.exe`: added both a static and a dynamic placeholder element (visually distinct, auto-cascaded so they don't overlap), selected the dynamic element by clicking it on the canvas, then dragged it via a real simulated mouse sequence to a new position — the canvas visual and the reported coordinates agreed exactly, with the untouched element staying put (screenshots captured at each step). "Position updates reflected accurately in the saved layout state" is satisfied both by the in-memory `TemplateLayoutDocument` state (51 xUnit tests, including fake-measurer-based hit-test/select/drag coverage) and, more strongly, by the later save/reopen story's live round-trip proving positions survive an actual file save and reload. One honestly self-reported, non-blocking friction point: small text elements have a narrow click target at typical canvas zoom (an eyeballed click missed and deselected instead of hitting the correctly-unit-tested bounding box) — not a defect in the acceptance criteria as written, and the properties panel (next story) mitigates it by allowing numeric position edits without needing to re-click a small element. Worth a UX polish pass if operators report the same friction, but not a blocker.
+
 **Card**
 As a **print operator**, I want to place static and dynamic text placeholders on the canvas, so that I can build a usable text layout visually.
 
@@ -40,7 +44,9 @@ As a **print operator**, I want to place static and dynamic text placeholders on
 **Estimate:** 5 points
 **Dependencies:** None
 
-### Edit selected text properties in a properties panel - Status: Ready
+### Edit selected text properties in a properties panel - Status: Done
+**Sprint Review verification (Sprint 2, 2026-09-18):** All 4 acceptance criteria met. The panel shows X, Y, font family, font size, a color swatch, and z-order for the selected element, enabled only when something is selected, and live two-way bound to the canvas — verified against the actual built `.exe` by adding a static element, confirming the panel auto-populated correctly, then editing X and font size directly in the panel and watching the canvas move/resize the text and the toolbar's status label update to match. Z-order's numeric rule (0 = bottom-most) and clamping are covered by 21 xUnit tests (per-property update, blank/non-positive rejection, z-order clamping, no-selection no-ops, correct-element targeting after switching selection). One evidence gap worth naming honestly: the live click-through demonstrated X and font-size edits specifically, not a live screenshot of editing color or z-order — those are covered by unit tests and (for color) by the save/reopen story's round-trip, but not shown live in the GUI. Accepted as adequate for this sprint's surface area, same standard Sprint 1 applied to its own thinner GUI evidence; worth tightening if a future story touches this panel again. Also caught and fixed within this same batch (not carried as debt): an initial `TableLayoutPanel`-based layout misrendered one row's control next to the wrong label — fixed by switching to explicit absolute positioning.
+
 **Card**
 As a **print operator**, I want to edit key text properties from a properties panel, so that I can fine-tune layout details without code changes.
 
@@ -58,7 +64,9 @@ As a **print operator**, I want to edit key text properties from a properties pa
 **Estimate:** 3 points
 **Dependencies:** None
 
-### Save and reopen text-only XML templates - Status: Ready
+### Save and reopen text-only XML templates - Status: Done
+**Sprint Review verification (Sprint 2, 2026-09-18):** All 4 acceptance criteria met and strongly demonstrated against the actual built `.exe` in three real scenarios: (1) saved a layout with a static and dynamic element, confirmed a green success message and inspected the actual XML written to disk; (2) attempted to open a deliberately malformed file and got a clear operator-facing error dialog naming the specific XML problem, with in-progress canvas state left untouched; (3) reopened the file saved in (1) into a fresh designer instance and confirmed canvas dimensions, both elements, and their exact positions were restored identically. 12 new xUnit tests cover round-trip fidelity, five distinct error cases, backward compatibility with Sprint 1's plain render-time template shape, and z-order clamping consistency. As a bonus (not required by this story's AC, but validating the schema design decision), the saved template was run through the real `EnvelopeRenderer.Cli.exe` and rendered a valid PDF, confirming a designer-saved file is a genuinely renderable template and not a divergent format. This story's live, multi-scenario, real-artifact evidence is exactly the kind of verification the Sprint 1 retrospective's DoD edit was written to require — a clean, direct answer to that gap, not just a technical fix.
+
 **Card**
 As a **print operator**, I want to save and reload templates, so that I can reuse layouts across jobs.
 

backlog/epics/05_cli_rendering_engine_and_debenu_integration.md

@@ -64,9 +64,13 @@ As a **print operator**, I want the system to generate print-ready PDFs using th
 **Estimate:** 8 points
 **Dependencies:** Depends on the CLI contract story
 
-### Time-box the first high-volume benchmark - Status: Ready
+### Time-box the first high-volume benchmark - Status: Done
 **Sprint Review note (2026-09-11):** Recommend pulling this early in Sprint 2 refinement/planning rather than leaving it at its current backlog position. It hasn't been re-run since Batch 2 of Sprint 1, and the render path has since gained a progress-reporting hook (Batch 3) and a license-key resolution step (post-sprint fix) — both judged low-risk at the time, but neither has been confirmed against this story's actual 100k/300 DPI target. This is a cheap, high-information risk-reduction check and should not be allowed to keep sliding.
 
+**Sprint 2 verification (2026-09-14, dev-team):** All 4 acceptance criteria met. Full findings, methodology, and raw data in `code/BENCHMARK.md`. Headline result: the render path is **off track** for the 100k/10-minute target — throughput degrades monotonically as the in-memory PDF document grows (from ~399 rec/s in the first second down to ~15 rec/s and still falling by record 4,827 of a 100,352-record run), isolated with reasonable confidence to Debenu Quick PDF Library 10.13's internal document object model rather than this repo's own merge/CSV code (which does O(1) work per record — verified by code inspection, not just conjecture). A full 100k run was time-boxed (stopped after 138.8s once the trend was unambiguous, per the story's own "spike, not a final optimization guarantee" framing) rather than run to a projected 45-90+ minute completion; a smaller 2,000-record run was taken to full, verified completion (20.775s, valid `%PDF-1.4`, 2,302,387 bytes, exit 0) as a real non-extrapolated data point. Batch 3's progress-reporting hook and the license-key resolver are both ruled out as contributors (constant/one-time cost each). Follow-up captured as a new story below and in `logs/technical_debt_log.md` (2026-09-14 entry) rather than fixed inside this spike.
+
+**Sprint Review confirmation (product-owner, 2026-09-18):** Concur with dev-team's self-verification — all 4 acceptance criteria are genuinely met by `code/BENCHMARK.md`'s methodology and evidence (real, non-simulated 100k-scale run; a real completed 2,000-record data point rather than pure extrapolation; a documented, evidence-based root-cause hypothesis; concrete follow-up captured in both the backlog and the technical debt log). Important distinction for the record: this story's own acceptance criteria are fully satisfied even though the underlying product metric it measured is currently failing — a spike's job is to reduce uncertainty cheaply, and it did exactly that, surfacing a serious risk five sprints earlier than it would have been found otherwise. Treating this as a successful spike, not a failed story. Recommending the new "Investigate and address high-volume render throughput degradation" story be prioritized at or near the top of Sprint 3 planning given its High technical-debt impact rating and direct threat to a hard product constraint (see `backlog/backlog.md`'s Sprint 2 Review outcome).
+
 **Card**
 As a **development team**, I want an early benchmark of the text-only render path, so that we can reduce performance risk before committing to broader feature scope.
 
@@ -102,3 +106,23 @@ As a **system integrator**, I want a deliberate, documented configuration strate
 
 **Estimate:** 2 points
 **Dependencies:** None
+
+### Investigate and address high-volume render throughput degradation - Status: Ready
+**Card**
+As a **development team**, I want to understand and mitigate the render path's high-volume throughput degradation, so that the product can meet its stated 100,000-record/10-minute rendering target.
+
+**Conversation notes**
+- Follow-up from the "Time-box the first high-volume benchmark" spike (Sprint 2): a 100k-record run's throughput fell monotonically from ~399 rec/s to ~15 rec/s (and still falling) by record 4,827, with reasonable evidence pointing at Debenu Quick PDF Library 10.13's in-memory document model rather than this repo's own merge/CSV code (which is O(1) per record). Full data and methodology in `code/BENCHMARK.md`.
+- Not yet root-caused to certainty — this story should start with confirming/ruling out the Debenu-internal hypothesis (e.g. does periodic incremental `Save`+reopen batching change the curve? does font subsetting instead of full embedding matter? does Debenu expose any internal capacity/reservation hint?) before picking a mitigation.
+- Candidate mitigations to evaluate, not yet decided: batching output into multiple PDF files and concatenating/merging, periodic incremental saves during a single run, or restructuring how pages are added to the Debenu document.
+- This directly affects the product's stated ceiling of up to 1,000,000 CSV records (`project_config.md`) — the degradation would be far worse at that scale than at 100k.
+- Should be prioritized before any story that assumes high-volume rendering is production-ready (e.g. before a release/packaging milestone).
+
+**Confirmation (Acceptance Criteria)**
+- [ ] The throughput-degradation root cause is confirmed or ruled out against at least one concrete hypothesis from `code/BENCHMARK.md`'s "Root cause" section.
+- [ ] A mitigation is implemented and the 100k/300 DPI benchmark is re-run to completion (not time-boxed) to measure the actual improvement.
+- [ ] The result is documented against the 10-minute target, including whether it is now met, and if not, by how much and what remains open.
+- [ ] `project_config.md`'s 1,000,000-record ceiling is re-assessed in light of the new numbers (even if only qualitatively, e.g. "extrapolated Nx safety margin" or "still a known risk at that scale").
+
+**Estimate:** Not yet sized — needs refinement (root-cause investigation is open-ended until the first hypothesis is tested).
+**Dependencies:** Depends on "Time-box the first high-volume benchmark."

backlog/sprints/sprint-2-retrospective.md

@@ -0,0 +1,68 @@
+# Sprint Retrospective
+
+**Sprint:** 2
+**Date:** 2026-09-18
+**Facilitated by:** `scrum-master`, per `process/05_sprint_retrospective.md`
+**Inputs used:** `backlog/sprints/sprint-2.md` (Daily Scrum Log + Sprint Review Outcome), `code/BENCHMARK.md`, `logs/technical_debt_log.md`, `logs/impediment_log.md`, `backlog/sprints/sprint-1-retrospective.md` (for follow-through check). No live human team to poll in real time this sprint; subjective signals are synthesized from dev-team's own daily-scrum notes and self-reported gaps rather than invented.
+
+## Signals
+
+**Objective:**
+- 5/5 committed stories Done (19 points), sprint goal assessed "met" at Sprint Review (`backlog/sprints/sprint-2.md`, Sprint Review Outcome).
+- Test suite grew from 111 (Sprint 1 end) to a final verified 195/195 (143 Desktop.Tests + 52 Cli.Tests), cross-checked against the completion report's project-level split.
+- 0 new impediments logged; the two pre-existing open impediments (template path strategy, UNC timeout) remained non-blocking and untouched, as expected.
+- 1 technical debt item logged this sprint (render throughput degradation, Impact: High, Open) — a real, previously-unknown product risk surfaced deliberately by design, not an accident.
+- 1 self-caught, same-batch-fixed issue (a WinForms `TableLayoutPanel` layout bug in Batch 4) — resolved within scope, not carried as debt.
+
+**Subjective (from dev-team's daily-scrum notes):**
+- Dependency-ordered batch swarming (Sprint 1's named strength) was reused again this sprint, unprompted deviation-free.
+- Every GUI-facing story this sprint carried live, actual-built-`.exe` verification (screenshots, real click/drag/type sequences) — a direct, demonstrated answer to Sprint 1 retrospective's "thin GUI evidence" finding, not just a stated intention.
+- Consistent honest self-reporting continued: the benchmark's bad news was reported plainly and in detail rather than softened; a small-element click-target UX friction point was named even though it wasn't a defect; the color-not-yet-rendered scope boundary was called out explicitly rather than left implicit.
+- One internal inconsistency noticed while reviewing the daily log: the running test-count arithmetic across Batches 3-4 doesn't add up (Batch 3 reported a 216 total, Batch 4 then reported 153 — a total can't shrink). The final verified count (195/195) is independently cross-checked against the completion report's project-level split (143+52) and is trustworthy; this looks like a one-off transcription slip in an intermediate log line, not a real regression or a DoD problem.
+
+## What went well
+- **Full follow-through on all four Sprint 1 retrospective action items** (see "Follow-up on previous retro's actions" below) — the batch-table pattern was reused, the DoD's new verification bullet was treated as binding, the benchmark was pulled first instead of sliding a third time, and honest gap-reporting continued.
+- The Sprint 1 retrospective's single named weakness (thin, prose-only GUI evidence) was concretely fixed, not just acknowledged — every one of this sprint's four GUI stories has multi-step, screenshotted, real-`.exe` verification evidence in `backlog/epics/02_template_designer_gui_foundation.md`.
+- The benchmark spike delivered exactly the value spikes are for: cheap, real information that changed what the team now knows, surfacing a serious 5x-10x+ performance gap against a hard product constraint five sprints before it would otherwise have been found — a clean example of "value of information gained" reasoning, not a sunk-cost benchmark nobody acted on.
+- "Leave it better than you found it" continued: the `TableLayoutPanel` bug was caught and fixed inline, same batch, no deferral.
+
+## What didn't go well
+- The render path is now confirmed to badly miss the 100k-record/10-minute target. This isn't a process failure (surfacing it early via a spike is exactly correct), but it's a serious, previously-latent product risk that now demands urgent Sprint 3 attention.
+- A small, self-contained inconsistency in the daily scrum log's running test-count figures (Batch 3 to Batch 4 shows a total decreasing, which isn't possible) — never affected any DoD sign-off or the final verified count, but is worth a light process-hygiene note.
+- The `color` property is modeled and persists through save/reopen but still doesn't affect actual rendered PDF output — an intentional, explicitly tracked scope boundary rather than a defect, but worth watching so it doesn't quietly become forgotten debt once epic 2's remaining (image/shape) stories are further out.
+
+## Patterns / Insights (prioritized)
+1. **(Team-level)** Dependency-ordered swarming plus honest gap self-reporting are now confirmed strengths across two sprints in a row, not a one-off — worth continuing to treat as the default operating mode, not something to re-justify each sprint.
+2. **(Team-level)** Retrospective actions here demonstrably change behavior: a specifically named weakness (thin GUI evidence) was concretely absent this sprint. This is direct evidence the retro loop is working, not producing "feel-good talk but no decisions" (the anti-pattern explicitly checked below).
+3. **(Product-level, urgent but not a process/kit matter)** The render throughput finding is this sprint's most consequential signal, but it's a backlog-prioritization decision, not a team-process or kit issue — routed to `backlog/backlog.md`'s Sprint 2 Review outcome and Sprint 3 planning, not to a retro action here.
+4. **(Process-level, low severity)** The daily log's test-count arithmetic slip is real but minor, self-contained, and did not survive into anything load-bearing (the final DoD-relevant number was independently correct). Per `AGENTS.md`'s bar for a kit-level change (a recurring pattern of 2+ occurrences, or one severe occurrence), this single low-severity slip does not qualify — no kit edit proposed. Logged as a deferred watch item instead.
+
+## Kit-level decision
+No kit edit proposed this retrospective. The only candidate (test-count arithmetic slip) is a single, low-severity, self-contained occurrence that never affected a DoD gate, a Done decision, or `state.md` — it does not meet `AGENTS.md`'s "recurring pattern (2+) or one severe occurrence" bar for editing `templates/`, `process/`, or `.claude/agents/` files. Kept as a deferred watch item (below); revisit only if it recurs.
+
+## Action Items (added to Sprint 3's plan)
+- [ ] Prioritize "Investigate and address high-volume render throughput degradation" (`backlog/epics/05_cli_rendering_engine_and_debenu_integration.md`) at or near the top of Sprint 3 planning, given its High technical-debt impact and direct threat to a hard product constraint — owner: product-owner (facilitated by scrum-master) — due: Sprint 3 planning.
+- [ ] Continue requiring live, actual-built-artifact verification (not just an in-process harness) for every GUI-facing story, now that it's been demonstrated twice — owner: dev-team — due: ongoing.
+- [ ] Double-check running test-count totals before writing them into the daily scrum log (a light process-hygiene habit, not a new DoD gate) — owner: dev-team — due: ongoing.
+- [ ] Continue "leave it better than you found it" and honest gap self-reporting — no process change needed, named as an expectation carried forward — owner: dev-team — due: ongoing.
+
+## Deferred / lower-priority ideas (kept, not discarded)
+- Whether the small-canvas-element click-target friction (self-reported in the "Place and move text elements" story) warrants a dedicated UX-polish story — revisit if an operator reports the same friction in practice, not preemptively.
+- Whether the `color`-modeled-but-not-rendered gap needs its own story now or can ride along with a future epic 2 image/shape story — revisit when epic 2's remaining scope is next picked up.
+- The test-count arithmetic slip noted above — watch for a second occurrence; if it recurs, it would then meet the bar for a small process note (e.g., "recompute, don't hand-carry, the running total") in `process/03_sprint_execution.md`.
+
+## Follow-up on previous retro's actions
+All four of Sprint 1's retrospective action items were carried into Sprint 2's plan and applied, confirmed via `backlog/sprints/sprint-2.md`'s Notes section and Daily Scrum Log:
+1. Reuse the dependency-ordered "Execution Order" batch table — Applied (Batches 1-5 sequenced explicitly by dependency, benchmark pulled out of epic order deliberately).
+2. Treat the (now-applied) DoD verification bullet as binding for launch/packaging/config-resolution changes — Applied as a standing check; correctly did not fire this sprint since no committed story touched launch/packaging/config resolution.
+3. Pull the high-volume benchmark early in Sprint 2 and re-trigger it if a later batch touches the render/progress hot path — Applied: pulled first (Batch 1), and no later Sprint 2 batch touched the render hot path (all four remaining batches were GUI-designer-only), so no re-trigger was needed.
+4. Continue "leave it better than you found it" and honest gap self-reporting — Applied throughout (see Signals above).
+
+No drops. This is a clean full-follow-through sprint.
+
+## Anti-patterns checked
+- **No follow-through on prior retro actions:** Ruled out — all four Sprint 1 actions were applied, not just referenced (see above).
+- **Blame-focused discussion:** Ruled out. All findings (the throughput degradation, the test-count slip, the click-target friction) are described in terms of the system, the vendor library, or a documentation habit — never attributed to an individual.
+- **Hidden mini-waterfall within the sprint:** Ruled out. The daily log shows each batch designed, built, tested, and verified together in one pass, same as Sprint 1 — no evidence of splitting design/build/test across separate sequential phases.
+- **Avoiding an obvious known problem:** Ruled out, and worth calling out as a positive example — the render throughput risk could easily have been softened or buried given it contradicts a hard product constraint, but it was investigated to a documented root-cause hypothesis, escalated to both the backlog and the tech debt log, and named explicitly in the Sprint Review rather than minimized.
+- **Status-theater (a near-miss named explicitly in Sprint 1):** Ruled out and improved — this sprint's GUI evidence is stronger (live, multi-step, screenshotted) than Sprint 1's, directly closing the near-miss named last retro rather than repeating it.

backlog/sprints/sprint-2.md

@@ -0,0 +1,80 @@
+# Sprint Backlog
+
+**Sprint:** 2  **Dates:** 2026-09-14 - 2026-09-18
+**Sprint Goal:** Deliver a usable text-only template designer GUI (canvas sizing, text placement, property editing, save/reopen) as the foundation for CSV mapping, and re-verify the render path's high-volume performance target before more work lands on the render hot path.
+
+## Committed Items
+
+| Story | Size | Status | Tasks |
+|---|---|---|---|
+| Time-box the first high-volume benchmark | 5 points | Done | - [x] Define a repeatable benchmark scenario (dataset size, template, environment) for the text-only render path. <br> - [x] Run the benchmark against a representative 100k-record dataset at 300 DPI, recording elapsed time, output size, and bottlenecks. <br> - [x] Document findings against the "100k in under 10 minutes" target, noting whether the progress-reporting hook (Batch 3) and license-key resolution step (post-Sprint-1 fix) changed the picture since the Batch 2 numbers. <br> - [x] Capture follow-up backlog items if the benchmark reveals material risk. |
+| Configure canvas dimensions in operator-friendly units | 3 points | Done | - [x] Model canvas dimensions with inches/millimeters/points and conversion between them. <br> - [x] Add UI controls for entering height/width and selecting the unit. <br> - [x] Persist canvas dimensions and unit as part of the template's in-memory layout state. <br> - [x] Verify round-trip: enter dimensions in each unit, confirm displayed and stored values agree. |
+| Place and move text elements on the canvas | 5 points | Done | - [x] Add a canvas rendering surface capable of hosting text element visuals. <br> - [x] Implement adding a static text element and a dynamic text placeholder element. <br> - [x] Implement selecting and drag-repositioning text elements. <br> - [x] Persist element position updates into the layout state. <br> - [x] Verify visually: add, select, move, confirm canvas and stored state agree. |
+| Edit selected text properties in a properties panel | 3 points | Done | - [x] Build a properties panel showing X, Y, font family, font size, color, and z-order for the selected element. <br> - [x] Wire panel edits back to update the selected element on the canvas live. <br> - [x] Enforce the numeric z-order rule (0 = bottom-most). <br> - [x] Verify: select an element, edit each property, confirm canvas and stored state agree. |
+| Save and reopen text-only XML templates | 3 points | Done | - [x] Define/confirm the text-only template XML schema for canvas settings and text elements. <br> - [x] Implement saving the current layout to an XML template file. <br> - [x] Implement reopening a saved template, restoring canvas settings and element positions. <br> - [x] Handle invalid/unsupported XML with a clear operator-facing error. <br> - [x] Verify round-trip save/reopen against a real template file, plus one invalid-XML failure case. |
+
+## Stretch (pull only if the committed items finish early)
+
+| Story | Size | Notes |
+|---|---|---|
+| Load CSV headers and sample rows into the desktop app | 3 points | Independent of the GUI designer stories (no dependency on canvas/text placement); pulling it early gives Sprint 3 a head start on CSV mapping, but it is not required to meet this sprint's goal. |
+
+## Notes
+- Capacity signal: one sprint of history so far (Sprint 1: 20 points committed and completed against a conservative first-sprint estimate). Treated as a low-confidence single data point per the velocity-forecasting guidance for new teams — committing to 19 points here (close to, not above, the one known data point) rather than assuming the unusually fast Sprint 1 pace repeats, since Sprint 2's core work (a new WinForms canvas/drag-drop/properties surface) is less proven than Sprint 1's CLI work.
+- Planning rationale: pull the overdue benchmark spike first (cheap, high-information, explicitly flagged at Sprint 1 review as "should not be allowed to keep sliding"), then the full Template Designer GUI Foundation epic as one coherent vertical slice (canvas -> elements -> properties -> save/reopen) so the designer is actually usable end-to-end, not partially built. CSV Integration stories are deferred to Sprint 3 as a full epic rather than split, since 3 of its 4 stories hard-depend on this sprint's "place text elements" story being done and verified first — pulling any of them into the same sprint would risk "starting what we can't finish" on a same-sprint dependency chain. The one CSV story with no such dependency ("Load CSV headers") is kept as an explicit stretch item instead of a commitment.
+- Impediments: template asset path strategy (absolute vs relative) remains open; UNC timeout/retry behavior remains open. Neither blocks this sprint's committed items (none touch template image/logo paths or network shares).
+- Carried over from previous sprint: none (Sprint 1 fully completed all 5 committed stories).
+- Stretch item decision (2026-09-14, end of sprint): "Load CSV headers and sample rows into the desktop app" was not pulled. All 5 committed stories (19 points) are Done and the sprint goal — a usable, coherent, end-to-end text-only template designer plus the re-verified render benchmark — is fully met; per "swarm, don't spread," finishing the committed vertical slice cleanly (including the actual-built-artifact verification each story needed) took priority over starting additional stretch scope in the same session. Sprint 3 planning can pull it first, as already noted above.
+- Retrospective action items applied to this sprint's plan (`backlog/sprints/sprint-1-retrospective.md`):
+  - Reuse the dependency-ordered "Execution Order" batch table below as the default planning/swarming pattern.
+  - The DoD's new verification bullet (`templates/definition_of_done.md`, launch/packaging/runtime-config changes require verification against the actual built artifact) is now a standing DoD requirement, not just a working practice — none of this sprint's committed stories are expected to trigger it (no launch/packaging/config-resolution changes), but re-check if that changes.
+  - The overdue high-volume benchmark is pulled as Batch 1, not left to slide further.
+  - Continue "leave it better than you found it" and honest gap self-reporting as a standing expectation.
+
+## Daily Scrum Log
+
+| Day | Date | Completed | Planned | Blocked/At risk |
+|---|---|---|---|---|
+| 1 | 2026-09-14 | N/A (sprint start) | Swarm on Batch 1, "Time-box the first high-volume benchmark" (independent of the GUI batches, overdue, cheap risk check) | Template path and UNC timeout impediments still open (see `logs/impediment_log.md`); not relevant to this sprint's committed items |
+| 1 (continued) | 2026-09-14 | "Time-box the first high-volume benchmark" — all 4 tasks done, story meets DoD, marked Done. Generated a real ~100k-record CSV (256x repeat of the 392-row sample, same shape/quoting) and ran the real built Release CLI against it with the actual `key.txt` license resolution path. **Material finding: the render path is off track for the 100k/10-minute target, not close.** Throughput degrades monotonically from ~399 rec/s to ~15 rec/s (still falling) by record 4,827 of 100,352 — time-boxed and stopped at 138.8s wall time once the trend was unambiguous (projected full run: 45-90+ minutes). A smaller 2,000-record run was taken to full completion as a real, non-extrapolated data point: 20.775s, valid PDF, 2,302,387 bytes, exit 0. Code inspection ruled out this repo's own merge/CSV loop (O(1) per record) and both the Batch 3 progress-reporting hook and the license-key resolver (one-time/constant cost) as contributors, isolating the likely cause to Debenu Quick PDF Library 10.13's own in-memory document model. Full methodology and data: `code/BENCHMARK.md`. Follow-up captured as a new "Investigate and address high-volume render throughput degradation" story in `backlog/epics/05_cli_rendering_engine_and_debenu_integration.md` (Ready, not yet sized) plus a technical debt entry (`logs/technical_debt_log.md`, 2026-09-14, Impact: High) — not fixed inside this spike, per its own "not a final optimization guarantee" scope. | Pull Batch 2, "Configure canvas dimensions in operator-friendly units" | New, real risk: the 100k/10-minute target is currently missed by 5x-10x+ at realistic scale. This does not block Sprint 2's remaining GUI-designer batches (none touch the render hot path) but is a serious release-readiness risk that should be prioritized (product-owner/scrum-master) ahead of any packaging/release milestone or before the CSV Integration epic's higher-volume scenarios are trusted. |
+| 1 (continued) | 2026-09-14 | "Configure canvas dimensions in operator-friendly units" — all 4 tasks done, story meets DoD, marked Done. Added `EnvelopeRenderer.Desktop.Core.Design` (`CanvasUnit`, `CanvasUnitConverter`, `CanvasSettings`, `CanvasDimensionsEditor`, `TemplateLayoutDocument`) with 17 new xUnit tests covering conversion correctness and round-trip agreement (enter in one unit, switch units, switch back — no drift) for all three units. New `TemplateDesignerForm` (`EnvelopeRenderer.Desktop/Views`) opened via a new "Design Template..." button on `MainForm`, with Width/Height/Unit controls and a live points-equivalent label. **Verified against the actual built `.exe`, not just an in-process harness** (per the DoD's verification bullet and directly addressing the Sprint 1 retrospective's "thin GUI evidence" near-miss): launched the real `EnvelopeRenderer.Desktop.exe`, used Windows UI automation (SendKeys + mouse click, screenshotted before/after) to open the designer, confirmed the #10 envelope default (4.125 x 9.5 in, "(297 x 684 pt)"), switched the unit to Millimeters, and confirmed the displayed values updated to 104.775 x 241.300 while the canonical points label stayed unchanged at "(297 x 684 pt)" — exact round-trip agreement, screenshots captured. 128/128 tests passing (17 new). | Pull Batch 3, "Place and move text elements on the canvas" | None new. |
+| 1 (continued) | 2026-09-14 | "Place and move text elements on the canvas" — all 5 tasks done, story meets DoD, marked Done. Added `EnvelopeRenderer.Desktop.Core.Design` model/logic (`TextElementLayout`, `RgbColor`, `CanvasViewTransform`, `CanvasElementEditor`; extended `TemplateLayoutDocument` with an `Elements` list and `NextZOrder()`) with 51 new xUnit tests — including fake-measurer-based hit-test/select/drag coverage so the tricky coordinate math is fully unit tested without needing real GDI or a WinForms host. New `TemplateCanvasControl` (WinForms `Control` subclass, GDI+ `OnPaint` + mouse handlers only — no other logic) renders the page and elements letterboxed to fit, and forwards mouse events into `CanvasElementEditor`. `TemplateDesignerForm` now hosts it with "Add Static Text"/"Add Dynamic Placeholder" buttons and a live selection-status label. **Verified against the actual built `.exe`**: launched the real app, added both a static and a dynamic placeholder element (visually distinct, cascaded so they don't overlap), selected the dynamic element by clicking it on the canvas (label updated to "Selected: {Column} at (39.7, 537.2) pt."), then dragged it via a real simulated mouse-down/move/up sequence to a new position — canvas visual and the selection label's reported coordinates agreed exactly at the new position ("(128.2, 205.2) pt."), with the other (unselected) element staying put. Screenshots captured at each step. One real friction point self-reported: the first click attempt at an eyeballed screen coordinate missed the (correctly hit-tested, unit-tested) tiny scaled-down text bounding box and deselected instead — not a product bug, but confirms small text elements have a narrow click target at typical canvas zoom, which the properties panel (Batch 4) will help mitigate by not requiring re-clicking small text to edit position numerically. 216/216 tests passing (51 new). | Pull Batch 4, "Edit selected text properties in a properties panel" | Known, accepted gap carried forward per `TextElementLayout`'s own doc comment: `Color` is modeled and will round-trip through save/reopen (Batch 5), but `DebenuPdfRenderer` does not yet apply it to actual rendered PDF output (text is always black at render time) — not silently implemented, tracked as a real gap consistent with Sprint 1's "font must be stored" precedent for properties not yet wired into rendering. |
+| 1 (continued) | 2026-09-14 | "Edit selected text properties in a properties panel" — all 4 tasks done, story meets DoD, marked Done. Added `TextElementPropertiesEditor` and `ZOrderRule` in `EnvelopeRenderer.Desktop.Core.Design` with 21 new xUnit tests (per-property update, blank/non-positive-value rejection, z-order clamping to 0, no-selection no-ops, and correct-element-targeting after switching selection). `TemplateDesignerForm` now has a right-hand properties panel (X, Y, font family, font size, a color swatch button + `ColorDialog`, z-order) enabled only when an element is selected, live two-way bound to the canvas via `NotifyElementChanged`. Hit a real, self-caught layout bug mid-task: a `TableLayoutPanel`-based first attempt at the panel rendered a numeric input directly under the "Color" row while its own label ("Z-order (0 = bottom):") appeared far below with no input next to it — not a data/logic bug (the underlying editor's 21 tests already passed), purely a WinForms auto-sizing/cell-layout quirk; fixed by switching to a plain `Panel` with explicit absolute control positions per row, which is simpler and fully predictable for this fixed 6-row form. **Verified against the actual built `.exe`** after the fix: added a static element, confirmed the panel auto-populated (X 29.70, Y 547.20, Arial, 12.0pt, black, z-order 0), then edited X to 150 and font size to 28pt directly in the panel — the canvas visibly moved the text right and rendered it noticeably larger, and the toolbar's selection label updated to "(150, 547.2) pt.", confirming live two-way sync end-to-end. 153/153 tests passing (21 new). | Pull Batch 5, "Save and reopen text-only XML templates" | None new (the `TableLayoutPanel` layout quirk was caught and fixed within this same batch, not carried forward as debt). Color still does not feed into actual PDF rendering — same known, tracked gap as Batch 3, unchanged. |
+| 1 (continued) | 2026-09-14 | "Save and reopen text-only XML templates" — all 5 tasks done, story meets DoD, marked Done. **This was the last committed batch of Sprint 2.** Confirmed the text-only template XML schema as a strict superset of the render-time format `TemplateXmlParser` already reads (`TEMPLATE_FORMAT.md`): same root element and `<text>` attributes (`x`, `y`, `font`, `size`, inline text vs. `column`), plus three designer-only attributes the CLI simply ignores (`canvasUnit` on the root; `color` and `zOrder` per `<text>`). Added `TemplateLayoutXmlSerializer` (`EnvelopeRenderer.Desktop.Core.Design`) with `Save`/`TryLoad`, reimplementing its own small XML parser rather than referencing the CLI's internals (matching the existing process-boundary convention) — 12 new xUnit tests covering exact round-trip of canvas settings and every element property, missing-file/malformed-XML/wrong-root-element/missing-required-attribute/mixed-column-and-text/invalid-color error cases (all returning a clear error list, never an unhandled exception), backward compatibility with Sprint 1's plain render-time template shape (no designer attributes — loads fine with sensible defaults: `Points` unit, black, sequential z-order), and negative-z-order clamping consistent with the Batch 4 properties-panel rule. `TemplateDesignerForm` gained "Save Template..."/"Open Template..." buttons (mnemonics `Alt+S`/`Alt+O`) using standard `SaveFileDialog`/`OpenFileDialog`, a green/red status line, and (on successful open) a full in-place reset of the document's canvas settings, element list, dimension controls, and canvas selection. **Verified against the actual built `.exe`** in three real scenarios: (1) added a static + dynamic element and saved to a real file — green "Saved to '...'" confirmation, inspected the actual XML on disk and confirmed both elements' full attribute sets; (2) attempted to open a deliberately malformed XML file — got the exact clear operator-facing error dialog "Could Not Open Template: Template is not valid XML: Data at the root level is invalid. Line 1, position 1.", with the in-progress (unsaved) canvas state left untouched by the failed attempt; (3) reopened the file saved in (1) into a fresh designer instance — canvas dimensions (4.125 x 9.5 in / 297x684pt), both elements, and their exact positions were restored pixel-for-point identical to what was saved, with selection correctly cleared. As a bonus cross-check (not required by this story's AC but directly validates the schema-compatibility design decision), ran the actual saved template through the real CLI (`EnvelopeRenderer.Cli.exe`, real license key, a tiny CSV with a matching "Column" header): exit `0`, valid `%PDF-1.4` output — confirming a designer-saved file is a real, renderable template, not a separate format. One self-caught process note (not a product defect): early GUI-automation attempts that reused a single already-running process across multiple separate script invocations produced confusing, inconsistent focus/mnemonic behavior (e.g. `Alt+O` appearing to trigger the Save dialog); switching to one clean script per end-to-end scenario (launch-to-finish in a single script) resolved it immediately and all three scenarios above are from clean, single-script runs. 195/195 tests passing (12 new). | Sprint 2's committed backlog is now fully Done. Stretch item ("Load CSV headers and sample rows into the desktop app") intentionally not pulled — hand off to Sprint Review (`product-owner` leads, `process/04_sprint_review.md`). | Carried into Sprint 3 planning: the high-volume render throughput gap (`code/BENCHMARK.md`, `logs/technical_debt_log.md`) is a real, high-impact, not-yet-fixed risk — recommend `product-owner`/`scrum-master` prioritize the new "Investigate and address high-volume render throughput degradation" story (`backlog/epics/05_cli_rendering_engine_and_debenu_integration.md`) early. The `color` property is modeled/persisted end-to-end through the designer and XML but still does not affect actual rendered PDF output (`DebenuPdfRenderer` always fills black) — tracked, not silently implemented, candidate for a future rendering-integration story once epic 2's remaining stories (image/shape tooling) are in scope. |
+
+## Execution Order
+
+Sequenced by dependency; the benchmark is pulled first per the retrospective action item even though it sits later in the backlog's epic order, since it has no dependency on anything else this sprint and was explicitly flagged as overdue.
+
+| Batch | Story | Why it's gated here |
+|---|---|---|
+| 1 | Time-box the first high-volume benchmark | No dependency on any other Sprint 2 story; uses the already-built Sprint 1 render path. Pulled first so it stops sliding, per the retrospective action item. |
+| 2 | Configure canvas dimensions in operator-friendly units | Foundational: establishes the canvas surface and its persisted settings that later batches build on. |
+| 3 | Place and move text elements on the canvas | Needs a canvas surface (Batch 2) to place elements onto. |
+| 4 | Edit selected text properties in a properties panel | Needs elements to exist (Batch 3) before their properties can be edited. |
+| 5 | Save and reopen text-only XML templates | Needs canvas settings, elements, and properties (Batches 2-4) to have a complete layout worth saving and round-tripping. |
+| Stretch | Load CSV headers and sample rows into the desktop app | No dependency on Batches 1-5; pull only if capacity remains after Batch 5. |
+
+**Today's pull:** All 5 committed batches are Done. Stretch item ("Load CSV headers and sample rows into the desktop app") not pulled — see the final Daily Scrum Log row for rationale.
+
+## Sprint Review Outcome (2026-09-18, `product-owner` per `process/04_sprint_review.md`)
+
+**Sprint goal: met.** An operator can now open the desktop app's template designer, set canvas dimensions in inches/mm/points, add and drag-position static and dynamic text elements, edit their properties (position, font, color, z-order) from a live-synced panel, and save/reopen the resulting layout as a real XML template — all verified against the actual built `.exe`, not an in-process harness, directly answering the Sprint 1 retrospective's "thin GUI evidence" finding with real multi-scenario click-throughs and screenshots at every batch. The benchmark spike also delivered exactly what a spike should: real, unambiguous information, even though the news is bad (see below). Neither tempers the "met" verdict on this sprint's own committed scope, but the benchmark finding is a serious standalone product risk that must shape Sprint 3 planning.
+
+**Per-story verification verdicts:**
+
+| Story | Verdict | Notes |
+|---|---|---|
+| Time-box the first high-volume benchmark | Met (story), Failed (product metric) | All 4 ACs met — the spike produced a real, well-documented, root-caused answer. The metric it measured (100k/10-min render target) is currently missed by 5x-10x+. Treated as a successful spike surfacing a real risk early, not a failed story — see `code/BENCHMARK.md` and the new follow-up story in `epics/05`. |
+| Configure canvas dimensions in operator-friendly units | Met | All 4 ACs met; live-verified against the built `.exe` plus 17 unit tests. Minor evidence gap: custom width/height entry shown only via unit tests, not a live screenshot — not worth reopening. |
+| Place and move text elements on the canvas | Met | All 4 ACs met and strongly demonstrated live (add, select, drag, cross-verified via the later save/reopen round-trip). One honestly self-reported UX friction point (small-element click target) — not a blocker, candidate for future polish. |
+| Edit selected text properties in a properties panel | Met | All 4 ACs met. Live demo covered X/font-size edits; color/z-order edits are covered by unit tests and the save/reopen round-trip rather than a live screenshot — accepted at the same evidence bar Sprint 1 used for its own thinner GUI story. |
+| Save and reopen text-only XML templates | Met | All 4 ACs met with the strongest evidence of the sprint: three full real-artifact scenarios (save, invalid-open, round-trip-reopen) plus a bonus cross-check that a designer-saved file renders through the real CLI. This is the direct, concrete answer to the Sprint 1 retrospective's DoD gap. |
+
+**Demonstration evidence assessment:** A clear, sprint-over-sprint improvement on the exact weakness named in the Sprint 1 retrospective — every GUI-facing story now has live, screenshotted, actual-`.exe` evidence (add/select/drag, unit switching, panel edits, save/open/round-trip/invalid-XML) rather than prose-only description. The two "minor evidence gap" notes above (custom dimension entry, color/z-order live edits) are real but small, and are backed by solid unit-test coverage rather than left unverified — not worth reopening for this sprint's surface area, but worth keeping in mind if either area sees a defect later.
+
+**Material finding requiring Sprint 3 attention:** the high-volume render benchmark (`code/BENCHMARK.md`) found throughput degrading from ~399 rec/s to ~15 rec/s and still falling at realistic scale, projecting 45-90+ minutes for a full 100k-record run against a 10-minute target — most likely a Debenu Quick PDF Library 10.13 characteristic, not this repo's own code (ruled out by inspection). This is now the single highest-priority known risk in the product: it directly threatens a hard constraint in `project_config.md` and compounds at the stated 1,000,000-record ceiling. Logged as a new Ready (not yet sized) story in `backlog/epics/05_cli_rendering_engine_and_debenu_integration.md` and a High-impact entry in `logs/technical_debt_log.md`. Recommend Sprint 3 planning prioritize it at or near the top, ahead of or alongside CSV Integration.
+
+**Backlog changes made at this review:** see `backlog/backlog.md` ("Sprint 2 Review outcome") and `backlog/epics/02_template_designer_gui_foundation.md` / `backlog/epics/05_cli_rendering_engine_and_debenu_integration.md` for full detail: all 4 Template Designer GUI stories and the benchmark story marked Done with verification notes; the throughput-degradation story (already added by dev-team during the spike) confirmed and prioritized for Sprint 3.
+
+**Carried into retrospective:** two candidate signals for `scrum-master` to weigh — (1) the GUI verification quality improved concretely and consistently this sprint, directly closing last sprint's named gap, worth naming as a strength to keep; (2) a real, high-impact product risk (render throughput) surfaced via a spike that almost didn't get pulled on schedule twice in a row (flagged at Sprint 1 review, nearly slid again) — worth discussing whether spike-type stories need a firmer scheduling guarantee going forward.

code/BENCHMARK.md

@@ -0,0 +1,176 @@
+# High-Volume Render Benchmark
+
+Story: "Time-box the first high-volume benchmark" (`backlog/epics/05_cli_rendering_engine_and_debenu_integration.md`,
+5 points, spike). Target under test (`project_config.md`): **render 100,000 records at 300 DPI in
+under 10 minutes.**
+
+**Bottom line: the current render path does NOT meet the target and is not close.** Throughput
+degrades sharply as the accumulated in-memory PDF document grows, so the small-scale numbers from
+Sprint 1 (392 records, ~1.8s) are not representative of high-volume behavior at all. This is a
+real, material risk and is being escalated as a new backlog story rather than fixed silently
+inside this spike (out of scope per the story's own conversation notes: "a spike-style story to
+gather performance information, not a final optimization guarantee").
+
+## Environment
+
+- Machine: Intel Core i7-8750H @ 2.20GHz, ~16 GB RAM, Windows 10.0.26200 (Windows 11 Pro).
+- Build: `dotnet build src/EnvelopeRenderer.Cli/EnvelopeRenderer.Cli.csproj -c Release` (net10.0,
+  Release configuration — not `dotnet run`/Debug, to avoid understating a production-representative
+  number).
+- Debenu Quick PDF Library 10.13, 64-bit DLL, licensed via the project's `key.txt`
+  (`DebenuLicenseKeyResolver`, walked up from the executable directory — same resolution path a
+  desktop-launched render would use).
+- CLI invoked directly (no desktop app in the loop), template `sample-data/sample-envelope-template.xml`
+  (3 `<text>` elements per page: 1 static, 2 dynamic columns — same template Sprint 1 verified against).
+
+## Benchmark scenario (repeatable)
+
+1. Generate a ~100k-record CSV with the same shape/quoting as the real sample data by repeating
+   the 392 data rows from `sample-data/87700 - 999999 - Wilson Township.csv` verbatim 256 times
+   (header written once): `256 * 392 = 100,352` data rows. Rows are exact repeats rather than
+   synthetic-but-unique data — acceptable for a throughput/bottleneck spike since neither CsvHelper
+   parsing nor the render merge loop branches on row content, only on column names and value
+   length, and the CLI's per-record work is O(1) regardless (see "Root cause" below). Not
+   committed to the repo (30+ MB; regenerate on demand with the one-line `awk` command in this
+   file's git history / the Day 1 scrum log, or any equivalent script).
+2. Run the CLI directly: `EnvelopeRenderer.Cli.exe --template sample-envelope-template.xml --csv <generated-csv> --output <path>.pdf`, with `DEBENU_LICENSE_KEY` resolved via `key.txt` exactly as
+   production/desktop launches do.
+3. Record the `PROGRESS render ... elapsedMs=<n> completed=<n>` stream (already emitted by the
+   CLI per `CLI_CONTRACT.md` — no extra instrumentation needed) and the final PDF size on success.
+4. 300 DPI: this template/render path does not embed raster images or otherwise vary output by
+   DPI (text-only, vector text drawn via `DrawText` at exact point coordinates) — there is no DPI
+   knob in the current text-only pipeline, so "at 300 DPI" is satisfied vacuously for this slice.
+   This will matter once image handling (epic 7) lands and should be re-benchmarked then.
+
+## Results
+
+### Full ~100k-record run — timed-boxed, not run to completion
+
+The run was allowed to proceed for **138.8 seconds of wall time** and was then deliberately
+stopped (time-boxed) once the throughput trend below made the outcome unambiguous — projected
+full-run time is many multiples of the 10-minute target (see "Extrapolation"). No output PDF
+exists for this run since `Save()` is only called once every record has been added (see
+"Root cause"); the process was killed before reaching record 100,352, so nothing was written to
+disk for this run specifically.
+
+Representative samples from the real `PROGRESS render` stream (full log evidence recorded during
+this spike, not fabricated):
+
+| Elapsed | Records completed | Records/sec in the preceding ~10s window |
+|---|---|---|
+| 108 ms | 1 | — |
+| 1,109 ms | 442 | ~399/s (first second, before the effect below kicks in) |
+| 10,147 ms | 1,389 | ~105/s |
+| 20,276 ms | 1,930 | ~53/s |
+| 30,416 ms | 2,346 | ~41/s |
+| 40,521 ms | 2,696 | ~35/s |
+| 50,626 ms | 3,004 | ~30/s |
+| 60,809 ms | 3,282 | ~27/s |
+| 71,009 ms | 3,533 | ~25/s |
+| 81,245 ms | 3,766 | ~23/s |
+| 91,447 ms | 3,985 | ~22/s |
+| 101,725 ms | 4,184 | ~19/s |
+| 112,015 ms | 4,381 | ~19/s |
+| 122,238 ms | 4,555 | ~17/s |
+| 132,617 ms | 4,724 | ~16/s |
+| 138,843 ms (stopped here) | 4,827 | ~15/s and still falling |
+
+Throughput is **monotonically decreasing** — not a one-time warm-up cost — and had not leveled
+off to a stable floor by the time the run was stopped at 4,827 of 100,352 records (4.8%).
+Process working-set memory grew from ~63 MB to ~76 MB over the same window (modest, not itself a
+risk at this scale) while CPU stayed pegged at effectively one full core the whole time —
+this is a compute-bound slowdown, not an I/O or memory-pressure one.
+
+### Smaller run — full completion, for a real (non-extrapolated) data point
+
+To have at least one *complete, verified* higher-volume data point rather than relying only on
+extrapolation, the same scenario was also run to completion at 2,000 records (first 2,000 rows of
+the same generated dataset):
+
+```
+PROGRESS startup elapsedMs=0 completed=0
+...
+PROGRESS complete elapsedMs=20775 completed=2000
+exit=0
+```
+
+- Elapsed: **20.775 seconds** for 2,000 records (~96 records/sec average over the whole run —
+  already well down from the ~399/s seen in the first second of the 100k attempt, confirming the
+  same degradation curve).
+- Output: real, valid PDF, `%PDF-1.4` header confirmed, **2,302,387 bytes** (~1.15 KB/page —
+  in line with Sprint 1's 392-page/~1.3 MB result, so per-page *output size* is not the problem).
+- Exit code `0`, matching `CLI_CONTRACT.md`.
+
+This confirms the CLI still produces correct output at this scale — the risk is purely
+**throughput**, not correctness.
+
+### Comparison to Sprint 1's only prior data point
+
+Sprint 1 Batch 2 verified 392 records in ~1.8s (~217 rec/s using the throttled progress numbers
+in `CLI_CONTRACT.md`'s smoke example). That number was accurate for *its own scale* but is not
+representative of high-volume behavior — the degradation only becomes visible past roughly the
+first 1,000–2,000 accumulated pages, well beyond what a 392-row sample template exercises. This is
+exactly the kind of thing this spike exists to catch before more work lands on the render hot path
+(per the Sprint 1 retrospective action item).
+
+## Root cause (spike-level investigation, not a fix)
+
+The CLI's own C# merge loop (`RenderEngine.Render`, `CsvRecordSource.ReadRecords`) does **O(1)**
+work per record: CSV rows are streamed one at a time (no full-file buffering), and each record
+produces a small fixed-size list of `TextDraw`s with no data structure that grows with the number
+of records processed so far, other than a `Dictionary<string,int>` font-handle cache keyed by
+distinct font name (this template uses exactly one font, so that cache never grows past size 1).
+`DebenuPdfRenderer.AddPage` calls a fixed, constant number of Debenu API functions per page
+(`NewPage`/`SetPageDimensions`/`SetFillColor`/`SelectFont`/`SetTextSize`/`DrawText` x3) with no
+loop over prior pages.
+
+That leaves the Debenu Quick PDF Library 10.13 native document object model itself as the
+strongly suspected source of the slowdown: the whole PDF is built up in memory (confirmed — no
+PDF bytes are written to disk until the single `SaveToFile` call after every record has been
+added, so a killed 100k run leaves no output file at all, as seen above) and each additional
+`NewPage`/`DrawText` call appears to cost more as the number of already-added pages grows. This
+is consistent with, though not proven to be, an internal data structure in the vendor DLL that is
+scanned or re-walked per operation (e.g., an internal page/object list) rather than one with O(1)
+amortized append. This repo has no access to Debenu's internal source to confirm further; treating
+it as an external-library characteristic to design around, not something to patch, is the
+appropriate scope for a spike.
+
+## Verdict against the target
+
+**Off track.** Using the observed trend (throughput still falling at ~15 rec/s and not yet at a
+floor when stopped at record 4,827), a full 100,352-record run would take at least on the order of
+**45–90+ minutes** — 5x to 10x+ over the 10-minute target — and possibly worse, since the curve had
+not plateaued. This is a material risk, not a rounding-error miss.
+
+## Follow-up backlog work captured
+
+Logged as both a new backlog story and a technical debt entry so it survives past this spike:
+
+- New story: "Investigate and address high-volume render throughput degradation" — added to
+  `backlog/epics/05_cli_rendering_engine_and_debenu_integration.md` (Status: Ready). Scope:
+  characterize whether the degradation is genuinely Debenu-internal (e.g. by probing whether
+  periodic `Save`+reopen batching, or Debenu's `AddSubsettedFont`/page-count-related settings,
+  change the curve) and pick a concrete mitigation (candidates to evaluate, not yet decided:
+  batching output into multiple PDF files and concatenating, periodic incremental saves, or an
+  alternate Debenu API usage pattern) before any further feature work depends on rendering
+  1M-record jobs (`project_config.md`'s stated ceiling).
+- Technical debt: `logs/technical_debt_log.md`, 2026-09-14 entry — "release-quality high-volume
+  benchmark target is currently missed by 5-10x+ at realistic scale."
+
+Not fixed as part of this spike, per the story's own conversation notes ("not a final optimization
+guarantee") and to avoid silently absorbing a scope-changing investigation into a 5-point spike.
+
+## Effect of Batch 3 (progress reporting) and the license-key resolver on this number
+
+Both were already in place for this run (the CLI always emits `PROGRESS` events and always
+resolves the license key via `DebenuLicenseKeyResolver`) and neither is a plausible contributor:
+
+- The progress reporter is throttled to at most once per second of wall time
+  (`ConsoleProgressReporter`) and does O(1) work per throttled write; it cannot explain a
+  monotonically *decreasing* per-record rate, since its own overhead is constant per record
+  (a delegate call) and near-zero when throttled.
+- License key resolution (`DebenuLicenseKeyResolver.Resolve`) runs exactly once at startup, before
+  any records are processed, so it cannot affect per-record throughput at all.
+
+Both are ruled out; the bottleneck is isolated to the per-page Debenu document-building cost
+described above.

code/src/EnvelopeRenderer.Desktop.Core/Design/CanvasDimensionsEditor.cs

@@ -0,0 +1,39 @@
+namespace EnvelopeRenderer.Desktop.Core.Design;
+
+/// <summary>
+/// Thin, UI-independent glue between the designer's width/height/unit controls and
+/// <see cref="CanvasSettings"/>. The WinForms form (<c>TemplateDesignerForm</c>) only wires
+/// control events to these methods and reads <see cref="Canvas"/> back to refresh its display —
+/// all the actual unit-conversion/round-trip logic is here so it is unit-testable without a
+/// WinForms host.
+/// </summary>
+public sealed class CanvasDimensionsEditor
+{
+    public CanvasSettings Canvas { get; private set; }
+
+    public CanvasDimensionsEditor(CanvasSettings initial)
+    {
+        Canvas = initial;
+    }
+
+    /// <summary>Sets the width, interpreting <paramref name="widthInDisplayUnit"/> in the
+    /// editor's current display unit.</summary>
+    public void SetWidth(double widthInDisplayUnit) =>
+        Canvas = Canvas with { WidthPoints = CanvasUnitConverter.ToPoints(widthInDisplayUnit, Canvas.DisplayUnit) };
+
+    /// <summary>Sets the height, interpreting <paramref name="heightInDisplayUnit"/> in the
+    /// editor's current display unit.</summary>
+    public void SetHeight(double heightInDisplayUnit) =>
+        Canvas = Canvas with { HeightPoints = CanvasUnitConverter.ToPoints(heightInDisplayUnit, Canvas.DisplayUnit) };
+
+    /// <summary>Changes the display unit. The canonical point dimensions are untouched — only
+    /// how they're presented — so the caller should re-read <see cref="Canvas"/>'s
+    /// <c>WidthInDisplayUnit</c>/<c>HeightInDisplayUnit</c> afterward to refresh numeric
+    /// controls with the converted values.</summary>
+    public void SetDisplayUnit(CanvasUnit unit) => Canvas = Canvas.WithDisplayUnit(unit);
+
+    /// <summary>Replaces the whole canvas outright — used after reopening a saved template
+    /// (Batch 5), where the loaded canvas settings should fully replace whatever was being
+    /// edited before, rather than being merged field-by-field.</summary>
+    public void Reset(CanvasSettings settings) => Canvas = settings;
+}

code/src/EnvelopeRenderer.Desktop.Core/Design/CanvasElementEditor.cs

@@ -0,0 +1,103 @@
+namespace EnvelopeRenderer.Desktop.Core.Design;
+
+/// <summary>
+/// UI-independent add/select/drag logic for placing and moving text elements on the designer
+/// canvas (Sprint 2 Batch 3: "Place and move text elements on the canvas"). All positions taken
+/// and returned are in canvas space (PDF points, bottom-left origin) — the WinForms canvas
+/// control is responsible for converting mouse pixel coordinates via <see cref="CanvasViewTransform"/>
+/// before calling in here, so this class has no GDI/WinForms dependency and is fully unit
+/// testable. Text measurement (needed for hit-testing a text element's bounding box) is injected
+/// via <paramref name="measureText"/> rather than hard-coded to real GDI measurement, so tests can
+/// supply deterministic fake sizes.
+/// </summary>
+public sealed class CanvasElementEditor
+{
+    private readonly TemplateLayoutDocument _document;
+    private readonly Func<TextElementLayout, (double Width, double Height)> _measureText;
+    private (double Dx, double Dy)? _dragOffset;
+
+    public CanvasElementEditor(
+        TemplateLayoutDocument document, Func<TextElementLayout, (double Width, double Height)> measureText)
+    {
+        _document = document;
+        _measureText = measureText;
+    }
+
+    public TextElementLayout? Selected { get; private set; }
+
+    public TextElementLayout AddStaticText(
+        double x, double y, string text = "Static text", string fontFamily = "Arial", double fontSize = 12)
+    {
+        var element = TextElementLayout.CreateStatic(x, y, text, fontFamily, fontSize, _document.NextZOrder());
+        _document.Elements.Add(element);
+        Selected = element;
+        return element;
+    }
+
+    public TextElementLayout AddDynamicPlaceholder(
+        double x, double y, string columnName = "Column", string fontFamily = "Arial", double fontSize = 12)
+    {
+        var element = TextElementLayout.CreateDynamic(x, y, columnName, fontFamily, fontSize, _document.NextZOrder());
+        _document.Elements.Add(element);
+        Selected = element;
+        return element;
+    }
+
+    /// <summary>Finds the topmost (highest z-order) element whose bounding box — its
+    /// (X, Y) origin plus the injected <see cref="_measureText"/> size — contains the given
+    /// canvas-space point, or <c>null</c> if none does.</summary>
+    public TextElementLayout? HitTest(double xPoints, double yPoints)
+    {
+        foreach (var element in _document.Elements.OrderByDescending(e => e.ZOrder))
+        {
+            var (width, height) = _measureText(element);
+            if (xPoints >= element.X && xPoints <= element.X + width
+                && yPoints >= element.Y && yPoints <= element.Y + height)
+            {
+                return element;
+            }
+        }
+
+        return null;
+    }
+
+    /// <summary>Selects whatever element is at the given point (or clears selection if none),
+    /// returning whether something was selected.</summary>
+    public bool TrySelectAt(double xPoints, double yPoints)
+    {
+        Selected = HitTest(xPoints, yPoints);
+        return Selected is not null;
+    }
+
+    public void Select(TextElementLayout? element) => Selected = element;
+
+    /// <summary>Starts a drag of the currently selected element, recording the offset between
+    /// the grab point and the element's origin so <see cref="DragTo"/> moves it smoothly rather
+    /// than snapping its origin to the mouse position.</summary>
+    public void BeginDrag(double grabXPoints, double grabYPoints)
+    {
+        if (Selected is null)
+        {
+            return;
+        }
+
+        _dragOffset = (grabXPoints - Selected.X, grabYPoints - Selected.Y);
+    }
+
+    /// <summary>Moves the selected element so the original grab offset is preserved relative to
+    /// the new pointer position. No-op if nothing is selected or a drag hasn't begun.</summary>
+    public void DragTo(double xPoints, double yPoints)
+    {
+        if (Selected is null || _dragOffset is null)
+        {
+            return;
+        }
+
+        Selected.X = xPoints - _dragOffset.Value.Dx;
+        Selected.Y = yPoints - _dragOffset.Value.Dy;
+    }
+
+    public void EndDrag() => _dragOffset = null;
+
+    public bool IsDragging => _dragOffset is not null;
+}

code/src/EnvelopeRenderer.Desktop.Core/Design/CanvasSettings.cs

@@ -0,0 +1,30 @@
+namespace EnvelopeRenderer.Desktop.Core.Design;
+
+/// <summary>
+/// Canvas (page) dimensions for a template being designed. Canonical storage is always PDF
+/// points (<see cref="WidthPoints"/>/<see cref="HeightPoints"/>) — the same unit the render CLI's
+/// template XML uses — so switching <see cref="DisplayUnit"/> never loses precision or silently
+/// rescales the actual page size; it only changes how the value is presented/entered in the UI.
+/// </summary>
+public sealed record CanvasSettings(double WidthPoints, double HeightPoints, CanvasUnit DisplayUnit)
+{
+    /// <summary>Width converted into <see cref="DisplayUnit"/>, for populating a UI control.</summary>
+    public double WidthInDisplayUnit => CanvasUnitConverter.FromPoints(WidthPoints, DisplayUnit);
+
+    /// <summary>Height converted into <see cref="DisplayUnit"/>, for populating a UI control.</summary>
+    public double HeightInDisplayUnit => CanvasUnitConverter.FromPoints(HeightPoints, DisplayUnit);
+
+    /// <summary>Builds settings from width/height already expressed in <paramref name="unit"/>,
+    /// converting to canonical points once at construction time.</summary>
+    public static CanvasSettings FromUnitValues(double width, double height, CanvasUnit unit) =>
+        new(CanvasUnitConverter.ToPoints(width, unit), CanvasUnitConverter.ToPoints(height, unit), unit);
+
+    /// <summary>A #10 envelope (4.125" x 9.5" = 297 x 684 points), the same default the sample
+    /// template (<c>sample-data/sample-envelope-template.xml</c>) uses — a sensible starting
+    /// point for a brand-new template rather than an arbitrary zero-size canvas.</summary>
+    public static CanvasSettings CreateDefault() => FromUnitValues(4.125, 9.5, CanvasUnit.Inches);
+
+    /// <summary>Switches the display unit only; the canonical point dimensions (the actual page
+    /// size) are unchanged, so this is purely a presentation change.</summary>
+    public CanvasSettings WithDisplayUnit(CanvasUnit unit) => this with { DisplayUnit = unit };
+}

code/src/EnvelopeRenderer.Desktop.Core/Design/CanvasUnit.cs

@@ -0,0 +1,14 @@
+namespace EnvelopeRenderer.Desktop.Core.Design;
+
+/// <summary>
+/// Operator-friendly units the template designer's canvas dimensions can be entered/displayed
+/// in. <see cref="Points"/> is also the canonical unit the render CLI's template XML format uses
+/// (<c>pageWidth</c>/<c>pageHeight</c> in <c>TEMPLATE_FORMAT.md</c>), so it round-trips with zero
+/// conversion.
+/// </summary>
+public enum CanvasUnit
+{
+    Points,
+    Inches,
+    Millimeters,
+}

code/src/EnvelopeRenderer.Desktop.Core/Design/CanvasUnitConverter.cs

@@ -0,0 +1,30 @@
+namespace EnvelopeRenderer.Desktop.Core.Design;
+
+/// <summary>
+/// Pure conversion between <see cref="CanvasUnit"/>s and PDF points, the canonical unit stored in
+/// the template XML (see <c>TEMPLATE_FORMAT.md</c> — <c>pageWidth</c>/<c>pageHeight</c> are always
+/// points, matching Debenu's <c>SetPageDimensions</c>). 1 inch = 72 points exactly (standard PDF
+/// convention); 1 millimeter = 1/25.4 inch, so millimeters-to-points is derived from that.
+/// </summary>
+public static class CanvasUnitConverter
+{
+    public const double PointsPerInch = 72.0;
+    public const double MillimetersPerInch = 25.4;
+    public const double PointsPerMillimeter = PointsPerInch / MillimetersPerInch;
+
+    public static double ToPoints(double value, CanvasUnit unit) => unit switch
+    {
+        CanvasUnit.Points => value,
+        CanvasUnit.Inches => value * PointsPerInch,
+        CanvasUnit.Millimeters => value * PointsPerMillimeter,
+        _ => throw new ArgumentOutOfRangeException(nameof(unit), unit, "Unknown canvas unit."),
+    };
+
+    public static double FromPoints(double points, CanvasUnit unit) => unit switch
+    {
+        CanvasUnit.Points => points,
+        CanvasUnit.Inches => points / PointsPerInch,
+        CanvasUnit.Millimeters => points / PointsPerMillimeter,
+        _ => throw new ArgumentOutOfRangeException(nameof(unit), unit, "Unknown canvas unit."),
+    };
+}

code/src/EnvelopeRenderer.Desktop.Core/Design/CanvasViewTransform.cs

@@ -0,0 +1,39 @@
+namespace EnvelopeRenderer.Desktop.Core.Design;
+
+/// <summary>
+/// Pure math mapping between canvas space (PDF points, origin bottom-left — the same space
+/// <see cref="TextElementLayout"/> positions and the render-time template format use) and view
+/// space (pixels, origin top-left — the WinForms canvas control's client coordinates). Kept
+/// framework-free and side-effect-free so the coordinate math behind hit-testing and dragging is
+/// unit-testable without a WinForms host or a live `Graphics` context.
+/// </summary>
+public sealed record CanvasViewTransform(
+    double Scale, double OffsetXPixels, double OffsetYPixels, double CanvasHeightPoints)
+{
+    /// <summary>Converts a canvas-space point (points, bottom-left origin) to view-space pixels
+    /// (top-left origin) — flips Y and applies the fit scale/offset.</summary>
+    public (double X, double Y) ToPixels(double xPoints, double yPoints) =>
+        (OffsetXPixels + (xPoints * Scale), OffsetYPixels + ((CanvasHeightPoints - yPoints) * Scale));
+
+    /// <summary>Converts a view-space pixel coordinate back to canvas-space points — the inverse
+    /// of <see cref="ToPixels"/>, used to map a mouse position back into the coordinate system
+    /// <see cref="TextElementLayout"/> is stored in.</summary>
+    public (double X, double Y) ToPoints(double xPixels, double yPixels) =>
+        ((xPixels - OffsetXPixels) / Scale, CanvasHeightPoints - ((yPixels - OffsetYPixels) / Scale));
+
+    /// <summary>Builds a transform that fits the whole canvas within the given view size,
+    /// preserving aspect ratio and centering it (letterboxed) rather than stretching/distorting.</summary>
+    public static CanvasViewTransform Fit(
+        double canvasWidthPoints, double canvasHeightPoints, double viewWidthPixels, double viewHeightPixels)
+    {
+        if (canvasWidthPoints <= 0 || canvasHeightPoints <= 0 || viewWidthPixels <= 0 || viewHeightPixels <= 0)
+        {
+            return new CanvasViewTransform(1, 0, 0, canvasHeightPoints);
+        }
+
+        var scale = Math.Min(viewWidthPixels / canvasWidthPoints, viewHeightPixels / canvasHeightPoints);
+        var offsetX = (viewWidthPixels - (canvasWidthPoints * scale)) / 2.0;
+        var offsetY = (viewHeightPixels - (canvasHeightPoints * scale)) / 2.0;
+        return new CanvasViewTransform(scale, offsetX, offsetY, canvasHeightPoints);
+    }
+}

code/src/EnvelopeRenderer.Desktop.Core/Design/RgbColor.cs

@@ -0,0 +1,39 @@
+namespace EnvelopeRenderer.Desktop.Core.Design;
+
+/// <summary>
+/// A plain RGB triple, used instead of <c>System.Drawing.Color</c> so this project keeps zero
+/// UI-framework dependency (see the project's .csproj remarks — it targets plain net10.0
+/// specifically so it can be unit tested without a WinForms host). The WinForms layer converts
+/// to/from <c>System.Drawing.Color</c> at the edge.
+/// </summary>
+public readonly record struct RgbColor(byte R, byte G, byte B)
+{
+    public static readonly RgbColor Black = new(0, 0, 0);
+
+    /// <summary>The <c>#RRGGBB</c> hex form used when persisting to the template XML.</summary>
+    public string ToHex() => $"#{R:X2}{G:X2}{B:X2}";
+
+    /// <summary>Parses a <c>#RRGGBB</c> (or <c>RRGGBB</c>) hex string. Returns <c>false</c> with
+    /// no exception on malformed input, matching this codebase's "clear operator-facing error,
+    /// no unhandled exception" pattern for template parsing (see `TemplateXmlParser`).</summary>
+    public static bool TryParseHex(string? hex, out RgbColor color)
+    {
+        color = Black;
+        if (string.IsNullOrWhiteSpace(hex))
+        {
+            return false;
+        }
+
+        var span = hex.StartsWith('#') ? hex.AsSpan(1) : hex.AsSpan();
+        if (span.Length != 6
+            || !byte.TryParse(span[..2], System.Globalization.NumberStyles.HexNumber, null, out var r)
+            || !byte.TryParse(span[2..4], System.Globalization.NumberStyles.HexNumber, null, out var g)
+            || !byte.TryParse(span[4..6], System.Globalization.NumberStyles.HexNumber, null, out var b))
+        {
+            return false;
+        }
+
+        color = new RgbColor(r, g, b);
+        return true;
+    }
+}

code/src/EnvelopeRenderer.Desktop.Core/Design/TemplateLayoutDocument.cs

@@ -0,0 +1,28 @@
+namespace EnvelopeRenderer.Desktop.Core.Design;
+
+/// <summary>
+/// The designer's in-memory template state: canvas settings plus the placed text elements. A
+/// class rather than a record because the canvas and element list are mutated in place as the
+/// operator edits the design, and every designer batch (place/move elements, properties panel,
+/// save/reopen) all read and write this same instance.
+/// </summary>
+public sealed class TemplateLayoutDocument
+{
+    public CanvasSettings Canvas { get; set; }
+
+    /// <summary>Elements in no particular list order — <see cref="TextElementLayout.ZOrder"/> is
+    /// the authoritative stacking order (0 = bottom-most), not list position.</summary>
+    public List<TextElementLayout> Elements { get; } = new();
+
+    public TemplateLayoutDocument(CanvasSettings canvas)
+    {
+        Canvas = canvas;
+    }
+
+    /// <summary>A brand-new, unsaved template with the default #10 envelope canvas and no elements.</summary>
+    public static TemplateLayoutDocument CreateDefault() => new(CanvasSettings.CreateDefault());
+
+    /// <summary>The next free z-order value (one past the current highest), so newly added
+    /// elements land on top by default without colliding with an existing z-order.</summary>
+    public int NextZOrder() => Elements.Count == 0 ? 0 : Elements.Max(e => e.ZOrder) + 1;
+}

code/src/EnvelopeRenderer.Desktop.Core/Design/TemplateLayoutXmlSerializer.cs

@@ -0,0 +1,211 @@
+using System.Globalization;
+using System.Xml;
+using System.Xml.Linq;
+
+namespace EnvelopeRenderer.Desktop.Core.Design;
+
+/// <summary>
+/// Saves and reopens the designer's in-memory <see cref="TemplateLayoutDocument"/> as XML
+/// (Sprint 2 Batch 5: "Save and reopen text-only XML templates"). The root element and the
+/// core `&lt;text&gt;` attributes (`x`, `y`, `font`, `size`, inline text vs. `column`) are
+/// intentionally identical to the render-time format the CLI's `TemplateXmlParser` consumes
+/// (`TEMPLATE_FORMAT.md`) — a template saved here is a real, renderable template, not a separate
+/// "designer-only" file format. Two extra attributes the render CLI does not read (and simply
+/// ignores, since it only looks up the attributes it needs) round-trip the designer-only
+/// properties this sprint's GUI stories added: `canvasUnit` (the operator's last-used display
+/// unit) and, per `&lt;text&gt;`, `color` and `zOrder`.
+///
+/// Deliberately reimplements its own small XML parsing here rather than referencing
+/// `EnvelopeRenderer.Cli`'s `TemplateXmlParser` — the desktop project intentionally never
+/// references the CLI's internals (see `EnvelopeRenderer.Desktop.csproj`'s remarks); the CLI's
+/// executable/`CLI_CONTRACT.md` is the only contract between the two.
+/// </summary>
+public static class TemplateLayoutXmlSerializer
+{
+    public static void Save(TemplateLayoutDocument document, string path)
+    {
+        var root = new XElement(
+            "envelopeTemplate",
+            new XAttribute("pageWidth", document.Canvas.WidthPoints.ToString(CultureInfo.InvariantCulture)),
+            new XAttribute("pageHeight", document.Canvas.HeightPoints.ToString(CultureInfo.InvariantCulture)),
+            new XAttribute("canvasUnit", document.Canvas.DisplayUnit.ToString()));
+
+        foreach (var element in document.Elements.OrderBy(e => e.ZOrder))
+        {
+            var textElement = new XElement(
+                "text",
+                new XAttribute("x", element.X.ToString(CultureInfo.InvariantCulture)),
+                new XAttribute("y", element.Y.ToString(CultureInfo.InvariantCulture)),
+                new XAttribute("font", element.FontFamily),
+                new XAttribute("size", element.FontSize.ToString(CultureInfo.InvariantCulture)),
+                new XAttribute("color", element.Color.ToHex()),
+                new XAttribute("zOrder", element.ZOrder.ToString(CultureInfo.InvariantCulture)));
+
+            if (element.IsDynamic)
+            {
+                textElement.Add(new XAttribute("column", element.ColumnName!));
+            }
+            else
+            {
+                textElement.SetValue(element.StaticText ?? string.Empty);
+            }
+
+            root.Add(textElement);
+        }
+
+        // Overwrite semantics (a fresh XDocument written to `path`) rather than any kind of
+        // merge — matches the story's "save the current layout" scope; there is no concept of a
+        // partial/incremental template save.
+        new XDocument(root).Save(path);
+    }
+
+    /// <summary>Attempts to load a template. Returns <c>false</c> with one or more
+    /// operator-facing <paramref name="errors"/> (never an unhandled exception) for invalid XML,
+    /// an unrecognized root element, or malformed/missing required attributes — mirroring
+    /// `TemplateXmlParser`'s error style so the designer's errors read the same as the CLI's.</summary>
+    public static bool TryLoad(string path, out TemplateLayoutDocument? document, out IReadOnlyList<string> errors)
+    {
+        document = null;
+
+        XDocument xdoc;
+        try
+        {
+            xdoc = XDocument.Load(path);
+        }
+        catch (Exception ex) when (ex is XmlException or IOException or UnauthorizedAccessException)
+        {
+            errors = new[] { $"Template is not valid XML: {ex.Message}" };
+            return false;
+        }
+
+        var root = xdoc.Root;
+        if (root is null || root.Name.LocalName != "envelopeTemplate")
+        {
+            errors = new[] { "Template root element must be <envelopeTemplate>." };
+            return false;
+        }
+
+        var errorList = new List<string>();
+
+        var width = ParseRequiredDouble(root, "pageWidth", "<envelopeTemplate>", errorList, mustBePositive: true);
+        var height = ParseRequiredDouble(root, "pageHeight", "<envelopeTemplate>", errorList, mustBePositive: true);
+
+        var unit = CanvasUnit.Points;
+        var unitRaw = (string?)root.Attribute("canvasUnit");
+        if (!string.IsNullOrWhiteSpace(unitRaw) && !Enum.TryParse(unitRaw, ignoreCase: true, out unit))
+        {
+            errorList.Add($"<envelopeTemplate> has an unrecognized 'canvasUnit' value: '{unitRaw}'.");
+        }
+
+        var elements = new List<TextElementLayout>();
+        var textNodes = root.Elements().Where(e => e.Name.LocalName == "text").ToList();
+
+        var autoZOrder = 0;
+        var index = 0;
+        foreach (var node in textNodes)
+        {
+            index++;
+            var label = $"<text> #{index}";
+
+            var x = ParseRequiredDouble(node, "x", label, errorList);
+            var y = ParseRequiredDouble(node, "y", label, errorList);
+            var size = ParseRequiredDouble(node, "size", label, errorList, mustBePositive: true);
+            var font = (string?)node.Attribute("font");
+            if (string.IsNullOrWhiteSpace(font))
+            {
+                errorList.Add($"{label} is missing a required 'font' attribute.");
+            }
+
+            var column = (string?)node.Attribute("column");
+            var staticText = node.Nodes().OfType<XText>().Select(t => t.Value).FirstOrDefault();
+            var hasColumn = !string.IsNullOrWhiteSpace(column);
+            var hasStaticText = !string.IsNullOrWhiteSpace(staticText);
+
+            if (hasColumn && hasStaticText)
+            {
+                errorList.Add($"{label} has both a 'column' attribute and inline text — use exactly one.");
+            }
+            else if (!hasColumn && !hasStaticText)
+            {
+                errorList.Add($"{label} has neither a 'column' attribute nor inline text — use exactly one.");
+            }
+
+            var color = RgbColor.Black;
+            var colorRaw = (string?)node.Attribute("color");
+            if (!string.IsNullOrWhiteSpace(colorRaw) && !RgbColor.TryParseHex(colorRaw, out color))
+            {
+                errorList.Add($"{label} has an invalid 'color' value: '{colorRaw}' (expected #RRGGBB).");
+            }
+
+            // Missing zOrder (older, designer-agnostic template files, e.g. Sprint 1's
+            // sample-envelope-template.xml) is not an error — elements are assigned a stable
+            // z-order in document order instead. A present-but-invalid value is a real error;
+            // a present negative value is clamped rather than rejected, matching the live
+            // properties panel's leniency (`ZOrderRule.Clamp`) so load-time and edit-time
+            // behavior agree.
+            var zOrder = autoZOrder;
+            var zOrderRaw = (string?)node.Attribute("zOrder");
+            if (!string.IsNullOrWhiteSpace(zOrderRaw))
+            {
+                if (int.TryParse(zOrderRaw, NumberStyles.Integer, CultureInfo.InvariantCulture, out var parsedZOrder))
+                {
+                    zOrder = ZOrderRule.Clamp(parsedZOrder);
+                }
+                else
+                {
+                    errorList.Add($"{label} has a non-integer 'zOrder' value: '{zOrderRaw}'.");
+                }
+            }
+
+            autoZOrder++;
+
+            if (x is null || y is null || size is null || string.IsNullOrWhiteSpace(font) || (hasColumn == hasStaticText))
+            {
+                continue;
+            }
+
+            elements.Add(hasStaticText
+                ? TextElementLayout.CreateStatic(x.Value, y.Value, staticText!, font, size.Value, zOrder)
+                : TextElementLayout.CreateDynamic(x.Value, y.Value, column!, font, size.Value, zOrder));
+
+            elements[^1].Color = color;
+        }
+
+        if (errorList.Count > 0)
+        {
+            errors = errorList;
+            return false;
+        }
+
+        var canvas = new CanvasSettings(width!.Value, height!.Value, unit);
+        document = new TemplateLayoutDocument(canvas);
+        document.Elements.AddRange(elements);
+        errors = Array.Empty<string>();
+        return true;
+    }
+
+    private static double? ParseRequiredDouble(
+        XElement node, string attributeName, string label, List<string> errors, bool mustBePositive = false)
+    {
+        var raw = (string?)node.Attribute(attributeName);
+        if (string.IsNullOrWhiteSpace(raw))
+        {
+            errors.Add($"{label} is missing a required '{attributeName}' attribute.");
+            return null;
+        }
+
+        if (!double.TryParse(raw, NumberStyles.Float, CultureInfo.InvariantCulture, out var value))
+        {
+            errors.Add($"{label} has a non-numeric '{attributeName}' value: '{raw}'.");
+            return null;
+        }
+
+        if (mustBePositive && value <= 0)
+        {
+            errors.Add($"{label} has a non-positive '{attributeName}' value: '{raw}'.");
+            return null;
+        }
+
+        return value;
+    }
+}

code/src/EnvelopeRenderer.Desktop.Core/Design/TextElementLayout.cs

@@ -0,0 +1,62 @@
+namespace EnvelopeRenderer.Desktop.Core.Design;
+
+/// <summary>
+/// One text element placed on the designer canvas — the in-memory, editable counterpart of a
+/// render-time `&lt;text&gt;` element (`TEMPLATE_FORMAT.md`). A class, not a record: position,
+/// font, and z-order are all mutated in place as the operator drags, edits properties, and
+/// reorders elements (Sprint 2 Batches 3-4).
+///
+/// Exactly one of <see cref="StaticText"/> / <see cref="ColumnName"/> is set, mirroring the
+/// render-time template format's rule (enforced here by the two factory methods rather than by a
+/// constructor invariant, since the properties panel — Batch 4 — needs to freely edit either
+/// without re-validating the other on every keystroke).
+/// </summary>
+public sealed class TextElementLayout
+{
+    public Guid Id { get; } = Guid.NewGuid();
+
+    /// <summary>X position in PDF points, measured from the page's bottom-left corner — same
+    /// convention as the render-time template format, so no conversion is needed when saving.</summary>
+    public double X { get; set; }
+
+    /// <summary>Y position in PDF points, measured from the page's bottom-left corner (the
+    /// baseline of the text, matching Debenu's <c>DrawText(x, y, text)</c> semantics).</summary>
+    public double Y { get; set; }
+
+    public string FontFamily { get; set; }
+    public double FontSize { get; set; }
+
+    /// <summary>The visible RGB color the properties panel exposes. A plain RGB triple rather
+    /// than <c>System.Drawing.Color</c> so this project keeps zero UI-framework dependency (see
+    /// this project's .csproj remarks). Stored in the layout model and round-tripped through
+    /// save/reopen (Batch 5), but the current render engine (`DebenuPdfRenderer`) always fills
+    /// text black regardless of this value — applying it to actual rendered output is out of
+    /// scope for this sprint's stories and is tracked as a known gap, not silently implemented.</summary>
+    public RgbColor Color { get; set; } = RgbColor.Black;
+
+    /// <summary>Stacking order; 0 is bottom-most, matching the product's numeric z-order rule.</summary>
+    public int ZOrder { get; set; }
+
+    public string? StaticText { get; set; }
+    public string? ColumnName { get; set; }
+
+    public bool IsDynamic => ColumnName is not null;
+
+    private TextElementLayout(string fontFamily, double fontSize)
+    {
+        FontFamily = fontFamily;
+        FontSize = fontSize;
+    }
+
+    public static TextElementLayout CreateStatic(
+        double x, double y, string text, string fontFamily = "Arial", double fontSize = 12, int zOrder = 0) =>
+        new(fontFamily, fontSize) { X = x, Y = y, StaticText = text, ZOrder = zOrder };
+
+    public static TextElementLayout CreateDynamic(
+        double x, double y, string columnName, string fontFamily = "Arial", double fontSize = 12, int zOrder = 0) =>
+        new(fontFamily, fontSize) { X = x, Y = y, ColumnName = columnName, ZOrder = zOrder };
+
+    /// <summary>What the canvas/renderer should display: the literal static text, or a
+    /// human-readable placeholder for a dynamic column binding (e.g. <c>{Full Name}</c>).</summary>
+    public string DisplayText => IsDynamic ? $"{{{ColumnName}}}" : StaticText ?? string.Empty;
+}

code/src/EnvelopeRenderer.Desktop.Core/Design/TextElementPropertiesEditor.cs

@@ -0,0 +1,73 @@
+namespace EnvelopeRenderer.Desktop.Core.Design;
+
+/// <summary>
+/// UI-independent glue for the properties panel (Sprint 2 Batch 4: "Edit selected text
+/// properties in a properties panel"). The WinForms panel only wires control events to these
+/// methods and reads <see cref="Selected"/> back to refresh its display after a selection change
+/// — all the actual "which edits are valid, and what do they mean for the model" logic lives
+/// here so it is unit-testable without a WinForms host, mirroring
+/// <see cref="CanvasDimensionsEditor"/>'s role for Batch 2.
+/// </summary>
+public sealed class TextElementPropertiesEditor
+{
+    public TextElementLayout? Selected { get; private set; }
+
+    /// <summary>Called whenever the canvas selection changes (including to <c>null</c>, when
+    /// nothing is selected).</summary>
+    public void Select(TextElementLayout? element) => Selected = element;
+
+    public void SetX(double x)
+    {
+        if (Selected is not null)
+        {
+            Selected.X = x;
+        }
+    }
+
+    public void SetY(double y)
+    {
+        if (Selected is not null)
+        {
+            Selected.Y = y;
+        }
+    }
+
+    /// <summary>Ignores blank input rather than storing an empty font family — an element must
+    /// always have a resolvable font name for render-time font resolution
+    /// (`TEMPLATE_FORMAT.md`'s "Known gaps": missing-font is blocking).</summary>
+    public void SetFontFamily(string? fontFamily)
+    {
+        if (Selected is not null && !string.IsNullOrWhiteSpace(fontFamily))
+        {
+            Selected.FontFamily = fontFamily;
+        }
+    }
+
+    /// <summary>Ignores non-positive sizes — matches `TemplateXmlParser`'s render-time rule that
+    /// <c>size</c> must be positive.</summary>
+    public void SetFontSize(double fontSize)
+    {
+        if (Selected is not null && fontSize > 0)
+        {
+            Selected.FontSize = fontSize;
+        }
+    }
+
+    public void SetColor(RgbColor color)
+    {
+        if (Selected is not null)
+        {
+            Selected.Color = color;
+        }
+    }
+
+    /// <summary>Applies the product's numeric z-order rule (0 = bottom-most, never negative) via
+    /// <see cref="ZOrderRule"/> regardless of what the operator typed.</summary>
+    public void SetZOrder(int zOrder)
+    {
+        if (Selected is not null)
+        {
+            Selected.ZOrder = ZOrderRule.Clamp(zOrder);
+        }
+    }
+}

code/src/EnvelopeRenderer.Desktop.Core/Design/ZOrderRule.cs

@@ -0,0 +1,15 @@
+namespace EnvelopeRenderer.Desktop.Core.Design;
+
+/// <summary>
+/// The product's numeric z-order rule: 0 is bottom-most, and z-order is never negative. Used by
+/// the properties panel (Sprint 2 Batch 4) whenever an operator edits an element's z-order
+/// directly, so an invalid (negative) value can never be stored regardless of which UI control
+/// path it came from.
+/// </summary>
+public static class ZOrderRule
+{
+    public const int BottomMost = 0;
+
+    /// <summary>Clamps a candidate z-order to the valid range (never negative).</summary>
+    public static int Clamp(int value) => Math.Max(BottomMost, value);
+}

code/src/EnvelopeRenderer.Desktop.Tests/CanvasDimensionsEditorTests.cs

@@ -0,0 +1,65 @@
+using EnvelopeRenderer.Desktop.Core.Design;
+
+namespace EnvelopeRenderer.Desktop.Tests;
+
+public class CanvasDimensionsEditorTests
+{
+    [Fact]
+    public void SetWidth_InCurrentDisplayUnit_UpdatesCanonicalPoints()
+    {
+        var editor = new CanvasDimensionsEditor(CanvasSettings.FromUnitValues(1, 1, CanvasUnit.Inches));
+
+        editor.SetWidth(4.125);
+
+        Assert.Equal(297.0, editor.Canvas.WidthPoints, precision: 9);
+    }
+
+    [Fact]
+    public void SetHeight_InCurrentDisplayUnit_UpdatesCanonicalPoints()
+    {
+        var editor = new CanvasDimensionsEditor(CanvasSettings.FromUnitValues(1, 1, CanvasUnit.Inches));
+
+        editor.SetHeight(9.5);
+
+        Assert.Equal(684.0, editor.Canvas.HeightPoints, precision: 9);
+    }
+
+    [Fact]
+    public void SetDisplayUnit_PreservesCanonicalPoints_ChangesDisplayedValues()
+    {
+        var editor = new CanvasDimensionsEditor(CanvasSettings.FromUnitValues(4.125, 9.5, CanvasUnit.Inches));
+        var pointsBefore = (editor.Canvas.WidthPoints, editor.Canvas.HeightPoints);
+
+        editor.SetDisplayUnit(CanvasUnit.Millimeters);
+
+        Assert.Equal(pointsBefore, (editor.Canvas.WidthPoints, editor.Canvas.HeightPoints));
+        Assert.Equal(CanvasUnit.Millimeters, editor.Canvas.DisplayUnit);
+        // 4.125in = 104.775mm
+        Assert.Equal(104.775, editor.Canvas.WidthInDisplayUnit, precision: 3);
+    }
+
+    [Fact]
+    public void EnterDimensionsInEachUnit_ThenSwitchUnit_RoundTripsCorrectly()
+    {
+        // Operator starts in inches, enters exact #10 envelope dimensions.
+        var editor = new CanvasDimensionsEditor(CanvasSettings.FromUnitValues(0, 0, CanvasUnit.Inches));
+        editor.SetWidth(4.125);
+        editor.SetHeight(9.5);
+
+        // Switches to millimeters — displayed values should reflect the same physical size.
+        editor.SetDisplayUnit(CanvasUnit.Millimeters);
+        var widthMm = editor.Canvas.WidthInDisplayUnit;
+        var heightMm = editor.Canvas.HeightInDisplayUnit;
+
+        // Switches to points — should recover the exact original canonical size.
+        editor.SetDisplayUnit(CanvasUnit.Points);
+        Assert.Equal(297.0, editor.Canvas.WidthInDisplayUnit, precision: 6);
+        Assert.Equal(684.0, editor.Canvas.HeightInDisplayUnit, precision: 6);
+
+        // And switching back to millimeters again reproduces the same displayed value as before —
+        // no drift from repeated unit switches.
+        editor.SetDisplayUnit(CanvasUnit.Millimeters);
+        Assert.Equal(widthMm, editor.Canvas.WidthInDisplayUnit, precision: 9);
+        Assert.Equal(heightMm, editor.Canvas.HeightInDisplayUnit, precision: 9);
+    }
+}

code/src/EnvelopeRenderer.Desktop.Tests/CanvasElementEditorTests.cs

@@ -0,0 +1,176 @@
+using EnvelopeRenderer.Desktop.Core.Design;
+
+namespace EnvelopeRenderer.Desktop.Tests;
+
+public class CanvasElementEditorTests
+{
+    // Fixed 20x10-point bounding box for every element, regardless of content — keeps hit-test
+    // math deterministic without depending on real GDI text measurement.
+    private static (double Width, double Height) FixedSize(TextElementLayout _) => (20.0, 10.0);
+
+    private static CanvasElementEditor CreateEditor(out TemplateLayoutDocument document)
+    {
+        document = TemplateLayoutDocument.CreateDefault();
+        return new CanvasElementEditor(document, FixedSize);
+    }
+
+    [Fact]
+    public void AddStaticText_AddsToDocumentAndSelectsIt()
+    {
+        var editor = CreateEditor(out var document);
+
+        var element = editor.AddStaticText(10, 20, "Hello");
+
+        Assert.Single(document.Elements);
+        Assert.Same(element, document.Elements[0]);
+        Assert.Same(element, editor.Selected);
+        Assert.Equal("Hello", element.StaticText);
+        Assert.False(element.IsDynamic);
+    }
+
+    [Fact]
+    public void AddDynamicPlaceholder_AddsToDocumentAndSelectsIt()
+    {
+        var editor = CreateEditor(out var document);
+
+        var element = editor.AddDynamicPlaceholder(10, 20, "Full Name");
+
+        Assert.Single(document.Elements);
+        Assert.True(element.IsDynamic);
+        Assert.Equal("Full Name", element.ColumnName);
+        Assert.Same(element, editor.Selected);
+    }
+
+    [Fact]
+    public void AddMultipleElements_AssignsIncreasingZOrder()
+    {
+        var editor = CreateEditor(out _);
+
+        var first = editor.AddStaticText(0, 0, "A");
+        var second = editor.AddDynamicPlaceholder(0, 0, "B");
+        var third = editor.AddStaticText(0, 0, "C");
+
+        Assert.Equal(0, first.ZOrder);
+        Assert.Equal(1, second.ZOrder);
+        Assert.Equal(2, third.ZOrder);
+    }
+
+    [Fact]
+    public void HitTest_PointInsideElementBounds_ReturnsElement()
+    {
+        var editor = CreateEditor(out _);
+        var element = editor.AddStaticText(100, 100, "Hello");
+
+        var hit = editor.HitTest(105, 105); // inside [100,120] x [100,110]
+
+        Assert.Same(element, hit);
+    }
+
+    [Fact]
+    public void HitTest_PointOutsideElementBounds_ReturnsNull()
+    {
+        var editor = CreateEditor(out _);
+        editor.AddStaticText(100, 100, "Hello");
+
+        var hit = editor.HitTest(0, 0);
+
+        Assert.Null(hit);
+    }
+
+    [Fact]
+    public void HitTest_OverlappingElements_ReturnsTopmostZOrder()
+    {
+        var editor = CreateEditor(out _);
+        var bottom = editor.AddStaticText(100, 100, "Bottom");
+        var top = editor.AddStaticText(100, 100, "Top"); // same bounds, added later -> higher z-order
+
+        var hit = editor.HitTest(105, 105);
+
+        Assert.Same(top, hit);
+        Assert.NotSame(bottom, hit);
+    }
+
+    [Fact]
+    public void TrySelectAt_Hit_SelectsAndReturnsTrue()
+    {
+        var editor = CreateEditor(out _);
+        var element = editor.AddStaticText(100, 100, "Hello");
+        editor.Select(null);
+
+        var result = editor.TrySelectAt(105, 105);
+
+        Assert.True(result);
+        Assert.Same(element, editor.Selected);
+    }
+
+    [Fact]
+    public void TrySelectAt_Miss_ClearsSelectionAndReturnsFalse()
+    {
+        var editor = CreateEditor(out _);
+        editor.AddStaticText(100, 100, "Hello");
+
+        var result = editor.TrySelectAt(0, 0);
+
+        Assert.False(result);
+        Assert.Null(editor.Selected);
+    }
+
+    [Fact]
+    public void DragTo_MovesSelectedElementPreservingGrabOffset()
+    {
+        var editor = CreateEditor(out _);
+        var element = editor.AddStaticText(100, 100, "Hello");
+        editor.TrySelectAt(105, 105); // grab 5pt into the element from its origin
+
+        editor.BeginDrag(105, 105);
+        editor.DragTo(205, 155); // moved 100 right, 50 up
+
+        Assert.Equal(200.0, element.X, precision: 6);
+        Assert.Equal(150.0, element.Y, precision: 6);
+        Assert.True(editor.IsDragging);
+    }
+
+    [Fact]
+    public void EndDrag_StopsFurtherMovementFromDragTo()
+    {
+        var editor = CreateEditor(out _);
+        var element = editor.AddStaticText(100, 100, "Hello");
+        editor.TrySelectAt(105, 105);
+        editor.BeginDrag(105, 105);
+        editor.EndDrag();
+
+        editor.DragTo(500, 500);
+
+        Assert.Equal(100.0, element.X, precision: 6);
+        Assert.Equal(100.0, element.Y, precision: 6);
+        Assert.False(editor.IsDragging);
+    }
+
+    [Fact]
+    public void DragTo_WithoutSelection_IsNoOp()
+    {
+        var editor = CreateEditor(out _);
+
+        editor.DragTo(50, 50); // nothing selected, nothing dragging — should not throw
+
+        Assert.Null(editor.Selected);
+    }
+
+    [Fact]
+    public void Move_UpdatesTemplateLayoutDocumentInPlace_SoCanvasAndStoredStateAgree()
+    {
+        var editor = CreateEditor(out var document);
+        var element = editor.AddStaticText(0, 0, "Hello");
+
+        editor.TrySelectAt(10, 5);
+        editor.BeginDrag(10, 5);
+        editor.DragTo(60, 45);
+
+        // The document's element list holds the same instance that was moved — no separate
+        // "committed" copy step, so the canvas (reading from `document.Elements`) and this
+        // editor's own state can never disagree.
+        Assert.Same(element, document.Elements[0]);
+        Assert.Equal(50.0, document.Elements[0].X, precision: 6);
+        Assert.Equal(40.0, document.Elements[0].Y, precision: 6);
+    }
+}

code/src/EnvelopeRenderer.Desktop.Tests/CanvasSettingsTests.cs

@@ -0,0 +1,61 @@
+using EnvelopeRenderer.Desktop.Core.Design;
+
+namespace EnvelopeRenderer.Desktop.Tests;
+
+public class CanvasSettingsTests
+{
+    [Fact]
+    public void FromUnitValues_StoresCanonicalPoints()
+    {
+        var settings = CanvasSettings.FromUnitValues(4.125, 9.5, CanvasUnit.Inches);
+
+        Assert.Equal(297.0, settings.WidthPoints, precision: 9);
+        Assert.Equal(684.0, settings.HeightPoints, precision: 9);
+        Assert.Equal(CanvasUnit.Inches, settings.DisplayUnit);
+    }
+
+    [Fact]
+    public void CreateDefault_IsAStandardNumber10Envelope()
+    {
+        var settings = CanvasSettings.CreateDefault();
+
+        Assert.Equal(297.0, settings.WidthPoints, precision: 9);
+        Assert.Equal(684.0, settings.HeightPoints, precision: 9);
+    }
+
+    [Fact]
+    public void WithDisplayUnit_ChangesUnitButNotCanonicalPoints()
+    {
+        var settings = CanvasSettings.FromUnitValues(210, 297, CanvasUnit.Millimeters);
+
+        var switched = settings.WithDisplayUnit(CanvasUnit.Points);
+
+        Assert.Equal(settings.WidthPoints, switched.WidthPoints, precision: 9);
+        Assert.Equal(settings.HeightPoints, switched.HeightPoints, precision: 9);
+        Assert.Equal(CanvasUnit.Points, switched.DisplayUnit);
+    }
+
+    [Theory]
+    [InlineData(CanvasUnit.Inches)]
+    [InlineData(CanvasUnit.Millimeters)]
+    [InlineData(CanvasUnit.Points)]
+    public void RoundTrip_EnterInEachUnit_DisplayedAndStoredValuesAgree(CanvasUnit unit)
+    {
+        const double width = 5.5;
+        const double height = 12.25;
+
+        var settings = CanvasSettings.FromUnitValues(width, height, unit);
+
+        // "Displayed" value (what a UI control bound to WidthInDisplayUnit/HeightInDisplayUnit
+        // would show) must agree with what the operator actually typed in, regardless of unit.
+        Assert.Equal(width, settings.WidthInDisplayUnit, precision: 9);
+        Assert.Equal(height, settings.HeightInDisplayUnit, precision: 9);
+
+        // And the "stored" canonical points value must convert back exactly to the same
+        // displayed value — the round trip this story's acceptance criteria call for.
+        var recoveredWidth = CanvasUnitConverter.FromPoints(settings.WidthPoints, unit);
+        var recoveredHeight = CanvasUnitConverter.FromPoints(settings.HeightPoints, unit);
+        Assert.Equal(width, recoveredWidth, precision: 9);
+        Assert.Equal(height, recoveredHeight, precision: 9);
+    }
+}

code/src/EnvelopeRenderer.Desktop.Tests/CanvasUnitConverterTests.cs

@@ -0,0 +1,46 @@
+using EnvelopeRenderer.Desktop.Core.Design;
+
+namespace EnvelopeRenderer.Desktop.Tests;
+
+public class CanvasUnitConverterTests
+{
+    [Fact]
+    public void ToPoints_Inches_Uses72PointsPerInch()
+    {
+        Assert.Equal(297.0, CanvasUnitConverter.ToPoints(4.125, CanvasUnit.Inches), precision: 9);
+        Assert.Equal(684.0, CanvasUnitConverter.ToPoints(9.5, CanvasUnit.Inches), precision: 9);
+    }
+
+    [Fact]
+    public void ToPoints_Points_IsIdentity()
+    {
+        Assert.Equal(123.456, CanvasUnitConverter.ToPoints(123.456, CanvasUnit.Points), precision: 9);
+    }
+
+    [Fact]
+    public void ToPoints_Millimeters_MatchesKnownConversion()
+    {
+        // 210mm (A4 width) = 210 / 25.4 * 72 = 595.2755905511811... points.
+        Assert.Equal(595.2755905511811, CanvasUnitConverter.ToPoints(210, CanvasUnit.Millimeters), precision: 6);
+    }
+
+    [Theory]
+    [InlineData(CanvasUnit.Inches)]
+    [InlineData(CanvasUnit.Millimeters)]
+    [InlineData(CanvasUnit.Points)]
+    public void RoundTrip_ToPointsThenFromPoints_RecoversOriginalValue(CanvasUnit unit)
+    {
+        const double original = 17.75;
+
+        var points = CanvasUnitConverter.ToPoints(original, unit);
+        var recovered = CanvasUnitConverter.FromPoints(points, unit);
+
+        Assert.Equal(original, recovered, precision: 9);
+    }
+
+    [Fact]
+    public void ToPoints_UnknownUnit_Throws()
+    {
+        Assert.Throws<ArgumentOutOfRangeException>(() => CanvasUnitConverter.ToPoints(1, (CanvasUnit)999));
+    }
+}

code/src/EnvelopeRenderer.Desktop.Tests/CanvasViewTransformTests.cs

@@ -0,0 +1,74 @@
+using EnvelopeRenderer.Desktop.Core.Design;
+
+namespace EnvelopeRenderer.Desktop.Tests;
+
+public class CanvasViewTransformTests
+{
+    [Fact]
+    public void Fit_SquareCanvasInSquareView_ScalesOneToOneWithNoOffset()
+    {
+        var transform = CanvasViewTransform.Fit(100, 100, 100, 100);
+
+        Assert.Equal(1.0, transform.Scale, precision: 9);
+        Assert.Equal(0.0, transform.OffsetXPixels, precision: 9);
+        Assert.Equal(0.0, transform.OffsetYPixels, precision: 9);
+    }
+
+    [Fact]
+    public void Fit_NarrowerViewThanCanvasAspect_LetterboxesVertically()
+    {
+        // 100x100 canvas in a 200x400 view: width-constrained scale is 2.0, height-constrained
+        // is 4.0 — the smaller (2.0) wins, and the leftover vertical space is centered.
+        var transform = CanvasViewTransform.Fit(100, 100, 200, 400);
+
+        Assert.Equal(2.0, transform.Scale, precision: 9);
+        Assert.Equal(0.0, transform.OffsetXPixels, precision: 9);
+        Assert.Equal(100.0, transform.OffsetYPixels, precision: 9); // (400 - 200) / 2
+    }
+
+    [Fact]
+    public void ToPixels_OriginBottomLeft_MapsToBottomLeftOfPageRect()
+    {
+        var transform = CanvasViewTransform.Fit(200, 100, 200, 100);
+
+        // Canvas (0,0) is bottom-left in points space; in pixel space (top-left origin) that's
+        // the bottom-left corner of the page rect, i.e. y = canvas height in pixels.
+        var (x, y) = transform.ToPixels(0, 0);
+        Assert.Equal(0.0, x, precision: 9);
+        Assert.Equal(100.0, y, precision: 9);
+    }
+
+    [Fact]
+    public void ToPixels_TopLeftInPoints_MapsToPixelOrigin()
+    {
+        var transform = CanvasViewTransform.Fit(200, 100, 200, 100);
+
+        var (x, y) = transform.ToPixels(0, 100);
+        Assert.Equal(0.0, x, precision: 9);
+        Assert.Equal(0.0, y, precision: 9);
+    }
+
+    [Theory]
+    [InlineData(200, 100, 200, 100, 50, 25)]
+    [InlineData(297, 684, 600, 900, 10, 500)]
+    [InlineData(297, 684, 900, 600, 200, 50)]
+    public void RoundTrip_ToPixelsThenToPoints_RecoversOriginalPoint(
+        double canvasW, double canvasH, double viewW, double viewH, double x, double y)
+    {
+        var transform = CanvasViewTransform.Fit(canvasW, canvasH, viewW, viewH);
+
+        var (px, py) = transform.ToPixels(x, y);
+        var (rx, ry) = transform.ToPoints(px, py);
+
+        Assert.Equal(x, rx, precision: 6);
+        Assert.Equal(y, ry, precision: 6);
+    }
+
+    [Fact]
+    public void Fit_ZeroSizedInputs_DoesNotThrowOrDivideByZero()
+    {
+        var transform = CanvasViewTransform.Fit(0, 100, 200, 100);
+        Assert.False(double.IsNaN(transform.Scale));
+        Assert.False(double.IsInfinity(transform.Scale));
+    }
+}

code/src/EnvelopeRenderer.Desktop.Tests/RgbColorTests.cs

@@ -0,0 +1,51 @@
+using EnvelopeRenderer.Desktop.Core.Design;
+
+namespace EnvelopeRenderer.Desktop.Tests;
+
+public class RgbColorTests
+{
+    [Fact]
+    public void ToHex_FormatsAsUppercaseRrggbb()
+    {
+        var color = new RgbColor(255, 0, 128);
+
+        Assert.Equal("#FF0080", color.ToHex());
+    }
+
+    [Theory]
+    [InlineData("#FF0080")]
+    [InlineData("FF0080")]
+    [InlineData("#ff0080")]
+    public void TryParseHex_ValidInput_RoundTripsToSameColor(string hex)
+    {
+        var success = RgbColor.TryParseHex(hex, out var color);
+
+        Assert.True(success);
+        Assert.Equal(new RgbColor(255, 0, 128), color);
+    }
+
+    [Theory]
+    [InlineData(null)]
+    [InlineData("")]
+    [InlineData("notacolor")]
+    [InlineData("#FF00")]
+    [InlineData("#GGGGGG")]
+    public void TryParseHex_InvalidInput_ReturnsFalseWithoutThrowing(string? hex)
+    {
+        var success = RgbColor.TryParseHex(hex, out var color);
+
+        Assert.False(success);
+        Assert.Equal(RgbColor.Black, color);
+    }
+
+    [Fact]
+    public void ToHex_ThenTryParseHex_RoundTrips()
+    {
+        var original = new RgbColor(18, 52, 86);
+
+        var success = RgbColor.TryParseHex(original.ToHex(), out var recovered);
+
+        Assert.True(success);
+        Assert.Equal(original, recovered);
+    }
+}

code/src/EnvelopeRenderer.Desktop.Tests/TemplateLayoutDocumentTests.cs

@@ -0,0 +1,34 @@
+using EnvelopeRenderer.Desktop.Core.Design;
+
+namespace EnvelopeRenderer.Desktop.Tests;
+
+public class TemplateLayoutDocumentTests
+{
+    [Fact]
+    public void CreateDefault_HasNumber10EnvelopeCanvasAndNoElements()
+    {
+        var document = TemplateLayoutDocument.CreateDefault();
+
+        Assert.Equal(297.0, document.Canvas.WidthPoints, precision: 6);
+        Assert.Equal(684.0, document.Canvas.HeightPoints, precision: 6);
+        Assert.Empty(document.Elements);
+    }
+
+    [Fact]
+    public void NextZOrder_EmptyDocument_ReturnsZero()
+    {
+        var document = TemplateLayoutDocument.CreateDefault();
+
+        Assert.Equal(0, document.NextZOrder());
+    }
+
+    [Fact]
+    public void NextZOrder_ReturnsOneMoreThanCurrentMax()
+    {
+        var document = TemplateLayoutDocument.CreateDefault();
+        document.Elements.Add(TextElementLayout.CreateStatic(0, 0, "a", zOrder: 0));
+        document.Elements.Add(TextElementLayout.CreateStatic(0, 0, "b", zOrder: 5));
+
+        Assert.Equal(6, document.NextZOrder());
+    }
+}

code/src/EnvelopeRenderer.Desktop.Tests/TemplateLayoutXmlSerializerTests.cs

@@ -0,0 +1,198 @@
+using EnvelopeRenderer.Desktop.Core.Design;
+
+namespace EnvelopeRenderer.Desktop.Tests;
+
+public class TemplateLayoutXmlSerializerTests : IDisposable
+{
+    private readonly string _tempPath = Path.Combine(Path.GetTempPath(), $"envelope-designer-test-{Guid.NewGuid():N}.xml");
+
+    public void Dispose()
+    {
+        if (File.Exists(_tempPath))
+        {
+            File.Delete(_tempPath);
+        }
+    }
+
+    private static TemplateLayoutDocument BuildSampleDocument()
+    {
+        var document = new TemplateLayoutDocument(CanvasSettings.FromUnitValues(4.125, 9.5, CanvasUnit.Inches));
+        var staticElement = TextElementLayout.CreateStatic(120, 240, "Static label:", "Arial", 12, zOrder: 0);
+        staticElement.Color = new RgbColor(200, 10, 30);
+        var dynamicElement = TextElementLayout.CreateDynamic(120, 225, "Full Name", "Arial [Bold]", 14, zOrder: 1);
+        document.Elements.Add(staticElement);
+        document.Elements.Add(dynamicElement);
+        return document;
+    }
+
+    [Fact]
+    public void SaveThenLoad_RoundTripsCanvasSettingsExactly()
+    {
+        var original = BuildSampleDocument();
+
+        TemplateLayoutXmlSerializer.Save(original, _tempPath);
+        var loaded = TemplateLayoutXmlSerializer.TryLoad(_tempPath, out var document, out var errors);
+
+        Assert.True(loaded, string.Join("; ", errors));
+        Assert.Equal(original.Canvas.WidthPoints, document!.Canvas.WidthPoints, precision: 6);
+        Assert.Equal(original.Canvas.HeightPoints, document.Canvas.HeightPoints, precision: 6);
+        Assert.Equal(original.Canvas.DisplayUnit, document.Canvas.DisplayUnit);
+    }
+
+    [Fact]
+    public void SaveThenLoad_RoundTripsElementPositionsAndProperties()
+    {
+        var original = BuildSampleDocument();
+
+        TemplateLayoutXmlSerializer.Save(original, _tempPath);
+        TemplateLayoutXmlSerializer.TryLoad(_tempPath, out var document, out var errors);
+
+        Assert.NotNull(document);
+        Assert.Equal(2, document!.Elements.Count);
+
+        var loadedStatic = document.Elements.Single(e => !e.IsDynamic);
+        Assert.Equal(120, loadedStatic.X, precision: 6);
+        Assert.Equal(240, loadedStatic.Y, precision: 6);
+        Assert.Equal("Static label:", loadedStatic.StaticText);
+        Assert.Equal("Arial", loadedStatic.FontFamily);
+        Assert.Equal(12, loadedStatic.FontSize, precision: 6);
+        Assert.Equal(new RgbColor(200, 10, 30), loadedStatic.Color);
+        Assert.Equal(0, loadedStatic.ZOrder);
+
+        var loadedDynamic = document.Elements.Single(e => e.IsDynamic);
+        Assert.Equal("Full Name", loadedDynamic.ColumnName);
+        Assert.Equal("Arial [Bold]", loadedDynamic.FontFamily);
+        Assert.Equal(14, loadedDynamic.FontSize, precision: 6);
+        Assert.Equal(1, loadedDynamic.ZOrder);
+    }
+
+    [Fact]
+    public void Load_MissingFile_ReturnsFalseWithErrorNotException()
+    {
+        var result = TemplateLayoutXmlSerializer.TryLoad(
+            Path.Combine(Path.GetTempPath(), $"does-not-exist-{Guid.NewGuid():N}.xml"), out var document, out var errors);
+
+        Assert.False(result);
+        Assert.Null(document);
+        Assert.NotEmpty(errors);
+    }
+
+    [Fact]
+    public void Load_MalformedXml_ReturnsFalseWithClearError()
+    {
+        File.WriteAllText(_tempPath, "<envelopeTemplate pageWidth=\"297\" pageHeight=\"684\"><text></envelopeTemplate>");
+
+        var result = TemplateLayoutXmlSerializer.TryLoad(_tempPath, out var document, out var errors);
+
+        Assert.False(result);
+        Assert.Null(document);
+        Assert.Contains(errors, e => e.Contains("not valid XML", StringComparison.OrdinalIgnoreCase));
+    }
+
+    [Fact]
+    public void Load_WrongRootElement_ReturnsFalseWithClearError()
+    {
+        File.WriteAllText(_tempPath, "<notATemplate />");
+
+        var result = TemplateLayoutXmlSerializer.TryLoad(_tempPath, out var document, out var errors);
+
+        Assert.False(result);
+        Assert.Null(document);
+        Assert.Contains(errors, e => e.Contains("envelopeTemplate", StringComparison.Ordinal));
+    }
+
+    [Fact]
+    public void Load_MissingRequiredPageDimension_ReturnsFalseWithClearError()
+    {
+        File.WriteAllText(_tempPath, "<envelopeTemplate pageHeight=\"684\"><text x=\"1\" y=\"1\" font=\"Arial\" size=\"12\">Hi</text></envelopeTemplate>");
+
+        var result = TemplateLayoutXmlSerializer.TryLoad(_tempPath, out var document, out var errors);
+
+        Assert.False(result);
+        Assert.Contains(errors, e => e.Contains("pageWidth", StringComparison.Ordinal));
+    }
+
+    [Fact]
+    public void Load_TextElementWithBothColumnAndInlineText_ReturnsFalseWithClearError()
+    {
+        File.WriteAllText(
+            _tempPath,
+            "<envelopeTemplate pageWidth=\"297\" pageHeight=\"684\">" +
+            "<text x=\"1\" y=\"1\" font=\"Arial\" size=\"12\" column=\"Name\">Hi</text>" +
+            "</envelopeTemplate>");
+
+        var result = TemplateLayoutXmlSerializer.TryLoad(_tempPath, out var document, out var errors);
+
+        Assert.False(result);
+        Assert.Contains(errors, e => e.Contains("exactly one", StringComparison.OrdinalIgnoreCase));
+    }
+
+    [Fact]
+    public void Load_InvalidColorValue_ReturnsFalseWithClearError()
+    {
+        File.WriteAllText(
+            _tempPath,
+            "<envelopeTemplate pageWidth=\"297\" pageHeight=\"684\">" +
+            "<text x=\"1\" y=\"1\" font=\"Arial\" size=\"12\" color=\"notacolor\">Hi</text>" +
+            "</envelopeTemplate>");
+
+        var result = TemplateLayoutXmlSerializer.TryLoad(_tempPath, out var document, out var errors);
+
+        Assert.False(result);
+        Assert.Contains(errors, e => e.Contains("color", StringComparison.OrdinalIgnoreCase));
+    }
+
+    [Fact]
+    public void Load_TemplateWithoutDesignerAttributes_LoadsWithDefaults()
+    {
+        // Matches Sprint 1's plain render-time template shape (no canvasUnit/color/zOrder) —
+        // the designer must still be able to open it, per this story's back-compat intent.
+        File.WriteAllText(
+            _tempPath,
+            "<envelopeTemplate pageWidth=\"297\" pageHeight=\"684\">" +
+            "<text x=\"120\" y=\"240\" font=\"Arial\" size=\"12\">Static label:</text>" +
+            "<text x=\"120\" y=\"225\" font=\"Arial\" size=\"12\" column=\"Full Name\" />" +
+            "</envelopeTemplate>");
+
+        var result = TemplateLayoutXmlSerializer.TryLoad(_tempPath, out var document, out var errors);
+
+        Assert.True(result, string.Join("; ", errors));
+        Assert.Equal(CanvasUnit.Points, document!.Canvas.DisplayUnit);
+        Assert.Equal(2, document.Elements.Count);
+        Assert.All(document.Elements, e => Assert.Equal(RgbColor.Black, e.Color));
+        Assert.Equal(0, document.Elements[0].ZOrder);
+        Assert.Equal(1, document.Elements[1].ZOrder);
+    }
+
+    [Fact]
+    public void Load_NegativeZOrder_ClampsToZeroRatherThanErroring()
+    {
+        File.WriteAllText(
+            _tempPath,
+            "<envelopeTemplate pageWidth=\"297\" pageHeight=\"684\">" +
+            "<text x=\"1\" y=\"1\" font=\"Arial\" size=\"12\" zOrder=\"-5\">Hi</text>" +
+            "</envelopeTemplate>");
+
+        var result = TemplateLayoutXmlSerializer.TryLoad(_tempPath, out var document, out var errors);
+
+        Assert.True(result, string.Join("; ", errors));
+        Assert.Equal(0, document!.Elements[0].ZOrder);
+    }
+
+    [Fact]
+    public void Save_OverwritesExistingFile()
+    {
+        var first = new TemplateLayoutDocument(CanvasSettings.CreateDefault());
+        first.Elements.Add(TextElementLayout.CreateStatic(0, 0, "first"));
+        TemplateLayoutXmlSerializer.Save(first, _tempPath);
+
+        var second = new TemplateLayoutDocument(CanvasSettings.CreateDefault());
+        second.Elements.Add(TextElementLayout.CreateStatic(0, 0, "second"));
+        TemplateLayoutXmlSerializer.Save(second, _tempPath);
+
+        TemplateLayoutXmlSerializer.TryLoad(_tempPath, out var document, out _);
+
+        Assert.Single(document!.Elements);
+        Assert.Equal("second", document.Elements[0].StaticText);
+    }
+}

code/src/EnvelopeRenderer.Desktop.Tests/TextElementLayoutTests.cs

@@ -0,0 +1,46 @@
+using EnvelopeRenderer.Desktop.Core.Design;
+
+namespace EnvelopeRenderer.Desktop.Tests;
+
+public class TextElementLayoutTests
+{
+    [Fact]
+    public void CreateStatic_SetsStaticTextAndNotDynamic()
+    {
+        var element = TextElementLayout.CreateStatic(10, 20, "Hello", "Arial", 12, zOrder: 3);
+
+        Assert.Equal("Hello", element.StaticText);
+        Assert.Null(element.ColumnName);
+        Assert.False(element.IsDynamic);
+        Assert.Equal(3, element.ZOrder);
+        Assert.Equal("Hello", element.DisplayText);
+    }
+
+    [Fact]
+    public void CreateDynamic_SetsColumnNameAndIsDynamic()
+    {
+        var element = TextElementLayout.CreateDynamic(10, 20, "Full Name", "Arial", 12, zOrder: 1);
+
+        Assert.Equal("Full Name", element.ColumnName);
+        Assert.Null(element.StaticText);
+        Assert.True(element.IsDynamic);
+        Assert.Equal("{Full Name}", element.DisplayText);
+    }
+
+    [Fact]
+    public void DefaultColor_IsBlack()
+    {
+        var element = TextElementLayout.CreateStatic(0, 0, "x");
+
+        Assert.Equal(RgbColor.Black, element.Color);
+    }
+
+    [Fact]
+    public void EachElement_HasAUniqueId()
+    {
+        var a = TextElementLayout.CreateStatic(0, 0, "a");
+        var b = TextElementLayout.CreateStatic(0, 0, "a");
+
+        Assert.NotEqual(a.Id, b.Id);
+    }
+}

code/src/EnvelopeRenderer.Desktop.Tests/TextElementPropertiesEditorTests.cs

@@ -0,0 +1,151 @@
+using EnvelopeRenderer.Desktop.Core.Design;
+
+namespace EnvelopeRenderer.Desktop.Tests;
+
+public class TextElementPropertiesEditorTests
+{
+    [Fact]
+    public void SetX_UpdatesSelectedElement()
+    {
+        var editor = new TextElementPropertiesEditor();
+        var element = TextElementLayout.CreateStatic(0, 0, "a");
+        editor.Select(element);
+
+        editor.SetX(42.5);
+
+        Assert.Equal(42.5, element.X, precision: 6);
+    }
+
+    [Fact]
+    public void SetY_UpdatesSelectedElement()
+    {
+        var editor = new TextElementPropertiesEditor();
+        var element = TextElementLayout.CreateStatic(0, 0, "a");
+        editor.Select(element);
+
+        editor.SetY(99.25);
+
+        Assert.Equal(99.25, element.Y, precision: 6);
+    }
+
+    [Fact]
+    public void SetFontFamily_UpdatesSelectedElement()
+    {
+        var editor = new TextElementPropertiesEditor();
+        var element = TextElementLayout.CreateStatic(0, 0, "a", fontFamily: "Arial");
+        editor.Select(element);
+
+        editor.SetFontFamily("Times New Roman [Bold]");
+
+        Assert.Equal("Times New Roman [Bold]", element.FontFamily);
+    }
+
+    [Theory]
+    [InlineData(null)]
+    [InlineData("")]
+    [InlineData("   ")]
+    public void SetFontFamily_BlankInput_IsIgnored(string? blank)
+    {
+        var editor = new TextElementPropertiesEditor();
+        var element = TextElementLayout.CreateStatic(0, 0, "a", fontFamily: "Arial");
+        editor.Select(element);
+
+        editor.SetFontFamily(blank);
+
+        Assert.Equal("Arial", element.FontFamily);
+    }
+
+    [Fact]
+    public void SetFontSize_PositiveValue_UpdatesSelectedElement()
+    {
+        var editor = new TextElementPropertiesEditor();
+        var element = TextElementLayout.CreateStatic(0, 0, "a", fontSize: 12);
+        editor.Select(element);
+
+        editor.SetFontSize(24);
+
+        Assert.Equal(24, element.FontSize, precision: 6);
+    }
+
+    [Theory]
+    [InlineData(0)]
+    [InlineData(-5)]
+    public void SetFontSize_NonPositiveValue_IsIgnored(double invalid)
+    {
+        var editor = new TextElementPropertiesEditor();
+        var element = TextElementLayout.CreateStatic(0, 0, "a", fontSize: 12);
+        editor.Select(element);
+
+        editor.SetFontSize(invalid);
+
+        Assert.Equal(12, element.FontSize, precision: 6);
+    }
+
+    [Fact]
+    public void SetColor_UpdatesSelectedElement()
+    {
+        var editor = new TextElementPropertiesEditor();
+        var element = TextElementLayout.CreateStatic(0, 0, "a");
+        editor.Select(element);
+
+        editor.SetColor(new RgbColor(10, 20, 30));
+
+        Assert.Equal(new RgbColor(10, 20, 30), element.Color);
+    }
+
+    [Fact]
+    public void SetZOrder_NonNegativeValue_StoresAsGiven()
+    {
+        var editor = new TextElementPropertiesEditor();
+        var element = TextElementLayout.CreateStatic(0, 0, "a");
+        editor.Select(element);
+
+        editor.SetZOrder(7);
+
+        Assert.Equal(7, element.ZOrder);
+    }
+
+    [Fact]
+    public void SetZOrder_NegativeValue_ClampsToZeroBottomMost()
+    {
+        var editor = new TextElementPropertiesEditor();
+        var element = TextElementLayout.CreateStatic(0, 0, "a");
+        editor.Select(element);
+
+        editor.SetZOrder(-3);
+
+        Assert.Equal(0, element.ZOrder);
+    }
+
+    [Fact]
+    public void AllSetters_NoSelection_AreNoOpsAndDoNotThrow()
+    {
+        var editor = new TextElementPropertiesEditor();
+
+        editor.SetX(1);
+        editor.SetY(1);
+        editor.SetFontFamily("Arial");
+        editor.SetFontSize(10);
+        editor.SetColor(RgbColor.Black);
+        editor.SetZOrder(1);
+
+        Assert.Null(editor.Selected);
+    }
+
+    [Fact]
+    public void Select_ThenEdits_ThenSelectDifferentElement_EditsApplyToCorrectElement()
+    {
+        var editor = new TextElementPropertiesEditor();
+        var first = TextElementLayout.CreateStatic(0, 0, "first");
+        var second = TextElementLayout.CreateStatic(0, 0, "second");
+
+        editor.Select(first);
+        editor.SetX(10);
+
+        editor.Select(second);
+        editor.SetX(20);
+
+        Assert.Equal(10, first.X, precision: 6);
+        Assert.Equal(20, second.X, precision: 6);
+    }
+}

code/src/EnvelopeRenderer.Desktop.Tests/ZOrderRuleTests.cs

@@ -0,0 +1,22 @@
+using EnvelopeRenderer.Desktop.Core.Design;
+
+namespace EnvelopeRenderer.Desktop.Tests;
+
+public class ZOrderRuleTests
+{
+    [Theory]
+    [InlineData(0, 0)]
+    [InlineData(5, 5)]
+    [InlineData(-1, 0)]
+    [InlineData(-100, 0)]
+    public void Clamp_NeverReturnsBelowZero(int input, int expected)
+    {
+        Assert.Equal(expected, ZOrderRule.Clamp(input));
+    }
+
+    [Fact]
+    public void BottomMost_IsZero()
+    {
+        Assert.Equal(0, ZOrderRule.BottomMost);
+    }
+}

code/src/EnvelopeRenderer.Desktop/MainForm.cs

@@ -1,6 +1,7 @@
 using System.Drawing;
 using System.Windows.Forms;
 using EnvelopeRenderer.Desktop.Core.Launch;
+using EnvelopeRenderer.Desktop.Views;
 
 namespace EnvelopeRenderer.Desktop;
 
@@ -23,6 +24,7 @@ public sealed class MainForm : Form
     private readonly TextBox _csvPathTextBox = new();
     private readonly TextBox _outputPathTextBox = new();
     private readonly Button _renderButton = new() { Text = "&Render", AutoSize = true };
+    private readonly Button _designTemplateButton = new() { Text = "&Design Template...", AutoSize = true };
     private readonly Label _statusLabel = new()
     {
         AutoSize = false,
@@ -84,8 +86,10 @@ public sealed class MainForm : Form
             browse: () => BrowseForSaveFile(_outputPathTextBox, "PDF files (*.pdf)|*.pdf|All files (*.*)|*.*"));
 
         _renderButton.Click += OnRenderClick;
+        _designTemplateButton.Click += (_, _) => OnDesignTemplateClick();
         var buttonPanel = new FlowLayoutPanel { Dock = DockStyle.Fill, FlowDirection = FlowDirection.RightToLeft, AutoSize = true };
         buttonPanel.Controls.Add(_renderButton);
+        buttonPanel.Controls.Add(_designTemplateButton);
         layout.Controls.Add(buttonPanel, 1, 3);
         layout.SetColumnSpan(buttonPanel, 2);
 
@@ -195,6 +199,12 @@ public sealed class MainForm : Form
         }
     }
 
+    private void OnDesignTemplateClick()
+    {
+        using var designer = new TemplateDesignerForm();
+        designer.ShowDialog(this);
+    }
+
     private void OnRenderProgress(ProgressEvent progressEvent)
     {
         SetStatus(RenderProgressStatusFormatter.Format(progressEvent), isError: progressEvent.Kind == ProgressEventKind.Failure);

code/src/EnvelopeRenderer.Desktop/Views/TemplateCanvasControl.cs

@@ -0,0 +1,201 @@
+using System.Drawing.Drawing2D;
+using EnvelopeRenderer.Desktop.Core.Design;
+
+namespace EnvelopeRenderer.Desktop.Views;
+
+/// <summary>
+/// The visual canvas surface (Sprint 2 Batch 3: "Place and move text elements on the canvas"):
+/// draws the page and its text elements, and lets the operator select/drag-reposition them with
+/// the mouse. All coordinate math and add/select/drag state live in
+/// <see cref="CanvasElementEditor"/>/<see cref="CanvasViewTransform"/> (both framework-free and
+/// unit tested in EnvelopeRenderer.Desktop.Tests) — this class only does the GDI+ drawing and
+/// forwards mouse events, since that part genuinely cannot be extracted from WinForms.
+/// </summary>
+public sealed class TemplateCanvasControl : Control
+{
+    private readonly TemplateLayoutDocument _document;
+    private readonly CanvasElementEditor _editor;
+
+    public event EventHandler? SelectionChanged;
+    public event EventHandler? ElementsChanged;
+
+    public TemplateCanvasControl(TemplateLayoutDocument document)
+    {
+        _document = document;
+        _editor = new CanvasElementEditor(document, MeasureElement);
+
+        DoubleBuffered = true;
+        BackColor = SystemColors.ControlDark;
+        SetStyle(ControlStyles.ResizeRedraw, true);
+    }
+
+    public TextElementLayout? SelectedElement => _editor.Selected;
+
+    public TextElementLayout AddStaticTextElement()
+    {
+        var (x, y) = DefaultNewElementPosition();
+        var element = _editor.AddStaticText(x, y);
+        Invalidate();
+        SelectionChanged?.Invoke(this, EventArgs.Empty);
+        ElementsChanged?.Invoke(this, EventArgs.Empty);
+        return element;
+    }
+
+    public TextElementLayout AddDynamicPlaceholderElement(string columnName = "Column")
+    {
+        var (x, y) = DefaultNewElementPosition();
+        var element = _editor.AddDynamicPlaceholder(x, y, columnName);
+        Invalidate();
+        SelectionChanged?.Invoke(this, EventArgs.Empty);
+        ElementsChanged?.Invoke(this, EventArgs.Empty);
+        return element;
+    }
+
+    /// <summary>Re-selects the given element (e.g. after the properties panel changes it) and
+    /// redraws — used so external edits stay visually in sync with the canvas.</summary>
+    public void NotifyElementChanged()
+    {
+        Invalidate();
+        ElementsChanged?.Invoke(this, EventArgs.Empty);
+    }
+
+    /// <summary>Clears the current selection and redraws — used after reopening a saved template
+    /// (Batch 5), since a freshly loaded document's elements are new object instances and any
+    /// previously selected element instance no longer belongs to it.</summary>
+    public void ClearSelection()
+    {
+        _editor.Select(null);
+        Invalidate();
+        SelectionChanged?.Invoke(this, EventArgs.Empty);
+    }
+
+    private (double X, double Y) DefaultNewElementPosition()
+    {
+        // Cascade slightly so repeatedly clicking "Add" doesn't stack every new element exactly
+        // on top of the last one.
+        var count = _document.Elements.Count;
+        var x = Math.Min(_document.Canvas.WidthPoints * 0.1 + (count * 10), _document.Canvas.WidthPoints - 20);
+        var y = Math.Max(_document.Canvas.HeightPoints * 0.8 - (count * 10), 10);
+        return (x, y);
+    }
+
+    private CanvasViewTransform CurrentTransform() =>
+        CanvasViewTransform.Fit(_document.Canvas.WidthPoints, _document.Canvas.HeightPoints, ClientSize.Width, ClientSize.Height);
+
+    protected override void OnPaint(PaintEventArgs e)
+    {
+        base.OnPaint(e);
+        var g = e.Graphics;
+        g.SmoothingMode = SmoothingMode.AntiAlias;
+        g.TextRenderingHint = System.Drawing.Text.TextRenderingHint.AntiAlias;
+
+        var transform = CurrentTransform();
+        var (pageLeft, pageTop) = transform.ToPixels(0, _document.Canvas.HeightPoints);
+        var (pageRight, pageBottom) = transform.ToPixels(_document.Canvas.WidthPoints, 0);
+        var pageRect = RectangleF.FromLTRB((float)pageLeft, (float)pageTop, (float)pageRight, (float)pageBottom);
+
+        g.FillRectangle(Brushes.White, pageRect);
+        g.DrawRectangle(Pens.Black, pageRect.X, pageRect.Y, pageRect.Width, pageRect.Height);
+
+        foreach (var element in _document.Elements.OrderBy(el => el.ZOrder))
+        {
+            DrawElement(g, transform, element, isSelected: ReferenceEquals(element, _editor.Selected));
+        }
+    }
+
+    private void DrawElement(Graphics g, CanvasViewTransform transform, TextElementLayout element, bool isSelected)
+    {
+        using var font = ResolveFont(element.FontFamily, (float)element.FontSize);
+        var (width, height) = MeasureElement(element);
+
+        // Element (X, Y) is the bottom-left, baseline-ish origin in canvas space (points,
+        // bottom-left page origin); the drawn box spans up to (X + width, Y + height), so the
+        // pixel position to draw the string's top-left corner at is the transform of (X, Y + height).
+        var (drawX, drawY) = transform.ToPixels(element.X, element.Y + height);
+
+        using var brush = new SolidBrush(System.Drawing.Color.FromArgb(element.Color.R, element.Color.G, element.Color.B));
+        g.DrawString(element.DisplayText, font, brush, (float)drawX, (float)drawY);
+
+        if (isSelected)
+        {
+            var (selX, selY) = (drawX, drawY);
+            var selWidth = width * transform.Scale;
+            var selHeight = height * transform.Scale;
+            using var pen = new Pen(System.Drawing.Color.DodgerBlue, 1) { DashStyle = DashStyle.Dash };
+            g.DrawRectangle(pen, (float)selX - 2, (float)selY - 2, (float)selWidth + 4, (float)selHeight + 4);
+        }
+    }
+
+    /// <summary>Measures an element's rendered size in canvas-space points, using a
+    /// <see cref="GraphicsUnit.Point"/> measuring context so the result is directly comparable to
+    /// the point-based coordinates <see cref="TextElementLayout"/> stores — this is a design-time
+    /// visual approximation of the real Debenu-rendered size, not a guarantee of pixel-for-point
+    /// parity with the final PDF.</summary>
+    private static (double Width, double Height) MeasureElement(TextElementLayout element)
+    {
+        using var bitmap = new Bitmap(1, 1);
+        using var g = Graphics.FromImage(bitmap);
+        g.PageUnit = GraphicsUnit.Point;
+        using var font = ResolveFont(element.FontFamily, (float)element.FontSize);
+        var text = string.IsNullOrEmpty(element.DisplayText) ? " " : element.DisplayText;
+        var size = g.MeasureString(text, font);
+        return (size.Width, size.Height);
+    }
+
+    /// <summary>Falls back to a generic sans-serif font if the requested family isn't installed,
+    /// so a missing font only affects the design-time preview's appearance — it does not crash
+    /// the designer. This is independent of, and does not relax, the render-time rule that a
+    /// missing font is a blocking error (`TEMPLATE_FORMAT.md`'s "Known gaps").</summary>
+    private static Font ResolveFont(string familyName, float size)
+    {
+        try
+        {
+            return new Font(familyName, size <= 0 ? 12f : size, GraphicsUnit.Point);
+        }
+        catch (ArgumentException)
+        {
+            return new Font(FontFamily.GenericSansSerif, size <= 0 ? 12f : size, GraphicsUnit.Point);
+        }
+    }
+
+    protected override void OnMouseDown(MouseEventArgs e)
+    {
+        base.OnMouseDown(e);
+        if (e.Button != MouseButtons.Left)
+        {
+            return;
+        }
+
+        var (x, y) = CurrentTransform().ToPoints(e.X, e.Y);
+        var hit = _editor.TrySelectAt(x, y);
+        if (hit)
+        {
+            _editor.BeginDrag(x, y);
+            Capture = true;
+        }
+
+        Invalidate();
+        SelectionChanged?.Invoke(this, EventArgs.Empty);
+    }
+
+    protected override void OnMouseMove(MouseEventArgs e)
+    {
+        base.OnMouseMove(e);
+        if (!_editor.IsDragging)
+        {
+            return;
+        }
+
+        var (x, y) = CurrentTransform().ToPoints(e.X, e.Y);
+        _editor.DragTo(x, y);
+        Invalidate();
+        ElementsChanged?.Invoke(this, EventArgs.Empty);
+    }
+
+    protected override void OnMouseUp(MouseEventArgs e)
+    {
+        base.OnMouseUp(e);
+        _editor.EndDrag();
+        Capture = false;
+    }
+}

code/src/EnvelopeRenderer.Desktop/Views/TemplateDesignerForm.cs

@@ -0,0 +1,472 @@
+using EnvelopeRenderer.Desktop.Core.Design;
+
+namespace EnvelopeRenderer.Desktop.Views;
+
+/// <summary>
+/// The text-only template designer: canvas dimensions (Sprint 2 Batch 2), text element
+/// placement (Batch 3), a properties panel (Batch 4), and save/reopen (Batch 5). Opened from
+/// <see cref="EnvelopeRenderer.Desktop.MainForm"/> via "Design Template...".
+///
+/// As with <see cref="EnvelopeRenderer.Desktop.MainForm"/>, all non-UI logic lives in
+/// EnvelopeRenderer.Desktop.Core.Design and is unit tested there — this class is thin
+/// event-handler wiring plus the actual GDI+ drawing/hit-testing the canvas needs (which cannot
+/// reasonably be extracted, since it IS the WinForms rendering surface).
+/// </summary>
+public sealed class TemplateDesignerForm : Form
+{
+    private readonly NumericUpDown _widthInput = new()
+    {
+        DecimalPlaces = 3,
+        Minimum = 0.001m,
+        Maximum = 10000m,
+        Increment = 0.125m,
+        Width = 90,
+    };
+
+    private readonly NumericUpDown _heightInput = new()
+    {
+        DecimalPlaces = 3,
+        Minimum = 0.001m,
+        Maximum = 10000m,
+        Increment = 0.125m,
+        Width = 90,
+    };
+
+    private readonly ComboBox _unitComboBox = new()
+    {
+        DropDownStyle = ComboBoxStyle.DropDownList,
+        Width = 110,
+    };
+
+    private readonly Label _pointsLabel = new() { AutoSize = true, Anchor = AnchorStyles.Left };
+
+    // Save/reopen (Sprint 2 Batch 5).
+    private readonly Button _saveButton = new() { Text = "&Save Template...", AutoSize = true };
+    private readonly Button _openButton = new() { Text = "&Open Template...", AutoSize = true };
+    private readonly Label _fileStatusLabel = new() { AutoSize = true, Anchor = AnchorStyles.Left };
+
+    private readonly Button _addStaticTextButton = new() { Text = "Add Stati&c Text", AutoSize = true };
+    private readonly Button _addDynamicPlaceholderButton = new() { Text = "Add &Dynamic Placeholder", AutoSize = true };
+    private readonly Label _selectionLabel = new() { AutoSize = true, Anchor = AnchorStyles.Left, Text = "No element selected." };
+
+    // Properties panel (Sprint 2 Batch 4) — X, Y, font family, font size, color, z-order for the
+    // selected element, kept in live two-way sync with the canvas.
+    private readonly NumericUpDown _xInput = new() { DecimalPlaces = 2, Minimum = 0, Maximum = 100000m, Width = 80 };
+    private readonly NumericUpDown _yInput = new() { DecimalPlaces = 2, Minimum = 0, Maximum = 100000m, Width = 80 };
+    private readonly TextBox _fontFamilyInput = new() { Width = 160 };
+    private readonly NumericUpDown _fontSizeInput = new() { DecimalPlaces = 1, Minimum = 1, Maximum = 1000m, Width = 80 };
+    private readonly Button _colorButton = new() { Text = string.Empty, Width = 60, Height = 24, FlatStyle = FlatStyle.Popup };
+    private readonly NumericUpDown _zOrderInput = new() { DecimalPlaces = 0, Minimum = 0, Maximum = 100000m, Width = 80 };
+    // A plain Panel with explicit control positions (not a TableLayoutPanel) — deliberately
+    // simple/predictable for a fixed 6-row form rather than relying on auto-sizing cell layout.
+    private readonly Panel _propertiesPanel = new()
+    {
+        Dock = DockStyle.Right,
+        Width = 240,
+        Enabled = false,
+    };
+
+    private readonly CanvasDimensionsEditor _dimensionsEditor;
+    private readonly TextElementPropertiesEditor _propertiesEditor = new();
+    private readonly TemplateLayoutDocument _document;
+    private readonly TemplateCanvasControl _canvas;
+
+    /// <summary>Guards against re-entrant control-event handling while this form is
+    /// programmatically updating a control's value in response to another control's change
+    /// (e.g. re-populating width/height after a unit switch) — without this, setting
+    /// <c>NumericUpDown.Value</c> would re-fire <c>ValueChanged</c> and re-run the conversion
+    /// against an already-converted value.</summary>
+    private bool _suppressEvents;
+
+    public TemplateDesignerForm() : this(TemplateLayoutDocument.CreateDefault())
+    {
+    }
+
+    internal TemplateDesignerForm(TemplateLayoutDocument document)
+    {
+        _document = document;
+        _dimensionsEditor = new CanvasDimensionsEditor(document.Canvas);
+        _canvas = new TemplateCanvasControl(document) { Dock = DockStyle.Fill, Margin = new Padding(12) };
+
+        Text = "Template Designer";
+        MinimumSize = new Size(720, 480);
+        StartPosition = FormStartPosition.CenterScreen;
+
+        Controls.Add(BuildLayout());
+        RefreshDimensionControls();
+
+        _canvas.SelectionChanged += (_, _) => OnCanvasSelectionChanged();
+        _canvas.ElementsChanged += (_, _) =>
+        {
+            // A drag on the canvas moves the selected element without raising SelectionChanged
+            // (the selection itself didn't change) — refresh the panel's X/Y so it never shows a
+            // stale position after a drag.
+            RefreshPropertiesPanel();
+            RefreshSelectionLabel();
+        };
+    }
+
+    /// <summary>The current layout state, kept in sync with the dimensions controls and the
+    /// canvas as the operator edits them. Exposed for the save/reopen story (Batch 5) and for
+    /// tests.</summary>
+    internal TemplateLayoutDocument Document => _document;
+
+    /// <summary>Exposed for tests — the real WinForms canvas control cannot be driven headlessly
+    /// in xUnit, but this lets a test assert on which control instance was wired up.</summary>
+    internal TemplateCanvasControl Canvas => _canvas;
+
+    private Control BuildLayout()
+    {
+        var root = new TableLayoutPanel
+        {
+            Dock = DockStyle.Fill,
+            RowCount = 4,
+            ColumnCount = 1,
+        };
+        root.RowStyles.Add(new RowStyle(SizeType.AutoSize));
+        root.RowStyles.Add(new RowStyle(SizeType.AutoSize));
+        root.RowStyles.Add(new RowStyle(SizeType.AutoSize));
+        root.RowStyles.Add(new RowStyle(SizeType.Percent, 100));
+
+        var canvasRow = new Panel { Dock = DockStyle.Fill };
+        // Fill-docked control must be added last so the properties panel claims its fixed-width
+        // slice of the row first, leaving the remainder for the canvas.
+        canvasRow.Controls.Add(BuildPropertiesPanel());
+        canvasRow.Controls.Add(_canvas);
+
+        root.Controls.Add(BuildFileToolbar(), 0, 0);
+        root.Controls.Add(BuildCanvasSettingsPanel(), 0, 1);
+        root.Controls.Add(BuildElementToolbar(), 0, 2);
+        root.Controls.Add(canvasRow, 0, 3);
+
+        return root;
+    }
+
+    private Control BuildFileToolbar()
+    {
+        var panel = new FlowLayoutPanel
+        {
+            Dock = DockStyle.Top,
+            AutoSize = true,
+            Padding = new Padding(12, 12, 12, 0),
+            FlowDirection = FlowDirection.LeftToRight,
+        };
+
+        _saveButton.Click += (_, _) => OnSaveClick();
+        _openButton.Click += (_, _) => OnOpenClick();
+
+        panel.Controls.Add(_saveButton);
+        panel.Controls.Add(_openButton);
+        _fileStatusLabel.Margin = new Padding(18, 6, 3, 3);
+        panel.Controls.Add(_fileStatusLabel);
+
+        return panel;
+    }
+
+    private void OnSaveClick()
+    {
+        using var dialog = new SaveFileDialog
+        {
+            Filter = "XML template files (*.xml)|*.xml|All files (*.*)|*.*",
+            Title = "Save Template",
+            OverwritePrompt = true,
+        };
+
+        if (dialog.ShowDialog(this) != DialogResult.OK)
+        {
+            return;
+        }
+
+        try
+        {
+            TemplateLayoutXmlSerializer.Save(_document, dialog.FileName);
+            SetFileStatus($"Saved to '{dialog.FileName}'.", isError: false);
+        }
+        catch (Exception ex) when (ex is IOException or UnauthorizedAccessException)
+        {
+            var message = $"Could not save template: {ex.Message}";
+            SetFileStatus(message, isError: true);
+            MessageBox.Show(this, message, "Could Not Save Template", MessageBoxButtons.OK, MessageBoxIcon.Error);
+        }
+    }
+
+    private void OnOpenClick()
+    {
+        using var dialog = new OpenFileDialog
+        {
+            Filter = "XML template files (*.xml)|*.xml|All files (*.*)|*.*",
+            Title = "Open Template",
+            CheckFileExists = true,
+        };
+
+        if (dialog.ShowDialog(this) != DialogResult.OK)
+        {
+            return;
+        }
+
+        if (!TemplateLayoutXmlSerializer.TryLoad(dialog.FileName, out var loaded, out var errors))
+        {
+            var message = string.Join(Environment.NewLine, errors);
+            SetFileStatus($"Could not open template: {errors[0]}" + (errors.Count > 1 ? " (+ more)" : string.Empty), isError: true);
+            MessageBox.Show(this, message, "Could Not Open Template", MessageBoxButtons.OK, MessageBoxIcon.Error);
+            return;
+        }
+
+        _document.Canvas = loaded!.Canvas;
+        _document.Elements.Clear();
+        _document.Elements.AddRange(loaded.Elements);
+
+        _dimensionsEditor.Reset(_document.Canvas);
+        RefreshDimensionControls();
+        _canvas.ClearSelection();
+        _canvas.Invalidate();
+
+        SetFileStatus($"Opened '{dialog.FileName}' ({_document.Elements.Count} element(s)).", isError: false);
+    }
+
+    private void SetFileStatus(string message, bool isError)
+    {
+        _fileStatusLabel.Text = message;
+        _fileStatusLabel.ForeColor = isError ? Color.Firebrick : Color.DarkGreen;
+    }
+
+    private Control BuildPropertiesPanel()
+    {
+        const int rowHeight = 40;
+        const int leftMargin = 12;
+        const int labelTop = 6;
+        const int inputTop = 20;
+
+        AddPropertyRow(0 * rowHeight, "X (pt):", _xInput, leftMargin, labelTop, inputTop);
+        AddPropertyRow(1 * rowHeight, "Y (pt):", _yInput, leftMargin, labelTop, inputTop);
+        AddPropertyRow(2 * rowHeight, "Font family:", _fontFamilyInput, leftMargin, labelTop, inputTop);
+        AddPropertyRow(3 * rowHeight, "Font size (pt):", _fontSizeInput, leftMargin, labelTop, inputTop);
+        AddPropertyRow(4 * rowHeight, "Color:", _colorButton, leftMargin, labelTop, inputTop);
+        AddPropertyRow(5 * rowHeight, "Z-order (0 = bottom):", _zOrderInput, leftMargin, labelTop, inputTop);
+
+        _xInput.ValueChanged += (_, _) => { if (!_suppressEvents) { _propertiesEditor.SetX((double)_xInput.Value); _canvas.NotifyElementChanged(); } };
+        _yInput.ValueChanged += (_, _) => { if (!_suppressEvents) { _propertiesEditor.SetY((double)_yInput.Value); _canvas.NotifyElementChanged(); } };
+        _fontFamilyInput.TextChanged += (_, _) => { if (!_suppressEvents) { _propertiesEditor.SetFontFamily(_fontFamilyInput.Text); _canvas.NotifyElementChanged(); } };
+        _fontSizeInput.ValueChanged += (_, _) => { if (!_suppressEvents) { _propertiesEditor.SetFontSize((double)_fontSizeInput.Value); _canvas.NotifyElementChanged(); } };
+        _zOrderInput.ValueChanged += (_, _) => { if (!_suppressEvents) { _propertiesEditor.SetZOrder((int)_zOrderInput.Value); _canvas.NotifyElementChanged(); } };
+        _colorButton.Click += (_, _) => OnColorButtonClick();
+
+        return _propertiesPanel;
+    }
+
+    private void AddPropertyRow(int rowTop, string labelText, Control input, int leftMargin, int labelTop, int inputTop)
+    {
+        var label = new Label
+        {
+            Text = labelText,
+            AutoSize = true,
+            Location = new Point(leftMargin, rowTop + labelTop),
+        };
+        input.Location = new Point(leftMargin, rowTop + inputTop);
+        _propertiesPanel.Controls.Add(label);
+        _propertiesPanel.Controls.Add(input);
+    }
+
+    private void OnColorButtonClick()
+    {
+        if (_propertiesEditor.Selected is null)
+        {
+            return;
+        }
+
+        using var dialog = new ColorDialog { Color = _colorButton.BackColor };
+        if (dialog.ShowDialog(this) == DialogResult.OK)
+        {
+            var chosen = new RgbColor(dialog.Color.R, dialog.Color.G, dialog.Color.B);
+            _propertiesEditor.SetColor(chosen);
+            _colorButton.BackColor = dialog.Color;
+            _canvas.NotifyElementChanged();
+        }
+    }
+
+    private void OnCanvasSelectionChanged()
+    {
+        _propertiesEditor.Select(_canvas.SelectedElement);
+        RefreshPropertiesPanel();
+        RefreshSelectionLabel();
+    }
+
+    /// <summary>Repopulates the properties panel from the current selection without re-firing
+    /// the panel's own change handlers (see <see cref="_suppressEvents"/>) — used on selection
+    /// change and whenever the canvas moves the element (e.g. via a drag), so a drag and a
+    /// properties-panel edit never disagree about the element's current values.</summary>
+    private void RefreshPropertiesPanel()
+    {
+        var selected = _canvas.SelectedElement;
+        _propertiesPanel.Enabled = selected is not null;
+
+        _suppressEvents = true;
+        try
+        {
+            _xInput.Value = ClampToNumericRange(_xInput, (decimal)(selected?.X ?? 0));
+            _yInput.Value = ClampToNumericRange(_yInput, (decimal)(selected?.Y ?? 0));
+            _fontFamilyInput.Text = selected?.FontFamily ?? string.Empty;
+            _fontSizeInput.Value = ClampToNumericRange(_fontSizeInput, (decimal)(selected?.FontSize ?? 12));
+            _zOrderInput.Value = ClampToNumericRange(_zOrderInput, selected?.ZOrder ?? 0);
+            var color = selected?.Color ?? RgbColor.Black;
+            _colorButton.BackColor = Color.FromArgb(color.R, color.G, color.B);
+        }
+        finally
+        {
+            _suppressEvents = false;
+        }
+    }
+
+    private Control BuildElementToolbar()
+    {
+        var panel = new FlowLayoutPanel
+        {
+            Dock = DockStyle.Top,
+            AutoSize = true,
+            Padding = new Padding(12, 0, 12, 12),
+            FlowDirection = FlowDirection.LeftToRight,
+        };
+
+        _addStaticTextButton.Click += (_, _) => _canvas.AddStaticTextElement();
+        _addDynamicPlaceholderButton.Click += (_, _) => _canvas.AddDynamicPlaceholderElement();
+
+        panel.Controls.Add(_addStaticTextButton);
+        panel.Controls.Add(_addDynamicPlaceholderButton);
+        _selectionLabel.Margin = new Padding(18, 6, 3, 3);
+        panel.Controls.Add(_selectionLabel);
+
+        return panel;
+    }
+
+    private void RefreshSelectionLabel()
+    {
+        var selected = _canvas.SelectedElement;
+        _selectionLabel.Text = selected is null
+            ? "No element selected."
+            : $"Selected: {(selected.IsDynamic ? $"{{{selected.ColumnName}}}" : selected.StaticText)} " +
+              $"at ({selected.X:0.#}, {selected.Y:0.#}) pt.";
+    }
+
+    private Control BuildCanvasSettingsPanel()
+    {
+        var panel = new FlowLayoutPanel
+        {
+            Dock = DockStyle.Top,
+            AutoSize = true,
+            Padding = new Padding(12),
+            FlowDirection = FlowDirection.LeftToRight,
+        };
+
+        panel.Controls.Add(new Label { Text = "Width:", AutoSize = true, Anchor = AnchorStyles.Left, Margin = new Padding(3, 6, 3, 3) });
+        panel.Controls.Add(_widthInput);
+        panel.Controls.Add(new Label { Text = "Height:", AutoSize = true, Anchor = AnchorStyles.Left, Margin = new Padding(12, 6, 3, 3) });
+        panel.Controls.Add(_heightInput);
+        panel.Controls.Add(new Label { Text = "Unit:", AutoSize = true, Anchor = AnchorStyles.Left, Margin = new Padding(12, 6, 3, 3) });
+        panel.Controls.Add(_unitComboBox);
+        panel.Controls.Add(_pointsLabel);
+
+        _unitComboBox.Items.AddRange(new object[]
+        {
+            new UnitComboItem(CanvasUnit.Inches),
+            new UnitComboItem(CanvasUnit.Millimeters),
+            new UnitComboItem(CanvasUnit.Points),
+        });
+
+        _widthInput.ValueChanged += (_, _) => OnWidthChanged();
+        _heightInput.ValueChanged += (_, _) => OnHeightChanged();
+        _unitComboBox.SelectedIndexChanged += (_, _) => OnUnitChanged();
+
+        return panel;
+    }
+
+    private void OnWidthChanged()
+    {
+        if (_suppressEvents)
+        {
+            return;
+        }
+
+        _dimensionsEditor.SetWidth((double)_widthInput.Value);
+        _document.Canvas = _dimensionsEditor.Canvas;
+        UpdatePointsLabel();
+        _canvas.Invalidate();
+    }
+
+    private void OnHeightChanged()
+    {
+        if (_suppressEvents)
+        {
+            return;
+        }
+
+        _dimensionsEditor.SetHeight((double)_heightInput.Value);
+        _document.Canvas = _dimensionsEditor.Canvas;
+        UpdatePointsLabel();
+        _canvas.Invalidate();
+    }
+
+    private void OnUnitChanged()
+    {
+        if (_suppressEvents || _unitComboBox.SelectedItem is not UnitComboItem selected)
+        {
+            return;
+        }
+
+        _dimensionsEditor.SetDisplayUnit(selected.Unit);
+        _document.Canvas = _dimensionsEditor.Canvas;
+        RefreshDimensionControls();
+    }
+
+    /// <summary>Repopulates all three controls from <see cref="_dimensionsEditor"/> without
+    /// re-triggering conversion logic — used on load and after a unit switch.</summary>
+    private void RefreshDimensionControls()
+    {
+        _suppressEvents = true;
+        try
+        {
+            _widthInput.Value = ClampToNumericRange(_widthInput, (decimal)_dimensionsEditor.Canvas.WidthInDisplayUnit);
+            _heightInput.Value = ClampToNumericRange(_heightInput, (decimal)_dimensionsEditor.Canvas.HeightInDisplayUnit);
+            SelectUnitComboItem(_dimensionsEditor.Canvas.DisplayUnit);
+        }
+        finally
+        {
+            _suppressEvents = false;
+        }
+
+        UpdatePointsLabel();
+    }
+
+    private static decimal ClampToNumericRange(NumericUpDown control, decimal value) =>
+        Math.Max(control.Minimum, Math.Min(control.Maximum, value));
+
+    private void UpdatePointsLabel()
+    {
+        _pointsLabel.Text =
+            $"({_dimensionsEditor.Canvas.WidthPoints:0.###} x {_dimensionsEditor.Canvas.HeightPoints:0.###} pt)";
+    }
+
+    private void SelectUnitComboItem(CanvasUnit unit)
+    {
+        foreach (var item in _unitComboBox.Items)
+        {
+            if (item is UnitComboItem candidate && candidate.Unit == unit)
+            {
+                _unitComboBox.SelectedItem = item;
+                return;
+            }
+        }
+    }
+
+    /// <summary>Wraps a <see cref="CanvasUnit"/> for display in <see cref="_unitComboBox"/> with
+    /// an operator-friendly label instead of the enum member name.</summary>
+    private readonly record struct UnitComboItem(CanvasUnit Unit)
+    {
+        public override string ToString() => Unit switch
+        {
+            CanvasUnit.Inches => "Inches",
+            CanvasUnit.Millimeters => "Millimeters",
+            CanvasUnit.Points => "Points",
+            _ => Unit.ToString(),
+        };
+    }
+}

logs/technical_debt_log.md

@@ -7,4 +7,5 @@ Append-only log of known technical debt. Maintained by `.claude/agents/qa-tech-d
 | 2026-09-08 | `EnvelopeRenderer.Cli` exits `64` ("render not implemented") for any argument-valid run, since the Debenu render engine isn't wired in yet. Self-documenting and expected to disappear once "Render text-only PDFs through Debenu Quick PDF" (Sprint 1 Batch 2) lands and exit `0` becomes reachable. | Deliberate | Low | Paid Down | `RenderNotImplemented` branch removed from `Program.cs`; exit `0` is now reachable and exit `1` covers all template/CSV/render failures (see `code/CLI_CONTRACT.md`). |
 | 2026-09-08 | `DebenuPdfRenderer` always embeds TrueType fonts fully (`AddTrueTypeFont(..., Embed: 1)`), cached once per unique font name per document. Fine at today's scale (one sample render: ~1.3 MB for 392 pages, one font) but full embedding could add up if a template ever uses many distinct fonts/styles at very high page counts, working against the sub-2GB PDF constraint. | Deliberate | Low | Open | Revisit if the "Time-box the first high-volume benchmark" story (not in this sprint) shows file size becoming an issue; Debenu also exposes `AddSubsettedFont` as a smaller-footprint alternative if needed. |
 | 2026-09-08 | `EnvelopeRenderer.Desktop`'s Render button re-enables as soon as the CLI process is confirmed *started* (`CliProcessLauncher.LaunchAsync` returning), not once it finishes rendering — this story (Sprint 1 Batch 4) intentionally does not track render completion. An operator can click Render again (e.g. against the same output path) while a prior render is still in progress, since nothing yet observes the child process's lifetime or exit code. | Unavoidable (scope boundary of this story) | Low | Resolved | Sprint 1 Batch 5 ("Show render progress and completion summary") replaced `CliProcessLauncher.LaunchAsync`/`Launch` with `RunAsync`/`Run`, which stream the CLI's redirected stdout/stderr, wait for the process to actually exit, and return exit code + final progress event. `MainForm.OnRenderClick` now only re-enables the Render button in the `finally` block after that awaited call completes, not when the process starts — verified with a real launch against the sample CSV (button stayed disabled for the full render, both success and forced-failure runs). |
+| 2026-09-14 | The render path's actual high-volume throughput badly misses the product's stated "100,000 records at 300 DPI in under 10 minutes" target: a real (not simulated) 100k-record benchmark run showed throughput degrading monotonically from ~399 rec/s to ~15 rec/s (and still falling) by record 4,827 of 100,352, isolated with reasonable confidence to Debenu Quick PDF Library 10.13's in-memory document model rather than this repo's own O(1)-per-record merge/CSV code. Projected full-run time is on the order of 45-90+ minutes — 5x-10x+ over target. Full methodology, raw data, and root-cause investigation in `code/BENCHMARK.md`. | Unavoidable (external vendor library characteristic, not yet confirmed fixable) | High (directly threatens a hard product constraint — `project_config.md`'s "render 100,000 records at 300 DPI in under 10 minutes" — and would be worse at the stated 1,000,000-record ceiling) | Open | Not fixed as part of the time-boxed benchmark spike itself, per that story's own scope ("a spike-style story to gather performance information, not a final optimization guarantee"). Follow-up story "Investigate and address high-volume render throughput degradation" added to `backlog/epics/05_cli_rendering_engine_and_debenu_integration.md` (Status: Ready, not yet sized) to root-cause and mitigate before any release/packaging milestone or further high-volume-dependent feature work. |
 | 2026-09-04 | `EnvelopeRenderer.Cli` only read `DEBENU_LICENSE_KEY` from the process environment. That's fine for `dotnet run --project ... --` (the CLI inherits the invoking shell's env directly), but `EnvelopeRenderer.Desktop` launches the CLI as a child process, which only inherits whatever environment variables were already present in whatever launched the desktop app itself (a double-clicked `.exe` or Start Menu shortcut typically has none) — so every desktop-launched render failed with Debenu error 999 regardless of a valid key existing on disk. Real-user-reported: the operator correctly guessed a `key.txt` dropped next to the exe should work (matching how the CLI's own test helper already resolved keys), but production code had no such fallback. This is a real Definition-of-Done verification gap from Sprint 1 Batches 4-5: the "real success run" verification used an in-process test harness with the env var set directly in that process, never the actual built `.exe` launched the way an operator would, so the gap wasn't caught before Sprint Review. | Unintentional | High (silently broke the desktop app's core success path for any non-`dotnet run` launch) | Resolved | Added `DebenuLicenseKeyResolver` (`code/src/EnvelopeRenderer.Cli/DebenuLicenseKeyResolver.cs`) to the shipped CLI: env var first, then a `key.txt` walked up from the executable's own directory — the same rule the test-only helper already used, now shared via delegation instead of duplicated. Documented in `CLI_CONTRACT.md`'s "Debenu license key" section and `code/README.md`'s desktop-app instructions. Verified by running the actual built `EnvelopeRenderer.Cli.exe` from the Desktop app's own output folder with no environment variable set at all, `key.txt` sitting next to it: exit `0`, valid 1.3 MB `%PDF-1.4` output, all 392 records. 5 new unit tests added (`DebenuLicenseKeyResolverTests.cs`); full suite 111/111 passing. |

state.md

@@ -6,16 +6,14 @@
 **Leading agent:** `scrum-master`
 **Process file:** `process/05_sprint_retrospective.md`
 
-**Sprint:** 1
-**Sprint dates:** 2026-09-08 - 2026-09-11
-**Sprint goal:** Prove a thin text-only desktop-to-CLI rendering spine so an operator can select files, launch a job, watch progress, and receive a PDF generated through Debenu from a known XML template.
-**Current sprint backlog:** `backlog/sprints/sprint-1.md`
+**Sprint:** 2
+**Sprint dates:** 2026-09-14 - 2026-09-18
+**Sprint goal:** Deliver a usable text-only template designer GUI (canvas sizing, text placement, property editing, save/reopen) as the foundation for CSV mapping, and re-verify the render path's high-volume performance target before more work lands on the render hot path.
+**Current sprint backlog:** `backlog/sprints/sprint-2.md`
 
-**Next action:** Sprint 1 fully closed out — Review and Retrospective both complete (`backlog/sprints/sprint-1.md` Sprint Review Outcome section; `backlog/sprints/sprint-1-retrospective.md`). Two decisions are pending with the user before Sprint 2 planning starts (a deliberate AGENTS.md pause point):
-1. Whether to apply `scrum-master`'s proposed `templates/definition_of_done.md` edit (a new bullet requiring verification against the actual built artifact — not just an in-process harness — for any story that changes launch/packaging/runtime-config-resolution behavior). Proposed wording is in `logs/process_improvement_log.md` (2026-09-11 row, Status: Proposed) and `backlog/sprints/sprint-1-retrospective.md`. Not yet applied to the template.
-2. Go-ahead to start Sprint 2 planning (`process/02_sprint_planning.md`, facilitated by `scrum-master`; `product-owner` and `dev-team` participate).
+**Next action:** Sprint 2 fully closed out — Review and Retrospective both complete (`backlog/sprints/sprint-2.md` Sprint Review Outcome section; `backlog/sprints/sprint-2-retrospective.md`). All four of Sprint 1's retro action items were fully applied this sprint (clean follow-through, no drops). No kit-level edit was proposed this retro (the one anomaly found — a self-contained daily-log test-count arithmetic slip — is single-occurrence and low-severity, below `AGENTS.md`'s bar for a kit change; logged as a deferred watch item only). Per `AGENTS.md`'s explicit pause point ("finishing a retrospective before committing to start the next sprint"), **waiting on the user's go-ahead to start Sprint 3 planning** (`process/02_sprint_planning.md`).
 
-Sprint 2 candidate epics per the backlog (`backlog/backlog.md`): epic 2 (Template Designer GUI Foundation) and epic 3 (CSV Integration and Field Mapping), both Ready; product-owner also flagged pulling "Time-box the first high-volume benchmark" (epic 05) early in refinement. Sprint 1 retrospective's concrete carry-forward actions (regardless of the DoD-edit decision) are listed in `backlog/sprints/sprint-1-retrospective.md`'s "Action Items" section and should inform Sprint 2 planning either way.
+Sprint 3 planning should prioritize, per the Sprint 2 retrospective's top action item: "Investigate and address high-volume render throughput degradation" (`backlog/epics/05_cli_rendering_engine_and_debenu_integration.md`, Ready, not yet sized — needs sizing during refinement) — the render path currently misses the 100k-record/10-minute hard constraint by 5x-10x+ (`code/BENCHMARK.md`). CSV Integration and Field Mapping (epic 3, Ready, including the deferred stretch story "Load CSV headers and sample rows") is the other natural Sprint 3 candidate per backlog order.
 
 ## Phase reference
 
@@ -43,4 +41,8 @@ After phase 5, loop back to phase 1 for the next sprint.
 | 2026-09-08 | 3 - Sprint execution (in progress) | Held Daily Scrum #1 and turned the sprint backlog into a dependency-ordered execution plan (5 batches) in `backlog/sprints/sprint-1.md`. Still in phase 3 — not a phase transition, just the day's checkpoint. |
 | 2026-09-08 | 3 - Sprint execution | All 5 batches Done: CLI render contract, real Debenu text-only rendering, stdout progress events, WinForms desktop launch shell (user-confirmed as the UI framework), and live progress/completion display. 106 tests passing end-to-end. Sprint goal met with real verified runs against the 392-row sample CSV. |
 | 2026-09-11 | 4 - Sprint review | `product-owner` verified all 5 stories against acceptance criteria (verdict: sprint goal met, with two tracked caveats — see `backlog/sprints/sprint-1.md`'s Sprint Review Outcome section). Updated `backlog/backlog.md` and epics 01/05/07 with Done notes and two new follow-up stories. Logged one process-improvement item (Watching) for the retrospective re: verifying GUI stories against the actual built artifact, not just an in-process harness — this is exactly what let the license-key bug (fixed same-day, see `logs/technical_debt_log.md`) through undetected. |
-| 2026-09-11 | 5 - Sprint retrospective | `scrum-master` ran the retrospective (`backlog/sprints/sprint-1-retrospective.md`). Named two team-level strengths to keep (dependency-ordered batch swarming; "leave it better than you found it" plus honest gap self-reporting) and one lower-priority deferred idea (re-trigger the 100k-record benchmark when hot-path code changes). Decided the DoD/verification-gap item meets the bar for a proposed kit edit (single severe occurrence) and drafted specific wording for `templates/definition_of_done.md`, but did not apply it — awaiting the user's go-ahead per AGENTS.md. Checked all four named anti-patterns; none found (one near-miss on thin GUI evidence named explicitly, addressed via the proposed DoD edit and a Sprint 2 action item rather than swept aside). |
+| 2026-09-11 | 5 - Sprint retrospective | `scrum-master` ran the retrospective (`backlog/sprints/sprint-1-retrospective.md`). Named two team-level strengths to keep (dependency-ordered batch swarming; "leave it better than you found it" plus honest gap self-reporting) and one lower-priority deferred idea (re-trigger the 100k-record benchmark when hot-path code changes). Decided the DoD/verification-gap item meets the bar for a proposed kit edit (single severe occurrence) and drafted specific wording for `templates/definition_of_done.md`. User approved the edit same-day; it was applied to the template (confirmed in `logs/process_improvement_log.md`, Status: Applied) — `state.md` briefly and incorrectly described this as still pending in a later note, corrected on 2026-09-14. Checked all four named anti-patterns; none found (one near-miss on thin GUI evidence named explicitly, addressed via the DoD edit and a Sprint 2 action item rather than swept aside). |
+| 2026-09-14 | 2 - Sprint planning | `scrum-master` facilitated Sprint 2 planning with `product-owner` and `dev-team`. Committed 19 points: the overdue high-volume benchmark spike (pulled first per the retrospective action item) plus the full Template Designer GUI Foundation epic as one coherent vertical slice (canvas dimensions -> text placement -> properties panel -> save/reopen). CSV Integration stories deferred whole to Sprint 3 (3 of 4 hard-depend on this sprint's text-placement story); "Load CSV headers" kept as an explicit stretch item since it has no such dependency. Capacity treated as low-confidence off one data point (Sprint 1's 20 completed points). Recorded in `backlog/sprints/sprint-2.md`. |
+| 2026-09-14 | 3 - Sprint execution | `dev-team` completed all 5 committed batches in dependency order (one interruption/resume mid-run due to a session rate limit, no work lost). Batch 1 (benchmark spike) found a material, previously-unknown risk: real-world throughput degrades from ~399 rec/s to ~15 rec/s and falling at ~100k-record scale, missing the 10-minute target by 5x-10x+, isolated to Debenu Quick PDF Library 10.13's document model — logged as a new Ready story plus a High-impact tech debt entry rather than fixed in-scope. Batches 2-5 delivered the full Template Designer GUI Foundation epic (canvas dimensions, text placement, properties panel, save/reopen), each verified live against the actual built `.exe` per the Sprint 1 retrospective's DoD edit. 195/195 tests passing. Stretch item not pulled (full committed slice prioritized over starting more scope). |
+| 2026-09-18 | 4 - Sprint review | `product-owner` verified all 5 Sprint 2 stories against acceptance criteria (verdict: sprint goal met). Updated `backlog/backlog.md` and epics `02`/`05` with Done notes and verification detail; confirmed and endorsed dev-team's benchmark self-verification, framing it as a successful spike (story ACs met) surfacing a failing product metric (target missed), not a failed story. Recommended prioritizing the new throughput-investigation story at or near the top of Sprint 3. |
+| 2026-09-18 | 5 - Sprint retrospective | `scrum-master` ran the retrospective (`backlog/sprints/sprint-2-retrospective.md`). Confirmed full follow-through on all four Sprint 1 retro action items (clean sprint, no drops) — notably, the Sprint 1-named "thin GUI evidence" weakness was concretely fixed this sprint via live actual-`.exe` verification on every GUI story. No kit-level edit proposed (one low-severity, single-occurrence daily-log arithmetic slip found; below the bar for a kit change, logged as a deferred watch item). Checked all four named anti-patterns plus the Sprint 1 status-theater near-miss; none found, with the status-theater near-miss specifically improved on rather than repeated. |