@syntax-syllogism/flow-delta 0.3.0 → 0.5.0

package/README.md

@@ -5,10 +5,12 @@ A semantic, visual diff for Salesforce Flows: parse two versions of a
 interactive HTML artifact (plus `diff.json`) that shows added / deleted /
 modified / unchanged nodes and edges with per-property deltas.
 
-Inspired by Google's [Flow Lens](https://github.com/google/flow-lens), with
-a focus on making it work with GitLab's pipelines. We also opted for our own HTML output over plantuml, graphviz, or mermaid.
+Inspired by Google's [Flow Lens](https://github.com/google/flow-lens), with a
+focus on CI review workflows for GitLab merge requests and GitHub pull requests.
+We also opted for our own HTML output over plantuml, graphviz, or mermaid.
 
-[Sample Gitlab Project with artifacts](https://gitlab.com/j.p.richter/flow-delta-example/-/merge_requests/1)
+- [Sample GitLab project with artifacts](https://gitlab.com/j.p.richter/flow-delta-example/-/merge_requests/)
+- [Sample GitHub project with artifacts](https://github.com/Syntax-Syllogism/flow-delta-example/pulls)
 
 ## Usage
 
@@ -19,6 +21,19 @@ for full file-mode and git-mode options.
 npx tsx src/cli.ts --old before.flow-meta.xml --new after.flow-meta.xml --out ./flow-delta-out --json
 ```
 
+CI reporters read the generated `flow-delta-out/*.diff.json` files and post a
+sticky review comment:
+
+```bash
+flow-delta-gitlab --in flow-delta-out
+flow-delta-github --in flow-delta-out
+```
+
+The GitHub reporter can also consume `--artifact-urls <manifest.json>` for
+user-owned live-render links, such as R2 presigned URLs or Cloudflare
+Worker-backed URLs. See [docs/ci.md](docs/ci.md) for GitLab/GitHub workflow
+recipes, private-repo artifact viewing, and smoke harnesses.
+
 ## Development
 
 ```bash

package/dist/cli.js

@@ -628,6 +628,38 @@ function isPlainObject(value) {
   return Boolean(value) && typeof value === "object" && !Array.isArray(value);
 }
 
+// src/model/flow-header.ts
+import { Parser as Parser2 } from "xml2js";
+var FLOW_HEADER_KEYS = [
+  "status",
+  "processType",
+  "runInMode",
+  "apiVersion",
+  "triggerOrder",
+  "description",
+  "interviewLabel",
+  "isTemplate"
+];
+async function extractFlowHeader(xml) {
+  try {
+    const parsed = await new Parser2({ explicitArray: false }).parseStringPromise(xml);
+    const flow = parsed.Flow;
+    if (!flow) {
+      return {};
+    }
+    const header = {};
+    for (const key of FLOW_HEADER_KEYS) {
+      const value = flow[key];
+      if (value !== void 0 && (value === null || typeof value !== "object")) {
+        header[key] = String(value);
+      }
+    }
+    return header;
+  } catch {
+    return {};
+  }
+}
+
 // src/diff/deep-diff.ts
 function deepDiff(before, after, path = "") {
   if (Object.is(before, after)) {
@@ -685,21 +717,32 @@ function diffModel(oldModel, newModel) {
   const edgeIds = [.../* @__PURE__ */ new Set([...oldEdges.keys(), ...newEdges.keys()])].sort();
   const nodes = nodeIds.map((id) => classifyNode(oldNodes.get(id), newNodes.get(id)));
   const edges = edgeIds.map((id) => classifyEdge(oldEdges.get(id), newEdges.get(id)));
+  const flowChanges = diffFlowHeaders(oldModel, newModel);
   const summary = {
     addedNodes: nodes.filter((node) => node.status === "added").length,
     removedNodes: nodes.filter((node) => node.status === "deleted").length,
     modifiedNodes: nodes.filter((node) => node.status === "modified").length,
     unchangedNodes: nodes.filter((node) => node.status === "unchanged").length,
     addedEdges: edges.filter((edge) => edge.status === "added").length,
-    removedEdges: edges.filter((edge) => edge.status === "deleted").length
+    removedEdges: edges.filter((edge) => edge.status === "deleted").length,
+    changedFlowAttributes: flowChanges.length
   };
   return {
     flowName: selectFlowName(oldModel, newModel),
     summary,
+    ...flowChanges.length > 0 ? { flowChanges } : {},
     nodes,
     edges
   };
 }
+function diffFlowHeaders(oldModel, newModel) {
+  if (!oldModel.header || !newModel.header) {
+    return [];
+  }
+  const changes = deepDiff(oldModel.header, newModel.header);
+  const order = new Map(FLOW_HEADER_KEYS.map((key, index) => [key, index]));
+  return changes.sort((left, right) => (order.get(left.path) ?? 999) - (order.get(right.path) ?? 999));
+}
 function selectFlowName(oldModel, newModel) {
   if (newModel.nodes.length > 0 || newModel.edges.length > 0) {
     return newModel.flowName;
@@ -1516,6 +1559,7 @@ function snapshotPanelClientScript() {
 }
 
 // src/render/render-html.ts
+var THEME_STORAGE_KEY = "flow-delta-theme";
 function renderHtml(layout) {
   const data = {
     diff: layout.diff,
@@ -1532,25 +1576,72 @@ function renderHtml(layout) {
   const edgeStat = s.addedEdges + s.removedEdges > 0 ? `<span class="sep">\xB7</span><span class="stat edges">+${s.addedEdges}/\u2212${s.removedEdges} edges</span>` : "";
   const metaHtml = `${stat(s.addedNodes, "added", "added")}<span class="sep">\xB7</span>${stat(s.removedNodes, "deleted", "deleted")}<span class="sep">\xB7</span>${stat(s.modifiedNodes, "modified", "modified")}${edgeStat}`;
   const viewBox = fitViewBox(layout.width, layout.height);
+  const flowBannerHtml = renderFlowBanner(layout.diff.flowChanges);
   return `<!doctype html>
 <html lang="en">
 <head>
   <meta charset="utf-8" />
   <meta name="viewport" content="width=device-width, initial-scale=1" />
   <title>${escapeHtml2(layout.diff.flowName)}</title>
+  <script>
+    (() => {
+      const key = ${JSON.stringify(THEME_STORAGE_KEY)};
+      const allowed = new Set(["system", "light", "dark"]);
+      let theme = "system";
+      try {
+        const stored = localStorage.getItem(key);
+        if (allowed.has(stored)) theme = stored;
+      } catch {}
+      document.documentElement.dataset.theme = theme;
+    })();
+  </script>
   <style>
     :root {
       color-scheme: light;
       font-family: system-ui, -apple-system, "Segoe UI", sans-serif;
-      --bg: #f5f7fb; --surface: #ffffff; --border: #e3e8ef;
+      --bg: #f5f7fb; --surface: #ffffff; --surface-muted: #f8fafc; --surface-subtle: #fbfcfe; --surface-selected: #eff6ff; --border: #e3e8ef; --focus: #93c5fd;
       --text: #1f2937; --muted: #64748b; --faint: #94a3b8;
+      --node-text: #111827; --shadow: rgba(15, 23, 42, 0.12); --shadow-strong: rgba(15, 23, 42, 0.2);
+      --grid-dot: #dfe5ee; --canvas-start: #ffffff; --canvas-end: #f7f9fc;
       --added: #16a34a; --added-fill: #dcfce7;
       --deleted: #dc2626; --deleted-fill: #fee2e2;
       --modified: #d97706; --modified-fill: #fef3c7;
       --unchanged: #94a3b8; --unchanged-fill: #e9edf3;
       --edge: #64748b; --fault: #7c3aed;
+      --inserted-text: #14532d; --deleted-text: #7f1d1d; --deleted-line: rgba(127, 29, 29, 0.5);
       --panel-width: 34vw;
     }
+    @media (prefers-color-scheme: dark) {
+      :root:not([data-theme="light"]) {
+        color-scheme: dark;
+        --bg: #0f172a; --surface: #111827; --surface-muted: #1f2937; --surface-subtle: #172033; --surface-selected: #1e3a5f; --border: #334155; --focus: #60a5fa;
+        --text: #e5e7eb; --muted: #a5b4c7; --faint: #718096;
+        --node-text: #f8fafc; --shadow: rgba(0, 0, 0, 0.35); --shadow-strong: rgba(0, 0, 0, 0.55);
+        --grid-dot: #334155; --canvas-start: #0f172a; --canvas-end: #111827;
+        --added: #4ade80; --added-fill: #123f2a;
+        --deleted: #f87171; --deleted-fill: #4a1d23;
+        --modified: #fbbf24; --modified-fill: #46330d;
+        --unchanged: #64748b; --unchanged-fill: #263241;
+        --edge: #94a3b8; --fault: #c4b5fd;
+        --inserted-text: #bbf7d0; --deleted-text: #fecaca; --deleted-line: rgba(254, 202, 202, 0.55);
+      }
+    }
+    :root[data-theme="light"] {
+      color-scheme: light;
+    }
+    :root[data-theme="dark"] {
+      color-scheme: dark;
+      --bg: #0f172a; --surface: #111827; --surface-muted: #1f2937; --surface-subtle: #172033; --surface-selected: #1e3a5f; --border: #334155; --focus: #60a5fa;
+      --text: #e5e7eb; --muted: #a5b4c7; --faint: #718096;
+      --node-text: #f8fafc; --shadow: rgba(0, 0, 0, 0.35); --shadow-strong: rgba(0, 0, 0, 0.55);
+      --grid-dot: #334155; --canvas-start: #0f172a; --canvas-end: #111827;
+      --added: #4ade80; --added-fill: #123f2a;
+      --deleted: #f87171; --deleted-fill: #4a1d23;
+      --modified: #fbbf24; --modified-fill: #46330d;
+      --unchanged: #64748b; --unchanged-fill: #263241;
+      --edge: #94a3b8; --fault: #c4b5fd;
+      --inserted-text: #bbf7d0; --deleted-text: #fecaca; --deleted-line: rgba(254, 202, 202, 0.55);
+    }
     * { box-sizing: border-box; }
     body { margin: 0; height: 100vh; display: grid; grid-template-rows: auto 1fr; background: var(--bg); color: var(--text); font-size: 14px; line-height: 1.45; }
     header { display: flex; justify-content: space-between; gap: 16px; align-items: center; padding: 12px 20px; border-bottom: 1px solid var(--border); background: var(--surface); }
@@ -1566,7 +1657,7 @@ function renderHtml(layout) {
     .filters { display: flex; gap: 8px; flex-wrap: wrap; justify-content: flex-end; }
     .filters button {
       border: 1px solid var(--border);
-      background: #f8fafc;
+      background: var(--surface-muted);
       color: var(--muted);
       padding: 6px 11px;
       border-radius: 999px;
@@ -1577,15 +1668,19 @@ function renderHtml(layout) {
       transition: background-color 0.15s ease, border-color 0.15s ease, color 0.15s ease, box-shadow 0.15s ease;
     }
     .filters button.active {
-      background: #eff6ff;
-      border-color: #93c5fd;
+      background: var(--surface-selected);
+      border-color: var(--focus);
       color: var(--text);
       box-shadow: 0 0 0 1px rgba(59, 130, 246, 0.12);
     }
     .filters button:focus-visible {
-      outline: 2px solid #93c5fd;
+      outline: 2px solid var(--focus);
       outline-offset: 2px;
     }
+    .theme-toggle { display: inline-flex; padding: 2px; border: 1px solid var(--border); border-radius: 999px; background: var(--surface-muted); }
+    .theme-toggle button { border: 0; border-radius: 999px; background: transparent; color: var(--muted); padding: 4px 9px; font: inherit; font-size: 11.5px; font-weight: 650; cursor: pointer; }
+    .theme-toggle button[aria-pressed="true"] { background: var(--surface); color: var(--text); box-shadow: 0 1px 3px var(--shadow); }
+    .theme-toggle button:focus-visible { outline: 2px solid var(--focus); outline-offset: 2px; }
     .legend { display: flex; gap: 14px; font-size: 12px; flex-wrap: wrap; color: var(--muted); }
     .legend span::before { content: ""; display: inline-block; width: 9px; height: 9px; border-radius: 2px; margin-right: 6px; vertical-align: 0; }
     .legend .added::before { background: var(--added); }
@@ -1598,8 +1693,8 @@ function renderHtml(layout) {
     svg {
       width: 100%; height: 100%; display: block;
       background:
-        radial-gradient(circle, #dfe5ee 1px, transparent 1.4px) -11px -11px / 22px 22px,
-        linear-gradient(#ffffff, #f7f9fc);
+        radial-gradient(circle, var(--grid-dot) 1px, transparent 1.4px) -11px -11px / 22px 22px,
+        linear-gradient(var(--canvas-start), var(--canvas-end));
     }
     .panel { position: relative; min-width: 0; border-left: 1px solid var(--border); background: var(--surface); padding: 20px; overflow-y: auto; overflow-x: hidden; }
     body.panel-collapsed .panel { padding: 0; border-left: 0; overflow: hidden; }
@@ -1607,24 +1702,24 @@ function renderHtml(layout) {
     /* drag-to-resize handle on the panel's left edge */
     .panel-resizer { position: absolute; left: 0; top: 0; bottom: 0; width: 9px; transform: translateX(-50%); cursor: col-resize; z-index: 6; touch-action: none; }
     .panel-resizer::before { content: ""; position: absolute; left: 50%; top: 0; bottom: 0; width: 1px; background: var(--border); transform: translateX(-50%); transition: background-color 0.12s ease, width 0.12s ease; }
-    .panel-resizer:hover::before, .panel-resizer.dragging::before { background: #93c5fd; width: 3px; }
+    .panel-resizer:hover::before, .panel-resizer.dragging::before { background: var(--focus); width: 3px; }
     body.panel-collapsed .panel-resizer { display: none; }
     .panel-head { display: flex; align-items: flex-start; gap: 8px; }
     .panel-head h2 { flex: 1; min-width: 0; }
-    .panel-toggle, .panel-reopen { border: 1px solid var(--border); background: #f8fafc; color: var(--muted); border-radius: 7px; cursor: pointer; font: inherit; line-height: 1; }
+    .panel-toggle, .panel-reopen { border: 1px solid var(--border); background: var(--surface-muted); color: var(--muted); border-radius: 7px; cursor: pointer; font: inherit; line-height: 1; }
     .panel-toggle { flex: none; width: 26px; height: 26px; font-size: 16px; display: grid; place-items: center; }
-    .panel-toggle:hover, .panel-reopen:hover { color: var(--text); border-color: #93c5fd; background: #eff6ff; }
-    .panel-toggle:focus-visible, .panel-reopen:focus-visible { outline: 2px solid #93c5fd; outline-offset: 2px; }
+    .panel-toggle:hover, .panel-reopen:hover { color: var(--text); border-color: var(--focus); background: var(--surface-selected); }
+    .panel-toggle:focus-visible, .panel-reopen:focus-visible { outline: 2px solid var(--focus); outline-offset: 2px; }
     /* floating tab to reopen the panel once collapsed */
-    .panel-reopen { display: none; position: absolute; top: 14px; right: 14px; z-index: 7; padding: 7px 12px; font-size: 12px; font-weight: 600; box-shadow: 0 1px 3px rgba(15, 23, 42, 0.12); }
+    .panel-reopen { display: none; position: absolute; top: 14px; right: 14px; z-index: 7; padding: 7px 12px; font-size: 12px; font-weight: 600; box-shadow: 0 1px 3px var(--shadow); }
     body.panel-collapsed .panel-reopen { display: inline-flex; align-items: center; gap: 6px; }
     .panel h2 { margin: 0 0 8px; font-size: 15px; font-weight: 650; letter-spacing: -0.01em; }
-    .panel .badge { display: inline-block; padding: 3px 9px; border-radius: 999px; font-size: 11px; font-weight: 600; letter-spacing: 0.03em; background: #eef1f6; color: var(--muted); margin-bottom: 16px; }
+    .panel .badge { display: inline-block; padding: 3px 9px; border-radius: 999px; font-size: 11px; font-weight: 600; letter-spacing: 0.03em; background: var(--unchanged-fill); color: var(--muted); margin-bottom: 16px; }
     .panel.added .badge { background: var(--added-fill); color: var(--added); }
     .panel.deleted .badge { background: var(--deleted-fill); color: var(--deleted); }
     .panel.modified .badge { background: var(--modified-fill); color: var(--modified); }
     .panel .empty { color: var(--muted); font-size: 13px; }
-    .detail-section { margin: 0 0 12px; border: 1px solid var(--border); border-radius: 8px; background: #fbfcfe; overflow: hidden; }
+    .detail-section { margin: 0 0 12px; border: 1px solid var(--border); border-radius: 8px; background: var(--surface-subtle); overflow: hidden; }
     .detail-section.snapshot-section { border-left-width: 3px; }
     .detail-section.snapshot-section.added { border-left-color: rgba(22, 163, 74, 0.5); }
     .detail-section.snapshot-section.deleted { border-left-color: rgba(220, 38, 38, 0.45); }
@@ -1640,8 +1735,8 @@ function renderHtml(layout) {
     .change-kind.removed { color: var(--deleted); background: var(--deleted-fill); }
     /* git-diff value grammar */
     .val { font-family: ui-monospace, "SF Mono", Menlo, Consolas, monospace; font-size: 12px; border-radius: 4px; padding: 1px 5px; overflow-wrap: anywhere; }
-    .val.ins { color: #14532d; background: var(--added-fill); }
-    .val.del { color: #7f1d1d; background: var(--deleted-fill); text-decoration: line-through; text-decoration-color: rgba(127, 29, 29, 0.5); }
+    .val.ins { color: var(--inserted-text); background: var(--added-fill); }
+    .val.del { color: var(--deleted-text); background: var(--deleted-fill); text-decoration: line-through; text-decoration-color: var(--deleted-line); }
     .val.faint { color: var(--muted); background: transparent; padding-left: 0; }
     .val.one-sided { color: var(--text); background: transparent; padding-left: 0; }
     .val em { font-style: normal; color: var(--faint); }
@@ -1678,6 +1773,41 @@ function renderHtml(layout) {
     .group-head { display: flex; align-items: center; gap: 7px; margin-bottom: 8px; }
     .group-label { font-weight: 700; font-size: 12.5px; }
     .outcome-group .changes { margin-bottom: 8px; }
+    /* Flow-level changes: a floating tab over the canvas's top-left corner,
+       styled to match .panel-reopen's collapsed-state language (same surface,
+       border, radius, shadow) so there's one disclosure idiom in the artifact
+       instead of two. It reserves no layout row. */
+    .flow-tab {
+      position: absolute; top: 14px; left: 14px; z-index: 6;
+      display: inline-flex; align-items: center; gap: 7px;
+      border: 1px solid var(--border); background: var(--surface-muted); color: var(--muted);
+      border-radius: 7px; padding: 7px 12px; font: inherit; font-size: 12px; font-weight: 600; line-height: 1;
+      box-shadow: 0 1px 3px var(--shadow); cursor: pointer;
+    }
+    .flow-tab:hover { color: var(--text); border-color: var(--focus); background: var(--surface-selected); }
+    .flow-tab:focus-visible { outline: 2px solid var(--focus); outline-offset: 2px; }
+    .flow-tab .flow-tab-dot { width: 6px; height: 6px; border-radius: 50%; background: var(--modified); flex: none; }
+    .flow-tab.deactivated .flow-tab-dot { background: var(--deleted); }
+    .flow-tab.activated .flow-tab-dot { background: var(--added); }
+    .flow-tab .flow-tab-chev { font-size: 9px; opacity: 0.75; transition: transform 0.12s ease; }
+    .flow-tab[aria-expanded="true"] .flow-tab-chev { transform: rotate(180deg); }
+    .flow-popover {
+      position: absolute; top: 14px; left: 14px; z-index: 6; width: min(300px, calc(100% - 28px));
+      background: var(--surface); border: 1px solid var(--border); border-radius: 10px;
+      box-shadow: 0 16px 40px -12px var(--shadow-strong); overflow: hidden;
+    }
+    .flow-popover[hidden] { display: none; }
+    .flow-popover-head { padding: 10px 12px; border-bottom: 1px solid var(--border); background: var(--surface-muted); font-size: 12px; font-weight: 650; }
+    .flow-popover-body { padding: 12px; max-height: 60vh; overflow: auto; }
+    .flow-banner-callout { margin-bottom: 8px; font-weight: 750; }
+    .flow-banner-callout.deactivated { color: var(--deleted); }
+    .flow-banner-callout.activated { color: var(--added); }
+    .flow-banner-callout.neutral { color: var(--modified); }
+    .flow-banner-list { display: grid; gap: 7px; }
+    .flow-change-row { display: grid; grid-template-columns: minmax(90px, 120px) minmax(0, 1fr); align-items: start; gap: 10px; }
+    .flow-change-row + .flow-change-row { margin-top: 7px; }
+    .flow-change-label { color: var(--muted); font-size: 12px; font-weight: 700; }
+    .flow-change-value { min-width: 0; max-height: 180px; overflow: auto; }
     .edge { fill: none; }
     .edge.unchanged { stroke-width: 1.4; opacity: 0.55; }
     .edge.normal.unchanged { stroke: var(--edge); marker-end: url(#arrow-normal); }
@@ -1688,26 +1818,26 @@ function renderHtml(layout) {
     #arrow-fault path { fill: var(--fault); }
     #arrow-added path { fill: var(--added); }
     #arrow-deleted path { fill: var(--deleted); }
-    .node rect { rx: 11; ry: 11; stroke-width: 1.75; filter: drop-shadow(0 1px 2px rgba(15, 23, 42, 0.08)); }
+    .node rect { rx: 11; ry: 11; stroke-width: 1.75; filter: drop-shadow(0 1px 2px var(--shadow)); }
     .node { cursor: pointer; }
-    .node text { font-size: 12px; fill: #111827; pointer-events: none; }
+    .node text { font-size: 12px; fill: var(--node-text); pointer-events: none; }
     .node.added rect { fill: var(--added-fill); stroke: var(--added); }
     .node.deleted rect { fill: var(--deleted-fill); stroke: var(--deleted); }
     .node.modified rect { fill: var(--modified-fill); stroke: var(--modified); }
     .node.unchanged rect { fill: var(--unchanged-fill); stroke: var(--unchanged); }
-    .node.selected rect { stroke-width: 3; filter: drop-shadow(0 2px 6px rgba(15, 23, 42, 0.18)); }
+    .node.selected rect { stroke-width: 3; filter: drop-shadow(0 2px 6px var(--shadow-strong)); }
     .node-label { white-space: pre; }
     /* Type-based styling \u2014 SHAPE & stroke pattern only. Status (added/deleted/
        modified/unchanged) remains the sole authority on fill/stroke COLOR, so
        the legend stays reliable. Start/end stand out via a pill shape, heavier
        stroke, and a neutral emphasis halo \u2014 never via a status-like color. */
-    .node.type-start rect, .node.type-end rect { rx: 24; ry: 24; stroke-width: 2.5; filter: drop-shadow(0 0 0 3px rgba(15, 23, 42, 0.16)) drop-shadow(0 1px 3px rgba(15, 23, 42, 0.18)); }
+    .node.type-start rect, .node.type-end rect { rx: 24; ry: 24; stroke-width: 2.5; filter: drop-shadow(0 0 0 3px var(--shadow)) drop-shadow(0 1px 3px var(--shadow-strong)); }
     .node.type-recordLookup rect, .node.type-recordCreate rect, .node.type-recordUpdate rect, .node.type-recordDelete rect { rx: 4; ry: 4; }
     .node.type-screen rect { rx: 6; ry: 6; }
     .node.type-subflow rect { stroke-width: 2.5; }
     .node.type-loop rect { stroke-dasharray: 2 3; }
     .node.type-wait rect { stroke-dasharray: 4 4; }
-    .node.selected.type-start rect, .node.selected.type-end rect { stroke-width: 3.5; filter: drop-shadow(0 0 0 5px rgba(15, 23, 42, 0.22)) drop-shadow(0 2px 6px rgba(15, 23, 42, 0.2)); }
+    .node.selected.type-start rect, .node.selected.type-end rect { stroke-width: 3.5; filter: drop-shadow(0 0 0 5px var(--shadow-strong)) drop-shadow(0 2px 6px var(--shadow-strong)); }
     @media (max-width: 1000px) {
       .panel { padding: 16px; }
     }
@@ -1720,6 +1850,11 @@ function renderHtml(layout) {
       <div class="meta">${metaHtml}</div>
     </div>
     <div class="header-actions">
+      <div class="theme-toggle" role="group" aria-label="Color theme">
+        <button type="button" data-theme-choice="system" aria-pressed="true">System</button>
+        <button type="button" data-theme-choice="light" aria-pressed="false">Light</button>
+        <button type="button" data-theme-choice="dark" aria-pressed="false">Dark</button>
+      </div>
       <div class="filters" role="group" aria-label="Diff view filters">
         <button type="button" class="active" data-view-mode="all">All</button>
         <button type="button" data-view-mode="after">After</button>
@@ -1736,6 +1871,7 @@ function renderHtml(layout) {
   </header>
   <main>
     <div class="canvas">
+      ${flowBannerHtml}
       <svg id="flow-svg" viewBox="${viewBox}" preserveAspectRatio="xMidYMid meet" role="img" aria-label="Flow diff">
         <defs>
           <marker id="arrow-normal" markerWidth="8" markerHeight="8" refX="7" refY="4" orient="auto" markerUnits="userSpaceOnUse">
@@ -1777,12 +1913,46 @@ function renderHtml(layout) {
     const panelBadge = document.getElementById("panel-badge");
     const panelBody = document.getElementById("panel-body");
     const filterButtons = [...document.querySelectorAll(".filters button")];
+    const themeButtons = [...document.querySelectorAll(".theme-toggle button")];
     const nodesById = new Map(DATA.nodes.map((node) => [node.id, node]));
     const nodeElements = new Map([...document.querySelectorAll(".node")].map((node) => [node.dataset.nodeId, node]));
     const edgeElements = new Map([...document.querySelectorAll(".edge")].map((edge) => [edge.dataset.edgeId, edge]));
+    const flowTab = document.getElementById("flow-tab");
+    const flowPopover = document.getElementById("flow-popover");
+    function closeFlowPopover() {
+      if (!flowTab || !flowPopover || flowPopover.hidden) return;
+      flowTab.setAttribute("aria-expanded", "false");
+      flowPopover.hidden = true;
+    }
     let viewBox = svg.viewBox.baseVal;
     let dragStart = null;
     let selectedNodeId = null;
+    const THEME_STORAGE_KEY = ${JSON.stringify(THEME_STORAGE_KEY)};
+    const VALID_THEMES = new Set(["system", "light", "dark"]);
+
+    function readStoredTheme() {
+      try {
+        const stored = localStorage.getItem(THEME_STORAGE_KEY);
+        return VALID_THEMES.has(stored) ? stored : "system";
+      } catch {
+        return "system";
+      }
+    }
+
+    function persistTheme(theme) {
+      try {
+        localStorage.setItem(THEME_STORAGE_KEY, theme);
+      } catch {}
+    }
+
+    function applyTheme(theme) {
+      const next = VALID_THEMES.has(theme) ? theme : "system";
+      document.documentElement.dataset.theme = next;
+      themeButtons.forEach((button) => {
+        const active = button.dataset.themeChoice === next;
+        button.setAttribute("aria-pressed", active ? "true" : "false");
+      });
+    }
 
     function isNodeVisible(node, mode) {
       if (mode === "after") return node.status !== "deleted";
@@ -1997,6 +2167,7 @@ function renderHtml(layout) {
     document.querySelectorAll(".node").forEach((node) => {
       node.addEventListener("click", (event) => {
         event.stopPropagation();
+        closeFlowPopover();
         selectNode(node.dataset.nodeId);
       });
     });
@@ -2035,6 +2206,14 @@ function renderHtml(layout) {
       });
     });
 
+    themeButtons.forEach((button) => {
+      button.addEventListener("click", () => {
+        const theme = button.dataset.themeChoice;
+        applyTheme(theme);
+        persistTheme(theme);
+      });
+    });
+
     // Panel: collapse to focus on the canvas, and drag the left edge to resize.
     const panelToggle = document.getElementById("panel-toggle");
     const panelReopen = document.getElementById("panel-reopen");
@@ -2068,11 +2247,91 @@ function renderHtml(layout) {
       panelResizer.addEventListener("pointercancel", endResize);
     }
 
+    // Flow-level changes tab: floats over the canvas, opens a popover on click.
+    if (flowTab && flowPopover) {
+      flowTab.addEventListener("click", (event) => {
+        event.stopPropagation();
+        const open = flowPopover.hidden;
+        flowTab.setAttribute("aria-expanded", open ? "true" : "false");
+        flowPopover.hidden = !open;
+      });
+      document.addEventListener("click", (event) => {
+        if (!flowPopover.hidden && !flowPopover.contains(event.target)) {
+          closeFlowPopover();
+        }
+      });
+      document.addEventListener("keydown", (event) => {
+        if (event.key === "Escape" && !flowPopover.hidden) {
+          closeFlowPopover();
+          flowTab.focus();
+        }
+      });
+    }
+
+    applyTheme(readStoredTheme());
     applyView("all");
   </script>
 </body>
 </html>`;
 }
+function renderFlowBanner(changes) {
+  if (!changes || changes.length === 0) {
+    return "";
+  }
+  const statusChange = changes.find((change) => change.path === "status");
+  const kind = statusChange ? getStatusKind(statusChange.before, statusChange.after) : "neutral";
+  const callout = statusChange ? renderStatusCallout(statusChange.before, statusChange.after, kind) : "";
+  const count = changes.length;
+  const tabLabel = statusChange && kind !== "neutral" ? `${kind === "deactivated" ? "Deactivated" : "Activated"}${count > 1 ? ` \xB7 ${count} changes` : ""}` : `${count} flow-level ${count === 1 ? "change" : "changes"}`;
+  return `<button type="button" id="flow-tab" class="flow-tab ${kind}" aria-expanded="false" aria-controls="flow-popover">
+    <span class="flow-tab-dot"></span>${escapeHtml2(tabLabel)}<span class="flow-tab-chev">\u25BE</span>
+  </button>
+  <div id="flow-popover" class="flow-popover" role="region" aria-label="Flow-level changes" hidden>
+    <div class="flow-popover-head">Flow-level changes</div>
+    <div class="flow-popover-body">
+      ${callout}
+      <div class="flow-banner-list">
+        ${changes.map((change) => `<div class="flow-change-row">
+          <div class="flow-change-label">${escapeHtml2(humanizePath(change.path))}</div>
+          <div class="flow-change-value">${renderValueDelta(change.before, change.after)}</div>
+        </div>`).join("")}
+      </div>
+    </div>
+  </div>`;
+}
+function getStatusKind(before, after) {
+  const beforeText = String(before);
+  const afterText = String(after);
+  if (beforeText === "Active" && afterText !== "Active") return "deactivated";
+  if (beforeText !== "Active" && afterText === "Active") return "activated";
+  return "neutral";
+}
+function renderStatusCallout(before, after, kind) {
+  const beforeText = String(before);
+  const afterText = String(after);
+  if (kind === "deactivated") {
+    return `<div class="flow-banner-callout deactivated">Deactivated (${escapeHtml2(beforeText)} -> ${escapeHtml2(afterText)})</div>`;
+  }
+  if (kind === "activated") {
+    return `<div class="flow-banner-callout activated">Activated (${escapeHtml2(beforeText)} -> ${escapeHtml2(afterText)})</div>`;
+  }
+  return `<div class="flow-banner-callout neutral">Status: ${escapeHtml2(beforeText)} -> ${escapeHtml2(afterText)}</div>`;
+}
+function renderValueDelta(before, after) {
+  if (before === void 0) {
+    return `<span class="val ins">${escapeHtml2(formatValue(after))}</span>`;
+  }
+  if (after === void 0) {
+    return `<span class="val del">${escapeHtml2(formatValue(before))}</span>`;
+  }
+  return `<span class="val del">${escapeHtml2(formatValue(before))}</span><span class="arrow">-></span><span class="val ins">${escapeHtml2(formatValue(after))}</span>`;
+}
+function formatValue(value) {
+  if (value === void 0) {
+    return "(missing)";
+  }
+  return String(value);
+}
 function fitViewBox(contentWidth, contentHeight) {
   const minWidth = 720;
   const minHeight = 540;
@@ -2236,8 +2495,10 @@ async function main(argv = process.argv.slice(2)) {
   }
 }
 async function runFileMode(oldPath, newPath, outDir, writeJson) {
-  const oldModel = buildModel(await parseXml(readFlowFromFile(oldPath)));
-  const newModel = buildModel(await parseXml(readFlowFromFile(newPath)));
+  const oldXml = readFlowFromFile(oldPath);
+  const newXml = readFlowFromFile(newPath);
+  const oldModel = await buildModelWithHeader(oldXml);
+  const newModel = await buildModelWithHeader(newXml);
   await writeArtifacts(oldModel, newModel, outDir, writeJson);
 }
 async function runGitMode(repo, from, to, pattern, outDir, writeJson, changedOnly) {
@@ -2247,8 +2508,8 @@ async function runGitMode(repo, from, to, pattern, outDir, writeJson, changedOnl
     try {
       const oldXml = readFlowFromGit(repo, from, filePath);
       const newXml = readFlowFromGit(repo, to, filePath);
-      const oldModel = oldXml ? buildModel(await parseXml(oldXml)) : buildEmptyModel();
-      const newModel = newXml ? buildModel(await parseXml(newXml)) : buildEmptyModel();
+      const oldModel = oldXml ? await buildModelWithHeader(oldXml) : buildEmptyModel();
+      const newModel = newXml ? await buildModelWithHeader(newXml) : buildEmptyModel();
       await writeArtifacts(oldModel, newModel, outDir, writeJson, filePath);
     } catch (error) {
       hadFailure = true;
@@ -2263,6 +2524,11 @@ async function parseXml(xml) {
   const parser = new FlowParser(xml);
   return parser.generateFlowDefinition();
 }
+async function buildModelWithHeader(xml) {
+  const model = buildModel(await parseXml(xml));
+  model.header = await extractFlowHeader(xml);
+  return model;
+}
 function buildEmptyModel() {
   return {
     flowName: "(unknown)",
@@ -2281,9 +2547,15 @@ async function writeArtifacts(oldModel, newModel, outDir, writeJson, sourcePath)
     writeFileSync(join(outDir, `${fileStem}.diff.json`), JSON.stringify(diff, null, 2), "utf8");
   }
   console.log(
-    `${diff.flowName}: nodes ${diff.summary.addedNodes} added, ${diff.summary.removedNodes} deleted, ${diff.summary.modifiedNodes} modified; edges ${diff.summary.addedEdges} added, ${diff.summary.removedEdges} deleted`
+    `${diff.flowName}: nodes ${diff.summary.addedNodes} added, ${diff.summary.removedNodes} deleted, ${diff.summary.modifiedNodes} modified; edges ${diff.summary.addedEdges} added, ${diff.summary.removedEdges} deleted${formatFlowAttributeSummary(diff.flowChanges)}`
   );
 }
+function formatFlowAttributeSummary(flowChanges) {
+  if (!flowChanges || flowChanges.length === 0) {
+    return "";
+  }
+  return `; flow attributes: ${flowChanges.length} changed (${flowChanges.map((change) => change.path).join(", ")})`;
+}
 function discoverGitFiles(repo, from, to, pattern, changedOnly) {
   const matcher = createPathMatcher(pattern);
   if (!changedOnly) {