@principal-ai/subsystems-react 0.44.3 → 0.45.0

package/dist/subsystem/{walkthroughBrief.js → trailBrief.js}

@@ -1,24 +1,24 @@
 /**
- * walkthroughBrief — build a paste-ready markdown brief for a single
- * walkthrough step so a reviewer can hand one hop to an agent without
+ * trailBrief — build a paste-ready markdown brief for a single
+ * trail step so a reviewer can hand one step to an agent without
  * transcribing it by hand.
  *
- * The unit of handoff is one hop, not the whole flow. A bare hop is ambiguous
+ * The unit of handoff is one step, not the whole flow. A bare step is ambiguous
  * on its own — the same `from`/`to`/`mechanism` can repeat across flows — so the
  * brief also carries the flow it belongs to and its position within it, plus
  * the exact seam site (`symbol`, `file:line`, `purl`) that resolves the
  * checkout.
  */
 /**
- * Markdown brief for `walkthrough.steps[stepIndex]`. Returns `''` when the
+ * Markdown brief for `trail.steps[stepIndex]`. Returns `''` when the
  * index is out of range so a caller can treat it as "nothing to copy".
  */
-export function buildStepBrief(walkthrough, stepIndex) {
-    const step = walkthrough.steps[stepIndex];
+export function buildStepBrief(trail, stepIndex) {
+    const step = trail.steps[stepIndex];
     if (!step)
         return '';
     const lines = [];
-    lines.push(`Walkthrough: ${walkthrough.title} (${walkthrough.id}) — step ${stepIndex + 1}/${walkthrough.steps.length}`);
+    lines.push(`Trail: ${trail.title} (${trail.id}) — step ${stepIndex + 1}/${trail.steps.length}`);
     lines.push('');
     lines.push(`- from: \`${step.from}\``);
     lines.push(`- to: \`${step.to}\``);
@@ -31,4 +31,4 @@ export function buildStepBrief(walkthrough, stepIndex) {
     }
     return lines.join('\n');
 }
-//# sourceMappingURL=walkthroughBrief.js.map
+//# sourceMappingURL=trailBrief.js.map

package/dist/subsystem/trailBrief.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"trailBrief.js","sourceRoot":"","sources":["../../src/subsystem/trailBrief.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH;;;GAGG;AACH,MAAM,UAAU,cAAc,CAC5B,KAAqB,EACrB,SAAiB;IAEjB,MAAM,IAAI,GAAG,KAAK,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;IACpC,IAAI,CAAC,IAAI;QAAE,OAAO,EAAE,CAAC;IACrB,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,CAAC,IAAI,CACR,UAAU,KAAK,CAAC,KAAK,KAAK,KAAK,CAAC,EAAE,YAAY,SAAS,GAAG,CAAC,IAAI,KAAK,CAAC,KAAK,CAAC,MAAM,EAAE,CACpF,CAAC;IACF,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACf,KAAK,CAAC,IAAI,CAAC,aAAa,IAAI,CAAC,IAAI,IAAI,CAAC,CAAC;IACvC,KAAK,CAAC,IAAI,CAAC,WAAW,IAAI,CAAC,EAAE,IAAI,CAAC,CAAC;IACnC,KAAK,CAAC,IAAI,CAAC,kBAAkB,IAAI,CAAC,SAAS,IAAI,CAAC,CAAC;IACjD,KAAK,CAAC,IAAI,CAAC,eAAe,IAAI,CAAC,MAAM,IAAI,CAAC,CAAC;IAC3C,KAAK,CAAC,IAAI,CAAC,aAAa,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,IAAI,IAAI,CAAC,CAAC;IACpD,KAAK,CAAC,IAAI,CAAC,aAAa,IAAI,CAAC,IAAI,IAAI,CAAC,CAAC;IACvC,IAAI,IAAI,CAAC,UAAU,IAAI,IAAI,IAAI,IAAI,CAAC,UAAU,CAAC,MAAM,GAAG,CAAC,EAAE;QACzD,KAAK,CAAC,IAAI,CAAC,WAAW,IAAI,CAAC,UAAU,EAAE,CAAC,CAAC;KAC1C;IACD,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@principal-ai/subsystems-react",
-  "version": "0.44.3",
+  "version": "0.45.0",
   "description": "React UI for Subsystem Models — graph, Pierre code views, and session-event feeds",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -38,7 +38,7 @@
   "peerDependencies": {
     "@pierre/diffs": ">=1.1.20",
     "@principal-ade/industry-theme": "^0.1.7",
-    "@principal-ai/subsystems-core": "^0.42.0",
+    "@principal-ai/subsystems-core": "^0.44.0",
     "react": "^18.0.0 || ^19.0.0",
     "react-dom": "^18.0.0 || ^19.0.0"
   },
@@ -46,7 +46,7 @@
     "@pierre/diffs": "1.3.6",
     "@principal-ade/industry-theme": "0.1.7",
     "@principal-ai/agent-monitoring": "^0.3.38",
-    "@principal-ai/subsystems-core": "^0.42.0",
+    "@principal-ai/subsystems-core": "^0.44.0",
     "@storybook/addon-docs": "10.1.2",
     "@storybook/addon-links": "10.1.2",
     "@storybook/addon-onboarding": "10.1.2",

package/src/index.ts

@@ -100,7 +100,7 @@ export type { UseElkLayoutOptions, UseElkLayoutResult } from './hooks/useElkLayo
 
 // Subsystem component graph
 export { SubsystemComponentGraph } from './subsystem/SubsystemComponentGraph';
-export type { SubsystemComponentGraphProps, WalkthroughViewerContext } from './subsystem/SubsystemComponentGraph';
+export type { SubsystemComponentGraphProps, TrailViewerContext } from './subsystem/SubsystemComponentGraph';
 export { SubsystemModelTransition } from './subsystem/SubsystemModelTransition';
 export type {
   SubsystemModelTransitionProps,
@@ -205,12 +205,12 @@ export type {
 export { SubsystemFileTree } from './subsystem/SubsystemFileTree';
 export type { SubsystemFileTreeProps } from './subsystem/SubsystemFileTree';
 export {
-  WalkthroughsPanel,
-  WALKTHROUGH_PLAY_PAUSE_MS,
+  TrailsPanel,
+  TRAIL_PLAY_PAUSE_MS,
   STEP_COPY_FEEDBACK_MS,
-} from './subsystem/WalkthroughsPanel';
-export type { WalkthroughsPanelProps } from './subsystem/WalkthroughsPanel';
-export { buildStepBrief } from './subsystem/walkthroughBrief';
+} from './subsystem/TrailsPanel';
+export type { TrailsPanelProps } from './subsystem/TrailsPanel';
+export { buildStepBrief } from './subsystem/trailBrief';
 export { GraphLayoutCover } from './subsystem/GraphLayoutCover';
 export type { GraphLayoutCoverProps } from './subsystem/GraphLayoutCover';
 export {
@@ -222,9 +222,9 @@ export type {
   SubsystemComponent,
   SubsystemGraphNodeData,
   SubsystemComponentEdge,
-  SubsystemWalkthrough,
-  SubsystemWalkthroughStep,
-  SubsystemWalkthroughMechanism,
+  SubsystemTrail,
+  SubsystemTrailStep,
+  SubsystemTrailMechanism,
   SubsystemModelDocument,
   SubsystemComponentConstruct,
   SubsystemComponentRole,
@@ -249,11 +249,11 @@ export {
   deriveGraphEdges,
   isConstructsOnlyModel,
   derivedGraphEdgeId,
-  walkthroughStepGraphEdgeId,
-  reorderWalkthroughs,
+  trailStepGraphEdgeId,
+  reorderTrails,
   reorderTargetIndex,
-  isWalkthroughMechanism,
-  SUBSYSTEM_WALKTHROUGH_MECHANISMS,
+  isTrailMechanism,
+  SUBSYSTEM_TRAIL_MECHANISMS,
   ROLE_COLOR,
   ROLE_LABEL,
   FRAMEWORK_BADGE_COLOR,
@@ -277,11 +277,11 @@ export {
 export type { PrettierBundle } from './subsystem/prettierProvider';
 
 // Pierre code views (@pierre/diffs wrappers)
-export { PierreFileView, PierreSnippetView, PierreWalkthroughCodeView, sliceSnippetWindow, resolvePierreSyntaxThemeName } from './pierre';
+export { PierreFileView, PierreSnippetView, PierreTrailCodeView, sliceSnippetWindow, resolvePierreSyntaxThemeName } from './pierre';
 export type {
   PierreFileViewProps,
   PierreSnippetViewProps,
-  PierreWalkthroughCodeViewProps,
+  PierreTrailCodeViewProps,
   SnippetSlice,
   PierreSyntaxThemeName,
 } from './pierre';

package/src/pierre/{PierreWalkthroughCodeView.tsx → PierreTrailCodeView.tsx}

@@ -1,7 +1,7 @@
 /**
- * PierreWalkthroughCodeView — multi-file step snippets via `@pierre/diffs` CodeView.
+ * PierreTrailCodeView — multi-file step snippets via `@pierre/diffs` CodeView.
  *
- * Renders one sliced window per walkthrough step in a single virtualized
+ * Renders one sliced window per trail step in a single virtualized
  * scroll; when `stepIndex` changes, scrolls that step's site line into view
  * and highlights it via CodeView `selectedLines` (same mechanism as
  * `PierreSnippetView`).
@@ -31,12 +31,12 @@ type CodeViewLineSelection = {
   id: string;
   range: { start: number; end: number };
 };
-/** Metadata carried on a walkthrough step's line annotation. */
-type WalkthroughStepAnnotation = { text: string };
+/** Metadata carried on a trail step's line annotation. */
+type TrailStepAnnotation = { text: string };
 import { useTheme } from '@principal-ade/industry-theme';
 import type {
-  SubsystemWalkthrough,
-  SubsystemWalkthroughStep,
+  SubsystemTrail,
+  SubsystemTrailStep,
 } from '../subsystem/model';
 import type { SubsystemOpenFileOptions } from '../subsystem/declarationRef';
 import { buildPierreOptions, PIERRE_FILE_STYLE } from './pierreBackground';
@@ -51,15 +51,15 @@ import {
 
 /**
  * A token the user clicked or hovered inside a step's snippet. `stepIndex` is
- * the zero-based index of the walkthrough step whose snippet it sits in, so a
+ * the zero-based index of the trail step whose snippet it sits in, so a
  * host can resolve the token against that step's construct endpoints.
  */
-export interface WalkthroughSymbolQuery {
+export interface TrailSymbolQuery {
   stepIndex: number;
   tokenText: string;
 }
 
-/** Ctx item id → step index, for CodeView's `walkthroughId:index` item ids. */
+/** Ctx item id → step index, for CodeView's `trailId:index` item ids. */
 function stepIndexFromItemContext(context: unknown): number | null {
   const id = (context as { item?: { id?: string } } | undefined)?.item?.id;
   if (id == null) return null;
@@ -76,8 +76,8 @@ function paintSymbolToken(el: HTMLElement | undefined, active: boolean): void {
   el.style.textUnderlineOffset = active ? '2px' : '';
 }
 
-export interface PierreWalkthroughCodeViewProps {
-  walkthrough: SubsystemWalkthrough;
+export interface PierreTrailCodeViewProps {
+  trail: SubsystemTrail;
   /** Focused step; `null` shows all snippets without scrolling to a step. */
   stepIndex: number | null;
   /** Read a step site; `purl` names the seam site's repo for checkout resolution. */
@@ -99,9 +99,9 @@ export interface PierreWalkthroughCodeViewProps {
    * construct this flow touches. When both this and `onSymbolClick` are set,
    * matching tokens read as clickable (pointer + dotted underline).
    */
-  resolveSymbol?: (query: WalkthroughSymbolQuery) => string | null;
+  resolveSymbol?: (query: TrailSymbolQuery) => string | null;
   /** Fired when a token resolved by `resolveSymbol` is clicked. */
-  onSymbolClick?: (symbol: string, query: WalkthroughSymbolQuery) => void;
+  onSymbolClick?: (symbol: string, query: TrailSymbolQuery) => void;
 }
 
 type FileLoadState =
@@ -113,18 +113,18 @@ type FileLoadState =
       unavailable: Map<string, string>;
     };
 
-function stepItemId(walkthroughId: string, index: number): string {
-  return `${walkthroughId}:${index}`;
+function stepItemId(trailId: string, index: number): string {
+  return `${trailId}:${index}`;
 }
 
 /** Stable key for a step's file within a repo (mirrors `pathsKey`). */
-function siteKey(step: Pick<SubsystemWalkthroughStep, 'purl' | 'file'>): string {
+function siteKey(step: Pick<SubsystemTrailStep, 'purl' | 'file'>): string {
   return `${step.purl}\0${step.file}`;
 }
 
 /** Notice shown in place of a snippet whose file the host couldn't read. */
 function unavailableNotice(
-  step: SubsystemWalkthroughStep,
+  step: SubsystemTrailStep,
   error: string,
   proposed: boolean,
 ): string {
@@ -186,8 +186,8 @@ function OpenFileHeaderButton({
   );
 }
 
-export function PierreWalkthroughCodeView({
-  walkthrough,
+export function PierreTrailCodeView({
+  trail,
   stepIndex,
   readFile,
   contextLines = 8,
@@ -196,7 +196,7 @@ export function PierreWalkthroughCodeView({
   proposedAliases,
   resolveSymbol,
   onSymbolClick,
-}: PierreWalkthroughCodeViewProps) {
+}: PierreTrailCodeViewProps) {
   const { theme, mode } = useTheme();
   const viewRef = useRef<CodeViewHandle<undefined>>(null);
   const [load, setLoad] = useState<FileLoadState>({ status: 'loading' });
@@ -208,28 +208,28 @@ export function PierreWalkthroughCodeView({
   const onSymbolClickRef = useRef(onSymbolClick);
   onSymbolClickRef.current = onSymbolClick;
 
-  // A hop onto a proposed component is planned work; label its missing file
+  // A step onto a proposed component is planned work; label its missing file
   // accordingly instead of showing a bare "not found".
   const isProposedStep = useCallback(
-    (step: SubsystemWalkthroughStep): boolean =>
+    (step: SubsystemTrailStep): boolean =>
       proposedAliases != null &&
       (proposedAliases.has(step.from) || proposedAliases.has(step.to)),
     [proposedAliases],
   );
 
   const pathsKey = useMemo(() => {
-    const keys = [...new Set(walkthrough.steps.map((s) => siteKey(s)))];
+    const keys = [...new Set(trail.steps.map((s) => siteKey(s)))];
     keys.sort();
     return keys.join('\0');
-  }, [walkthrough.steps]);
+  }, [trail.steps]);
 
   // Load each site independently: one unreadable step (a proposed seam whose
-  // file isn't implemented yet) must not blank the whole walkthrough. Failures
+  // file isn't implemented yet) must not blank the whole trail. Failures
   // are kept per-path and rendered as inline placeholders below.
   useEffect(() => {
     let cancelled = false;
     setLoad({ status: 'loading' });
-    const sites = [...new Map(walkthrough.steps.map((s) => [siteKey(s), s])).values()];
+    const sites = [...new Map(trail.steps.map((s) => [siteKey(s), s])).values()];
     void Promise.all(
       sites.map(async (step) => {
         const key = siteKey(step);
@@ -257,11 +257,11 @@ export function PierreWalkthroughCodeView({
     return () => {
       cancelled = true;
     };
-  }, [walkthrough.id, pathsKey, readFile]);
+  }, [trail.id, pathsKey, readFile]);
 
   const slices = useMemo((): SnippetSlice[] => {
     if (load.status !== 'ready') return [];
-    return walkthrough.steps.map((step) => {
+    return trail.steps.map((step) => {
       const key = siteKey(step);
       const failure = load.unavailable.get(key);
       if (failure != null) {
@@ -278,11 +278,11 @@ export function PierreWalkthroughCodeView({
         step.line,
       );
     });
-  }, [load, walkthrough.steps, contextLines, isProposedStep]);
+  }, [load, trail.steps, contextLines, isProposedStep]);
 
-  const items = useMemo((): CodeViewItem<WalkthroughStepAnnotation>[] => {
+  const items = useMemo((): CodeViewItem<TrailStepAnnotation>[] => {
     if (load.status !== 'ready' || slices.length === 0) return [];
-    return walkthrough.steps.map((step, index) => {
+    return trail.steps.map((step, index) => {
       const slice = slices[index]!;
       const focus = slice.focusOffset;
       const key = siteKey(step);
@@ -290,7 +290,7 @@ export function PierreWalkthroughCodeView({
       // The placeholder line already carries the reason, so it replaces any
       // authored annotation rather than stacking with it.
       const annotations:
-        | LineAnnotation<WalkthroughStepAnnotation>[]
+        | LineAnnotation<TrailStepAnnotation>[]
         | undefined =
         failure == null &&
         step.annotation != null &&
@@ -304,7 +304,7 @@ export function PierreWalkthroughCodeView({
             ]
           : undefined;
       return {
-        id: stepItemId(walkthrough.id, index),
+        id: stepItemId(trail.id, index),
         type: 'file' as const,
         version: 1,
         annotations,
@@ -312,11 +312,11 @@ export function PierreWalkthroughCodeView({
           name: step.file,
           contents: slice.contents,
           lang: pierreLangForPath(step.file),
-          cacheKey: `${walkthrough.id}:${index}:${step.file}:${step.line}:${slice.sliceStart}-${slice.sliceEnd}${failure != null ? ':unavailable' : ''}`,
+          cacheKey: `${trail.id}:${index}:${step.file}:${step.line}:${slice.sliceStart}-${slice.sliceEnd}${failure != null ? ':unavailable' : ''}`,
         },
       };
     });
-  }, [load, slices, walkthrough.id, walkthrough.steps, isProposedStep]);
+  }, [load, slices, trail.id, trail.steps, isProposedStep]);
 
   const selectedLines = useMemo((): CodeViewLineSelection | null => {
     if (stepIndex == null || stepIndex < 0 || stepIndex >= slices.length) {
@@ -325,18 +325,18 @@ export function PierreWalkthroughCodeView({
     const focus = slices[stepIndex]?.focusOffset;
     if (focus == null) return null;
     return {
-      id: stepItemId(walkthrough.id, stepIndex),
+      id: stepItemId(trail.id, stepIndex),
       range: { start: focus, end: focus },
     };
-  }, [stepIndex, slices, walkthrough.id]);
+  }, [stepIndex, slices, trail.id]);
 
   const sliceStartByItemId = useMemo(() => {
     const map = new Map<string, number>();
     for (let i = 0; i < slices.length; i++) {
-      map.set(stepItemId(walkthrough.id, i), slices[i]!.sliceStart);
+      map.set(stepItemId(trail.id, i), slices[i]!.sliceStart);
     }
     return map;
-  }, [slices, walkthrough.id]);
+  }, [slices, trail.id]);
 
   const onPostRender = useCallback(
     (
@@ -357,7 +357,7 @@ export function PierreWalkthroughCodeView({
   const renderHeaderPrefix = useMemo(() => {
     return (item: CodeViewItem) => {
       const index = Number.parseInt(item.id.split(':').pop() ?? '', 10);
-      if (!walkthrough.steps[index]) return null;
+      if (!trail.steps[index]) return null;
       return (
         <span
           style={{
@@ -371,12 +371,12 @@ export function PierreWalkthroughCodeView({
         </span>
       );
     };
-  }, [walkthrough.steps, theme]);
+  }, [trail.steps, theme]);
 
   const renderHeaderMetadata = useMemo(() => {
     return (item: CodeViewItem) => {
       const index = Number.parseInt(item.id.split(':').pop() ?? '', 10);
-      const step = walkthrough.steps[index];
+      const step = trail.steps[index];
       if (!step) return null;
       // Unreadable sites have nothing to open — say so instead of offering a
       // button that would only fail again in the full-file overlay.
@@ -413,17 +413,17 @@ export function PierreWalkthroughCodeView({
         </span>
       );
     };
-  }, [walkthrough.steps, theme, onOpenFile, load]);
+  }, [trail.steps, theme, onOpenFile, load]);
 
   const renderAnnotation = useMemo(() => {
     return (
       annotation:
-        | LineAnnotation<WalkthroughStepAnnotation>
-        | DiffLineAnnotation<WalkthroughStepAnnotation>,
-      item: CodeViewItem<WalkthroughStepAnnotation>,
+        | LineAnnotation<TrailStepAnnotation>
+        | DiffLineAnnotation<TrailStepAnnotation>,
+      item: CodeViewItem<TrailStepAnnotation>,
     ) => {
       const index = Number.parseInt(item.id.split(':').pop() ?? '', 10);
-      const step = walkthrough.steps[index];
+      const step = trail.steps[index];
       const text = annotation.metadata?.text;
       if (!text || !step) return null;
       return (
@@ -441,7 +441,7 @@ export function PierreWalkthroughCodeView({
         </span>
       );
     };
-  }, [walkthrough.steps, theme]);
+  }, [trail.steps, theme]);
 
   const onLineClick = useCallback(
     (
@@ -453,12 +453,12 @@ export function PierreWalkthroughCodeView({
       const id = context?.item?.id;
       if (id == null) return;
       const index = Number.parseInt(id.split(':').pop() ?? '', 10);
-      const step = walkthrough.steps[index];
+      const step = trail.steps[index];
       if (!step) return;
       if (load.status === 'ready' && load.unavailable.has(siteKey(step))) return;
       onOpenFile(step.file, { startLine: step.line, fullFile: true });
     },
-    [onOpenFile, walkthrough.steps, load],
+    [onOpenFile, trail.steps, load],
   );
 
   // Per-token interactions for construct navigation. Only wired when the host
@@ -469,7 +469,7 @@ export function PierreWalkthroughCodeView({
     const resolveAt = (
       props: TokenEventBase,
       context: unknown,
-    ): { symbol: string; query: WalkthroughSymbolQuery } | null => {
+    ): { symbol: string; query: TrailSymbolQuery } | null => {
       const stepIndex = stepIndexFromItemContext(context);
       const tokenText = props?.tokenText;
       if (stepIndex == null || !tokenText) return null;
@@ -507,10 +507,10 @@ export function PierreWalkthroughCodeView({
 
   useEffect(() => {
     if (load.status !== 'ready' || stepIndex == null) return;
-    if (stepIndex < 0 || stepIndex >= walkthrough.steps.length) return;
+    if (stepIndex < 0 || stepIndex >= trail.steps.length) return;
     const focus = slices[stepIndex]?.focusOffset;
     if (focus == null) return;
-    const id = stepItemId(walkthrough.id, stepIndex);
+    const id = stepItemId(trail.id, stepIndex);
     const t = window.setTimeout(() => {
       viewRef.current?.scrollTo({
         type: 'line',
@@ -523,8 +523,8 @@ export function PierreWalkthroughCodeView({
   }, [
     load.status,
     stepIndex,
-    walkthrough.id,
-    walkthrough.steps.length,
+    trail.id,
+    trail.steps.length,
     slices,
     items.length,
   ]);
@@ -539,7 +539,7 @@ export function PierreWalkthroughCodeView({
   if (items.length === 0) {
     return (
       <div style={{ padding: 16, color: theme.colors.textSecondary }}>
-        No steps in this walkthrough.
+        No steps in this trail.
       </div>
     );
   }

package/src/pierre/index.ts

@@ -2,8 +2,8 @@ export { PierreFileView } from './PierreFileView';
 export type { PierreFileViewProps } from './PierreFileView';
 export { PierreSnippetView } from './PierreSnippetView';
 export type { PierreSnippetViewProps } from './PierreSnippetView';
-export { PierreWalkthroughCodeView } from './PierreWalkthroughCodeView';
-export type { PierreWalkthroughCodeViewProps } from './PierreWalkthroughCodeView';
+export { PierreTrailCodeView } from './PierreTrailCodeView';
+export type { PierreTrailCodeViewProps } from './PierreTrailCodeView';
 export { remapSnippetLineNumbers, sliceSnippetWindow } from './sliceSnippet';
 export type { SnippetSlice } from './sliceSnippet';
 export {

package/src/stories/Pierre/CodeView.stories.tsx

@@ -1,7 +1,7 @@
 /**
  * Demo: Pierre CodeView with snippets from different files.
  *
- * Walkthroughs want many short windows across files in one scroll —
+ * Trails want many short windows across files in one scroll —
  * CodeView is the Pierre primitive for that (virtualized list of file items).
  */
 import React, { useMemo, useRef } from 'react';
@@ -54,7 +54,7 @@ const SNIPPETS: SnippetSpec[] = [
     startLine: 216,
     endLine: 250,
     focusLine: 216,
-    label: '3 · Walkthrough types',
+    label: '3 · Trail types',
   },
 ];
 
@@ -159,7 +159,7 @@ function MultiFileSnippetsDemo() {
         }}
       >
         <div style={{ fontSize: 13, fontWeight: 600, marginBottom: 4 }}>
-          Walkthrough steps
+          Trail steps
         </div>
         <div style={{ fontSize: 12, color: theme.colors.textSecondary, marginBottom: 8 }}>
           Click a step to scroll + highlight its site line.

package/src/stories/Subsystem/AggregateGraph/AggregateFrameGraph.stories.tsx

@@ -29,7 +29,7 @@ export default meta;
 type Story = StoryObj<typeof meta>;
 
 // ---------------------------------------------------------------------------
-// Frame-level aggregate: process/module boxes with deduped walkthrough flows.
+// Frame-level aggregate: process/module boxes with deduped trail flows.
 // Same stack as the component graph (React Flow + ELK), purpose-built nodes.
 // Hover highlights the neighborhood; click selects and lists members.
 // ---------------------------------------------------------------------------