@principal-ai/principal-view-react 0.16.49 → 0.16.51

package/src/subsystem/ComponentDeclaration.tsx

@@ -7,7 +7,7 @@
  */
 
 import { useEffect, useRef, useState, type ReactNode } from 'react';
-import { AlignLeft, FileText } from 'lucide-react';
+import { AlignLeft, FileText, ShieldCheck } from 'lucide-react';
 import { useTheme } from '@principal-ade/industry-theme';
 import {
   KIND_COLOR,
@@ -15,8 +15,64 @@ import {
   type SubsystemComponent,
   type SubsystemDeclTokenKind,
 } from './model';
+import type { SubsystemOpenFileOptions } from './declarationRef';
+import { parseSourceLocation } from './declarationRef';
 import { tokenizeComponent } from './tokenizeComponent';
 
+/** Live / result state for the declaration-panel Verify control. */
+export type ComponentVerificationPhase =
+  | 'idle'
+  | 'checking'
+  | 'done'
+  | 'error';
+
+export interface ComponentVerificationState {
+  phase: ComponentVerificationPhase;
+  message?: string;
+  /** Mirrors host `ok` when a structured verify result is available. */
+  ok?: boolean;
+  code?: string;
+  file?: {
+    exists: boolean;
+    symbolDeclared?: boolean | null;
+  };
+  cache?: {
+    status: 'ready' | 'missing' | 'unavailable';
+    purl: string;
+  };
+  anchor?: {
+    resolution: 'exact' | 'file-only' | 'ambiguous' | 'missing';
+    nodeId?: string;
+    label?: string;
+    source_file?: string;
+    source_location?: string;
+    candidates?: Array<{ nodeId: string; label: string; source_file?: string }>;
+  };
+  kind?: {
+    claimed: string;
+    inferred: string;
+    match: boolean;
+    evidence?: string[];
+  };
+  signature?: {
+    match: boolean;
+    skipped: boolean;
+    skipCode?: string;
+    reason?: string;
+    claimed: { parameterTypes: string[]; returnTypes: string[] };
+    inferred: { parameterTypes: string[]; returnTypes: string[] };
+    /** Graphify `inline_parameter` marker count (anonymous eager args). */
+    inlineParameters?: number;
+  };
+  declaration?: {
+    freshness: 'valid' | 'stale' | 'missing' | 'unanchored' | 'unchecked';
+    ref?: {
+      startLine: number;
+      lineHash: string;
+    };
+  };
+}
+
 /** Shared affordance for clickable text pieces. */
 const clickableStyle = {
   cursor: 'pointer',
@@ -46,31 +102,169 @@ function DetailLink({ children, onClick }: { children: ReactNode; onClick?: () =
   );
 }
 
-/** Panel props. The two callbacks are wired by the graph; standalone usage
- *  without them renders the same panel with nothing clickable. */
+/** Panel props. Callbacks are wired by the graph; standalone usage without
+ *  them renders the same panel with nothing clickable. */
 export interface ComponentDeclarationProps {
   component: SubsystemComponent;
-  /** File-path click → open that file in the bottom drawer. */
-  onOpenFile?: (file: string) => void;
+  /** File-path click → open that file in the bottom drawer (optional start line). */
+  onOpenFile?: (file: string, opts?: SubsystemOpenFileOptions) => void;
   /** Related-name click (types, callers/callees, implementors, …) → select
    *  that component if one matches; unmatched refs no-op. */
   onRelatedSelect?: (ref: string) => void;
   /** Max width of the declaration panel (CSS value). Defaults to none. */
   maxWidth?: string | number;
+  /** When set, shows a Verify control that calls back with the component id. */
+  onVerify?: (componentId: string) => void;
+  /** Live verification status for the selected component. */
+  verification?: ComponentVerificationState | null;
+}
+
+function verificationSummary(
+  v: ComponentVerificationState,
+  muted: string,
+  ok: string,
+  warn: string,
+): { text: string; color: string } {
+  if (v.phase === 'checking') {
+    return { text: v.message ?? 'Verifying…', color: muted };
+  }
+  if (v.phase === 'error') {
+    return { text: v.message ?? 'Verification failed', color: '#e5534b' };
+  }
+  if (v.phase !== 'done') {
+    return { text: '', color: muted };
+  }
+  const bits: string[] = [];
+  if (v.file) {
+    if (!v.file.exists) bits.push('file missing');
+    else if (v.file.symbolDeclared === false) bits.push('symbol not declared in file');
+    else if (v.file.symbolDeclared === true) bits.push('file+symbol ok');
+    else bits.push('file exists');
+  }
+  if (v.cache?.status === 'missing') {
+    return {
+      text: [...bits, 'graphify cache not ready — run graphify from Subsystems list'].join(' · '),
+      color: warn,
+    };
+  }
+  if (v.cache?.status === 'unavailable') {
+    return {
+      text: [...bits, 'no local checkout for this purl'].join(' · '),
+      color: muted,
+    };
+  }
+  const res = v.anchor?.resolution;
+  if (res === 'exact') {
+    const loc = v.anchor?.source_location ? ` @ ${v.anchor.source_location}` : '';
+    const declFresh = v.declaration?.freshness;
+    const declBit =
+      declFresh && declFresh !== 'unanchored'
+        ? ` · declaration ${declFresh}${v.declaration?.ref ? ` L${v.declaration.ref.startLine}` : ''}`
+        : '';
+    const anchorBit = `exact → ${v.anchor?.label ?? v.anchor?.nodeId ?? 'node'}${loc}${declBit}`;
+    if (v.kind && !v.kind.match) {
+      const why =
+        v.kind.inferred === 'unknown'
+          ? `kind unknown (claimed ${v.kind.claimed})`
+          : `kind mismatch: claimed ${v.kind.claimed}, inferred ${v.kind.inferred}`;
+      return {
+        text: [...bits, anchorBit, why].join(' · '),
+        color: '#e5534b',
+      };
+    }
+    if (v.signature && !v.signature.skipped && !v.signature.match) {
+      const cParams = v.signature.claimed.parameterTypes.join(', ') || '∅';
+      const iParams = v.signature.inferred.parameterTypes.join(', ') || '∅';
+      const cRet = v.signature.claimed.returnTypes.join(', ') || '∅';
+      const iRet = v.signature.inferred.returnTypes.join(', ') || '∅';
+      return {
+        text: [
+          ...bits,
+          anchorBit,
+          v.kind?.match ? `kind ${v.kind.inferred}` : undefined,
+          `signature mismatch: params [${cParams}]≠[${iParams}] return [${cRet}]≠[${iRet}]`,
+        ]
+          .filter(Boolean)
+          .join(' · '),
+        color: '#e5534b',
+      };
+    }
+    const kindBit =
+      v.kind?.match ? `kind ${v.kind.inferred}` : undefined;
+    const inlineBit =
+      v.signature?.inlineParameters
+        ? `${v.signature.inlineParameters} inline param${v.signature.inlineParameters === 1 ? '' : 's'} verified`
+        : undefined;
+    if (v.signature?.skipped) {
+      const skipPhrase: Record<string, string> = {
+        no_claimed_types: 'no claimable named types (primitives/inline only)',
+        generic_arg_only:
+          'return only as generic_arg — wrapper types (Promise/Omit/Map/Array) not read as return edges',
+        partially_generic_arg:
+          'claimed types resolve only via generic_arg; rest unresolved',
+        unresolved_claimed_types:
+          'claimed return type has no graphify edge (npm/global/DOM type)',
+      };
+      return {
+        text: [
+          ...bits,
+          anchorBit,
+          ...(kindBit ? [kindBit] : []),
+          ...(inlineBit ? [inlineBit] : []),
+          v.signature.skipCode
+            ? `params/return not fully checked — ${skipPhrase[v.signature.skipCode] ?? v.signature.skipCode}`
+            : 'params/return not checked',
+        ].join(' · '),
+        color: warn,
+      };
+    }
+    const sigBit =
+      v.signature && v.signature.match ? 'params/return ok' : undefined;
+    return {
+      text: [...bits, anchorBit, ...(kindBit ? [kindBit] : []), ...(sigBit ? [sigBit] : [])].join(' · '),
+      color: ok,
+    };
+  }
+  if (res === 'file-only') {
+    return {
+      text: [...bits, 'file in graph, symbol not uniquely matched'].join(' · '),
+      color: warn,
+    };
+  }
+  if (res === 'ambiguous') {
+    const n = v.anchor?.candidates?.length ?? 0;
+    return {
+      text: [...bits, `ambiguous (${n} candidates)`].join(' · '),
+      color: warn,
+    };
+  }
+  if (res === 'missing') {
+    return {
+      text: [...bits, 'no matching graphify node'].join(' · '),
+      color: '#e5534b',
+    };
+  }
+  return { text: bits.join(' · ') || 'done', color: muted };
 }
 
 /** Declaration panel for the selected component — its definition, code-style. */
-export function ComponentDeclaration({ component, onOpenFile, onRelatedSelect: _onRelatedSelect, maxWidth }: ComponentDeclarationProps) {
+export function ComponentDeclaration({
+  component,
+  onOpenFile,
+  onRelatedSelect: _onRelatedSelect,
+  maxWidth,
+  onVerify,
+  verification,
+}: ComponentDeclarationProps) {
   const { theme } = useTheme();
   const [fileHovered, setFileHovered] = useState(false);
-  // Header visibility toggles — off by default so the panel opens as pure
-  // code; the repo-row icons bring the path and description back.
   const [showFile, setShowFile] = useState(false);
   const [showPurpose, setShowPurpose] = useState(false);
   const muted = theme.colors.textMuted ?? theme.colors.textSecondary;
   const color = KIND_COLOR[component.kind] ?? '#888';
+  const okColor = '#3d9a5f';
+  const warnColor = theme.colors.textSecondary;
 
-  // Token-kind → theme-color map (used by the token iterator below).
   const tokenColor: Record<SubsystemDeclTokenKind, string> = {
     keyword: theme.colors.secondary,
     name: color,
@@ -78,7 +272,7 @@ export function ComponentDeclaration({ component, onOpenFile, onRelatedSelect: _
     type: theme.colors.accent,
     punctuation: muted,
     string: theme.colors.success,
-    newline: '', // not rendered — drives line breaks
+    newline: '',
   };
 
   const line = (children: ReactNode, key?: string, indent?: boolean | number) => {
@@ -98,9 +292,6 @@ export function ComponentDeclaration({ component, onOpenFile, onRelatedSelect: _
       key,
       indent,
     );
-  // Purpose is the panel's actual prose, not code — body font, readable
-  // size/contrast, capped measure. The `//` metadata lines above it stay
-  // muted mono on purpose.
   const purposeStyle = {
     color: theme.colors.text,
     fontFamily: theme.fonts.body,
@@ -108,17 +299,9 @@ export function ComponentDeclaration({ component, onOpenFile, onRelatedSelect: _
     lineHeight: 1.5,
     maxWidth: '52ch',
   } as const;
-  // Trailing relationship comments (`// called by:`, `// constructed by:`,
-  // `// implemented by:`, …) are deliberately not rendered — the graph's
-  // edges carry interactions, and duplicated name lists read as clutter. The
-  // data stays on the Graphify detail types for other surfaces.
+
   const lines: ReactNode[] = [];
-  // Repo identity — owner avatar + name for GitHub-hosted purls; anything
-  // else falls back to the formatted purl as a quiet comment. The avatar
-  // hides itself on load failure (offline / blocked hosts).
   const ghMatch = /^pkg:github\/([^/]+)\/([^/#?]+)/.exec(component.purl ?? '');
-  // Small ghost icon button for the header toggles — accent when its section
-  // is shown, muted when hidden.
   const toggleBtn = (on: boolean, onClick: () => void, title: string, Icon: typeof FileText) => (
     <button
       type="button"
@@ -142,6 +325,44 @@ export function ComponentDeclaration({ component, onOpenFile, onRelatedSelect: _
       <Icon size={13} />
     </button>
   );
+  const verifyBusy = verification?.phase === 'checking';
+  const headerActions = (
+    <span style={{ marginLeft: 'auto', display: 'flex', alignItems: 'center', gap: 2 }}>
+      {onVerify && (
+        <button
+          type="button"
+          title="Verify against graphify"
+          aria-label="Verify against graphify"
+          disabled={verifyBusy}
+          onClick={(e) => {
+            e.stopPropagation();
+            onVerify(component.id);
+          }}
+          style={{
+            display: 'flex',
+            alignItems: 'center',
+            gap: 4,
+            height: 20,
+            padding: '0 6px',
+            border: `1px solid ${theme.colors.border}`,
+            borderRadius: 4,
+            background: 'transparent',
+            color: verifyBusy ? muted : theme.colors.textSecondary,
+            cursor: verifyBusy ? 'wait' : 'pointer',
+            fontSize: theme.fontSizes[0],
+            fontFamily: theme.fonts.body,
+            opacity: verifyBusy ? 0.7 : 1,
+          }}
+        >
+          <ShieldCheck size={12} />
+          {verifyBusy ? '…' : 'Verify'}
+        </button>
+      )}
+      {toggleBtn(showFile, () => setShowFile((v) => !v), 'Toggle file path', FileText)}
+      {toggleBtn(showPurpose, () => setShowPurpose((v) => !v), 'Toggle description', AlignLeft)}
+    </span>
+  );
+
   if (ghMatch) {
     const [, ghOwner, ghRepo] = ghMatch;
     lines.push(
@@ -166,27 +387,87 @@ export function ComponentDeclaration({ component, onOpenFile, onRelatedSelect: _
           >
             {ghRepo}
           </span>
-          <span style={{ marginLeft: 'auto', display: 'flex', alignItems: 'center', gap: 2 }}>
-            {toggleBtn(showFile, () => setShowFile((v) => !v), 'Toggle file path', FileText)}
-            {toggleBtn(showPurpose, () => setShowPurpose((v) => !v), 'Toggle description', AlignLeft)}
-          </span>
+          {headerActions}
         </span>,
         'repo',
       ),
     );
   } else if (component.purl) {
-    lines.push(commentLine(`// ${formatPurl(component.purl)}`, 'purl'));
+    lines.push(
+      line(
+        <span style={{ display: 'flex', alignItems: 'center', gap: 6, width: '100%' }}>
+          <span style={commentStyle}>{`// ${formatPurl(component.purl)}`}</span>
+          {headerActions}
+        </span>,
+        'purl',
+      ),
+    );
+  } else if (onVerify) {
+    lines.push(line(headerActions, 'actions'));
+  }
+
+  if (verification && verification.phase !== 'idle') {
+    const summary = verificationSummary(verification, muted, okColor, warnColor);
+    if (summary.text) {
+      lines.push(
+        line(
+          <span
+            style={{
+              color: summary.color,
+              fontFamily: theme.fonts.body,
+              fontSize: theme.fontSizes[0],
+              whiteSpace: 'normal',
+            }}
+          >
+            {summary.text}
+          </span>,
+          'verify-status',
+        ),
+      );
+    }
+    if (
+      verification.anchor?.resolution === 'ambiguous' &&
+      verification.anchor.candidates &&
+      verification.anchor.candidates.length > 0
+    ) {
+      for (const c of verification.anchor.candidates.slice(0, 5)) {
+        lines.push(
+          commentLine(
+            `//   ${c.label}${c.source_file ? ` — ${c.source_file}` : ''}`,
+            `cand-${c.nodeId}`,
+          ),
+        );
+      }
+    }
+    if (verification.signature?.skipped && verification.signature.reason) {
+      lines.push(
+        commentLine(
+          `// why: ${verification.signature.reason}`,
+          'verify-skip-reason',
+        ),
+      );
+    }
   }
-  if (showFile && component.file)
+
+  if (showFile && component.file) {
+    const startLine =
+      component.declarationRef?.startLine ??
+      verification?.declaration?.ref?.startLine ??
+      parseSourceLocation(verification?.anchor?.source_location) ??
+      undefined;
     lines.push(
       line(
-        <DetailLink onClick={onOpenFile ? () => onOpenFile(component.file) : undefined}>
+        <DetailLink
+          onClick={
+            onOpenFile
+              ? () => onOpenFile(component.file, startLine != null ? { startLine } : undefined)
+              : undefined
+          }
+        >
           <span
             onMouseEnter={() => setFileHovered(true)}
             onMouseLeave={() => setFileHovered(false)}
             style={{
-              // Path as UI text, not a code comment — matches the repo-name
-              // row. Quiet until hover; the underline only appears then.
               color: theme.colors.textSecondary ?? muted,
               fontFamily: theme.fonts.body,
               fontSize: theme.fontSizes[1],
@@ -195,15 +476,14 @@ export function ComponentDeclaration({ component, onOpenFile, onRelatedSelect: _
             }}
           >
             {component.file}
+            {startLine != null ? `:${startLine}` : ''}
           </span>
         </DetailLink>,
         'file',
       ),
     );
+  }
 
-  // --- Container width measurement --------------------------------------
-  // Approximate character count from the container's clientWidth so Prettier
-  // wraps at the same column the code block will actually use.
   const containerRef = useRef<HTMLDivElement>(null);
   const [printWidth, setPrintWidth] = useState(80);
 
@@ -212,8 +492,6 @@ export function ComponentDeclaration({ component, onOpenFile, onRelatedSelect: _
     if (!el) return;
 
     function measureWidth() {
-      // Measure a single `ch` using an offscreen element so we don't disturb
-      // the component's own DOM.
       const probe = document.createElement('div');
       probe.style.cssText =
         'position:absolute;visibility:hidden;white-space:pre;' +
@@ -233,9 +511,6 @@ export function ComponentDeclaration({ component, onOpenFile, onRelatedSelect: _
     return () => ro.disconnect();
   }, []);
 
-  // --- Declaration tokens ------------------------------------------------
-  // Tokenize asynchronously via Prettier + highlight.js. Pre-tokenized
-  // tokens from the wire skip the pipeline entirely.
   const [tokens, setTokens] = useState(component.tokens ?? []);
   useEffect(() => {
     if (component.tokens) {
@@ -246,7 +521,9 @@ export function ComponentDeclaration({ component, onOpenFile, onRelatedSelect: _
     tokenizeComponent(component, printWidth).then((t) => {
       if (!cancelled) setTokens(t);
     });
-    return () => { cancelled = true; };
+    return () => {
+      cancelled = true;
+    };
   }, [component, printWidth]);
   const declLines: ReactNode[][] = [[]];
   let di = 0;
@@ -271,12 +548,9 @@ export function ComponentDeclaration({ component, onOpenFile, onRelatedSelect: _
     );
   }
 
-  // Purpose prose follows the declaration — identity and syntax first, the
-  // explanation underneath. Newlines split into separate prose lines so a
-  // two-thought purpose reads as a short paragraph instead of one blob.
   if (showPurpose && component.purpose) {
     lines.push(line(<div style={{ height: 6 }} />, 'purpose-gap'));
-    component.purpose.split("\n").forEach((purposeLine, i) =>
+    component.purpose.split('\n').forEach((purposeLine, i) =>
       lines.push(
         line(
           <span style={{ ...purposeStyle, display: 'block' }} key={`purpose${i}`}>

package/src/subsystem/SubsystemComponentGraph.tsx

@@ -41,10 +41,12 @@ import {
   type SubsystemComponent,
   type SubsystemEdgeMechanism,
 } from './model';
+import type { SubsystemOpenFileOptions } from './declarationRef';
 import { SubsystemComponentNode, SubsystemEdge, SUBSYSTEM_CALLBACKS } from './nodes';
 import { SubsystemFileTree } from './SubsystemFileTree';
 import { GraphLayoutCover } from './GraphLayoutCover';
 import { ComponentDeclaration } from './ComponentDeclaration';
+import type { ComponentVerificationState } from './ComponentDeclaration';
 import { FileDrawer } from './FileDrawer';
 import { EdgeLegendModal, MECHANISM_DESCRIPTIONS } from './EdgeLegendModal';
 import { buildRepoGroups, repoAvatarUrl, type RepoGroup } from './paths';
@@ -76,7 +78,7 @@ export interface SubsystemComponentGraphProps {
    * `file`) and sidebar file-tree click. Keeps this package free of fs and
    * code-view dependencies.
    */
-  renderFileViewer?: (file: string) => ReactNode;
+  renderFileViewer?: (file: string, opts?: SubsystemOpenFileOptions) => ReactNode;
   /**
    * Legacy component-keyed variant, kept for backward compatibility. When
    * `renderFileViewer` is absent, drawer content resolves via the first
@@ -88,6 +90,10 @@ export interface SubsystemComponentGraphProps {
    * path). The tree is derived from the components' `file` values.
    */
   onFileSelect?: (file: string) => void;
+  /** Verify the selected component against graphify (declaration panel). */
+  onVerifyComponent?: (componentId: string) => void;
+  /** Live verification status for the selected component. */
+  componentVerification?: ComponentVerificationState | null;
 }
 
 const nodeTypes: NodeTypes = {
@@ -105,19 +111,21 @@ const edgeTypes: EdgeTypes = {
 const DrawerContent = memo(function DrawerContent({
   render,
   file,
+  startLine,
 }: {
-  render: (file: string) => ReactNode;
+  render: (file: string, opts?: SubsystemOpenFileOptions) => ReactNode;
   file: string | null;
+  startLine?: number;
 }) {
   if (!file) return null;
-  return <>{render(file)}</>;
+  return <>{render(file, startLine != null ? { startLine } : undefined)}</>;
 });
 
 interface InnerProps extends SubsystemComponentGraphProps {
   measured: { w: number; h: number } | null;
 }
 
-function Inner({ components, edges, onSelect, onEdgeSelect, measured: _measured, maxNodeWidth, showEdgeLabels, title, description, canvasOverlay, sidebarExtra, sidebarAfterDescription, renderFileView, renderFileViewer, onFileSelect }: InnerProps) {
+function Inner({ components, edges, onSelect, onEdgeSelect, measured: _measured, maxNodeWidth, showEdgeLabels, title, description, canvasOverlay, sidebarExtra, sidebarAfterDescription, renderFileView, renderFileViewer, onFileSelect, onVerifyComponent, componentVerification }: InnerProps) {
   const { theme } = useTheme();
   const { fitView } = useReactFlow();
   const viewport = useViewport();
@@ -127,8 +135,13 @@ function Inner({ components, edges, onSelect, onEdgeSelect, measured: _measured,
   });
   const [layoutReady, setLayoutReady] = useState(false);
   const [selected, setSelected] = useState<SubsystemComponent | null>(null);
-  // File currently shown in the bottom drawer (repo-root-relative path).
-  const [openFile, setOpenFile] = useState<string | null>(null);
+  /** File shown in the bottom drawer + optional declaration scroll target. */
+  const [openFileTarget, setOpenFileTarget] = useState<{
+    file: string;
+    startLine?: number;
+  } | null>(null);
+  const openFile = openFileTarget?.file ?? null;
+  const openFileStartLine = openFileTarget?.startLine;
   // Edge-legend modal visibility (opened from the canvas's top-left button).
   const [legendOpen, setLegendOpen] = useState(false);
   // Component the pointer is over (null on leave) → transient tree highlight.
@@ -138,8 +151,8 @@ function Inner({ components, edges, onSelect, onEdgeSelect, measured: _measured,
   const selectedRef = useRef<SubsystemComponent | null>(null);
   selectedRef.current = selected;
   // Ref mirror of `openFile` for the tree-click toggle.
-  const openFileRef = useRef<string | null>(null);
-  openFileRef.current = openFile;
+  const openFileRef = useRef<{ file: string; startLine?: number } | null>(null);
+  openFileRef.current = openFileTarget;
 
   // Pass 1: build with estimated widths so React Flow can measure the DOM.
   // The pane stays hidden until Pass 2 completes.
@@ -367,11 +380,27 @@ function Inner({ components, edges, onSelect, onEdgeSelect, measured: _measured,
   );
   const onTreeSelectFile = useCallback(
     (file: string) => {
-      if (openFileRef.current === file) {
-        setOpenFile(null);
+      if (openFileRef.current?.file === file && openFileRef.current.startLine == null) {
+        setOpenFileTarget(null);
         return;
       }
-      setOpenFile(file);
+      setOpenFileTarget({ file });
+      onFileSelect?.(file);
+    },
+    [onFileSelect],
+  );
+
+  const onOpenDeclarationFile = useCallback(
+    (file: string, opts?: SubsystemOpenFileOptions) => {
+      const startLine = opts?.startLine;
+      if (
+        openFileRef.current?.file === file &&
+        openFileRef.current.startLine === startLine
+      ) {
+        setOpenFileTarget(null);
+        return;
+      }
+      setOpenFileTarget({ file, startLine });
       onFileSelect?.(file);
     },
     [onFileSelect],
@@ -434,20 +463,19 @@ function Inner({ components, edges, onSelect, onEdgeSelect, measured: _measured,
       const byFile = new Map(
         components.filter((c) => c.file).map((c) => [c.file, c] as const),
       );
-      return (file: string) => {
+      return (file: string, _opts?: SubsystemOpenFileOptions) => {
         const comp = byFile.get(file);
         return comp ? renderFileView(comp) : null;
       };
     }
-    return undefined;
+    return renderFileViewer;
   }, [renderFileViewer, renderFileView, components]);
 
-  // Latest-viewer ref + stable callback so DrawerContent's memo holds across
-  // unrelated Inner renders (see comment there).
   const fileViewerRef = useRef(fileViewer);
   fileViewerRef.current = fileViewer;
   const renderDrawerContent = useCallback(
-    (file: string) => fileViewerRef.current?.(file) ?? null,
+    (file: string, opts?: SubsystemOpenFileOptions) =>
+      fileViewerRef.current?.(file, opts) ?? null,
     [],
   );
 
@@ -697,8 +725,10 @@ function Inner({ components, edges, onSelect, onEdgeSelect, measured: _measured,
           >
             <ComponentDeclaration
               component={selected}
-              onOpenFile={onTreeSelectFile}
+              onOpenFile={onOpenDeclarationFile}
               onRelatedSelect={resolveRelatedComponent}
+              onVerify={onVerifyComponent}
+              verification={componentVerification}
             />
           </div>
         )}
@@ -708,8 +738,12 @@ function Inner({ components, edges, onSelect, onEdgeSelect, measured: _measured,
           mechanisms={usedMechanisms}
           onClose={() => setLegendOpen(false)}
         />
-      <FileDrawer file={openFile} onClose={() => setOpenFile(null)}>
-        <DrawerContent render={renderDrawerContent} file={openFile} />
+      <FileDrawer file={openFile} onClose={() => setOpenFileTarget(null)}>
+        <DrawerContent
+          render={renderDrawerContent}
+          file={openFile}
+          startLine={openFileStartLine}
+        />
       </FileDrawer>
       {/* Startup cover — hides measurement, layout swap, and camera settle. */}
       <GraphLayoutCover revealed={layoutReady} />

package/src/subsystem/declarationRef.test.ts

@@ -0,0 +1,33 @@
+import { describe, expect, test } from 'bun:test';
+import {
+  extractDeclarationLine,
+  normalizeDeclarationLine,
+  parseSourceLocation,
+} from './declarationRef';
+
+describe('parseSourceLocation', () => {
+  test('parses L-prefixed lines', () => {
+    expect(parseSourceLocation('L42')).toBe(42);
+    expect(parseSourceLocation(' L1 ')).toBe(1);
+  });
+
+  test('rejects invalid', () => {
+    expect(parseSourceLocation('42')).toBeNull();
+    expect(parseSourceLocation('')).toBeNull();
+    expect(parseSourceLocation(undefined)).toBeNull();
+  });
+});
+
+describe('normalizeDeclarationLine', () => {
+  test('trims trailing whitespace and CR', () => {
+    expect(normalizeDeclarationLine('export class Foo {\r')).toBe('export class Foo {');
+    expect(normalizeDeclarationLine('  x  ')).toBe('  x');
+  });
+});
+
+describe('extractDeclarationLine', () => {
+  test('1-based indexing', () => {
+    expect(extractDeclarationLine('a\nb\nc', 2)).toBe('b');
+    expect(extractDeclarationLine('a\nb', 3)).toBeNull();
+  });
+});