Server: return loss (error + penalties) per step, use fixed-LR stepping

Server handler (`handlers.rs`):
- Compute `loss = |error| + penalties.total()` for each training step
- `sparklineData.errors` now contains loss values (was area error)
- Add `sparklineData.areaErrors` for pure area error
- Add `minLoss` / `minLossStepIndex` to batch result
- Switch from error-scaled `step()` to fixed-LR `step_clipped()`:
  `step()` freezes when area error → 0 because `step_size = error * lr`;
  `step_clipped()` uses `step = clamp(grad) * lr` so penalty gradients
  still drive optimization when area error is negligible

WASM worker (`worker.ts`):
- Add `penaltyTotal()` and `stepLoss()` helpers to `utils.ts`
- Compute per-step loss from WASM step penalties
- `sparklineData.errors` now contains loss, `.areaErrors` contains area error

Also suppress pre-existing warnings:
- `_non_largest_sum_v` unused variable in `step.rs`
- `#[allow(dead_code)]` on `LayoutResult` in `layout_opt.rs`

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: ryan-williams

apvd-cli/src/layout_opt.rs

@@ -19,6 +19,7 @@ use apvd_core::scene::Scene;
 use apvd_core::shape::Shape;
 
 /// Result of a layout optimization run.
+#[allow(dead_code)]
 pub struct LayoutResult {
     /// Number of shapes
     pub num_shapes: usize,

apvd-cli/src/server/handlers.rs

@@ -389,9 +389,13 @@ pub(super) fn handle_train_batch(id: &str, params: &Value) -> JsonRpcResponse {
     let mut steps: Vec<Value> = Vec::with_capacity(num_steps);
     let mut min_error = current_step.error.v();
     let mut min_step_index = 0usize;
+    let initial_loss = current_step.error.v().abs() + current_step.penalties.total();
+    let mut min_loss = initial_loss;
+    let mut min_loss_step_index = 0usize;
 
-    // Collect sparkline data: errors and gradients for each step
-    let mut sparkline_errors: Vec<f64> = Vec::with_capacity(num_steps);
+    // Collect sparkline data: loss and area errors for each step
+    let mut sparkline_errors: Vec<f64> = Vec::with_capacity(num_steps);  // loss (error + penalties)
+    let mut sparkline_area_errors: Vec<f64> = Vec::with_capacity(num_steps);  // pure area error
     let mut sparkline_gradients: Vec<Vec<f64>> = Vec::with_capacity(num_steps);
     // Region errors: key -> [error at step 0, error at step 1, ...]
     let mut sparkline_region_errors: std::collections::BTreeMap<String, Vec<f64>> = std::collections::BTreeMap::new();
@@ -408,21 +412,27 @@ pub(super) fn handle_train_batch(id: &str, params: &Value) -> JsonRpcResponse {
     steps.push(serde_json::json!({
         "stepIndex": 0,
         "error": current_step.error.v(),
+        "loss": initial_loss,
         "shapes": initial_shapes,
     }));
-    sparkline_errors.push(current_step.error.v());
+    sparkline_errors.push(initial_loss);
+    sparkline_area_errors.push(current_step.error.v());
     sparkline_gradients.push(current_step.error.d().to_vec());
     for (key, err) in &current_step.errors {
         if let Some(vec) = sparkline_region_errors.get_mut(key) {
             vec.push(err.error.v());
         }
     }
 
-    // Compute remaining steps
+    // Compute remaining steps using fixed-LR stepping (not error-scaled).
+    // Error-scaled step() freezes the optimizer when area error → 0 but penalties remain.
+    let max_grad_value = 0.5;
+    let max_grad_norm = 1.0;
     for i in 1..num_steps {
-        match current_step.step(learning_rate) {
+        match current_step.step_clipped(learning_rate, max_grad_value, max_grad_norm) {
             Ok(next_step) => {
                 let error = next_step.error.v();
+                let loss = error.abs() + next_step.penalties.total();
 
                 // Check for NaN in error or shape coordinates
                 if error.is_nan() {
@@ -448,24 +458,32 @@ pub(super) fn handle_train_batch(id: &str, params: &Value) -> JsonRpcResponse {
                     };
                 }
 
-                // Track minimum
+                // Track minimum area error
                 if error < min_error {
                     min_error = error;
                     min_step_index = i;
                 }
 
+                // Track minimum loss
+                if loss < min_loss {
+                    min_loss = loss;
+                    min_loss_step_index = i;
+                }
+
                 // Record step
                 let shapes: Vec<Value> = next_step.shapes.iter()
                     .map(|s| serde_json::to_value(s.v()).unwrap())
                     .collect();
                 steps.push(serde_json::json!({
                     "stepIndex": i,
                     "error": error,
+                    "loss": loss,
                     "shapes": shapes,
                 }));
 
                 // Collect sparkline data
-                sparkline_errors.push(error);
+                sparkline_errors.push(loss);
+                sparkline_area_errors.push(error);
                 sparkline_gradients.push(next_step.error.d().to_vec());
                 for (key, err) in &next_step.errors {
                     if let Some(vec) = sparkline_region_errors.get_mut(key) {
@@ -493,17 +511,21 @@ pub(super) fn handle_train_batch(id: &str, params: &Value) -> JsonRpcResponse {
         .map(|s| serde_json::to_value(s.v()).unwrap())
         .collect();
 
-    eprintln!("[trainBatch] Completed {} steps, minError={} at step {}", steps.len(), min_error, min_step_index);
+    eprintln!("[trainBatch] Completed {} steps, minError={} at step {}, minLoss={} at step {}",
+        steps.len(), min_error, min_step_index, min_loss, min_loss_step_index);
 
     JsonRpcResponse {
         id: id.to_string(),
         result: Some(serde_json::json!({
             "steps": steps,
             "minError": min_error,
             "minStepIndex": min_step_index,
+            "minLoss": min_loss,
+            "minLossStepIndex": min_loss_step_index,
             "finalShapes": final_shapes,
             "sparklineData": {
                 "errors": sparkline_errors,
+                "areaErrors": sparkline_area_errors,
                 "gradients": sparkline_gradients,
                 "regionErrors": sparkline_region_errors,
             },

apvd-core/src/optimization/step.rs

@@ -382,12 +382,16 @@ impl Step {
         }
 
         // Fragmentation penalty: for region keys with multiple disconnected geometric
-        // components, penalize all but the largest. Each key's penalty is the fraction of
-        // that region's own area that's in non-largest fragments (normalized per-region,
-        // not per-total-area). This produces stronger gradients for eliminating tiny nubs
-        // on small regions.
+        // components, penalize the existence of fragments weighted by the region's
+        // importance (its share of total area).
+        //
+        // Uses saturating normalization on the fragment fraction: sat(f) = f/(f+k).
+        // This means any non-trivial fragment quickly produces a penalty proportional
+        // to the region's share of total area, creating strong gradients to eliminate
+        // even tiny fragment nubs.
         let mut total_fragmentation_penalty = scene.zero();
         let mut region_penalties: BTreeMap<String, RegionPenalties> = BTreeMap::new();
+        let frag_k = 1e-4_f64; // half-saturation: frag fraction of 0.01% gets half-penalty
         {
             let mut regions_by_key: BTreeMap<String, Vec<Dual>> = BTreeMap::new();
             for component in &scene.components {
@@ -401,16 +405,24 @@ impl Step {
                     geo_areas.sort_by(|a, b| b.v().partial_cmp(&a.v()).unwrap());
                     // Sum all fragments for this key (region total area)
                     let region_total: Dual = geo_areas.iter().cloned().sum();
+                    let region_weight = region_total.v() / total_area.v();
                     // Sum non-largest fragments
                     let non_largest_sum: Dual = geo_areas.into_iter().skip(1).sum();
-                    let non_largest_sum_v = non_largest_sum.v();
-                    // Fraction of region that's fragmented (in [0, 1))
-                    let key_frac = non_largest_sum / &region_total;
-                    debug!("  fragmentation penalty: key={}, region_total={}, frag_sum={}, frac={}", key, region_total.v(), non_largest_sum_v, key_frac.v());
+                    let _non_largest_sum_v = non_largest_sum.v();
+                    // Fraction of region that's fragmented
+                    let frag_frac = non_largest_sum / &region_total;
+                    // Saturate: sat(f) = f/(f+k), so even tiny frags → ~1
+                    let frag_frac_v = frag_frac.v();
+                    let sat_denom = frag_frac.clone() + frag_k;
+                    let saturated = frag_frac / &sat_denom;
+                    // Weight by region's share of total area
+                    let key_penalty = saturated * region_weight;
+                    debug!("  fragmentation: key={}, region_weight={:.4}, frag_frac={:.6}, saturated={:.4}, penalty={:.6}",
+                        key, region_weight, frag_frac_v, key_penalty.v() / region_weight, key_penalty.v());
                     let rp = region_penalties.entry(key).or_default();
-                    rp.fragmentation = key_frac.v();
+                    rp.fragmentation = key_penalty.v();
                     rp.fragment_count = fragment_count;
-                    total_fragmentation_penalty += key_frac;
+                    total_fragmentation_penalty += key_penalty;
                 }
             }
         }

apvd-wasm/ts/utils.ts

@@ -60,6 +60,34 @@ export function extractShapes(wasmShapes: unknown[]): Shape[] {
   return wasmShapes.map(s => extractShape(s));
 }
 
+// ============================================================================
+// Penalty extraction
+// ============================================================================
+
+/** Shape of the WASM Penalties struct after serde serialization */
+interface WasmPenalties {
+  disjoint: number;
+  contained: number;
+  self_intersection: number;
+  regularity: number;
+  fragmentation: number;
+  perimeter_area: number;
+  region_perimeter_area: number;
+}
+
+/** Sum all penalty fields from a serialized WASM Penalties struct */
+export function penaltyTotal(p: WasmPenalties | undefined | null): number {
+  if (!p) return 0;
+  return (p.disjoint ?? 0) + (p.contained ?? 0) + (p.self_intersection ?? 0)
+    + (p.regularity ?? 0) + (p.fragmentation ?? 0) + (p.perimeter_area ?? 0)
+    + (p.region_perimeter_area ?? 0);
+}
+
+/** Compute loss (|area error| + penalties) from a WASM step */
+export function stepLoss(wasmStep: { error: { v: number }; penalties?: WasmPenalties }): number {
+  return Math.abs(wasmStep.error.v) + penaltyTotal(wasmStep.penalties);
+}
+
 // ============================================================================
 // Sparkline data extraction
 // ============================================================================

apvd-wasm/ts/worker.ts

@@ -64,6 +64,7 @@ import {
   extractShape,
   extractShapes,
   extractSparklineData,
+  stepLoss,
   tier,
   resolution,
   isKeyframe,
@@ -447,6 +448,11 @@ async function handleTrainBatch(id: string, request: BatchTrainingRequest): Prom
       shapes: extractShapes((wasmStep as { shapes: unknown[] }).shapes),
     }));
 
+    // Compute per-step loss (area error + penalties)
+    const lossPerStep = modelSteps.map((ws: unknown) =>
+      stepLoss(ws as { error: { v: number }; penalties?: any })
+    );
+
     // Extract sparkline data from all steps
     const { gradients, regionErrors } = extractSparklineData(modelSteps, 0);
 
@@ -456,7 +462,8 @@ async function handleTrainBatch(id: string, request: BatchTrainingRequest): Prom
       minStepIndex: minIdx,
       finalShapes: steps[steps.length - 1].shapes,
       sparklineData: {
-        errors: steps.map(s => s.error),
+        errors: lossPerStep,
+        areaErrors: steps.map(s => s.error),
         gradients,
         regionErrors,
       },
@@ -503,18 +510,21 @@ async function handleContinueTraining(id: string, handleId: string, numSteps: nu
 
     // Collect per-step data (skip first step as it duplicates last)
     const batchSteps: Array<{ stepIndex: number; error: number; shapes: Shape[] }> = [];
+    const lossPerStep: number[] = [];
 
     // Extract sparkline data (starting from index 1, skipping duplicate)
     const { gradients: sparklineGradients, regionErrors: sparklineRegionErrors } =
       extractSparklineData(modelSteps, 1);
 
     for (let i = 1; i < modelSteps.length; i++) {
-      const wasmStep = modelSteps[i] as { error: { v: number }; shapes: unknown[] };
+      const wasmStep = modelSteps[i] as { error: { v: number }; shapes: unknown[]; penalties?: any };
       const stepIndex = startStep + i;
       const error = wasmStep.error.v;
       const shapes = extractShapes(wasmStep.shapes);
+      const loss = stepLoss(wasmStep);
 
       batchSteps.push({ stepIndex, error, shapes });
+      lossPerStep.push(loss);
 
       // Store keyframe in session history if tiered storage says so
       if (isKeyframe(stepIndex, bucketSize)) {
@@ -547,7 +557,8 @@ async function handleContinueTraining(id: string, handleId: string, numSteps: nu
       currentError,
       steps: batchSteps,
       sparklineData: {
-        errors: batchSteps.map(s => s.error),
+        errors: lossPerStep,
+        areaErrors: batchSteps.map(s => s.error),
         gradients: sparklineGradients,
         regionErrors: sparklineRegionErrors,
       },