@industry-theme/file-city-panel 0.5.69 → 0.5.71

package/dist/panels.bundle.js

@@ -257703,7 +257703,7 @@ const TrailLeaderLine = React.forwardRef(function TrailLeaderLine2({ containerRe
       const HEADER_BAND_OFFSET = 22;
       const bx = nodeRect.left - containerRect.left;
       const by = nodeRect.top - containerRect.top + HEADER_BAND_OFFSET;
-      const ELBOW_GAP = 60;
+      const ELBOW_GAP = 30;
       const CORNER_RADIUS = 14;
       const elbowX = Math.max(
         canvasLeft + 8,
@@ -257806,19 +257806,61 @@ const TrailLeaderLine = React.forwardRef(function TrailLeaderLine2({ containerRe
     )
   ] });
 });
-const TrailFilePath = React.forwardRef(function TrailFilePath2({ containerRef, buildings, cityCenter }, ref) {
+const CALLOUT_FADE_IN_MS = 350;
+const fileBasename = (path2) => {
+  const i = path2.lastIndexOf("/");
+  return i >= 0 ? path2.slice(i + 1) : path2;
+};
+const fileDirname = (path2) => {
+  const i = path2.lastIndexOf("/");
+  return i > 0 ? path2.slice(0, i) : "";
+};
+const TrailFilePath = React.forwardRef(function TrailFilePath2({
+  containerRef,
+  buildings,
+  markerTitles,
+  cityCenter,
+  animate: animate2 = true,
+  currentStepIndex = null,
+  stepMs = 1100,
+  dwellMs = 1400,
+  endHoldMs = 2200
+}, ref) {
   const { theme: theme2 } = useTheme();
   const color2 = theme2.colors.accent ?? "#22d3ee";
+  const fontFamily = theme2.fonts.body;
+  const calloutFontSize = String(theme2.fontSizes[1] ?? 14);
+  const calloutFontWeight = String(theme2.fontWeights.semibold ?? 600);
+  const calloutBodyFontWeight = String(theme2.fontWeights.body ?? 400);
+  const calloutLineDyPx = Math.round((theme2.fontSizes[1] ?? 14) * 1.45);
+  const calloutLineDy = String(calloutLineDyPx);
+  const surfaceColor = theme2.colors.backgroundSecondary ?? "#0f1419";
+  const filenameColor = theme2.colors.text ?? "#f8fafc";
+  const dirColor = theme2.colors.textMuted ?? "#94a3b8";
   const groupRef = React.useRef(null);
+  const calloutTextRef = React.useRef(null);
+  const calloutBgRef = React.useRef(null);
+  const leadDotRef = React.useRef(null);
   const projectScratch = React.useRef(new THREE.Vector3());
+  const animStartTsRef = React.useRef(
+    typeof performance !== "undefined" ? performance.now() : 0
+  );
   const buildingsRef = React.useRef(buildings);
+  const markerTitlesRef = React.useRef(markerTitles);
   const cityCenterRef = React.useRef(cityCenter);
+  const currentStepIndexRef = React.useRef(currentStepIndex);
   React.useEffect(() => {
     buildingsRef.current = buildings;
   }, [buildings]);
+  React.useEffect(() => {
+    markerTitlesRef.current = markerTitles;
+  }, [markerTitles]);
   React.useEffect(() => {
     cityCenterRef.current = cityCenter;
   }, [cityCenter]);
+  React.useEffect(() => {
+    currentStepIndexRef.current = currentStepIndex;
+  }, [currentStepIndex]);
   const hideAll = React.useCallback(() => {
     const g2 = groupRef.current;
     if (!g2) return;
@@ -257827,8 +257869,12 @@ const TrailFilePath = React.forwardRef(function TrailFilePath2({ containerRef, b
   React.useEffect(() => {
     if (buildings.length < 2) hideAll();
   }, [buildings, hideAll]);
+  React.useEffect(() => {
+    animStartTsRef.current = typeof performance !== "undefined" ? performance.now() : 0;
+  }, [animate2, buildings, dwellMs, stepMs, endHoldMs]);
   const onCameraFrame = React.useCallback(
     (camera, size) => {
+      var _a;
       const targets = buildingsRef.current;
       const center = cityCenterRef.current;
       const container = containerRef.current;
@@ -257857,31 +257903,80 @@ const TrailFilePath = React.forwardRef(function TrailFilePath2({ containerRef, b
         const y2 = canvasTop + (v.y * -0.5 + 0.5) * size.height;
         points.push({ x: x2, y: y2, visible });
       }
+      const N = points.length;
+      const slotMs = dwellMs + stepMs;
+      const period = N >= 2 ? (N - 1) * slotMs + dwellMs + endHoldMs : 0;
+      const rawFrozen = currentStepIndexRef.current;
+      const frozenIndex = rawFrozen != null && rawFrozen >= 0 && rawFrozen < N ? rawFrozen : null;
+      let revealedCount = animate2 ? 0 : N;
+      let leadingTip = null;
+      let traverseFrac = null;
+      let dwellElapsed = 0;
+      if (frozenIndex != null) {
+        revealedCount = frozenIndex + 1;
+        dwellElapsed = CALLOUT_FADE_IN_MS;
+      } else if (animate2 && period > 0) {
+        const elapsed = ((typeof performance !== "undefined" ? performance.now() : Date.now()) - animStartTsRef.current) % period;
+        const traversalsEnd = (N - 1) * slotMs;
+        if (elapsed >= traversalsEnd) {
+          revealedCount = N;
+          dwellElapsed = elapsed - traversalsEnd;
+        } else {
+          const slot = Math.floor(elapsed / slotMs);
+          const tInSlot = elapsed - slot * slotMs;
+          revealedCount = slot + 1;
+          if (tInSlot >= dwellMs) {
+            const t = tInSlot - dwellMs;
+            const frac2 = stepMs > 0 ? t / stepMs : 1;
+            traverseFrac = frac2;
+            const eased = frac2 * frac2 * (3 - 2 * frac2);
+            const a = points[slot];
+            const b = points[slot + 1];
+            leadingTip = {
+              x: a.x + (b.x - a.x) * eased,
+              y: a.y + (b.y - a.y) * eased,
+              visible: a.visible && b.visible
+            };
+          } else {
+            dwellElapsed = tInSlot;
+          }
+        }
+      }
+      const lastIndex = revealedCount - 1;
       let d = "";
-      for (let i = 0; i < points.length; i++) {
+      let started = false;
+      for (let i = 0; i <= lastIndex; i++) {
         const p2 = points[i];
         if (!p2.visible) {
-          d += "";
+          started = false;
           continue;
         }
-        if (i === 0 || !points[i - 1].visible) {
+        if (!started) {
           d += `M ${p2.x} ${p2.y} `;
+          started = true;
         } else {
           d += `L ${p2.x} ${p2.y} `;
         }
       }
-      while (g2.children.length < 1 + targets.length * 2) {
+      if (leadingTip && leadingTip.visible && started) {
+        d += `L ${leadingTip.x} ${leadingTip.y} `;
+      }
+      const needed = 1 + targets.length * 2;
+      if (g2.children.length === 0) {
         g2.appendChild(
           document.createElementNS("http://www.w3.org/2000/svg", "path")
         );
+      }
+      while (g2.children.length < needed) {
+        const isCircleSlot = g2.children.length % 2 === 1;
         g2.appendChild(
-          document.createElementNS("http://www.w3.org/2000/svg", "circle")
-        );
-        g2.appendChild(
-          document.createElementNS("http://www.w3.org/2000/svg", "text")
+          document.createElementNS(
+            "http://www.w3.org/2000/svg",
+            isCircleSlot ? "circle" : "text"
+          )
         );
       }
-      while (g2.children.length > 1 + targets.length * 2) {
+      while (g2.children.length > needed) {
         g2.removeChild(g2.children[g2.children.length - 1]);
       }
       const pathEl = g2.children[0];
@@ -257895,33 +257990,156 @@ const TrailFilePath = React.forwardRef(function TrailFilePath2({ containerRef, b
         const dot = g2.children[1 + i * 2];
         const label = g2.children[1 + i * 2 + 1];
         const p2 = points[i];
-        if (!p2.visible) {
+        const revealed = !animate2 || i <= lastIndex;
+        const isCurrent = animate2 && i === lastIndex;
+        if (!p2.visible || !revealed) {
           dot.setAttribute("opacity", "0");
           label.setAttribute("opacity", "0");
           continue;
         }
         dot.setAttribute("cx", String(p2.x));
         dot.setAttribute("cy", String(p2.y));
-        dot.setAttribute("r", "6");
+        dot.setAttribute("r", isCurrent ? "8" : "6");
         dot.setAttribute("fill", color2);
-        dot.setAttribute("stroke", "#0f1419");
+        dot.setAttribute("stroke", surfaceColor);
         dot.setAttribute("stroke-width", "1.5");
         dot.setAttribute("opacity", "1");
-        label.setAttribute("x", String(p2.x));
-        label.setAttribute("y", String(p2.y - 10));
-        label.setAttribute("text-anchor", "middle");
-        label.setAttribute("fill", color2);
-        label.setAttribute("font-size", "11");
-        label.setAttribute("font-weight", "600");
-        label.setAttribute("opacity", "1");
-        label.textContent = String(i + 1);
+        if (animate2) {
+          label.setAttribute("opacity", "0");
+        } else {
+          label.setAttribute("x", String(p2.x));
+          label.setAttribute("y", String(p2.y - 10));
+          label.setAttribute("text-anchor", "middle");
+          label.setAttribute("fill", color2);
+          label.setAttribute("font-size", "11");
+          label.setAttribute("font-weight", "600");
+          label.setAttribute("opacity", "1");
+          label.textContent = String(i + 1);
+        }
+      }
+      const leadDot = leadDotRef.current;
+      if (leadDot) {
+        if (leadingTip && leadingTip.visible) {
+          leadDot.setAttribute("cx", String(leadingTip.x));
+          leadDot.setAttribute("cy", String(leadingTip.y));
+          leadDot.setAttribute("r", "4");
+          leadDot.setAttribute("fill", color2);
+          leadDot.setAttribute("opacity", "0.85");
+        } else {
+          leadDot.setAttribute("opacity", "0");
+        }
       }
+      const SVG_NS = "http://www.w3.org/2000/svg";
+      const paintCallout = (textEl, bgEl, point2, path2, title, opacity) => {
+        if (!textEl || !bgEl) return;
+        if (!point2 || !point2.visible || opacity <= 1e-3 || !path2) {
+          textEl.setAttribute("opacity", "0");
+          bgEl.setAttribute("opacity", "0");
+          return;
+        }
+        while (textEl.children.length < 3) {
+          textEl.appendChild(document.createElementNS(SVG_NS, "tspan"));
+        }
+        while (textEl.children.length > 3) {
+          textEl.removeChild(textEl.lastChild);
+        }
+        const titleTspan = textEl.children[0];
+        const nameTspan = textEl.children[1];
+        const pathTspan = textEl.children[2];
+        const name2 = fileBasename(path2);
+        const dir = fileDirname(path2);
+        const trimmedTitle = (title == null ? void 0 : title.trim()) ?? "";
+        const lineCount = (trimmedTitle ? 1 : 0) + 1 + (dir ? 1 : 0);
+        const BOTTOM_LINE_OFFSET = 24;
+        const topLineY = point2.y - BOTTOM_LINE_OFFSET - (lineCount - 1) * calloutLineDyPx;
+        textEl.setAttribute("text-anchor", "middle");
+        textEl.setAttribute("font-family", fontFamily);
+        textEl.setAttribute("opacity", String(opacity));
+        titleTspan.textContent = trimmedTitle;
+        titleTspan.setAttribute("x", String(point2.x));
+        titleTspan.setAttribute("y", String(topLineY));
+        titleTspan.setAttribute("fill", filenameColor);
+        titleTspan.setAttribute("font-size", calloutFontSize);
+        titleTspan.setAttribute("font-weight", calloutFontWeight);
+        nameTspan.textContent = name2;
+        nameTspan.setAttribute("x", String(point2.x));
+        nameTspan.setAttribute(
+          "dy",
+          trimmedTitle ? calloutLineDy : "0"
+        );
+        nameTspan.setAttribute(
+          "fill",
+          trimmedTitle ? dirColor : filenameColor
+        );
+        nameTspan.setAttribute("font-size", calloutFontSize);
+        nameTspan.setAttribute(
+          "font-weight",
+          trimmedTitle ? calloutBodyFontWeight : calloutFontWeight
+        );
+        pathTspan.textContent = dir;
+        pathTspan.setAttribute("x", String(point2.x));
+        pathTspan.setAttribute("dy", dir ? calloutLineDy : "0");
+        pathTspan.setAttribute("fill", dirColor);
+        pathTspan.setAttribute("font-size", calloutFontSize);
+        pathTspan.setAttribute("font-weight", calloutFontWeight);
+        const bbox = textEl.getBBox();
+        const padX = 14;
+        const padY = 10;
+        bgEl.setAttribute("x", String(bbox.x - padX));
+        bgEl.setAttribute("y", String(bbox.y - padY));
+        bgEl.setAttribute("width", String(bbox.width + padX * 2));
+        bgEl.setAttribute("height", String(bbox.height + padY * 2));
+        bgEl.setAttribute("rx", "8");
+        bgEl.setAttribute("fill", surfaceColor);
+        bgEl.setAttribute("stroke", color2);
+        bgEl.setAttribute("stroke-width", "1.5");
+        bgEl.setAttribute("opacity", String(0.94 * opacity));
+      };
+      let calloutOpacity = 0;
+      if (frozenIndex != null && lastIndex >= 0) {
+        calloutOpacity = 1;
+      } else if (animate2 && lastIndex >= 0 && lastIndex < targets.length) {
+        if (traverseFrac !== null) {
+          const eased = traverseFrac * traverseFrac * (3 - 2 * traverseFrac);
+          calloutOpacity = 1 - eased;
+        } else {
+          const t = Math.min(1, dwellElapsed / CALLOUT_FADE_IN_MS);
+          calloutOpacity = t * t * (3 - 2 * t);
+        }
+      } else if (!animate2 && lastIndex >= 0) {
+        calloutOpacity = 1;
+      }
+      paintCallout(
+        calloutTextRef.current,
+        calloutBgRef.current,
+        lastIndex >= 0 ? points[lastIndex] : null,
+        lastIndex >= 0 ? targets[lastIndex].path : null,
+        lastIndex >= 0 ? ((_a = markerTitlesRef.current) == null ? void 0 : _a[lastIndex]) ?? null : null,
+        calloutOpacity
+      );
       g2.setAttribute("opacity", "1");
     },
-    [containerRef, hideAll, color2]
+    [
+      animate2,
+      containerRef,
+      hideAll,
+      color2,
+      stepMs,
+      dwellMs,
+      endHoldMs,
+      fontFamily,
+      calloutFontSize,
+      calloutFontWeight,
+      calloutBodyFontWeight,
+      calloutLineDy,
+      calloutLineDyPx,
+      surfaceColor,
+      filenameColor,
+      dirColor
+    ]
   );
   React.useImperativeHandle(ref, () => ({ onCameraFrame }), [onCameraFrame]);
-  return /* @__PURE__ */ jsx(
+  return /* @__PURE__ */ jsxs(
     "svg",
     {
       width: "100%",
@@ -257935,7 +258153,12 @@ const TrailFilePath = React.forwardRef(function TrailFilePath2({ containerRef, b
         // overlays (z 1900) so the path only paints over the city.
         zIndex: 26
       },
-      children: /* @__PURE__ */ jsx("g", { ref: groupRef, opacity: 0 })
+      children: [
+        /* @__PURE__ */ jsx("g", { ref: groupRef, opacity: 0 }),
+        /* @__PURE__ */ jsx("circle", { ref: leadDotRef, opacity: 0, pointerEvents: "none" }),
+        /* @__PURE__ */ jsx("rect", { ref: calloutBgRef, opacity: 0, pointerEvents: "none" }),
+        /* @__PURE__ */ jsx("text", { ref: calloutTextRef, opacity: 0, pointerEvents: "none" })
+      ]
     }
   );
 });
@@ -257946,6 +258169,7 @@ const RESIZE_HANDLE_WIDTH = 6;
 const TrailMarkdownOverlay = ({
   eyebrow,
   title,
+  subtitle,
   markdown: markdown2,
   slideIdPrefix,
   bottomOffset,
@@ -258053,7 +258277,7 @@ const TrailMarkdownOverlay = ({
           to { transform: translateX(0); }
         }
       ` }),
-        eyebrow || title ? /* @__PURE__ */ jsxs(
+        eyebrow || title || subtitle ? /* @__PURE__ */ jsxs(
           "div",
           {
             style: {
@@ -258092,6 +258316,22 @@ const TrailMarkdownOverlay = ({
                   title,
                   children: title
                 }
+              ) : null,
+              subtitle ? /* @__PURE__ */ jsx(
+                "span",
+                {
+                  style: {
+                    fontSize: theme2.fontSizes[0],
+                    color: theme2.colors.textSecondary,
+                    fontFamily: theme2.fonts.monospace,
+                    overflow: "hidden",
+                    textOverflow: "ellipsis",
+                    whiteSpace: "nowrap",
+                    marginTop: 2
+                  },
+                  title: subtitle,
+                  children: subtitle
+                }
               ) : null
             ]
           }
@@ -258495,32 +258735,15 @@ const TrailSnippetView = ({
   if (!fileObject || !slice) {
     return /* @__PURE__ */ jsx("div", { style: { padding: 16, color: theme2.colors.textSecondary }, children: "Loading…" });
   }
-  const rangeLabel = slice.sliceStart === slice.sliceEnd ? `Line ${slice.sliceStart}` : `Lines ${slice.sliceStart}–${slice.sliceEnd}`;
-  return /* @__PURE__ */ jsxs("div", { style: { display: "flex", flexDirection: "column", minHeight: 0 }, children: [
-    /* @__PURE__ */ jsx(
-      "div",
-      {
-        style: {
-          padding: "4px 14px 6px",
-          fontFamily: theme2.fonts.monospace,
-          fontSize: theme2.fontSizes[0],
-          color: theme2.colors.textSecondary,
-          letterSpacing: 0.4,
-          textTransform: "uppercase"
-        },
-        children: rangeLabel
-      }
-    ),
-    /* @__PURE__ */ jsx(
-      File$2,
-      {
-        file: fileObject,
-        options,
-        selectedLines: slice.focusOffset != null ? { start: slice.focusOffset, end: slice.focusOffset } : void 0,
-        style: pierreStyle$1
-      }
-    )
-  ] });
+  return /* @__PURE__ */ jsx("div", { style: { display: "flex", flexDirection: "column", minHeight: 0 }, children: /* @__PURE__ */ jsx(
+    File$2,
+    {
+      file: fileObject,
+      options,
+      selectedLines: slice.focusOffset != null ? { start: slice.focusOffset, end: slice.focusOffset } : void 0,
+      style: pierreStyle$1
+    }
+  ) });
 };
 const buildBackgroundCSS = (color2) => `
   :host {
@@ -258645,40 +258868,23 @@ const TrailDiffSnippetView = ({
   if (!fileDiff) {
     return /* @__PURE__ */ jsx("div", { style: { padding: 16, color: theme2.colors.error }, children: "Failed to compute diff" });
   }
-  const rangeLabel = startLine != null && endLine != null ? startLine === endLine ? `Line ${startLine}` : `Lines ${startLine}–${endLine}` : null;
-  return /* @__PURE__ */ jsxs("div", { style: { display: "flex", flexDirection: "column", minHeight: 0 }, children: [
-    rangeLabel && /* @__PURE__ */ jsx(
-      "div",
-      {
-        style: {
-          padding: "4px 14px 6px",
-          fontFamily: theme2.fonts.monospace,
-          fontSize: theme2.fontSizes[0],
-          color: theme2.colors.textSecondary,
-          letterSpacing: 0.4,
-          textTransform: "uppercase"
-        },
-        children: rangeLabel
-      }
-    ),
-    /* @__PURE__ */ jsx(
-      FileDiff$2,
-      {
-        fileDiff,
-        options: { ...pierreOptionsBase, diffStyle },
-        selectedLines: slice.focusOffset != null ? { start: slice.focusOffset, end: slice.focusOffset } : void 0,
-        style: background ? {
-          ...pierreStyle,
-          // Pierre derives addition/deletion/context surfaces by
-          // `color-mix`ing from --diffs-bg, which is keyed off
-          // --diffs-light-bg / --diffs-dark-bg. Overriding the
-          // source variables recolors the whole palette coherently.
-          ["--diffs-light-bg"]: background,
-          ["--diffs-dark-bg"]: background
-        } : pierreStyle
-      }
-    )
-  ] });
+  return /* @__PURE__ */ jsx("div", { style: { display: "flex", flexDirection: "column", minHeight: 0 }, children: /* @__PURE__ */ jsx(
+    FileDiff$2,
+    {
+      fileDiff,
+      options: { ...pierreOptionsBase, diffStyle },
+      selectedLines: slice.focusOffset != null ? { start: slice.focusOffset, end: slice.focusOffset } : void 0,
+      style: background ? {
+        ...pierreStyle,
+        // Pierre derives addition/deletion/context surfaces by
+        // `color-mix`ing from --diffs-bg, which is keyed off
+        // --diffs-light-bg / --diffs-dark-bg. Overriding the
+        // source variables recolors the whole palette coherently.
+        ["--diffs-light-bg"]: background,
+        ["--diffs-dark-bg"]: background
+      } : pierreStyle
+    }
+  ) });
 };
 const pierreOptionsBase = {
   disableFileHeader: true
@@ -258687,10 +258893,11 @@ const pierreStyle = {
   display: "block"
 };
 const SEQUENCE_DRAWER_HEIGHT_PCT = 45;
-const SNIPPET_PANE_WIDTH_PX = 460;
+const SNIPPET_PANE_RIGHT_GUTTER_PX = 16;
+const SNIPPET_PANE_LEADER_BUFFER_PX = 60;
 const PANEL_TRANSITION_MS = 280;
 const THREE_D_TOGGLE_DISABLED = true;
-const FileCityTrailExplorerPanel = ({ context, actions }) => {
+const FileCityTrailExplorerPanel = ({ context, actions, defaultViewMode, defaultShowSequenceDrawer }) => {
   var _a;
   const tree = context.fileTree.data;
   const lineCounts = ((_a = context.lineCounts.data) == null ? void 0 : _a.lineCounts) ?? null;
@@ -258746,7 +258953,9 @@ const FileCityTrailExplorerPanel = ({ context, actions }) => {
       onSelectMarker: setSelectedMarkerId,
       cityData,
       hasLineCounts: lineCounts != null && Object.keys(lineCounts).length > 0,
-      readFile: actions.readFile
+      readFile: actions.readFile,
+      defaultViewMode,
+      defaultShowSequenceDrawer
     }
   );
 };
@@ -258758,7 +258967,9 @@ const FileCityTrailSequenceLayout = ({
   onSelectMarker,
   cityData,
   hasLineCounts,
-  readFile
+  readFile,
+  defaultViewMode = "city",
+  defaultShowSequenceDrawer = true
 }) => {
   var _a, _b;
   const { theme: theme2 } = useTheme();
@@ -258769,8 +258980,12 @@ const FileCityTrailSequenceLayout = ({
     return;
   }, [hasLineCounts]);
   const effectiveShow3D = false;
-  const [viewMode, setViewMode] = React.useState("city");
-  const [showSequenceDrawer, setShowSequenceDrawer] = React.useState(true);
+  const [viewMode, setViewMode] = React.useState(
+    defaultViewMode
+  );
+  const [showSequenceDrawer, setShowSequenceDrawer] = React.useState(
+    defaultShowSequenceDrawer
+  );
   const [drawerHeightOverridePct, setDrawerHeightOverridePct] = React.useState(null);
   const [isResizingDrawer, setIsResizingDrawer] = React.useState(false);
   const drawerHeightPct = !showSequenceDrawer ? 0 : drawerHeightOverridePct ?? SEQUENCE_DRAWER_HEIGHT_PCT;
@@ -258937,17 +259152,43 @@ const FileCityTrailSequenceLayout = ({
       z: (cityData.bounds.minZ + cityData.bounds.maxZ) / 2
     };
   }, [cityData]);
-  const trailPathBuildings = React.useMemo(() => {
-    if (!cityData || markersForThisRepo.length === 0) return [];
-    const buildingByPath = new Map(cityData.buildings.map((b) => [b.path, b]));
-    const out = [];
+  const { trailPathBuildings, trailPathTitles, trailPathMarkerIds } = React.useMemo(() => {
+    var _a2;
+    if (!cityData || markersForThisRepo.length === 0) {
+      return {
+        trailPathBuildings: [],
+        trailPathTitles: [],
+        trailPathMarkerIds: []
+      };
+    }
+    const buildingByPath = new Map(
+      cityData.buildings.map((b) => [b.path, b])
+    );
+    const buildings = [];
+    const titles = [];
+    const markerIds = [];
     for (const m of markersForThisRepo) {
       if (!m.sourcePath) continue;
-      const b = buildingByPath.get(m.sourcePath) ?? cityData.buildings.find((cb) => cb.path.endsWith(`/${m.sourcePath}`));
-      if (b) out.push(b);
+      const b = buildingByPath.get(m.sourcePath) ?? cityData.buildings.find(
+        (cb) => cb.path.endsWith(`/${m.sourcePath}`)
+      );
+      if (b) {
+        buildings.push(b);
+        titles.push(((_a2 = m.label) == null ? void 0 : _a2.trim()) || null);
+        markerIds.push(m.id);
+      }
     }
-    return out;
+    return {
+      trailPathBuildings: buildings,
+      trailPathTitles: titles,
+      trailPathMarkerIds: markerIds
+    };
   }, [cityData, markersForThisRepo]);
+  const trailPathCurrentStepIndex = React.useMemo(() => {
+    if (!selectedMarkerId) return null;
+    const idx = trailPathMarkerIds.indexOf(selectedMarkerId);
+    return idx >= 0 ? idx : null;
+  }, [selectedMarkerId, trailPathMarkerIds]);
   const onCameraFrame = React.useCallback(
     (camera, size) => {
       var _a2, _b2;
@@ -258992,13 +259233,18 @@ const FileCityTrailSequenceLayout = ({
     return () => observer.disconnect();
   }, [snippetPaneEl]);
   const overlayMarkdown = ((_a = selectedMarker == null ? void 0 : selectedMarker.description) == null ? void 0 : _a.trim()) ? {
-    eyebrow: "Marker",
+    eyebrow: null,
     title: selectedMarker.label ?? selectedMarker.id,
+    // File path under the title — the panel header already names
+    // the trail, so swapping the "Marker" eyebrow for the marker's
+    // sourcePath gives the user the more useful piece of context.
+    subtitle: selectedMarker.sourcePath ?? null,
     markdown: selectedMarker.description,
     slideIdPrefix: `trail-${trail2.id}-marker-${selectedMarker.id}`
   } : ((_b = trail2.summary) == null ? void 0 : _b.trim()) ? {
     eyebrow: null,
     title: null,
+    subtitle: null,
     markdown: trail2.summary,
     slideIdPrefix: `trail-${trail2.id}-summary`
   } : null;
@@ -259082,6 +259328,7 @@ const FileCityTrailSequenceLayout = ({
           {
             trail: trail2,
             markerCount: markersForThisRepo.length,
+            activeMarkerIndex: stepperIndex,
             show3D: effectiveShow3D,
             onToggle3D: () => setShow3D((v) => !v),
             hideToggle: THREE_D_TOGGLE_DISABLED,
@@ -259094,13 +259341,16 @@ const FileCityTrailSequenceLayout = ({
               // Drawer-open is the default start state, so it no longer
               // counts as "non-idle". Exit is offered only when the user
               // has drilled into something the start view doesn't show.
-              selectedMarkerId != null || snippetExpanded || viewMode !== "city"
+              // The "idle" view-mode is the host-supplied default — when
+              // the host opens the panel in 'doc', staying in 'doc' is
+              // idle and switching to 'city' is the non-idle drill-in.
+              selectedMarkerId != null || snippetExpanded || viewMode !== defaultViewMode
             ),
             onExitTrail: () => {
               onSelectMarker(null);
               setDrawerHeightOverridePct(null);
               setSnippetExpanded(false);
-              setViewMode("city");
+              setViewMode(defaultViewMode);
             },
             viewMode,
             onSetViewMode: setViewMode
@@ -259149,6 +259399,8 @@ const FileCityTrailSequenceLayout = ({
                   ref: filePathRef,
                   containerRef,
                   buildings: trailPathBuildings,
+                  markerTitles: trailPathTitles,
+                  currentStepIndex: trailPathCurrentStepIndex,
                   cityCenter
                 }
               ),
@@ -259167,6 +259419,7 @@ const FileCityTrailSequenceLayout = ({
                 {
                   eyebrow: overlayMarkdown.eyebrow,
                   title: overlayMarkdown.title,
+                  subtitle: overlayMarkdown.subtitle,
                   markdown: overlayMarkdown.markdown,
                   slideIdPrefix: overlayMarkdown.slideIdPrefix,
                   bottomOffset: `${drawerHeightPct}%`,
@@ -259208,7 +259461,8 @@ const FileCityTrailSequenceLayout = ({
                   drawerHeightPct,
                   disableBottomTransition: isResizingDrawer,
                   expanded: snippetExpanded,
-                  onToggleExpanded: () => setSnippetExpanded((v) => !v)
+                  onToggleExpanded: () => setSnippetExpanded((v) => !v),
+                  markdownOverlayWidth
                 }
               ) : null
             ]
@@ -259375,7 +259629,8 @@ const SnippetSidePane = React.forwardRef(function SnippetSidePane2({
   drawerHeightPct,
   disableBottomTransition,
   expanded,
-  onToggleExpanded
+  onToggleExpanded,
+  markdownOverlayWidth
 }, ref) {
   const { theme: theme2 } = useTheme();
   if (!marker.sourcePath) {
@@ -259389,6 +259644,7 @@ const SnippetSidePane = React.forwardRef(function SnippetSidePane2({
         disableBottomTransition,
         expanded,
         onToggleExpanded,
+        markdownOverlayWidth,
         children: /* @__PURE__ */ jsx(
           "div",
           {
@@ -259414,6 +259670,7 @@ const SnippetSidePane = React.forwardRef(function SnippetSidePane2({
       disableBottomTransition,
       expanded,
       onToggleExpanded,
+      markdownOverlayWidth,
       children: snippet2.kind === "slice" ? /* @__PURE__ */ jsx(
         TrailSnippetView,
         {
@@ -259455,10 +259712,12 @@ const SidePaneFrame = React.forwardRef(
     drawerHeightPct,
     disableBottomTransition,
     expanded,
-    onToggleExpanded
+    onToggleExpanded,
+    markdownOverlayWidth
   }, ref) {
     const { theme: theme2 } = useTheme();
     const [widthPx, setWidthPx] = React.useState(null);
+    const defaultLeftInset = (markdownOverlayWidth ?? 0) + SNIPPET_PANE_LEADER_BUFFER_PX;
     const [isResizing, setIsResizing] = React.useState(false);
     const innerRef = React.useRef(null);
     const setInnerRef = React.useCallback(
@@ -259497,7 +259756,7 @@ const SidePaneFrame = React.forwardRef(
         const parentWidth = (parent == null ? void 0 : parent.clientWidth) ?? window.innerWidth;
         const maxWidth = Math.max(
           SNIPPET_PANE_MIN_WIDTH_PX,
-          parentWidth - 32
+          parentWidth - defaultLeftInset - SNIPPET_PANE_RIGHT_GUTTER_PX
         );
         const dx = e.clientX - drag2.startX;
         const next2 = Math.min(
@@ -259506,7 +259765,7 @@ const SidePaneFrame = React.forwardRef(
         );
         setWidthPx(next2);
       },
-      []
+      [defaultLeftInset]
     );
     const handleResizePointerUp = React.useCallback(
       (e) => {
@@ -259526,9 +259785,15 @@ const SidePaneFrame = React.forwardRef(
         style: {
           position: "absolute",
           top: 16,
-          right: 16,
+          right: SNIPPET_PANE_RIGHT_GUTTER_PX,
           bottom: expanded ? `calc(${drawerHeightPct}% + 16px)` : "50%",
-          width: widthPx ?? SNIPPET_PANE_WIDTH_PX,
+          // Auto-fill the right column when the user hasn't dragged an
+          // explicit width: anchor to the markdown overlay's right edge
+          // (plus a leader-line buffer) and the city container's right
+          // gutter. Once `widthPx` is set, switch to an explicit width
+          // and let `right` keep the right anchor.
+          left: widthPx == null ? defaultLeftInset : void 0,
+          width: widthPx ?? void 0,
           minWidth: SNIPPET_PANE_MIN_WIDTH_PX,
           backgroundColor: theme2.colors.background,
           border: `1px solid ${theme2.colors.border}`,
@@ -259591,33 +259856,77 @@ const SidePaneFrame = React.forwardRef(
                 flexShrink: 0
               },
               children: [
-                /* @__PURE__ */ jsxs("div", { style: { minWidth: 0 }, children: [
-                  /* @__PURE__ */ jsx(
-                    "div",
-                    {
-                      style: {
-                        fontFamily: theme2.fonts.heading,
-                        fontSize: theme2.fontSizes[0],
-                        fontWeight: theme2.fontWeights.semibold,
-                        color: theme2.colors.text
-                      },
-                      children: marker.label ?? marker.id
-                    }
-                  ),
-                  marker.sourcePath ? /* @__PURE__ */ jsx(
-                    "div",
-                    {
-                      style: {
-                        fontSize: theme2.fontSizes[0],
-                        color: theme2.colors.textSecondary,
-                        fontFamily: theme2.fonts.monospace,
-                        marginTop: 2,
-                        wordBreak: "break-all"
-                      },
-                      children: marker.sourcePath
-                    }
-                  ) : null
-                ] }),
+                /* @__PURE__ */ jsx("div", { style: { minWidth: 0, flex: 1 }, children: (() => {
+                  const path2 = marker.sourcePath ?? "";
+                  const slashIdx = path2.lastIndexOf("/");
+                  const filename = slashIdx >= 0 ? path2.slice(slashIdx + 1) : path2;
+                  const directory = slashIdx >= 0 ? path2.slice(0, slashIdx + 1) : null;
+                  const snippet2 = marker.snippet;
+                  const rangeLabel = snippet2 ? snippet2.startLine === snippet2.endLine ? `${snippet2.startLine}` : `${snippet2.startLine}–${snippet2.endLine}` : null;
+                  return /* @__PURE__ */ jsxs(Fragment, { children: [
+                    /* @__PURE__ */ jsxs(
+                      "div",
+                      {
+                        style: {
+                          display: "flex",
+                          alignItems: "baseline",
+                          gap: 8,
+                          minWidth: 0
+                        },
+                        children: [
+                          /* @__PURE__ */ jsx(
+                            "div",
+                            {
+                              style: {
+                                fontFamily: theme2.fonts.monospace,
+                                fontSize: theme2.fontSizes[1],
+                                fontWeight: theme2.fontWeights.semibold,
+                                color: theme2.colors.text,
+                                overflow: "hidden",
+                                textOverflow: "ellipsis",
+                                whiteSpace: "nowrap",
+                                minWidth: 0,
+                                flexShrink: 1
+                              },
+                              title: path2 || void 0,
+                              children: filename || marker.id
+                            }
+                          ),
+                          rangeLabel ? /* @__PURE__ */ jsx(
+                            "div",
+                            {
+                              style: {
+                                fontFamily: theme2.fonts.monospace,
+                                fontSize: theme2.fontSizes[0],
+                                color: theme2.colors.textSecondary,
+                                letterSpacing: 0.4,
+                                textTransform: "uppercase",
+                                flexShrink: 0
+                              },
+                              children: rangeLabel
+                            }
+                          ) : null
+                        ]
+                      }
+                    ),
+                    directory ? /* @__PURE__ */ jsx(
+                      "div",
+                      {
+                        style: {
+                          fontSize: theme2.fontSizes[0],
+                          color: theme2.colors.textSecondary,
+                          fontFamily: theme2.fonts.monospace,
+                          marginTop: 2,
+                          overflow: "hidden",
+                          textOverflow: "ellipsis",
+                          whiteSpace: "nowrap"
+                        },
+                        title: directory,
+                        children: directory
+                      }
+                    ) : null
+                  ] });
+                })() }),
                 /* @__PURE__ */ jsxs("div", { style: { display: "flex", gap: 6, flexShrink: 0 }, children: [
                   /* @__PURE__ */ jsx(
                     "button",
@@ -259914,6 +260223,7 @@ const TrailDocumentCard = ({
 const TrailHeader = ({
   trail: trail2,
   markerCount,
+  activeMarkerIndex,
   show3D,
   onToggle3D,
   hideToggle = false,
@@ -259993,20 +260303,34 @@ const TrailHeader = ({
                   children: trail2.title
                 }
               ),
-              /* @__PURE__ */ jsxs(
+              /* @__PURE__ */ jsx(
                 "div",
                 {
+                  "aria-label": `${markerCount} marker${markerCount === 1 ? "" : "s"} in this repo`,
                   style: {
-                    fontFamily: theme2.fonts.body,
-                    fontSize: theme2.fontSizes[0],
-                    color: theme2.colors.textSecondary
+                    display: "flex",
+                    alignItems: "center",
+                    height: theme2.fontSizes[0]
                   },
-                  children: [
-                    markerCount,
-                    " marker",
-                    markerCount === 1 ? "" : "s",
-                    " in this repo"
-                  ]
+                  children: Array.from({ length: markerCount }).map((_, i) => {
+                    const isActive = i === activeMarkerIndex;
+                    return /* @__PURE__ */ jsx(
+                      "span",
+                      {
+                        style: {
+                          width: 6,
+                          height: 6,
+                          borderRadius: "50%",
+                          background: isActive ? theme2.colors.accent : theme2.colors.textSecondary,
+                          // Group dots in fives for at-a-glance countability — a
+                          // wider gap before every 5th index (after the first)
+                          // creates visual columns of 5 like tally marks.
+                          marginLeft: i === 0 ? 0 : i % 5 === 0 ? 11 : 5
+                        }
+                      },
+                      i
+                    );
+                  })
                 }
               )
             ]