feat(export): make export and feature_trace answers actionable

.changepacks/changepack_log_export_actionability.json

@@ -0,0 +1,7 @@
+{
+  "changes": {
+    "crates/devup-mcp/Cargo.toml": "Minor"
+  },
+  "note": "Make export and feature_trace answers easier to act on: feature_trace reads an explicit componentPath first; a frame link with frameIds retries against its parent Section; add summary and reviewChecklist; add `fields` to narrow rawSnapshot/rawPayload/sourceMap; large debug outputs travel as resources under auto delivery; sourceMap entries carry the line-height calculation",
+  "date": "2026-10-02T12:41:10.3830670Z"
+}

crates/devup-mcp-devup-ui/src/codegen/component.rs

@@ -1220,6 +1220,7 @@ fn finalize_codegen_output(
         }
     }
     output.source_map.describe_properties(&output.tsx);
+    output.source_map.describe_conversions(snapshot);
     crate::provenance::attributes::audit_properties(snapshot, &mut output, options, root_id);
     output.fidelity_report = validate_fidelity(snapshot, root_id, &output)?;
     Ok(output)

crates/devup-mcp-devup-ui/src/provenance.rs

@@ -35,6 +35,10 @@ pub struct ProvenanceEntry {
     /// Internal renderer/validator bookkeeping; never a consumer-facing offset.
     #[serde(skip)]
     pub generated_range: Option<GeneratedRange>,
+    /// How a generated value was computed from the raw one, when that is not a
+    /// plain copy (e.g. a percent line-height written as px).
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub calculation: Option<String>,
     #[serde(default, skip_serializing_if = "Option::is_none")]
     pub generated_property: Option<String>,
     #[serde(default, skip_serializing_if = "Option::is_none")]
@@ -122,6 +126,50 @@ impl SourceMap {
         }
     }
 
+    /// Explain unit conversions the generator performs, so a reader can
+    /// reproduce `lineHeight="26px"` from the raw `{unit: PERCENT, value: 160}`.
+    pub(crate) fn describe_conversions(&mut self, snapshot: &devup_mcp_figma::Snapshot) {
+        for entry in &mut self.entries {
+            if entry.property.as_deref() != Some("lineHeight") {
+                continue;
+            }
+            let Some(node) = entry
+                .node_id
+                .as_deref()
+                .and_then(|id| snapshot.nodes.get(id))
+            else {
+                continue;
+            };
+            let view = node.typed_view();
+            let Some(line_height) = view.value("lineHeight") else {
+                continue;
+            };
+            if line_height["unit"] != "PERCENT" {
+                continue;
+            }
+            let percent =
+                (line_height["value"].as_f64().unwrap_or_default() * 100.0).round() / 100.0;
+            let bound = view
+                .value("boundVariables")
+                .and_then(|b| b.get("fontSize"))
+                .is_some();
+            entry.calculation = Some(
+                match (
+                    view.value("fontSize").and_then(serde_json::Value::as_f64),
+                    bound,
+                ) {
+                    (Some(size), false) => format!(
+                        "round(fontSize * percent / 100) = round({size} * {percent} / 100) = {}px",
+                        (size * percent / 100.0).round()
+                    ),
+                    _ => format!(
+                        "{percent}% kept as a percentage because fontSize is variable-bound or unknown"
+                    ),
+                },
+            );
+        }
+    }
+
     pub fn empty() -> Self {
         Self {
             version: 2,
@@ -1452,6 +1500,7 @@ pub(crate) fn finalize_tsx(
             continue;
         };
         entries.push(ProvenanceEntry {
+            calculation: None,
             generated_property: None,
             generated_range: Some(range.clone()),
             json_pointer: None,
@@ -1698,6 +1747,7 @@ pub(crate) fn finalize_tsx(
             && let Some((start, end)) = asset_prop_range(opening)
         {
             entries.push(ProvenanceEntry {
+                calculation: None,
                 generated_property: None,
                 generated_range: Some(GeneratedRange {
                     start: range.start + open_relative + start,
@@ -1827,6 +1877,7 @@ fn add_flattened_resource_entries(
                     let source = &tsx[range.start..range.end];
                     if let Some((start, end)) = asset_range_in_node_source(source) {
                         entries.push(ProvenanceEntry {
+                            calculation: None,
                             generated_property: None,
                             generated_range: Some(GeneratedRange {
                                 start: range.start + start,
@@ -2268,6 +2319,7 @@ fn generated_entry(
     resolution: &str,
 ) -> ProvenanceEntry {
     ProvenanceEntry {
+        calculation: None,
         generated_property: None,
         generated_range: Some(GeneratedRange { start, end }),
         json_pointer: None,
@@ -2335,3 +2387,51 @@ fn strip_markers(marked: &str) -> (String, Vec<(String, GeneratedRange)>) {
 pub(crate) fn json_pointer_segment(value: &str) -> String {
     value.replace('~', "~0").replace('/', "~1")
 }
+
+#[cfg(test)]
+mod line_height_calculation_tests {
+    use super::*;
+    use serde_json::json;
+
+    fn entry(node: &str) -> ProvenanceEntry {
+        ProvenanceEntry {
+            calculation: None,
+            generated_property: Some("lineHeight=\"26px\"".into()),
+            generated_range: None,
+            json_pointer: None,
+            node_id: Some(node.into()),
+            property: Some("lineHeight".into()),
+            variable_id: None,
+            style_id: None,
+            asset_id: None,
+            resolution: "raw-fallback".into(),
+        }
+    }
+
+    #[test]
+    fn percent_line_height_records_how_px_was_derived() {
+        let snapshot: devup_mcp_figma::Snapshot = serde_json::from_value(json!({
+            "fileKey":"k","roots":["t","b"],"diagnostics":[],"nodes":{
+                "t":{"id":"t","type":"TEXT","fields":{"fontSize":16.25,"lineHeight":{"unit":"PERCENT","value":160}}},
+                "b":{"id":"b","type":"TEXT","fields":{"fontSize":16,"lineHeight":{"unit":"PERCENT","value":150},
+                    "boundVariables":{"fontSize":{"id":"v"}}}}}
+        })).unwrap();
+        let mut map = SourceMap::empty();
+        map.entries = vec![entry("t"), entry("b")];
+        map.describe_conversions(&snapshot);
+        assert!(
+            map.entries[0]
+                .calculation
+                .as_deref()
+                .unwrap()
+                .ends_with("= 26px")
+        );
+        assert!(
+            map.entries[1]
+                .calculation
+                .as_deref()
+                .unwrap()
+                .contains("kept as a percentage")
+        );
+    }
+}

crates/devup-mcp-devup-ui/src/theme/devup_json.rs

@@ -328,6 +328,7 @@ pub fn generate_devup_json(
         }
         let category = if kind == "color" { "colors" } else { "length" };
         source_entries.push(ProvenanceEntry {
+            calculation: None,
             generated_property: None,
             generated_range: None,
             json_pointer: Some(format!(
@@ -450,6 +451,7 @@ pub fn generate_devup_json(
                     slots[level] = Some(typography_value(&style.value, &variable_names));
                 }
                 source_entries.push(ProvenanceEntry {
+                    calculation: None,
                     generated_property: None,
                     generated_range: None,
                     json_pointer: Some(format!(
@@ -473,6 +475,7 @@ pub fn generate_devup_json(
                     slots[level] = Some(shadow);
                 }
                 source_entries.push(ProvenanceEntry {
+                    calculation: None,
                     generated_property: None,
                     generated_range: None,
                     json_pointer: Some(format!(

crates/devup-mcp-devup-ui/tests/snapshots/wquw_151__wquw_151_proofread_source_map.snap

@@ -136,6 +136,7 @@ expression: output.source_map
       "resolution": "raw-fallback"
     },
     {
+      "calculation": "round(fontSize * percent / 100) = round(28 * 140 / 100) = 39px",
       "generatedProperty": "lineHeight=\"39px\"",
       "nodeId": "3879:35520",
       "property": "lineHeight",
@@ -290,6 +291,7 @@ expression: output.source_map
       "resolution": "raw-fallback"
     },
     {
+      "calculation": "round(fontSize * percent / 100) = round(16 * 160 / 100) = 26px",
       "generatedProperty": "lineHeight=\"26px\"",
       "nodeId": "3879:35523",
       "property": "lineHeight",
@@ -354,6 +356,7 @@ expression: output.source_map
       "resolution": "raw-fallback"
     },
     {
+      "calculation": "round(fontSize * percent / 100) = round(17 * 170 / 100) = 29px",
       "generatedProperty": "lineHeight=\"29px\"",
       "nodeId": "3879:35524",
       "property": "lineHeight",
@@ -528,6 +531,7 @@ expression: output.source_map
       "resolution": "raw-fallback"
     },
     {
+      "calculation": "round(fontSize * percent / 100) = round(16 * 160 / 100) = 26px",
       "generatedProperty": "lineHeight=\"26px\"",
       "nodeId": "3879:35528",
       "property": "lineHeight",
@@ -592,6 +596,7 @@ expression: output.source_map
       "resolution": "raw-fallback"
     },
     {
+      "calculation": "round(fontSize * percent / 100) = round(17 * 170 / 100) = 29px",
       "generatedProperty": "lineHeight=\"29px\"",
       "nodeId": "3879:35529",
       "property": "lineHeight",
@@ -844,6 +849,7 @@ expression: output.source_map
       "resolution": "raw-fallback"
     },
     {
+      "calculation": "round(fontSize * percent / 100) = round(15 * 160 / 100) = 24px",
       "generatedProperty": "lineHeight=\"24px\"",
       "nodeId": "3879:35535",
       "property": "lineHeight",
@@ -952,6 +958,7 @@ expression: output.source_map
       "resolution": "raw-fallback"
     },
     {
+      "calculation": "round(fontSize * percent / 100) = round(14 * 160 / 100) = 22px",
       "generatedProperty": "lineHeight=\"22px\"",
       "nodeId": "3879:35536",
       "property": "lineHeight",
@@ -1083,6 +1090,7 @@ expression: output.source_map
       "resolution": "raw-fallback"
     },
     {
+      "calculation": "round(fontSize * percent / 100) = round(16 * 160 / 100) = 26px",
       "generatedProperty": "lineHeight=\"26px\"",
       "nodeId": "3879:35538",
       "property": "lineHeight",
@@ -1141,6 +1149,7 @@ expression: output.source_map
       "resolution": "raw-fallback"
     },
     {
+      "calculation": "round(fontSize * percent / 100) = round(16 * 160 / 100) = 26px",
       "generatedProperty": "lineHeight=\"26px\"",
       "nodeId": "3879:35539",
       "property": "lineHeight",
@@ -1407,6 +1416,7 @@ expression: output.source_map
       "resolution": "raw-fallback"
     },
     {
+      "calculation": "round(fontSize * percent / 100) = round(16 * 160 / 100) = 26px",
       "generatedProperty": "lineHeight=\"26px\"",
       "nodeId": "I3879:35545;1690:32933",
       "property": "lineHeight",
@@ -1526,6 +1536,7 @@ expression: output.source_map
       "resolution": "raw-fallback"
     },
     {
+      "calculation": "round(fontSize * percent / 100) = round(14 * 160 / 100) = 22px",
       "generatedProperty": "lineHeight=\"22px\"",
       "nodeId": "I3879:35545;1690:32947",
       "property": "lineHeight",
@@ -1639,6 +1650,7 @@ expression: output.source_map
       "resolution": "raw-fallback"
     },
     {
+      "calculation": "round(fontSize * percent / 100) = round(22 * 140 / 100) = 31px",
       "generatedProperty": "lineHeight=\"31px\"",
       "nodeId": "3879:35547",
       "property": "lineHeight",
@@ -1776,6 +1788,7 @@ expression: output.source_map
       "resolution": "raw-fallback"
     },
     {
+      "calculation": "round(fontSize * percent / 100) = round(16 * 160 / 100) = 26px",
       "generatedProperty": "lineHeight=\"26px\"",
       "nodeId": "I3879:35549;1690:32933",
       "property": "lineHeight",
@@ -1895,6 +1908,7 @@ expression: output.source_map
       "resolution": "raw-fallback"
     },
     {
+      "calculation": "round(fontSize * percent / 100) = round(14 * 160 / 100) = 22px",
       "generatedProperty": "lineHeight=\"22px\"",
       "nodeId": "I3879:35549;1690:32947",
       "property": "lineHeight",
@@ -2008,6 +2022,7 @@ expression: output.source_map
       "resolution": "raw-fallback"
     },
     {
+      "calculation": "round(fontSize * percent / 100) = round(18 * 180 / 100) = 32px",
       "generatedProperty": "lineHeight=\"32px\"",
       "nodeId": "3879:35551",
       "property": "lineHeight",
@@ -2151,6 +2166,7 @@ expression: output.source_map
       "resolution": "raw-fallback"
     },
     {
+      "calculation": "round(fontSize * percent / 100) = round(16 * 160 / 100) = 26px",
       "generatedProperty": "lineHeight=\"26px\"",
       "nodeId": "I3879:35553;1690:32933",
       "property": "lineHeight",
@@ -2270,6 +2286,7 @@ expression: output.source_map
       "resolution": "raw-fallback"
     },
     {
+      "calculation": "round(fontSize * percent / 100) = round(14 * 160 / 100) = 22px",
       "generatedProperty": "lineHeight=\"22px\"",
       "nodeId": "I3879:35553;1690:32947",
       "property": "lineHeight",
@@ -2602,6 +2619,7 @@ expression: output.source_map
       "resolution": "raw-fallback"
     },
     {
+      "calculation": "round(fontSize * percent / 100) = round(16 * 160 / 100) = 26px",
       "generatedProperty": "lineHeight=\"26px\"",
       "nodeId": "I3879:35557;1690:32933",
       "property": "lineHeight",
@@ -2721,6 +2739,7 @@ expression: output.source_map
       "resolution": "raw-fallback"
     },
     {
+      "calculation": "round(fontSize * percent / 100) = round(14 * 160 / 100) = 22px",
       "generatedProperty": "lineHeight=\"22px\"",
       "nodeId": "I3879:35557;1690:32947",
       "property": "lineHeight",
@@ -2834,6 +2853,7 @@ expression: output.source_map
       "resolution": "raw-fallback"
     },
     {
+      "calculation": "round(fontSize * percent / 100) = round(18 * 180 / 100) = 32px",
       "generatedProperty": "lineHeight=\"32px\"",
       "nodeId": "3879:35559",
       "property": "lineHeight",
@@ -2977,6 +2997,7 @@ expression: output.source_map
       "resolution": "raw-fallback"
     },
     {
+      "calculation": "round(fontSize * percent / 100) = round(16 * 160 / 100) = 26px",
       "generatedProperty": "lineHeight=\"26px\"",
       "nodeId": "I3879:35561;1690:32933",
       "property": "lineHeight",
@@ -3096,6 +3117,7 @@ expression: output.source_map
       "resolution": "raw-fallback"
     },
     {
+      "calculation": "round(fontSize * percent / 100) = round(14 * 160 / 100) = 22px",
       "generatedProperty": "lineHeight=\"22px\"",
       "nodeId": "I3879:35561;1690:32947",
       "property": "lineHeight",
@@ -3209,6 +3231,7 @@ expression: output.source_map
       "resolution": "raw-fallback"
     },
     {
+      "calculation": "round(fontSize * percent / 100) = round(18 * 180 / 100) = 32px",
       "generatedProperty": "lineHeight=\"32px\"",
       "nodeId": "3879:35563",
       "property": "lineHeight",
@@ -3427,6 +3450,7 @@ expression: output.source_map
       "resolution": "raw-fallback"
     },
     {
+      "calculation": "round(fontSize * percent / 100) = round(18 * 170 / 100) = 31px",
       "generatedProperty": "lineHeight=\"31px\"",
       "nodeId": "3879:35566",
       "property": "lineHeight",
@@ -3532,6 +3556,7 @@ expression: output.source_map
       "resolution": "raw-fallback"
     },
     {
+      "calculation": "round(fontSize * percent / 100) = round(18 * 170 / 100) = 31px",
       "generatedProperty": "lineHeight=\"31px\"",
       "nodeId": "3879:35568",
       "property": "lineHeight",