@industry-theme/file-city-panel 0.5.70 → 0.5.72

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,6 +257806,11 @@ const TrailLeaderLine = React.forwardRef(function TrailLeaderLine2({ containerRe
     )
   ] });
 });
+const CALLOUT_FADE_IN_MS = 350;
+const TITLE_TYPEWRITER_CPS = 28;
+const TITLE_TYPEWRITER_HOLD_MS = 500;
+const TITLE_INTER_HOLD_MS = 220;
+const TITLE_CARET = "▍";
 const fileBasename = (path2) => {
   const i = path2.lastIndexOf("/");
   return i >= 0 ? path2.slice(i + 1) : path2;
@@ -257817,10 +257822,18 @@ const fileDirname = (path2) => {
 const TrailFilePath = React.forwardRef(function TrailFilePath2({
   containerRef,
   buildings,
+  markerTitles,
   cityCenter,
   animate: animate2 = true,
+  currentStepIndex = null,
   stepMs = 1100,
-  dwellMs = 1400,
+  // Dwell budget covers: fade-in (350ms) + initial hold (500ms) +
+  // filename typewriter (~ name.length * 36ms at 28cps) + inter-hold
+  // (220ms) + title typewriter (~ title.length * 36ms) + a digest
+  // beat after typing finishes so the user can read the full
+  // callout before the dot walks on. 3500ms leaves ~1.5s of digest
+  // for typical 10-char filenames + 15-char titles.
+  dwellMs = 3500,
   endHoldMs = 2200
 }, ref) {
   const { theme: theme2 } = useTheme();
@@ -257828,7 +257841,9 @@ const TrailFilePath = React.forwardRef(function TrailFilePath2({
   const fontFamily = theme2.fonts.body;
   const calloutFontSize = String(theme2.fontSizes[1] ?? 14);
   const calloutFontWeight = String(theme2.fontWeights.semibold ?? 600);
-  const calloutLineDy = String(Math.round((theme2.fontSizes[1] ?? 14) * 1.45));
+  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";
@@ -257840,14 +257855,24 @@ const TrailFilePath = React.forwardRef(function TrailFilePath2({
   const animStartTsRef = React.useRef(
     typeof performance !== "undefined" ? performance.now() : 0
   );
+  const hoverFrozenElapsedRef = React.useRef(null);
+  const periodRef = React.useRef(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;
@@ -257861,6 +257886,7 @@ const TrailFilePath = React.forwardRef(function TrailFilePath2({
   }, [animate2, buildings, dwellMs, stepMs, endHoldMs]);
   const onCameraFrame = React.useCallback(
     (camera, size) => {
+      var _a, _b;
       const targets = buildingsRef.current;
       const center = cityCenterRef.current;
       const container = containerRef.current;
@@ -257892,12 +257918,18 @@ const TrailFilePath = React.forwardRef(function TrailFilePath2({
       const N = points.length;
       const slotMs = dwellMs + stepMs;
       const period = N >= 2 ? (N - 1) * slotMs + dwellMs + endHoldMs : 0;
+      periodRef.current = period;
+      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 (animate2 && period > 0) {
-        const elapsed = ((typeof performance !== "undefined" ? performance.now() : Date.now()) - animStartTsRef.current) % period;
+      if (frozenIndex != null) {
+        revealedCount = frozenIndex + 1;
+        dwellElapsed = CALLOUT_FADE_IN_MS;
+      } else if (animate2 && period > 0) {
+        const elapsed = hoverFrozenElapsedRef.current !== null ? hoverFrozenElapsedRef.current : ((typeof performance !== "undefined" ? performance.now() : Date.now()) - animStartTsRef.current) % period;
         const traversalsEnd = (N - 1) * slotMs;
         if (elapsed >= traversalsEnd) {
           revealedCount = N;
@@ -258011,38 +258043,79 @@ const TrailFilePath = React.forwardRef(function TrailFilePath2({
         }
       }
       const SVG_NS = "http://www.w3.org/2000/svg";
-      const paintCallout = (textEl, bgEl, point2, path2, opacity) => {
+      const paintCallout = (textEl, bgEl, point2, path2, title, opacity, nameRevealChars2, titleRevealChars2) => {
         if (!textEl || !bgEl) return;
         if (!point2 || !point2.visible || opacity <= 1e-3 || !path2) {
           textEl.setAttribute("opacity", "0");
           bgEl.setAttribute("opacity", "0");
+          bgEl.setAttribute("pointer-events", "none");
+          textEl.setAttribute("pointer-events", "none");
           return;
         }
-        if (textEl.children.length < 2) {
-          while (textEl.firstChild) textEl.removeChild(textEl.firstChild);
-          textEl.appendChild(document.createElementNS(SVG_NS, "tspan"));
+        const interactive = opacity >= 0.6;
+        bgEl.setAttribute(
+          "pointer-events",
+          interactive ? "auto" : "none"
+        );
+        textEl.setAttribute(
+          "pointer-events",
+          interactive ? "auto" : "none"
+        );
+        while (textEl.children.length < 3) {
           textEl.appendChild(document.createElementNS(SVG_NS, "tspan"));
         }
-        const nameTspan = textEl.children[0];
-        const pathTspan = textEl.children[1];
+        while (textEl.children.length > 3) {
+          textEl.removeChild(textEl.lastChild);
+        }
+        const pathTspan = textEl.children[0];
+        const nameTspan = textEl.children[1];
+        const titleTspan = textEl.children[2];
         const name2 = fileBasename(path2);
         const dir = fileDirname(path2);
-        const nameLineY = point2.y - 44;
+        const trimmedTitle = (title == null ? void 0 : title.trim()) ?? "";
+        const displayTitle = trimmedTitle && titleRevealChars2 !== null ? titleRevealChars2 < 0 ? "" : titleRevealChars2 >= trimmedTitle.length ? trimmedTitle : trimmedTitle.slice(0, titleRevealChars2) + TITLE_CARET : trimmedTitle;
+        const displayName = nameRevealChars2 !== null ? nameRevealChars2 < 0 ? "" : nameRevealChars2 >= name2.length ? name2 : name2.slice(0, nameRevealChars2) + TITLE_CARET : name2;
+        const lineCount = (dir ? 1 : 0) + 1 + (trimmedTitle ? 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));
-        nameTspan.textContent = name2;
-        nameTspan.setAttribute("x", String(point2.x));
-        nameTspan.setAttribute("y", String(nameLineY));
-        nameTspan.setAttribute("fill", filenameColor);
-        nameTspan.setAttribute("font-size", calloutFontSize);
-        nameTspan.setAttribute("font-weight", calloutFontWeight);
         pathTspan.textContent = dir;
+        pathTspan.setAttribute("text-anchor", "middle");
         pathTspan.setAttribute("x", String(point2.x));
-        pathTspan.setAttribute("dy", dir ? calloutLineDy : "0");
-        pathTspan.setAttribute("fill", dirColor);
+        pathTspan.setAttribute("y", String(topLineY));
+        pathTspan.removeAttribute("dy");
+        pathTspan.setAttribute("fill", color2);
         pathTspan.setAttribute("font-size", calloutFontSize);
         pathTspan.setAttribute("font-weight", calloutFontWeight);
+        nameTspan.textContent = name2;
+        nameTspan.setAttribute("text-anchor", "start");
+        nameTspan.removeAttribute("y");
+        nameTspan.setAttribute("dy", dir ? calloutLineDy : "0");
+        nameTspan.setAttribute(
+          "fill",
+          trimmedTitle ? dirColor : filenameColor
+        );
+        nameTspan.setAttribute("font-size", calloutFontSize);
+        nameTspan.setAttribute(
+          "font-weight",
+          trimmedTitle ? calloutBodyFontWeight : calloutFontWeight
+        );
+        const nameWidth = typeof nameTspan.getComputedTextLength === "function" ? nameTspan.getComputedTextLength() : 0;
+        nameTspan.setAttribute("x", String(point2.x - nameWidth / 2));
+        titleTspan.textContent = trimmedTitle;
+        titleTspan.setAttribute("text-anchor", "start");
+        titleTspan.removeAttribute("y");
+        titleTspan.setAttribute(
+          "dy",
+          trimmedTitle ? calloutLineDy : "0"
+        );
+        titleTspan.setAttribute("fill", filenameColor);
+        titleTspan.setAttribute("font-size", calloutFontSize);
+        titleTspan.setAttribute("font-weight", calloutFontWeight);
+        const titleWidth = typeof titleTspan.getComputedTextLength === "function" ? titleTspan.getComputedTextLength() : 0;
+        titleTspan.setAttribute("x", String(point2.x - titleWidth / 2));
         const bbox = textEl.getBBox();
         const padX = 14;
         const padY = 10;
@@ -258055,26 +258128,70 @@ const TrailFilePath = React.forwardRef(function TrailFilePath2({
         bgEl.setAttribute("stroke", color2);
         bgEl.setAttribute("stroke-width", "1.5");
         bgEl.setAttribute("opacity", String(0.94 * opacity));
+        if (displayName !== name2) {
+          nameTspan.textContent = displayName;
+        }
+        if (displayTitle !== trimmedTitle) {
+          titleTspan.textContent = displayTitle;
+        }
       };
-      const fadeInMs = 350;
       let calloutOpacity = 0;
-      if (animate2 && lastIndex >= 0 && lastIndex < targets.length) {
+      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 / fadeInMs);
+          const t = Math.min(1, dwellElapsed / CALLOUT_FADE_IN_MS);
           calloutOpacity = t * t * (3 - 2 * t);
         }
       } else if (!animate2 && lastIndex >= 0) {
         calloutOpacity = 1;
       }
+      const activePath = lastIndex >= 0 ? targets[lastIndex].path : null;
+      const activeName = activePath ? fileBasename(activePath) : "";
+      const activeTitle = lastIndex >= 0 ? (((_a = markerTitlesRef.current) == null ? void 0 : _a[lastIndex]) ?? "").trim() : "";
+      let nameRevealChars = null;
+      let titleRevealChars = null;
+      if (animate2 && frozenIndex == null && traverseFrac === null && lastIndex >= 0) {
+        const charsPerMs = TITLE_TYPEWRITER_CPS / 1e3;
+        const nameStart = CALLOUT_FADE_IN_MS + TITLE_TYPEWRITER_HOLD_MS;
+        const nameDuration = activeName.length > 0 ? activeName.length / charsPerMs : 0;
+        const nameDone = nameStart + nameDuration;
+        const titleStart = nameDone + TITLE_INTER_HOLD_MS;
+        if (activeName.length > 0) {
+          if (dwellElapsed < nameStart) {
+            nameRevealChars = 0;
+          } else if (dwellElapsed < nameDone) {
+            const typed = Math.floor(
+              (dwellElapsed - nameStart) * charsPerMs
+            );
+            nameRevealChars = typed >= activeName.length ? null : Math.max(0, typed);
+          } else {
+            nameRevealChars = null;
+          }
+        }
+        if (activeTitle.length > 0) {
+          if (dwellElapsed < titleStart) {
+            titleRevealChars = -1;
+          } else {
+            const typed = Math.floor(
+              (dwellElapsed - titleStart) * charsPerMs
+            );
+            titleRevealChars = typed >= activeTitle.length ? null : Math.max(0, typed);
+          }
+        }
+      }
       paintCallout(
         calloutTextRef.current,
         calloutBgRef.current,
         lastIndex >= 0 ? points[lastIndex] : null,
-        lastIndex >= 0 ? targets[lastIndex].path : null,
-        calloutOpacity
+        activePath,
+        lastIndex >= 0 ? ((_b = markerTitlesRef.current) == null ? void 0 : _b[lastIndex]) ?? null : null,
+        calloutOpacity,
+        nameRevealChars,
+        titleRevealChars
       );
       g2.setAttribute("opacity", "1");
     },
@@ -258089,13 +258206,28 @@ const TrailFilePath = React.forwardRef(function TrailFilePath2({
       fontFamily,
       calloutFontSize,
       calloutFontWeight,
+      calloutBodyFontWeight,
       calloutLineDy,
+      calloutLineDyPx,
       surfaceColor,
       filenameColor,
       dirColor
     ]
   );
   React.useImperativeHandle(ref, () => ({ onCameraFrame }), [onCameraFrame]);
+  const handleCalloutEnter = React.useCallback(() => {
+    if (hoverFrozenElapsedRef.current !== null) return;
+    const period = periodRef.current;
+    if (period <= 0) return;
+    const now2 = typeof performance !== "undefined" ? performance.now() : Date.now();
+    hoverFrozenElapsedRef.current = (now2 - animStartTsRef.current) % period;
+  }, []);
+  const handleCalloutLeave = React.useCallback(() => {
+    if (hoverFrozenElapsedRef.current === null) return;
+    const now2 = typeof performance !== "undefined" ? performance.now() : Date.now();
+    animStartTsRef.current = now2 - hoverFrozenElapsedRef.current;
+    hoverFrozenElapsedRef.current = null;
+  }, []);
   return /* @__PURE__ */ jsxs(
     "svg",
     {
@@ -258113,8 +258245,26 @@ const TrailFilePath = React.forwardRef(function TrailFilePath2({
       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" })
+        /* @__PURE__ */ jsx(
+          "rect",
+          {
+            ref: calloutBgRef,
+            opacity: 0,
+            pointerEvents: "auto",
+            onMouseEnter: handleCalloutEnter,
+            onMouseLeave: handleCalloutLeave
+          }
+        ),
+        /* @__PURE__ */ jsx(
+          "text",
+          {
+            ref: calloutTextRef,
+            opacity: 0,
+            pointerEvents: "auto",
+            onMouseEnter: handleCalloutEnter,
+            onMouseLeave: handleCalloutLeave
+          }
+        )
       ]
     }
   );
@@ -258126,6 +258276,7 @@ const RESIZE_HANDLE_WIDTH = 6;
 const TrailMarkdownOverlay = ({
   eyebrow,
   title,
+  subtitle,
   markdown: markdown2,
   slideIdPrefix,
   bottomOffset,
@@ -258233,7 +258384,7 @@ const TrailMarkdownOverlay = ({
           to { transform: translateX(0); }
         }
       ` }),
-        eyebrow || title ? /* @__PURE__ */ jsxs(
+        eyebrow || title || subtitle ? /* @__PURE__ */ jsxs(
           "div",
           {
             style: {
@@ -258272,6 +258423,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
             ]
           }
@@ -258675,32 +258842,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 {
@@ -258825,40 +258975,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
@@ -258867,10 +259000,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;
@@ -258926,7 +259060,9 @@ const FileCityTrailExplorerPanel = ({ context, actions }) => {
       onSelectMarker: setSelectedMarkerId,
       cityData,
       hasLineCounts: lineCounts != null && Object.keys(lineCounts).length > 0,
-      readFile: actions.readFile
+      readFile: actions.readFile,
+      defaultViewMode,
+      defaultShowSequenceDrawer
     }
   );
 };
@@ -258938,7 +259074,9 @@ const FileCityTrailSequenceLayout = ({
   onSelectMarker,
   cityData,
   hasLineCounts,
-  readFile
+  readFile,
+  defaultViewMode = "city",
+  defaultShowSequenceDrawer = true
 }) => {
   var _a, _b;
   const { theme: theme2 } = useTheme();
@@ -258949,8 +259087,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;
@@ -258958,20 +259100,24 @@ const FileCityTrailSequenceLayout = ({
     if (!selectedMarkerId) return null;
     return trail2.markers.find((m) => m.id === selectedMarkerId) ?? null;
   }, [trail2.markers, selectedMarkerId]);
-  const markerBySourcePathForThisRepo = React.useMemo(() => {
+  const markerByBuildingPath = React.useMemo(() => {
     const map2 = /* @__PURE__ */ new Map();
+    if (!cityData) return map2;
     for (const m of markersForThisRepo) {
-      if (m.sourcePath) map2.set(m.sourcePath, m);
+      const cityPath = markerCityPath(m, trail2);
+      if (!cityPath) continue;
+      const b = cityData.buildings.find((cb) => cb.path === cityPath) ?? cityData.buildings.find((cb) => cb.path.endsWith(`/${cityPath}`));
+      if (b) map2.set(b.path, m);
     }
     return map2;
-  }, [markersForThisRepo]);
+  }, [markersForThisRepo, cityData, trail2]);
   const handleBuildingClick = React.useCallback(
     (building) => {
-      const marker = markerBySourcePathForThisRepo.get(building.path);
+      const marker = markerByBuildingPath.get(building.path);
       if (!marker) return;
       onSelectMarker(selectedMarkerId === marker.id ? null : marker.id);
     },
-    [markerBySourcePathForThisRepo, selectedMarkerId, onSelectMarker]
+    [markerByBuildingPath, selectedMarkerId, onSelectMarker]
   );
   const stepperIndex = React.useMemo(() => {
     if (!selectedMarkerId) return -1;
@@ -259007,37 +259153,39 @@ const FileCityTrailSequenceLayout = ({
     const firstMarkerByPath = /* @__PURE__ */ new Map();
     const order2 = [];
     for (const m of markersForThisRepo) {
-      if (!m.sourcePath) continue;
-      const existing = counts.get(m.sourcePath) ?? 0;
-      counts.set(m.sourcePath, existing + 1);
-      if (!firstMarkerByPath.has(m.sourcePath)) {
-        firstMarkerByPath.set(m.sourcePath, m.id);
-        order2.push(m.sourcePath);
-      }
-    }
-    return order2.map((sourcePath) => ({
-      sourcePath,
-      markerCount: counts.get(sourcePath) ?? 0,
-      isActive: (selectedMarker == null ? void 0 : selectedMarker.sourcePath) === sourcePath,
+      const cityPath = markerCityPath(m, trail2);
+      if (!cityPath) continue;
+      const existing = counts.get(cityPath) ?? 0;
+      counts.set(cityPath, existing + 1);
+      if (!firstMarkerByPath.has(cityPath)) {
+        firstMarkerByPath.set(cityPath, m.id);
+        order2.push(cityPath);
+      }
+    }
+    const selectedCityPath = selectedMarker ? markerCityPath(selectedMarker, trail2) : null;
+    return order2.map((cityPath) => ({
+      sourcePath: cityPath,
+      markerCount: counts.get(cityPath) ?? 0,
+      isActive: selectedCityPath === cityPath,
       onClick: () => {
-        const markerId = firstMarkerByPath.get(sourcePath);
+        const markerId = firstMarkerByPath.get(cityPath);
         if (markerId) onSelectMarker(markerId);
       },
       onHoverChange: setHoveredFilePath
     }));
-  }, [markersForThisRepo, selectedMarker, onSelectMarker]);
+  }, [markersForThisRepo, selectedMarker, onSelectMarker, trail2]);
   const trailFilesHighlightLayers = React.useMemo(() => {
     if (!cityData) return null;
-    const sourcePaths = markersForThisRepo.map((m) => m.sourcePath).filter((p2) => typeof p2 === "string" && p2.length > 0);
-    if (sourcePaths.length === 0) return null;
+    const cityPaths = markersForThisRepo.map((m) => markerCityPath(m, trail2)).filter((p2) => typeof p2 === "string" && p2.length > 0);
+    if (cityPaths.length === 0) return null;
     const buildingByPath = new Map(cityData.buildings.map((b) => [b.path, b]));
     const byColor = /* @__PURE__ */ new Map();
     const seen = /* @__PURE__ */ new Set();
-    for (const sourcePath of sourcePaths) {
-      if (seen.has(sourcePath)) continue;
-      const building = buildingByPath.get(sourcePath) ?? cityData.buildings.find((b) => b.path.endsWith(`/${sourcePath}`));
+    for (const cityPath of cityPaths) {
+      if (seen.has(cityPath)) continue;
+      const building = buildingByPath.get(cityPath) ?? cityData.buildings.find((b) => b.path.endsWith(`/${cityPath}`));
       if (!building) continue;
-      seen.add(sourcePath);
+      seen.add(cityPath);
       const color2 = building.color ?? getFileColor(building.path);
       if (!color2) continue;
       const list2 = byColor.get(color2) ?? [];
@@ -259059,7 +259207,7 @@ const FileCityTrailSequenceLayout = ({
         renderStrategy: "fill"
       }))
     }));
-  }, [markersForThisRepo, cityData]);
+  }, [markersForThisRepo, cityData, trail2]);
   const trailFilesActive = trailFilesHighlightLayers !== null && trailFilesHighlightLayers.length > 0;
   const hoveredFileHighlightLayer = React.useMemo(() => {
     if (!hoveredFilePath || !cityData) return null;
@@ -259084,12 +259232,49 @@ const FileCityTrailSequenceLayout = ({
       ]
     };
   }, [hoveredFilePath, cityData, theme2.colors.accent]);
+  const districtTintLayers = React.useMemo(() => {
+    if (!cityData) return null;
+    const repos = trail2.repos ?? [];
+    if (repos.length <= 1) return null;
+    const palette = ["#3b82f6", "#a855f7", "#f97316", "#10b981", "#eab308"];
+    const layers = [];
+    repos.forEach((repo, i) => {
+      const prefix = `${repo.name}/`;
+      const paths = [];
+      for (const b of cityData.buildings) {
+        if (b.path === repo.name || b.path.startsWith(prefix)) {
+          paths.push(b.path);
+        } else if (b.path.includes(`/${prefix}`)) {
+          paths.push(b.path);
+        }
+      }
+      if (paths.length === 0) return;
+      layers.push({
+        // The layer-system id is internal — using the PURL here is fine
+        // (and uniquely scopes by canonical identity even if two repos
+        // happened to share a `name`).
+        id: `district-${repo.id}`,
+        name: `District: ${repo.name}`,
+        enabled: true,
+        color: palette[i % palette.length],
+        opacity: 0.18,
+        priority: 10,
+        items: paths.map((path2) => ({
+          path: path2,
+          type: "file",
+          renderStrategy: "fill"
+        }))
+      });
+    });
+    return layers.length > 0 ? layers : null;
+  }, [cityData, trail2.repos]);
   const cityHighlightLayers = React.useMemo(() => {
     const layers = [];
+    if (districtTintLayers) layers.push(...districtTintLayers);
     if (trailFilesHighlightLayers) layers.push(...trailFilesHighlightLayers);
     if (hoveredFileHighlightLayer) layers.push(hoveredFileHighlightLayer);
     return layers.length > 0 ? layers : void 0;
-  }, [trailFilesHighlightLayers, hoveredFileHighlightLayer]);
+  }, [districtTintLayers, trailFilesHighlightLayers, hoveredFileHighlightLayer]);
   const containerRef = React.useRef(null);
   const snippetPaneRef = React.useRef(null);
   const leaderLineRef = React.useRef(null);
@@ -259106,10 +259291,11 @@ const FileCityTrailSequenceLayout = ({
   const [snippetPaneWidth, setSnippetPaneWidth] = React.useState(null);
   const [containerSize, setContainerSize] = React.useState(null);
   const selectedBuilding = React.useMemo(() => {
-    if (!cityData || !(selectedMarker == null ? void 0 : selectedMarker.sourcePath)) return null;
-    const path2 = selectedMarker.sourcePath;
+    if (!cityData || !selectedMarker) return null;
+    const path2 = markerCityPath(selectedMarker, trail2);
+    if (!path2) return null;
     return cityData.buildings.find((b) => b.path === path2) ?? cityData.buildings.find((b) => b.path.endsWith(`/${path2}`)) ?? null;
-  }, [cityData, selectedMarker]);
+  }, [cityData, selectedMarker, trail2]);
   const cityCenter = React.useMemo(() => {
     if (!cityData) return null;
     return {
@@ -259117,17 +259303,42 @@ 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 cityPath = markerCityPath(m, trail2);
+      if (!cityPath) continue;
+      const b = buildingByPath.get(cityPath) ?? cityData.buildings.find((cb) => cb.path.endsWith(`/${cityPath}`));
+      if (b) {
+        buildings.push(b);
+        titles.push(((_a2 = m.label) == null ? void 0 : _a2.trim()) || null);
+        markerIds.push(m.id);
+      }
     }
-    return out;
-  }, [cityData, markersForThisRepo]);
+    return {
+      trailPathBuildings: buildings,
+      trailPathTitles: titles,
+      trailPathMarkerIds: markerIds
+    };
+  }, [cityData, markersForThisRepo, trail2]);
+  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;
@@ -259172,13 +259383,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;
@@ -259262,6 +259478,7 @@ const FileCityTrailSequenceLayout = ({
           {
             trail: trail2,
             markerCount: markersForThisRepo.length,
+            activeMarkerIndex: stepperIndex,
             show3D: effectiveShow3D,
             onToggle3D: () => setShow3D((v) => !v),
             hideToggle: THREE_D_TOGGLE_DISABLED,
@@ -259274,13 +259491,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
@@ -259312,7 +259532,7 @@ const FileCityTrailSequenceLayout = ({
                   cityData,
                   width: "100%",
                   height: "100%",
-                  selectedPath: (selectedMarker == null ? void 0 : selectedMarker.sourcePath) ?? null,
+                  selectedPath: selectedMarker ? markerCityPath(selectedMarker, trail2) : null,
                   onBuildingClick: handleBuildingClick,
                   onCameraFrame,
                   showControls: false,
@@ -259329,6 +259549,8 @@ const FileCityTrailSequenceLayout = ({
                   ref: filePathRef,
                   containerRef,
                   buildings: trailPathBuildings,
+                  markerTitles: trailPathTitles,
+                  currentStepIndex: trailPathCurrentStepIndex,
                   cityCenter
                 }
               ),
@@ -259347,6 +259569,7 @@ const FileCityTrailSequenceLayout = ({
                 {
                   eyebrow: overlayMarkdown.eyebrow,
                   title: overlayMarkdown.title,
+                  subtitle: overlayMarkdown.subtitle,
                   markdown: overlayMarkdown.markdown,
                   slideIdPrefix: overlayMarkdown.slideIdPrefix,
                   bottomOffset: `${drawerHeightPct}%`,
@@ -259388,7 +259611,8 @@ const FileCityTrailSequenceLayout = ({
                   drawerHeightPct,
                   disableBottomTransition: isResizingDrawer,
                   expanded: snippetExpanded,
-                  onToggleExpanded: () => setSnippetExpanded((v) => !v)
+                  onToggleExpanded: () => setSnippetExpanded((v) => !v),
+                  markdownOverlayWidth
                 }
               ) : null
             ]
@@ -259555,7 +259779,8 @@ const SnippetSidePane = React.forwardRef(function SnippetSidePane2({
   drawerHeightPct,
   disableBottomTransition,
   expanded,
-  onToggleExpanded
+  onToggleExpanded,
+  markdownOverlayWidth
 }, ref) {
   const { theme: theme2 } = useTheme();
   if (!marker.sourcePath) {
@@ -259569,6 +259794,7 @@ const SnippetSidePane = React.forwardRef(function SnippetSidePane2({
         disableBottomTransition,
         expanded,
         onToggleExpanded,
+        markdownOverlayWidth,
         children: /* @__PURE__ */ jsx(
           "div",
           {
@@ -259594,6 +259820,7 @@ const SnippetSidePane = React.forwardRef(function SnippetSidePane2({
       disableBottomTransition,
       expanded,
       onToggleExpanded,
+      markdownOverlayWidth,
       children: snippet2.kind === "slice" ? /* @__PURE__ */ jsx(
         TrailSnippetView,
         {
@@ -259635,10 +259862,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(
@@ -259677,7 +259906,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(
@@ -259686,7 +259915,7 @@ const SidePaneFrame = React.forwardRef(
         );
         setWidthPx(next2);
       },
-      []
+      [defaultLeftInset]
     );
     const handleResizePointerUp = React.useCallback(
       (e) => {
@@ -259706,9 +259935,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}`,
@@ -259771,33 +260006,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",
@@ -260094,6 +260373,7 @@ const TrailDocumentCard = ({
 const TrailHeader = ({
   trail: trail2,
   markerCount,
+  activeMarkerIndex,
   show3D,
   onToggle3D,
   hideToggle = false,
@@ -260173,20 +260453,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
+                    );
+                  })
                 }
               )
             ]
@@ -260341,6 +260635,15 @@ function filterMarkersForRepo(trail2, repository) {
   }
   return trail2.markers.filter((m) => m.repo === repository.id);
 }
+function markerCityPath(marker, trail2) {
+  if (!marker.sourcePath) return null;
+  const repos = trail2.repos ?? [];
+  if (repos.length <= 1) return marker.sourcePath;
+  if (!marker.repo) return null;
+  const repo = repos.find((r2) => r2.id === marker.repo);
+  if (!repo) return null;
+  return `${repo.name}/${marker.sourcePath}`;
+}
 const focusBuildingTool = {
   name: "focus_building",
   description: "Focuses the camera on a specific file (building) in the file city visualization",