pkgviz 0.7.6 → 0.8.0

package/src/features/dependency-analysis/adapters/outbound/dependency-graph/analyzeTypeScriptImportsAsync.ts

@@ -0,0 +1,6 @@
+import { analyzeDependencyImportsAsync } from './analyzeDependencyImportsAsync';
+
+/*** Returns PKGViz imports indexed by source file from the canonical TypeScript analyzer. */
+export async function analyzeTypeScriptImportsAsync(projectRoot: string) {
+  return analyzeDependencyImportsAsync(projectRoot);
+}

package/src/features/graph-view/adapters/inbound/react/DependencyGraphView.tsx

@@ -0,0 +1,184 @@
+'use client';
+
+import { GraphView, type GraphViewElementEvent, type GraphViewLayoutName } from '@zora/graph-view';
+import type { ElementsDefinition, LayoutOptions } from 'cytoscape';
+import { useTheme } from 'next-themes';
+import React, { useMemo } from 'react';
+
+import { useSettings } from '@/contexts/SettingsContext';
+import { createGraphViewModel } from '@/features/graph-view/adapters/inbound/react/createGraphViewModel';
+import { createGraphViewStyles } from '@/features/graph-view/adapters/inbound/react/createGraphViewStyles';
+import { GraphZoomControls } from '@/features/graph-view/adapters/inbound/react/GraphZoomControls';
+import { useGraphFocus } from '@/features/graph-view/adapters/inbound/react/useGraphFocus';
+import { useGraphInteractions } from '@/features/graph-view/adapters/inbound/react/useGraphInteractions';
+import { useGraphProjection } from '@/features/graph-view/adapters/inbound/react/useGraphProjection';
+import { useGraphViewport } from '@/features/graph-view/adapters/inbound/react/useGraphViewport';
+import { LAYOUTS } from '@/layouts/constants';
+import { getCanvasBg } from '@/layouts/style';
+import type { CycleHighlight } from '@/types/auditVisualization';
+
+/*** Renders PKGViz graph policy through the materialized ZORA GraphView runtime. */
+export function DependencyGraphView(props: DependencyGraphViewProps) {
+  const settings = useSettings();
+  const { resolvedTheme } = useTheme();
+  const theme = resolvedTheme === 'dark' ? 'dark' : 'light';
+  const visibleElements = useGraphProjection({
+    currentPackage: props.currentPackage,
+    elements: props.packageGraph,
+    preservePackageScope: props.cycleHighlights.length > 0,
+    setCurrentPackage: props.setCurrentPackage,
+    setMaxSubPackageDepth: settings.setMaxSubPackageDepth,
+    setSubPackageDepth: settings.setSubPackageDepth,
+    showCompoundNodes: settings.showCompoundNodes,
+    showVendorPackages: settings.showVendorPackages,
+    subPackageDepth: settings.subPackageDepth,
+  });
+
+  useGraphFocus({
+    cycleHighlights: props.cycleHighlights,
+    currentPackage: props.currentPackage,
+    setCurrentPackage: props.setCurrentPackage,
+    setSubPackageDepth: settings.setSubPackageDepth,
+    subPackageDepth: settings.subPackageDepth,
+    visibleElements,
+  });
+
+  const presentation = useGraphViewPresentation({
+    cycleHighlights: props.cycleHighlights,
+    layout: settings.cytoscapeLayout,
+    packageGraph: props.packageGraph,
+    theme,
+    visibleElements,
+  });
+  if (presentation.model === null) return null;
+
+  return (
+    <DependencyGraphCanvas
+      {...props}
+      layout={presentation.layout}
+      layoutOptions={presentation.layoutOptions}
+      model={presentation.model}
+      onSpacingFactorChange={settings.setCytoscapeLayoutSpacing}
+      spacingFactor={settings.cytoscapeLayoutSpacing}
+      styles={presentation.styles}
+      theme={theme}
+    />
+  );
+}
+
+/***
+ * Memoizes GraphView model, style, and layout inputs from the active PKGViz projection.
+ * @performance
+ * Stable inputs avoid repeated projection work and let the owner distinguish presentation from
+ * topology/layout changes. Do not recreate these objects on unrelated renders or add compensating
+ * layout effects here. ZORA owns runtime reconciliation; memoization alone is not a correctness gate.
+ */
+function useGraphViewPresentation(input: GraphViewPresentationInput) {
+  const model = useMemo(
+    () =>
+      input.visibleElements === null
+        ? null
+        : createGraphViewModel(input.packageGraph, input.visibleElements, input.cycleHighlights),
+    [input.cycleHighlights, input.packageGraph, input.visibleElements]
+  );
+  const styles = useMemo(
+    () =>
+      input.visibleElements === null
+        ? []
+        : createGraphViewStyles(input.visibleElements, input.theme, input.layout),
+    [input.layout, input.theme, input.visibleElements]
+  );
+  const layoutOptions = useMemo<Readonly<Record<string, unknown>>>(
+    () => ({ ...LAYOUTS[input.layout] }),
+    [input.layout]
+  );
+
+  return {
+    layout: readGraphViewLayout(input.layout),
+    layoutOptions,
+    model,
+    styles,
+  };
+}
+
+/*** Owns GraphView controller callbacks and renders the viewport plus zoom controls. */
+function DependencyGraphCanvas(props: DependencyGraphCanvasProps) {
+  const viewport = useGraphViewport(props.layout);
+  const interactions = useGraphInteractions(props.model.nodes, props.model.edges);
+
+  /*** Handles structural graph navigation without touching the rendering engine. */
+  const handleNodeEvent = (event: GraphViewElementEvent) => {
+    interactions.handleNodeEvent(event);
+    if (event.type !== 'double-press' || !props.model.parentNodeIds.has(event.id)) return;
+    props.setCurrentPackage(event.id);
+  };
+
+  return (
+    <div className="flex min-h-0 min-w-0 flex-1 flex-col gap-2 overflow-hidden px-8">
+      <div className="relative min-h-0 flex-1 overflow-hidden">
+        <GraphView
+          edges={interactions.edges}
+          layout={props.layout}
+          layoutOptions={props.layoutOptions}
+          maxZoom={2}
+          minZoom={0.5}
+          minReadableLabelSize={24}
+          maxFitLabelSize={24}
+          nodes={interactions.nodes}
+          zoomMode="fit-relative"
+          sizeNodesToLabels
+          onLayoutComplete={viewport.handleLayoutComplete}
+          onNodeEvent={handleNodeEvent}
+          onReady={viewport.handleReady}
+          onViewportChange={viewport.handleViewportChange}
+          onSpacingFactorChange={props.onSpacingFactorChange}
+          spacingFactor={props.spacingFactor}
+          style={{ background: getCanvasBg(props.theme) }}
+          styleRules={props.styles}
+        />
+        {props.overlay}
+      </div>
+      <GraphZoomControls
+        controller={viewport.controller}
+        maxZoom={viewport.max}
+        minZoom={viewport.min}
+        zoom={viewport.zoom}
+      />
+    </div>
+  );
+}
+
+/*** Narrows persisted Cytoscape layout names to the layouts supported by ZORA GraphView. */
+function readGraphViewLayout(layout: LayoutOptions['name']): GraphViewLayoutName {
+  if (layout === 'breadthfirst') return 'breadthfirst';
+  if (layout === 'circle') return 'circle';
+  if (layout === 'elk') return 'elk';
+  if (layout === 'grid') return 'grid';
+  return 'concentric';
+}
+
+interface DependencyGraphViewProps {
+  readonly currentPackage: string;
+  readonly packageGraph: ElementsDefinition;
+  readonly setCurrentPackage: (path: string) => void;
+  readonly cycleHighlights: readonly CycleHighlight[];
+  readonly overlay?: React.ReactNode;
+}
+
+interface GraphViewPresentationInput {
+  readonly cycleHighlights: readonly CycleHighlight[];
+  readonly layout: LayoutOptions['name'];
+  readonly packageGraph: ElementsDefinition;
+  readonly theme: 'dark' | 'light';
+  readonly visibleElements: ElementsDefinition | null;
+}
+
+interface DependencyGraphCanvasProps extends DependencyGraphViewProps {
+  readonly onSpacingFactorChange: (spacingFactor: number) => void;
+  readonly layout: GraphViewLayoutName;
+  readonly layoutOptions: Readonly<Record<string, unknown>>;
+  readonly model: NonNullable<ReturnType<typeof createGraphViewModel>>;
+  readonly spacingFactor: number;
+  readonly styles: ReturnType<typeof createGraphViewStyles>;
+  readonly theme: 'dark' | 'light';
+}

package/src/features/graph-view/adapters/inbound/react/GraphZoomControls.tsx

@@ -0,0 +1,48 @@
+'use client';
+
+import type { GraphViewController } from '@zora/graph-view';
+import { CircleDotDashedIcon } from 'lucide-react';
+import React, { type ChangeEvent } from 'react';
+
+interface GraphZoomControlsProps {
+  readonly controller: GraphViewController | null;
+  readonly maxZoom: number;
+  readonly minZoom: number;
+  readonly zoom: number;
+}
+
+/*** Renders graph zoom controls against the engine-neutral ZORA viewport controller. */
+export function GraphZoomControls({ controller, maxZoom, minZoom, zoom }: GraphZoomControlsProps) {
+  /*** Applies one slider zoom value through the GraphView controller. */
+  const handleSliderChange = (event: ChangeEvent<HTMLInputElement>) => {
+    if (controller === null) return;
+    const level = Number.parseFloat(event.target.value);
+    controller.setZoom(Math.min(maxZoom, Math.max(minZoom, level)));
+  };
+
+  return (
+    <div className="flex shrink-0 items-center justify-center gap-2 border-t border-t-gray-200 p-4 dark:border-t-gray-800">
+      <label htmlFor="zoom">Zoom:</label>
+      <button
+        type="button"
+        title="Fit graph and optimize spacing for readability"
+        aria-label="Fit graph and optimize spacing for readability"
+        onClick={() => controller?.fit({ optimizeSpacing: true })}
+        className="p-1 rounded hover:bg-gray-100 dark:hover:bg-gray-800"
+      >
+        <CircleDotDashedIcon className="cursor-pointer" />
+      </button>
+      <input
+        id="zoom"
+        type="range"
+        min={minZoom}
+        max={maxZoom}
+        step="any"
+        value={zoom}
+        onChange={handleSliderChange}
+        className="w-64"
+      />
+      <span className="text-sm">{(zoom * 100).toFixed(0)}%</span>
+    </div>
+  );
+}

package/src/features/graph-view/adapters/inbound/react/applyGraphInteractionPresentation.ts

@@ -0,0 +1,35 @@
+import type { GraphViewEdge, GraphViewNode } from '@zora/graph-view';
+
+import { getDependencyHighlightClasses } from '@/features/graph-view/domain/getDependencyHighlightClasses';
+import type { GraphInteractionState } from '@/types/graphInteraction';
+
+/***
+ * Projects PKGViz interaction classes into the public GraphView presentation contract.
+ * @performance Reuse prepared model data and styles; interaction never rebuilds package/cycle indexes.
+ * Always start from the base model so pointer exit removes transient classes and preserves audit data.
+ */
+export function applyGraphInteractionPresentation(
+  nodes: readonly GraphViewNode[],
+  edges: readonly GraphViewEdge[],
+  state: GraphInteractionState
+) {
+  const activeIds = new Set(
+    state.hoveredNodeId === null ? state.selectedNodeIds : [state.hoveredNodeId]
+  );
+  if (activeIds.size === 0) return { nodes, edges };
+  const classes = getDependencyHighlightClasses(
+    nodes.map(node => node.id),
+    edges,
+    activeIds
+  );
+  return {
+    nodes: nodes.map((node, index) => ({
+      ...node,
+      classes: [node.classes, classes.nodeClasses.at(index)].filter(Boolean).join(' '),
+    })),
+    edges: edges.map((edge, index) => ({
+      ...edge,
+      classes: [edge.classes, classes.edgeClasses.at(index)].filter(Boolean).join(' '),
+    })),
+  };
+}

package/src/features/graph-view/adapters/inbound/react/createGraphViewModel.ts

@@ -0,0 +1,240 @@
+import type { GraphViewEdge, GraphViewNode } from '@zora/graph-view';
+import type { ElementsDefinition } from 'cytoscape';
+
+import { createCompoundOpacityIndex } from '@/features/graph-view/utils/createCompoundOpacityIndex';
+import { readNodeDefinitionId } from '@/features/graph-view/utils/readNodeDefinitionId';
+import type { CycleHighlight } from '@/types/auditVisualization';
+
+/***
+ * Projects PKGViz graph data into the engine-neutral ZORA GraphView contract.
+ * @performance
+ * Performance invariant: build package and cycle indexes once per projection, then use lookups
+ * in element conversion. Do not move full-graph or full-cycle scans into the node/edge callbacks.
+ * Recheck test/benchmarks/graphPresentation.ts and the README Performance evidence when changing
+ * this path; CPU model timings do not establish browser rendering or layout performance.
+ */
+export function createGraphViewModel(
+  allElements: ElementsDefinition,
+  visibleElements: ElementsDefinition,
+  cycleHighlights: readonly CycleHighlight[]
+): GraphViewModel {
+  const visibleNodeIds = new Set(
+    visibleElements.nodes
+      .map(node => readNodeDefinitionId(node))
+      .filter((id): id is string => id !== null)
+  );
+  const parentById = createVisibleParentMap(visibleElements, visibleNodeIds);
+  const detachedNodeIds = getDetachedNodeIds(visibleElements, parentById);
+  const packageParents = indexPackageParents(allElements);
+  const parentNodeIds = new Set([...visibleNodeIds].filter(id => packageParents.has(id)));
+  const cycles = indexCyclePresentation(cycleHighlights);
+  const appearance = {
+    cycles: cycles.nodes,
+    opacity: createCompoundOpacityIndex(parentById, detachedNodeIds),
+  };
+
+  return {
+    edges: visibleElements.edges.flatMap(edge => createGraphViewEdge(edge, cycles.edges)),
+    nodes: visibleElements.nodes.flatMap(node =>
+      createGraphViewNode(node, parentById, detachedNodeIds, parentNodeIds, appearance)
+    ),
+    parentNodeIds,
+  };
+}
+
+interface GraphViewModel {
+  readonly edges: readonly GraphViewEdge[];
+  readonly nodes: readonly GraphViewNode[];
+  readonly parentNodeIds: ReadonlySet<string>;
+}
+
+/***
+ * Indexes package ancestry once instead of scanning the full graph for each visible package.
+ * @performance
+ * Replacing this set with nodes.some(...) per visible node restores quadratic work for large
+ * projections. Walk dotted boundaries, including missing intermediate packages, so hidden
+ * descendants remain navigable without confusing sibling prefixes such as a.b and a.bc.
+ * Mutation is confined to this fresh index; source elements are never modified.
+ */
+function indexPackageParents(elements: ElementsDefinition): ReadonlySet<string> {
+  const parents = new Set<string>();
+  for (const node of elements.nodes) {
+    const id = readNodeDefinitionId(node);
+    if (id === null) continue;
+    for (
+      let boundary = id.lastIndexOf('.');
+      boundary >= 0;
+      boundary = id.lastIndexOf('.', boundary - 1)
+    ) {
+      parents.add(id.slice(0, boundary));
+      if (boundary === 0) break;
+    }
+  }
+  return parents;
+}
+
+/***
+ * Indexes cycle overlays with last-cycle precedence and the first matching directed-edge step.
+ * @performance
+ * Visit overlay membership once, not every cycle for every rendered element. The reverse edge
+ * traversal makes the first occurrence win within a cycle; later cycles still overwrite earlier
+ * ones. Keep directed source/target keys distinct. Model regression tests protect this precedence.
+ */
+function indexCyclePresentation(highlights: readonly CycleHighlight[]) {
+  const nodes = new Map<string, string>();
+  const edges = new Map<string, Map<string, { readonly color: string; readonly step: number }>>();
+  for (const highlight of highlights) {
+    for (const id of highlight.cycle.packages) nodes.set(id, highlight.color);
+    highlight.cycle.edges.toReversed().forEach((edge, index) => {
+      const targets =
+        edges.get(edge.from) ??
+        new Map<string, { readonly color: string; readonly step: number }>();
+      targets.set(edge.to, { color: highlight.color, step: highlight.cycle.edges.length - index });
+      edges.set(edge.from, targets);
+    });
+  }
+  return { edges, nodes };
+}
+
+/*** Builds only compound-parent relations whose parent is present in the visible graph. */
+function createVisibleParentMap(
+  elements: ElementsDefinition,
+  visibleNodeIds: ReadonlySet<string>
+): ReadonlyMap<string, string> {
+  return new Map(
+    elements.nodes.flatMap(node => {
+      const id = readNodeDefinitionId(node);
+      const parentId = readString(node.data.parent);
+      return id && parentId && visibleNodeIds.has(parentId) ? [[id, parentId] as const] : [];
+    })
+  );
+}
+
+/*** Detaches descendants participating in ancestor edges so every dependency has drawable endpoints. */
+function getDetachedNodeIds(
+  elements: ElementsDefinition,
+  parentById: ReadonlyMap<string, string>
+): ReadonlySet<string> {
+  const detachedNodeIds = new Set<string>();
+
+  for (const edge of elements.edges) {
+    const source = readString(edge.data.source);
+    const target = readString(edge.data.target);
+    if (!source || !target) continue;
+
+    if (isAncestor(source, target, parentById)) detachedNodeIds.add(target);
+    else if (isAncestor(target, source, parentById)) detachedNodeIds.add(source);
+  }
+
+  return detachedNodeIds;
+}
+
+/*** Returns whether one visible node contains another through the compound-parent chain. */
+function isAncestor(
+  possibleAncestor: string,
+  nodeId: string,
+  parentById: ReadonlyMap<string, string>
+): boolean {
+  const visited = new Set<string>();
+  let current = parentById.get(nodeId);
+
+  while (current !== undefined && !visited.has(current)) {
+    if (current === possibleAncestor) return true;
+    visited.add(current);
+    current = parentById.get(current);
+  }
+
+  return false;
+}
+
+/***
+ * Converts one visible node using prepared parent and cycle lookups.
+ * @performance
+ * Resolve labels once per model update. ZORA measures styled labels during reconciliation;
+ * do not restore character-count width estimates or per-frame consumer measurement callbacks.
+ */
+function createGraphViewNode(
+  node: ElementsDefinition['nodes'][number],
+  parentById: ReadonlyMap<string, string>,
+  detachedNodeIds: ReadonlySet<string>,
+  parentNodeIds: ReadonlySet<string>,
+  appearance: {
+    readonly cycles: ReadonlyMap<string, string>;
+    readonly opacity: ReadonlyMap<string, number>;
+  }
+): GraphViewNode[] {
+  const id = readNodeDefinitionId(node);
+  if (id === null) return [];
+
+  const cycleColor = appearance.cycles.get(id);
+  const parentId = detachedNodeIds.has(id) ? undefined : parentById.get(id);
+  const label = readString(node.data.label) ?? readString(node.data.name) ?? id;
+
+  return [
+    {
+      id,
+      label,
+      parentId,
+      classes: appendClasses(
+        readClasses(node.classes),
+        parentNodeIds.has(id) ? 'isParent' : undefined,
+        cycleColor !== undefined ? 'auditCycle' : undefined
+      ),
+      data: {
+        ...node.data,
+        compoundFillOpacity: appearance.opacity.get(id) ?? 0.04,
+        parent: parentId,
+        ...(cycleColor !== undefined ? { auditCycleColor: cycleColor } : {}),
+      },
+    },
+  ];
+}
+
+/*** Convert one visible edge while projecting audit-cycle presentation metadata. */
+function createGraphViewEdge(
+  edge: ElementsDefinition['edges'][number],
+  cycleEdges: ReturnType<typeof indexCyclePresentation>['edges']
+): GraphViewEdge[] {
+  const source = readString(edge.data.source);
+  const target = readString(edge.data.target);
+  if (!source || !target) return [];
+
+  const cycle = cycleEdges.get(source)?.get(target);
+  return [
+    {
+      id: readString(edge.data.id),
+      source,
+      target,
+      classes: appendClasses(readClasses(edge.classes), cycle ? 'auditCycle' : undefined),
+      data: {
+        ...edge.data,
+        ...(cycle
+          ? {
+              auditCycleColor: cycle.color,
+              auditCycleStep: String(cycle.step),
+            }
+          : {}),
+      },
+    },
+  ];
+}
+
+/*** Normalize Cytoscape class declarations into the GraphView string contract. */
+function readClasses(value: unknown): string {
+  if (typeof value === 'string') return value;
+  if (!Array.isArray(value)) return '';
+  return value.filter((entry): entry is string => typeof entry === 'string').join(' ');
+}
+
+/*** Append optional classes without introducing duplicate whitespace. */
+function appendClasses(base: string, ...classes: readonly (string | undefined)[]): string {
+  return [base, ...classes]
+    .filter(value => value && value.length > 0)
+    .join(' ')
+    .trim();
+}
+
+/*** Read one optional string data field at the adapter boundary. */
+function readString(value: unknown): string | undefined {
+  return typeof value === 'string' && value.length > 0 ? value : undefined;
+}

package/src/features/graph-view/adapters/inbound/react/createGraphViewStyles.ts

@@ -0,0 +1,37 @@
+import type { GraphViewStyleRule } from '@zora/graph-view';
+import type { ElementsDefinition, LayoutOptions, StylesheetJson } from 'cytoscape';
+
+import {
+  getBreadthfirstStyle,
+  getCircleStyle,
+  getConcentricStyle,
+  getElkStyle,
+  getGridStyle,
+} from '@/layouts';
+import { getStyle as getCommonStyle, type ThemeKey } from '@/layouts/style';
+
+/*** Builds ZORA GraphView style rules from the existing PKGViz Cytoscape style policy. */
+export function createGraphViewStyles(
+  elements: ElementsDefinition,
+  theme: ThemeKey,
+  layout: LayoutOptions['name']
+): readonly GraphViewStyleRule[] {
+  return [...getCommonStyle(elements, theme), ...getLayoutStyle(layout)].map(toGraphViewStyleRule);
+}
+
+/*** Converts one Cytoscape stylesheet rule into the GraphView presentation contract. */
+function toGraphViewStyleRule(rule: StylesheetJson[number]): GraphViewStyleRule {
+  return {
+    selector: rule.selector,
+    style: { ...('style' in rule ? rule.style : rule.css) },
+  };
+}
+
+/*** Resolves the visual style extension owned by the active layout. */
+function getLayoutStyle(layout: LayoutOptions['name']): StylesheetJson {
+  if (layout === 'breadthfirst') return getBreadthfirstStyle();
+  if (layout === 'circle') return getCircleStyle();
+  if (layout === 'elk') return getElkStyle();
+  if (layout === 'grid') return getGridStyle();
+  return getConcentricStyle();
+}

package/src/features/graph-view/adapters/inbound/react/useGraphFocus.ts

@@ -0,0 +1,104 @@
+'use client';
+
+import type { ElementsDefinition } from 'cytoscape';
+import { useEffect, useRef } from 'react';
+
+import { createCycleFocus } from '@/features/audit/utils/cycleVisualization';
+import { readNodeDefinitionId } from '@/features/graph-view/utils/readNodeDefinitionId';
+import type { CycleHighlight } from '@/types/auditVisualization';
+
+/*** Expands package projection once when active cycles are not yet visible. */
+export function useGraphFocus(input: UseGraphFocusInput) {
+  const handledCycleSignatureRef = useRef<string | null>(null);
+  const {
+    cycleHighlights,
+    currentPackage,
+    setCurrentPackage,
+    setSubPackageDepth,
+    subPackageDepth,
+    visibleElements,
+  } = input;
+
+  useEffect(
+    () =>
+      runCycleProjectionFocus(
+        {
+          cycleHighlights,
+          currentPackage,
+          setCurrentPackage,
+          setSubPackageDepth,
+          subPackageDepth,
+          visibleElements,
+        },
+        handledCycleSignatureRef
+      ),
+    [
+      cycleHighlights,
+      currentPackage,
+      setCurrentPackage,
+      setSubPackageDepth,
+      subPackageDepth,
+      visibleElements,
+    ]
+  );
+}
+
+/*** Runs one cycle-projection iteration without touching layout or viewport state. */
+function runCycleProjectionFocus(
+  input: UseGraphFocusInput,
+  handledCycleSignatureRef: { current: string | null }
+) {
+  if (input.visibleElements === null) return;
+
+  if (input.cycleHighlights.length === 0) {
+    handledCycleSignatureRef.current = null;
+    return;
+  }
+
+  const signature = getCycleSignature(input.cycleHighlights);
+  if (handledCycleSignatureRef.current === signature) return;
+  if (ensureCycleProjection(input)) return;
+  handledCycleSignatureRef.current = signature;
+}
+
+/*** Returns a stable identity for the current active-cycle set. */
+function getCycleSignature(highlights: readonly CycleHighlight[]): string {
+  return highlights
+    .map(highlight => highlight.id)
+    .sort()
+    .join('|');
+}
+
+/*** Expands only the projection dimensions required to expose every active cycle package. */
+function ensureCycleProjection(input: UseGraphFocusInput): boolean {
+  if (input.visibleElements === null) return false;
+  const activePackageNames = [
+    ...new Set(input.cycleHighlights.flatMap(highlight => highlight.cycle.packages)),
+  ];
+  const visibleNodeIds = new Set(
+    input.visibleElements.nodes
+      .map(node => readNodeDefinitionId(node))
+      .filter((id): id is string => id !== null)
+  );
+  if (activePackageNames.every(packageName => visibleNodeIds.has(packageName))) return false;
+
+  const focus = createCycleFocus(input.cycleHighlights);
+  if (!focus) return false;
+
+  const normalizedCurrentPackage = input.currentPackage.replace(/\//g, '.');
+  const scopeChanged = focus.currentPackage !== normalizedCurrentPackage;
+  const depthChanged = focus.packageDepth > input.subPackageDepth;
+
+  if (scopeChanged) input.setCurrentPackage(focus.currentPackage);
+  if (depthChanged) input.setSubPackageDepth(focus.packageDepth);
+  return scopeChanged || depthChanged;
+}
+
+interface UseGraphFocusInput {
+  readonly cycleHighlights: readonly CycleHighlight[];
+  readonly currentPackage: string;
+  readonly setCurrentPackage: (path: string) => void;
+  readonly setSubPackageDepth: (depth: number) => void;
+  readonly subPackageDepth: number;
+  readonly visibleElements: ElementsDefinition | null;
+}