docs: plan MovementTest path visualization refresh

2026-08-09 18:55:26 +08:00
parent 6de8c933f1
commit 99a7d5bb2f
1 changed files with 694 additions and 0 deletions
@@ -0,0 +1,694 @@
+# MovementTest Web Path Visualization Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Improve the MovementTest web path overview so coarse, smoothed, and EM paths remain distinguishable, while adding a metric coordinate system, a data-driven legend, fixed-size vehicle rendering, and explicit smoothed-path endpoints.
+
+**Architecture:** Keep the existing Canvas occupancy layer and SVG geometry layer. Extend the SVG renderer with world-to-screen metrics, metric grid/axis rendering, fixed-pixel marker transforms, and deterministic path layering; add one HTML legend overlay and one static `smooth-start` marker without changing the visualization JSON contract or planner behavior.
+
+**Tech Stack:** C# 10, .NET `netstandard2.0` visualization library, .NET 10 Windows verification hosts, embedded HTML/CSS/vanilla JavaScript, SVG, Canvas.
+
+## Global Constraints
+
+- Do not modify coarse-path, Local G2, EMPlanner, FullDirection, Rolling, or multi-segment state-machine behavior.
+- Do not add actuator calls, trajectory tracking, or any execution closed loop; `OBSERVE_ONLY` remains unchanged.
+- Do not introduce third-party JavaScript, CSS, map, chart, CDN, or NuGet dependencies.
+- Do not replace or version the visualization JSON contract; only add `smooth-start` to the existing static marker collection.
+- Keep X and Y at equal world scale and label coordinates in meters.
+- Keep all path strokes and marker geometry visually stable across world extents.
+- Do not add overview pan, zoom, fullscreen, or layer toggles.
+- Preserve unrelated dirty-worktree changes; stage only the files named by the current task.
+
+---
+
+## File Structure
+
+- `ClumsyPilot/ParkrobTrajplanner/tarjplanner_movementtest/TrajectoryObservationStaticSnapshotBuilder.cs`
+  - Owns MovementTest-to-generic-visualization static geometry conversion; it will add the smoothed-path start marker.
+- `ClumsyPilot/TrajectoryPlanningVisualization/Web/index.html`
+  - Owns overview DOM structure; it will add the screen-space legend container.
+- `ClumsyPilot/TrajectoryPlanningVisualization/Web/app.js`
+  - Owns browser rendering; it will add coordinate ticks, world/screen metrics, fixed-size markers, ordered paths, and legend population.
+- `ClumsyPilot/TrajectoryPlanningVisualization/Web/app.css`
+  - Owns semantic visual styling; it will define coordinate, path, marker, and legend appearance.
+- `ClumsyPilot/tests/EMPlannerVerificationHost/TrajectoryObservationVisualizationChecks.cs`
+  - Verifies MovementTest snapshot semantics, including the new `smooth-start` marker.
+- `ClumsyPilot/tests/TrajectoryPlanningVisualizationVerificationHost/WebAssetChecks.cs`
+  - Verifies embedded web assets expose coordinate, fixed-marker, layer, and legend capabilities.
+- `ClumsyPilot/tests/TrajectoryPlanningVisualizationVerificationHost/SampleSnapshotFactory.cs`
+  - Supplies deterministic overlapping coarse, smoothed, and EM geometry for the local browser smoke test.
+
+## Task 1: Export the Smoothed-Path Start Marker
+
+**Files:**
+- Modify: `ClumsyPilot/ParkrobTrajplanner/tarjplanner_movementtest/TrajectoryObservationStaticSnapshotBuilder.cs:56-76`
+- Test: `ClumsyPilot/tests/EMPlannerVerificationHost/TrajectoryObservationVisualizationChecks.cs:82-110`
+
+**Interfaces:**
+- Consumes: `TrajectoryObservationBootstrapResult.SmoothedPath.Path`, whose first element supplies `X` and `Y`.
+- Produces: one existing-contract `VisualizationMarker` with `Id = "smooth-start"`, `Kind = "smooth-start"`, and `LabelChinese = "平滑路径起点"` when the smoothed path is non-empty.
+
+- [ ] **Step 1: Write the failing snapshot assertions**
+
+Add these assertions immediately after the existing `local-g2-path` assertion in `VerifiesStaticSnapshotExportsFrozenConfigurationAndGeometry`:
+
+```csharp
+VisualizationMarker smoothStart = snapshot.StaticMarkers.Single(x => x.Kind == "smooth-start");
+Verification.Equal("平滑路径起点", smoothStart.LabelChinese,
+    "static snapshot labels the smoothed-path start");
+Verification.NearlyEqual(bootstrap.SmoothedPath.Path[0].X, smoothStart.Position.X,
+    "smoothed-path start marker X matches the first smoothed point");
+Verification.NearlyEqual(bootstrap.SmoothedPath.Path[0].Y, smoothStart.Position.Y,
+    "smoothed-path start marker Y matches the first smoothed point");
+```
+
+- [ ] **Step 2: Run the focused test and verify failure**
+
+Run:
+
+```powershell
+dotnet run --project ClumsyPilot/tests/EMPlannerVerificationHost/EMPlannerVerificationHost.csproj -- trajectory-observation
+```
+
+Expected: FAIL in `VerifiesStaticSnapshotExportsFrozenConfigurationAndGeometry` because no marker has `Kind == "smooth-start"`.
+
+- [ ] **Step 3: Add the minimal static marker**
+
+Insert this block at the start of `CreateMarkers`, after `var markers = new List<VisualizationMarker>();` and before iterating direction segments:
+
+```csharp
+if (bootstrap.SmoothedPath.Path.Count > 0)
+{
+    var start = bootstrap.SmoothedPath.Path[0];
+    markers.Add(new VisualizationMarker("smooth-start", "smooth-start",
+        "平滑路径起点", new VisualizationPoint(start.X, start.Y)));
+}
+```
+
+- [ ] **Step 4: Run the focused test and verify success**
+
+Run:
+
+```powershell
+dotnet run --project ClumsyPilot/tests/EMPlannerVerificationHost/EMPlannerVerificationHost.csproj -- trajectory-observation
+```
+
+Expected: `PASS trajectory-observation`.
+
+- [ ] **Step 5: Commit the marker contract change**
+
+```powershell
+git add -- ClumsyPilot/ParkrobTrajplanner/tarjplanner_movementtest/TrajectoryObservationStaticSnapshotBuilder.cs ClumsyPilot/tests/EMPlannerVerificationHost/TrajectoryObservationVisualizationChecks.cs
+git commit -m "feat: mark smoothed path start in EM overview"
+```
+
+## Task 2: Add the Metric Coordinate System
+
+**Files:**
+- Modify: `ClumsyPilot/TrajectoryPlanningVisualization/Web/app.js:40-94`
+- Modify: `ClumsyPilot/TrajectoryPlanningVisualization/Web/app.css:41-57`
+- Test: `ClumsyPilot/tests/TrajectoryPlanningVisualizationVerificationHost/WebAssetChecks.cs:21-43`
+
+**Interfaces:**
+- Consumes: the existing `getBounds()` result and `#world-overlay.getBoundingClientRect()`.
+- Produces: `niceWorldStep(span, targetTicks)`, `worldMetrics(bounds)`, and `renderWorldCoordinates(bounds, metrics)`; later tasks consume `metrics.unitsPerPixel` for fixed-size markers.
+
+- [ ] **Step 1: Write failing embedded-asset checks**
+
+Add the following assertions in `WebAssetChecks.Run` after the existing `.world-current` check:
+
+```csharp
+Verification.True(css.Contains(".world-coordinate-grid"),
+    "overview exposes a metric grid semantic class");
+Verification.True(css.Contains(".world-axis-zero"),
+    "overview exposes a zero-axis semantic class");
+Verification.True(css.Contains(".world-axis-tick"),
+    "overview exposes coordinate tick semantics");
+Verification.True(css.Contains(".world-axis-label"),
+    "overview exposes coordinate axis-label semantics");
+Verification.True(js.Contains("function niceWorldStep("),
+    "overview selects readable metric tick steps");
+Verification.True(js.Contains("function worldMetrics("),
+    "overview derives stable world-to-screen metrics");
+Verification.True(js.Contains("function renderWorldCoordinates("),
+    "overview renders its own metric coordinate system");
+Verification.True(js.Contains("X (m)") && js.Contains("Y (m)"),
+    "overview labels both metric axes");
+```
+
+- [ ] **Step 2: Run the web asset host and verify failure**
+
+Run:
+
+```powershell
+dotnet run --project ClumsyPilot/tests/TrajectoryPlanningVisualizationVerificationHost/TrajectoryPlanningVisualizationVerificationHost.csproj
+```
+
+Expected: FAIL with `overview exposes a metric grid semantic class`.
+
+- [ ] **Step 3: Add world/screen metrics and coordinate rendering**
+
+Insert the following functions after `drawOccupancy` and before `worldPath` in `app.js`:
+
+```javascript
+  function niceWorldStep(span, targetTicks = 7) {
+    if (!finite(span) || span <= 0) return 1;
+    const rough = span / Math.max(2, targetTicks);
+    const magnitude = Math.pow(10, Math.floor(Math.log10(rough)));
+    const normalized = rough / magnitude;
+    const factor = normalized <= 1 ? 1 : normalized <= 2 ? 2 : normalized <= 5 ? 5 : 10;
+    return factor * magnitude;
+  }
+
+  function worldMetrics(bounds) {
+    const box = overlay.getBoundingClientRect();
+    const pixelWidth = box.width > 0 ? box.width : 800;
+    const pixelHeight = box.height > 0 ? box.height : 520;
+    const spanX = Math.max(bounds.xMax - bounds.xMin, 1e-9);
+    const spanY = Math.max(bounds.yMax - bounds.yMin, 1e-9);
+    return {
+      pixelWidth,
+      pixelHeight,
+      spanX,
+      spanY,
+      unitsPerPixel: Math.max(spanX / pixelWidth, spanY / pixelHeight, 1e-9)
+    };
+  }
+
+  function renderWorldCoordinates(bounds, metrics) {
+    const group = svg("g", { class: "world-coordinate-system", "aria-hidden": "true" });
+    const xStep = niceWorldStep(metrics.spanX, 8);
+    const yStep = niceWorldStep(metrics.spanY, 8);
+    const epsilon = Math.max(xStep, yStep) * 1e-9;
+    let count = 0;
+    for (let x = Math.ceil(bounds.xMin / xStep) * xStep; x <= bounds.xMax + epsilon && count < 100; x += xStep, count += 1) {
+      const normalized = Math.abs(x) < epsilon ? 0 : x;
+      group.append(svg("line", { x1: normalized, y1: -bounds.yMax, x2: normalized, y2: -bounds.yMin, class: "world-coordinate-grid" }));
+      const tick = svg("text", { x: normalized, y: -bounds.yMin - 7 * metrics.unitsPerPixel, class: "world-axis-tick", "font-size": 11 * metrics.unitsPerPixel, "text-anchor": "middle" });
+      tick.textContent = formatTick(normalized);
+      group.append(tick);
+    }
+    count = 0;
+    for (let y = Math.ceil(bounds.yMin / yStep) * yStep; y <= bounds.yMax + epsilon && count < 100; y += yStep, count += 1) {
+      const normalized = Math.abs(y) < epsilon ? 0 : y;
+      group.append(svg("line", { x1: bounds.xMin, y1: -normalized, x2: bounds.xMax, y2: -normalized, class: "world-coordinate-grid" }));
+      const tick = svg("text", { x: bounds.xMin + 6 * metrics.unitsPerPixel, y: -normalized - 3 * metrics.unitsPerPixel, class: "world-axis-tick", "font-size": 11 * metrics.unitsPerPixel, "text-anchor": "start" });
+      tick.textContent = formatTick(normalized);
+      group.append(tick);
+    }
+    if (bounds.xMin <= 0 && bounds.xMax >= 0)
+      group.append(svg("line", { x1: 0, y1: -bounds.yMax, x2: 0, y2: -bounds.yMin, class: "world-axis-zero" }));
+    if (bounds.yMin <= 0 && bounds.yMax >= 0)
+      group.append(svg("line", { x1: bounds.xMin, y1: 0, x2: bounds.xMax, y2: 0, class: "world-axis-zero" }));
+    const xLabel = svg("text", { x: bounds.xMax - 8 * metrics.unitsPerPixel, y: -bounds.yMin - 8 * metrics.unitsPerPixel, class: "world-axis-label", "font-size": 12 * metrics.unitsPerPixel, "text-anchor": "end" });
+    xLabel.textContent = "X (m)";
+    const yLabel = svg("text", { x: bounds.xMin + 8 * metrics.unitsPerPixel, y: -bounds.yMax + 16 * metrics.unitsPerPixel, class: "world-axis-label", "font-size": 12 * metrics.unitsPerPixel, "text-anchor": "start" });
+    yLabel.textContent = "Y (m)";
+    group.append(xLabel, yLabel);
+    overlay.append(group);
+  }
+```
+
+Replace the first statement sequence in `renderWorld` with:
+
+```javascript
+    const bounds = getBounds();
+    const metrics = worldMetrics(bounds);
+    drawOccupancy(bounds);
+    overlay.replaceChildren();
+    overlay.setAttribute("viewBox", `${bounds.xMin} ${-bounds.yMax} ${bounds.xMax - bounds.xMin} ${bounds.yMax - bounds.yMin}`);
+    overlay.setAttribute("preserveAspectRatio", "xMidYMid meet");
+    renderWorldCoordinates(bounds, metrics);
+```
+
+Add the following CSS after `.world-line`:
+
+```css
+.world-coordinate-grid { stroke: #dfe4e8; stroke-opacity: .62; stroke-width: .7; vector-effect: non-scaling-stroke; }
+.world-axis-zero { stroke: #7c8791; stroke-opacity: .72; stroke-width: 1.1; vector-effect: non-scaling-stroke; }
+.world-axis-tick { fill: #68737d; font-family: ui-monospace, Consolas, monospace; }
+.world-axis-label { fill: #48535d; font-family: "Microsoft YaHei", "Noto Sans CJK SC", sans-serif; font-weight: 600; }
+```
+
+- [ ] **Step 4: Run the web asset host and verify success**
+
+Run:
+
+```powershell
+dotnet run --project ClumsyPilot/tests/TrajectoryPlanningVisualizationVerificationHost/TrajectoryPlanningVisualizationVerificationHost.csproj
+```
+
+Expected: `PASS trajectory-planning-visualization`.
+
+- [ ] **Step 5: Commit the coordinate system**
+
+```powershell
+git add -- ClumsyPilot/TrajectoryPlanningVisualization/Web/app.js ClumsyPilot/TrajectoryPlanningVisualization/Web/app.css ClumsyPilot/tests/TrajectoryPlanningVisualizationVerificationHost/WebAssetChecks.cs
+git commit -m "feat: add metric axes to trajectory overview"
+```
+
+## Task 3: Fix Path Layering and Screen-Size Markers
+
+**Files:**
+- Modify: `ClumsyPilot/TrajectoryPlanningVisualization/Web/app.js:52-93`
+- Modify: `ClumsyPilot/TrajectoryPlanningVisualization/Web/app.css:1-9,41-57`
+- Test: `ClumsyPilot/tests/TrajectoryPlanningVisualizationVerificationHost/WebAssetChecks.cs:21-43`
+
+**Interfaces:**
+- Consumes: `worldMetrics(bounds).unitsPerPixel` from Task 2 and existing polyline/marker kinds.
+- Produces: `lineKind(line)`, `markerTransform(position, unitsPerPixel, headingRadians)`, and `appendWorldMarker(marker, frame, metrics)`; the current EM trajectory is rendered after every static/reference layer.
+
+- [ ] **Step 1: Add failing checks for fixed-size rendering and semantic layers**
+
+Add these assertions after the coordinate checks in `WebAssetChecks.Run`:
+
+```csharp
+Verification.True(css.Contains("--world-smoothed-path"),
+    "overview defines a dedicated smoothed-path color");
+Verification.True(css.Contains("--world-em-trajectory"),
+    "overview defines a dedicated EM-path color");
+Verification.True(css.Contains(".world-marker-shape"),
+    "overview marker shapes use a shared screen-space class");
+Verification.True(css.Contains(".marker-smooth-start"),
+    "overview styles the smoothed-path start marker");
+Verification.True(js.Contains("function markerTransform("),
+    "overview anchors fixed-size markers in world coordinates");
+Verification.True(js.Contains("function appendWorldMarker("),
+    "overview centralizes fixed-size marker rendering");
+Verification.True(!js.Contains("const corners = [[.38, .18]"),
+    "vehicle marker no longer uses a large world-size rectangle");
+Verification.True(!css.Contains(".marker-vehicle .vehicle-outline { fill: none; stroke: #20252b; stroke-width: .7; }"),
+    "vehicle outline no longer uses a world-scale heavy stroke");
+Verification.True(!css.Contains(".marker-vehicle .vehicle-heading { stroke: #20252b; stroke-width: .8; }"),
+    "vehicle marker no longer uses world-scale heavy strokes");
+```
+
+- [ ] **Step 2: Run the web asset host and verify failure**
+
+Run:
+
+```powershell
+dotnet run --project ClumsyPilot/tests/TrajectoryPlanningVisualizationVerificationHost/TrajectoryPlanningVisualizationVerificationHost.csproj
+```
+
+Expected: FAIL with `overview defines a dedicated smoothed-path color`.
+
+- [ ] **Step 3: Define path and marker visual variables**
+
+Add these variables to `:root` without changing the chart color variables:
+
+```css
+  --world-coarse-path: #7e8790;
+  --world-smoothed-path: #168b83;
+  --world-active-segment: #3f78a8;
+  --world-em-trajectory: #df6b1f;
+```
+
+Replace the existing world path and marker CSS rules with:
+
+```css
+.world-line { fill: none; vector-effect: non-scaling-stroke; }
+.world-static { stroke: #8d959d; stroke-opacity: .38; stroke-width: 1.4; }
+.world-future { stroke: #b6bec6; stroke-dasharray: 5 4; stroke-width: 1.2; }
+.world-active { stroke: var(--world-active-segment); stroke-width: 1.5; }
+.world-previous { stroke: #887493; stroke-opacity: .66; stroke-dasharray: 7 5; stroke-width: 2; }
+.world-coarse { stroke: var(--world-coarse-path); stroke-opacity: .40; stroke-dasharray: 7 5; stroke-width: 2; }
+.world-local-g2 { stroke: var(--world-smoothed-path); stroke-opacity: .65; stroke-width: 4; }
+.world-segment-active { stroke: var(--world-active-segment); stroke-opacity: .50; stroke-width: 1.5; }
+.world-direction-inactive { stroke: #aab2b9; stroke-opacity: .30; stroke-dasharray: 5 5; stroke-width: 1.1; }
+.world-current { stroke: var(--world-em-trajectory); stroke-opacity: .96; stroke-width: 2.4; }
+.world-marker-shape { vector-effect: non-scaling-stroke; }
+.world-marker-label { fill: #20252b; font: 11px/1.2 "Microsoft YaHei", "Noto Sans CJK SC", sans-serif; paint-order: stroke; stroke: rgba(255, 255, 255, .88); stroke-width: 3px; stroke-linejoin: round; }
+.world-marker { fill: #d87918; stroke: #ffffff; stroke-width: 1.4; }
+.marker-vehicle .vehicle-outline { fill: rgba(32, 37, 43, .16); stroke: #20252b; stroke-width: 1.5; }
+.marker-vehicle .vehicle-heading { stroke: #20252b; stroke-width: 1.5; stroke-linecap: round; vector-effect: non-scaling-stroke; }
+.marker-smooth-start { fill: #2f8f56; stroke: #ffffff; stroke-width: 1.5; }
+.marker-plan-start { fill: #ffffff; stroke: #2f8f56; stroke-width: 2; }
+.marker-gear-switch { fill: #d87918; stroke: #ffffff; stroke-width: 1.5; }
+.marker-final-goal { fill: #1769aa; stroke: #ffffff; stroke-width: 1.5; }
+.world-empty-state { fill: #66707a; font: 14px/1.2 "Microsoft YaHei", "Noto Sans CJK SC", sans-serif; }
+```
+
+- [ ] **Step 4: Replace world marker and layer rendering**
+
+Add the following functions after `worldPath`:
+
+```javascript
+  function lineKind(line) { return String(line && line.kind || "").toLowerCase(); }
+
+  function markerTransform(position, unitsPerPixel, headingRadians = 0) {
+    const headingDegrees = (finite(headingRadians) ? headingRadians : 0) * 180 / Math.PI;
+    return `translate(${position.x} ${-position.y}) rotate(${-headingDegrees}) scale(${unitsPerPixel})`;
+  }
+
+  function appendWorldMarker(marker, frame, metrics) {
+    if (!marker.position || !finite(marker.position.x) || !finite(marker.position.y)) return;
+    const kind = String(marker.kind || "").toLowerCase();
+    const pose = frame.vehiclePose;
+    const heading = kind === "vehicle" && pose && finite(pose.headingRadians) ? pose.headingRadians : 0;
+    const group = svg("g", {
+      class: `world-marker-group marker-${kind || "generic"}`,
+      transform: markerTransform(marker.position, metrics.unitsPerPixel, heading)
+    });
+    if (kind === "vehicle") {
+      group.append(svg("path", { d: "M -9 -5 L 5 -5 L 9 0 L 5 5 L -9 5 Z", class: "world-marker-shape vehicle-outline" }));
+      group.append(svg("line", { x1: -4, y1: 0, x2: 7, y2: 0, class: "vehicle-heading" }));
+    } else if (kind === "smooth-start") {
+      group.append(svg("circle", { cx: 0, cy: 0, r: 5, class: "world-marker-shape marker-smooth-start" }));
+    } else if (kind === "plan-start") {
+      group.append(svg("circle", { cx: 0, cy: 0, r: 5, class: "world-marker-shape marker-plan-start" }));
+    } else if (kind === "gear-switch" || kind === "gear-switch-end") {
+      group.append(svg("path", { d: "M 0 -6 L 6 0 L 0 6 L -6 0 Z", class: "world-marker-shape marker-gear-switch" }));
+    } else if (kind === "final-goal") {
+      group.append(svg("path", { d: "M -6 -6 L 6 -6 L 6 6 L -6 6 Z", class: "world-marker-shape marker-final-goal" }));
+    } else {
+      group.append(svg("path", { d: "M 0 -6 L 6 0 L 0 6 L -6 0 Z", class: "world-marker-shape world-marker" }));
+    }
+    overlay.append(group);
+    const labelY = kind === "plan-start" ? 17 : -9;
+    const labelGroup = svg("g", { transform: `translate(${marker.position.x} ${-marker.position.y}) scale(${metrics.unitsPerPixel})` });
+    const label = svg("text", { x: 10, y: labelY, class: "world-marker-label" });
+    label.textContent = marker.labelChinese || "";
+    labelGroup.append(label);
+    overlay.append(labelGroup);
+  }
+```
+
+Replace the complete `renderWorld` function with:
+
+```javascript
+  function renderWorld() {
+    const bounds = getBounds();
+    const metrics = worldMetrics(bounds);
+    drawOccupancy(bounds);
+    overlay.replaceChildren();
+    overlay.setAttribute("viewBox", `${bounds.xMin} ${-bounds.yMax} ${bounds.xMax - bounds.xMin} ${bounds.yMax - bounds.yMin}`);
+    overlay.setAttribute("preserveAspectRatio", "xMidYMid meet");
+    renderWorldCoordinates(bounds, metrics);
+    const snapshot = state.staticSnapshot || {};
+    const frame = state.frame || {};
+    const addLine = (line, css) => {
+      const path = worldPath(line.points);
+      if (path) overlay.append(svg("path", { d: path, class: "world-line " + css }));
+    };
+    const staticLines = safeArray(snapshot.staticPolylines);
+    staticLines.filter(line => lineKind(line) === "global" || lineKind(line) === "coarse")
+      .forEach(line => addLine(line, "world-coarse"));
+    staticLines.filter(line => lineKind(line).includes("local-g2") || lineKind(line).includes("g2"))
+      .forEach(line => addLine(line, "world-local-g2"));
+    staticLines.filter(line => lineKind(line) !== "global" && lineKind(line) !== "coarse" && !lineKind(line).includes("local-g2") && !lineKind(line).includes("g2"))
+      .forEach(line => addLine(line, "world-static"));
+    safeArray(snapshot.directionSegments).forEach(segment => addLine(segment,
+      segment.segmentIndex === frame.activeSegmentIndex ? "world-segment-active" : "world-direction-inactive"));
+    const dynamicLines = safeArray(frame.dynamicPolylines);
+    dynamicLines.filter(line => lineKind(line) === "active-segment")
+      .forEach(line => addLine(line, "world-segment-active"));
+    dynamicLines.filter(line => lineKind(line) === "previous" || line.lineStyle === 1)
+      .forEach(line => addLine(line, "world-previous"));
+    dynamicLines.filter(line => lineKind(line) !== "active-segment" && lineKind(line) !== "previous" && line.lineStyle !== 1)
+      .forEach(line => addLine(line, "world-current"));
+    const allLines = staticLines.concat(safeArray(snapshot.directionSegments), dynamicLines);
+    const hasPath = allLines.some(line => safeArray(line && line.points)
+      .some(point => point && finite(point.x) && finite(point.y)));
+    safeArray(snapshot.staticMarkers).concat(safeArray(frame.dynamicMarkers))
+      .forEach(marker => appendWorldMarker(marker, frame, metrics));
+    if (!hasPath) {
+      const emptyGroup = svg("g", { transform: `translate(${(bounds.xMin + bounds.xMax) / 2} ${-((bounds.yMin + bounds.yMax) / 2)}) scale(${metrics.unitsPerPixel})` });
+      const empty = svg("text", { x: 0, y: 0, class: "world-empty-state", "text-anchor": "middle" });
+      empty.textContent = "未收到 Local G2 路径";
+      emptyGroup.append(empty);
+      overlay.append(emptyGroup);
+    }
+  }
+```
+
+Add resize-aware redraw beside the existing window error listeners:
+
+```javascript
+  let overviewResizeFrame = 0;
+  window.addEventListener("resize", () => {
+    if (overviewResizeFrame || state.activeTab !== "overview" || !state.redrawEnabled.overview) return;
+    overviewResizeFrame = window.requestAnimationFrame(() => {
+      overviewResizeFrame = 0;
+      renderWorld();
+    });
+  });
+```
+
+- [ ] **Step 5: Run the web asset host and verify success**
+
+Run:
+
+```powershell
+dotnet run --project ClumsyPilot/tests/TrajectoryPlanningVisualizationVerificationHost/TrajectoryPlanningVisualizationVerificationHost.csproj
+```
+
+Expected: `PASS trajectory-planning-visualization`.
+
+- [ ] **Step 6: Commit fixed markers and path layering**
+
+```powershell
+git add -- ClumsyPilot/TrajectoryPlanningVisualization/Web/app.js ClumsyPilot/TrajectoryPlanningVisualization/Web/app.css ClumsyPilot/tests/TrajectoryPlanningVisualizationVerificationHost/WebAssetChecks.cs
+git commit -m "fix: clarify EM overview path layers"
+```
+
+## Task 4: Add a Data-Driven World Legend
+
+**Files:**
+- Modify: `ClumsyPilot/TrajectoryPlanningVisualization/Web/index.html:21-26`
+- Modify: `ClumsyPilot/TrajectoryPlanningVisualization/Web/app.js:7-17,52-94`
+- Modify: `ClumsyPilot/TrajectoryPlanningVisualization/Web/app.css:22-24,41-70`
+- Test: `ClumsyPilot/tests/TrajectoryPlanningVisualizationVerificationHost/WebAssetChecks.cs:16-43`
+- Test fixture: `ClumsyPilot/tests/TrajectoryPlanningVisualizationVerificationHost/SampleSnapshotFactory.cs:11-33`
+
+**Interfaces:**
+- Consumes: existing `LegendChinese`, `Kind`, `staticPolylines`, `directionSegments`, `dynamicPolylines`, `staticMarkers`, and `dynamicMarkers`.
+- Produces: `renderWorldLegend(snapshot, frame)` and `#world-legend`; entries are deduplicated by semantic key and only emitted when corresponding data exists.
+
+- [ ] **Step 1: Write failing legend asset checks**
+
+Add these assertions in `WebAssetChecks.Run` after the `world-overlay` assertion:
+
+```csharp
+Verification.True(html.Contains("id=\"world-legend\""),
+    "overview contains a screen-space legend host");
+Verification.True(html.Contains("aria-label=\"路径图例\""),
+    "overview legend has a Chinese accessible name");
+Verification.True(css.Contains(".world-legend"),
+    "overview legend has a screen-space visual container");
+Verification.True(css.Contains(".world-legend-swatch"),
+    "overview legend exposes semantic line and marker samples");
+Verification.True(js.Contains("function renderWorldLegend("),
+    "overview builds legend entries from current snapshot data");
+Verification.True(js.Contains("legendChinese"),
+    "overview reuses exported Chinese polyline legends");
+```
+
+Add these assertions in `BuildsDeterministicSmokeSnapshots` after creating `staticSnapshot`:
+
+```csharp
+Verification.True(staticSnapshot.StaticPolylines.Any(line => line.Kind == "coarse"),
+    "smoke snapshot exposes the coarse comparison path");
+Verification.True(staticSnapshot.StaticPolylines.Any(line => line.Kind == "local-g2"),
+    "smoke snapshot exposes the smoothed comparison path");
+Verification.True(staticSnapshot.StaticMarkers.Any(marker => marker.Kind == "smooth-start"),
+    "smoke snapshot exposes the smoothed-path start marker");
+```
+
+- [ ] **Step 2: Run the web asset host and verify failure**
+
+Run:
+
+```powershell
+dotnet run --project ClumsyPilot/tests/TrajectoryPlanningVisualizationVerificationHost/TrajectoryPlanningVisualizationVerificationHost.csproj
+```
+
+Expected: FAIL with `smoke snapshot exposes the coarse comparison path`; the legend assertions also remain red until Steps 3–6 are complete.
+
+- [ ] **Step 3: Add the accessible legend host**
+
+Add this element inside `.world-stack`, after `#world-overlay`:
+
+```html
+        <aside id="world-legend" class="world-legend" aria-label="路径图例" hidden></aside>
+```
+
+- [ ] **Step 4: Expand the deterministic smoke snapshot**
+
+Replace the single static `global` polyline in `SampleSnapshotFactory.CreateStaticSnapshot` with:
+
+```csharp
+new[]
+{
+    new VisualizationPolyline("coarse-path", "粗路径", "coarse", VisualizationLineStyle.Dashed,
+        Points((0d, 1d), (3d, 1.2d), (6d, 1.85d), (8d, 4.2d), (11d, 6d))),
+    new VisualizationPolyline("local-g2-path", "完整 Local G2 路径", "local-g2", VisualizationLineStyle.Solid,
+        Points((0d, 1d), (3d, 1d), (6d, 2d), (8d, 4d), (11d, 6d)))
+},
+```
+
+Add this marker as the first item in the static marker array:
+
+```csharp
+new VisualizationMarker("smooth-start", "smooth-start", "平滑路径起点", new VisualizationPoint(0d, 1d)),
+```
+
+- [ ] **Step 5: Implement data-driven legend population**
+
+Add the legend reference after the existing overlay reference:
+
+```javascript
+  const worldLegend = document.getElementById("world-legend");
+```
+
+Add this function after `appendWorldMarker`:
+
+```javascript
+  function renderWorldLegend(snapshot, frame) {
+    if (!worldLegend) return;
+    worldLegend.replaceChildren();
+    const staticLines = safeArray(snapshot.staticPolylines);
+    const directionSegments = safeArray(snapshot.directionSegments);
+    const dynamicLines = safeArray(frame.dynamicPolylines);
+    const markers = safeArray(snapshot.staticMarkers).concat(safeArray(frame.dynamicMarkers));
+    const entries = [];
+    const seen = new Set();
+    const add = (key, label, swatchClass) => {
+      if (seen.has(key)) return;
+      seen.add(key);
+      entries.push({ label, swatchClass });
+    };
+    const coarse = staticLines.find(line => lineKind(line) === "global" || lineKind(line) === "coarse");
+    const smooth = staticLines.find(line => lineKind(line).includes("local-g2") || lineKind(line).includes("g2"));
+    const active = dynamicLines.find(line => lineKind(line) === "active-segment");
+    const previous = dynamicLines.find(line => lineKind(line) === "previous" || line.lineStyle === 1);
+    const current = dynamicLines.find(line => lineKind(line) !== "active-segment" && lineKind(line) !== "previous" && line.lineStyle !== 1);
+    if (coarse) add("coarse", coarse.legendChinese || "粗路径", "legend-line legend-coarse");
+    if (smooth) add("smooth", smooth.legendChinese || "完整 Local G2 路径", "legend-line legend-smooth");
+    if (active || directionSegments.length)
+      add("segment", active && active.legendChinese || "当前方向段", "legend-line legend-segment");
+    if (previous) add("previous", previous.legendChinese || "上一条 EM 轨迹", "legend-line legend-previous");
+    if (current) add("current", current.legendChinese || "当前 EM 轨迹", "legend-line legend-current");
+    if (markers.some(marker => lineKind(marker) === "smooth-start"))
+      add("smooth-start", "平滑路径起点", "legend-marker legend-smooth-start");
+    if (markers.some(marker => lineKind(marker) === "plan-start"))
+      add("plan-start", "EM 规划起点", "legend-marker legend-plan-start");
+    if (markers.some(marker => lineKind(marker) === "vehicle"))
+      add("vehicle", "当前车辆", "legend-marker legend-vehicle");
+    if (markers.some(marker => lineKind(marker) === "gear-switch" || lineKind(marker) === "gear-switch-end"))
+      add("gear", "换向点 / s_end", "legend-marker legend-gear");
+    if (markers.some(marker => lineKind(marker) === "final-goal"))
+      add("goal", "平滑路径终点", "legend-marker legend-goal");
+    entries.forEach(entry => {
+      const item = element("div", "world-legend-item");
+      item.append(element("span", "world-legend-swatch " + entry.swatchClass),
+        element("span", "world-legend-label", entry.label));
+      worldLegend.append(item);
+    });
+    worldLegend.hidden = entries.length === 0;
+  }
+```
+
+Add this call in `renderWorld` after all markers are appended and before the empty-state branch:
+
+```javascript
+    renderWorldLegend(snapshot, frame);
+```
+
+- [ ] **Step 6: Style the legend with matching semantic samples**
+
+Add this CSS after the world marker rules:
+
+```css
+.world-legend { position: absolute; top: 14px; right: 14px; z-index: 3; display: grid; gap: 6px; min-width: 154px; max-width: min(260px, calc(100% - 28px)); padding: 10px 12px; border: 1px solid rgba(112, 123, 133, .38); border-radius: 6px; background: rgba(255, 255, 255, .88); box-shadow: 0 2px 10px rgba(32, 37, 43, .08); color: #36404a; font-size: 12px; pointer-events: none; backdrop-filter: blur(2px); }
+.world-legend[hidden] { display: none; }
+.world-legend-item { display: grid; grid-template-columns: 30px minmax(0, 1fr); align-items: center; gap: 8px; min-height: 16px; }
+.world-legend-swatch { display: block; justify-self: center; }
+.legend-line { width: 28px; height: 0; border-top-style: solid; }
+.legend-coarse { border-top: 2px dashed rgba(126, 135, 144, .62); }
+.legend-smooth { border-top: 4px solid rgba(22, 139, 131, .65); }
+.legend-segment { border-top: 2px solid rgba(63, 120, 168, .50); }
+.legend-previous { border-top: 2px dashed rgba(136, 116, 147, .72); }
+.legend-current { border-top: 3px solid rgba(223, 107, 31, .96); }
+.legend-marker { width: 11px; height: 11px; border: 1.5px solid #ffffff; box-shadow: 0 0 0 1px rgba(32, 37, 43, .22); }
+.legend-smooth-start { border-radius: 50%; background: #2f8f56; }
+.legend-plan-start { border: 2px solid #2f8f56; border-radius: 50%; background: #ffffff; }
+.legend-vehicle { width: 17px; height: 9px; border: 1.5px solid #20252b; border-radius: 2px; background: rgba(32, 37, 43, .16); }
+.legend-gear { transform: rotate(45deg); background: #d87918; }
+.legend-goal { background: #1769aa; }
+.world-legend-label { overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+```
+
+Replace the existing mobile media query with the following complete rule:
+
+```css
+@media (max-width: 720px) {
+  header { align-items: start; flex-direction: column; gap: 10px; }
+  nav, main, header { padding-left: 14px; padding-right: 14px; }
+  .world-stack { min-height: 360px; }
+  .world-legend { top: 8px; right: 8px; min-width: 138px; padding: 8px 9px; font-size: 11px; }
+  .config-entry { grid-template-columns: 1fr 1fr; }
+}
+```
+
+- [ ] **Step 7: Run focused and integration verification**
+
+Run:
+
+```powershell
+dotnet run --project ClumsyPilot/tests/TrajectoryPlanningVisualizationVerificationHost/TrajectoryPlanningVisualizationVerificationHost.csproj
+dotnet run --project ClumsyPilot/tests/EMPlannerVerificationHost/EMPlannerVerificationHost.csproj -- trajectory-observation
+dotnet build ClumsyPilot/ClumsyPilot.csproj -p:ExcludeLegacyAutoAvoidance=true --no-restore
+```
+
+Expected output contains:
+
+```text
+PASS trajectory-planning-visualization
+PASS trajectory-observation
+Build succeeded.
+```
+
+- [ ] **Step 8: Run the local visual smoke test**
+
+Run the sample server for 60 seconds:
+
+```powershell
+dotnet run --project ClumsyPilot/tests/TrajectoryPlanningVisualizationVerificationHost/TrajectoryPlanningVisualizationVerificationHost.csproj -- --smoke-seconds 60
+```
+
+Open the printed loopback URL and verify every item:
+
+- the vehicle is approximately 18–20 screen pixels long and does not cover the route;
+- X and Y retain equal spatial scale;
+- metric ticks, grid, `X (m)`, and `Y (m)` are readable;
+- coarse gray dashes, wide translucent teal smooth path, and narrow orange EM path remain visible where they overlap;
+- the legend matches only elements visible in the snapshot;
+- smoothed start, final goal, current vehicle, and EM plan-start markers are visible;
+- no browser console error or “页面绘图异常” status appears.
+
+- [ ] **Step 9: Check scoped diff hygiene and commit**
+
+Run:
+
+```powershell
+git diff --check -- ClumsyPilot/TrajectoryPlanningVisualization/Web/index.html ClumsyPilot/TrajectoryPlanningVisualization/Web/app.js ClumsyPilot/TrajectoryPlanningVisualization/Web/app.css ClumsyPilot/tests/TrajectoryPlanningVisualizationVerificationHost/WebAssetChecks.cs ClumsyPilot/tests/TrajectoryPlanningVisualizationVerificationHost/SampleSnapshotFactory.cs
+git status --short -- ClumsyPilot/TrajectoryPlanningVisualization/Web/index.html ClumsyPilot/TrajectoryPlanningVisualization/Web/app.js ClumsyPilot/TrajectoryPlanningVisualization/Web/app.css ClumsyPilot/tests/TrajectoryPlanningVisualizationVerificationHost/WebAssetChecks.cs ClumsyPilot/tests/TrajectoryPlanningVisualizationVerificationHost/SampleSnapshotFactory.cs
+git add -- ClumsyPilot/TrajectoryPlanningVisualization/Web/index.html ClumsyPilot/TrajectoryPlanningVisualization/Web/app.js ClumsyPilot/TrajectoryPlanningVisualization/Web/app.css ClumsyPilot/tests/TrajectoryPlanningVisualizationVerificationHost/WebAssetChecks.cs ClumsyPilot/tests/TrajectoryPlanningVisualizationVerificationHost/SampleSnapshotFactory.cs
+git commit -m "feat: add legend to EM path overview"
+```
+
+Expected: `git diff --check` emits no error, scoped status lists only the intended files before staging, and the commit contains only those five paths.
+
+## Final Verification
+
+After all task commits, run:
+
+```powershell
+dotnet run --project ClumsyPilot/tests/TrajectoryPlanningVisualizationVerificationHost/TrajectoryPlanningVisualizationVerificationHost.csproj
+dotnet run --project ClumsyPilot/tests/EMPlannerVerificationHost/EMPlannerVerificationHost.csproj -- trajectory-observation
+dotnet build ClumsyPilot/ClumsyPilot.csproj -p:ExcludeLegacyAutoAvoidance=true --no-restore
+git diff --check -- ClumsyPilot/ParkrobTrajplanner/tarjplanner_movementtest/TrajectoryObservationStaticSnapshotBuilder.cs ClumsyPilot/TrajectoryPlanningVisualization/Web/index.html ClumsyPilot/TrajectoryPlanningVisualization/Web/app.js ClumsyPilot/TrajectoryPlanningVisualization/Web/app.css ClumsyPilot/tests/EMPlannerVerificationHost/TrajectoryObservationVisualizationChecks.cs ClumsyPilot/tests/TrajectoryPlanningVisualizationVerificationHost/WebAssetChecks.cs ClumsyPilot/tests/TrajectoryPlanningVisualizationVerificationHost/SampleSnapshotFactory.cs
+```
+
+Expected: both verification hosts print their PASS lines, the main project reports `Build succeeded.`, and the scoped diff check produces no errors.