docs: correct default degree to 3 (barrel distortion is cubic in machine coords)

docs/superpowers/specs/2026-06-11-wide-angle-distortion-design.md

@@ -27,10 +27,11 @@ This is a **model** limitation, not a calibration-points problem.
 ## Chosen approach: bivariate polynomial warp
 
 Replace the homography with a **bivariate polynomial warp** (`PolyWarp`) that maps machine
-coordinates directly to normalized image coordinates. The quadratic terms (`x², xy, y²`)
+coordinates directly to normalized image coordinates. The cubic terms (`x³, x²y, xy², y³`)
-capture both the bed's perspective trapezoid and the leading `r²` term of barrel
+are what capture the symmetric radial barrel distortion (see the degree correction below);
-distortion. Because the map is **linear in its coefficients**, it is fit with the same
+the lower-order terms absorb the bed's perspective trapezoid. Because the map is **linear in
-least-squares machinery the homography already used.
+its coefficients**, it is fit with the same least-squares machinery the homography already
+used.
 
 Considered and rejected for now:
 - **Physical radial lens model + homography (Brown–Conrady):** physically correct and
@@ -39,9 +40,15 @@ Considered and rejected for now:
 - **Thin-plate spline / mesh warp:** highest accuracy but wants many control points
   (20–40) and more code; overkill for the ~8–12-point budget.
 
-Escalation path: if degree-2 residuals stay high, bump to degree 3 (needs ≥12 points), or
+Fallback path: with sparse calibration (<10 points) drop to degree 2; if residuals stay
-graduate to the radial model. The polynomial is the smallest change that actually fixes the
+high after degree 3, graduate to the radial model. The polynomial is the smallest change
-observed drift.
+that actually fixes the observed drift.
+
+> **Correction (validated during implementation):** barrel distortion multiplies the
+> coordinate by `(1 + k·r²)`, so as a function of machine coordinates it is **degree 3**
+> (`dx·r²` expands to `dx³ + dx·dy²`), not degree 2. A degree-2 polynomial therefore does
+> *not* beat a homography on real radial distortion — only degree 3 does. Hence degree 3 is
+> the default below, not an escalation.
 
 ### The model
 
@@ -56,9 +63,10 @@ reverse direction directly from the same points. The inverse map only serves UI
 its few-pixel / sub-mm accuracy is sufficient; forward and inverse need not be exact mutual
 inverses.
 
-Default **degree 2** (6 coefficients per axis, needs ≥6 points). **Degree 3** (10
+Default **degree 3** (10 coefficients per axis, needs ≥10 points) — the degree that
-coefficients per axis, needs ≥10 points; recommend ≥12 to avoid overfit) is a manual
+actually compensates barrel distortion; the 16-point box+# target supports it comfortably.
-escalation when residuals warrant it.
+**Degree 2** (6 coefficients per axis, needs ≥6 points) is a manual fallback for sparse
+calibration. The calibration UI exposes a degree selector defaulting to 3.
 
 Image coordinates remain **normalized [0,1]** camera-frame fractions, as today — keeps
 calibration independent of display/canvas size.