@principal-ai/subsystems-react 0.24.27 → 0.25.1

package/src/stories/Subsystem/ComponentGraph/Spotlights.stories.tsx

@@ -149,7 +149,7 @@ const nodeSpotlights: Array<{ label: string; component: SubsystemComponent; note
     label: 'construct: type_alias — a type alias',
     note: 'the `type` keyword form: `type X = { … }` or a union — anything `=`-assigned',
     component: {
-      id: 'alias-status',
+      alias: 'alias-status',
       name: 'AnalysisStatus',
       construct: 'type_alias',
       file: 'packages/subsystems-studio/src/bun/analysis.ts',
@@ -170,7 +170,7 @@ const nodeSpotlights: Array<{ label: string; component: SubsystemComponent; note
     label: 'role: entry on construct: type — contract as entry',
     note: 'same role, different inherited anatomy — entries are topology, not shape',
     component: {
-        id: 'ipc-entry',
+        alias: 'ipc-entry',
       name: 'StudioMessages',
       construct: 'interface',
       file: 'packages/subsystems-studio/src/shared/contract.ts',
@@ -183,7 +183,7 @@ const nodeSpotlights: Array<{ label: string; component: SubsystemComponent; note
     label: 'construct: enum — runtime values + a type',
     note: 'the one type-family form that exists at runtime; members render in the drill-down',
     component: {
-      id: 'enum-phase',
+      alias: 'enum-phase',
       name: 'VerificationPhase',
       construct: 'enum',
       file: 'packages/subsystems-studio/src/bun/verify.ts',
@@ -201,7 +201,7 @@ const nodeSpotlights: Array<{ label: string; component: SubsystemComponent; note
     label: 'construct: function — plain accessor',
     note: 'indigo; the default for anchored behavior',
     component: {
-      id: 'create',
+      alias: 'create',
       name: 'createSubsystemModel',
       construct: 'function',
       file: 'packages/subsystems-studio/src/bun/subsystem-model-store.ts',
@@ -213,7 +213,7 @@ const nodeSpotlights: Array<{ label: string; component: SubsystemComponent; note
     label: 'framework: react · stereotype: component — still construct: function',
     note: 'badge reads "react · component"; name renders bare ; color stays function',
     component: {
-      id: 'analysis-view',
+      alias: 'analysis-view',
       name: 'AnalysisView',
       construct: 'function',
       file: 'packages/subsystems-studio/src/mainview/views/AnalysisView.tsx',
@@ -228,7 +228,7 @@ const nodeSpotlights: Array<{ label: string; component: SubsystemComponent; note
     label: 'framework: react · stereotype: hook',
     note: 'same construct, different stereotype — badge "react · hook", keeps ()',
     component: {
-      id: 'drawings-host',
+      alias: 'drawings-host',
       name: 'useDrawingsHost',
       construct: 'function',
       file: 'packages/subsystems-studio/src/mainview/hooks/useDrawingsHost.ts',
@@ -242,7 +242,7 @@ const nodeSpotlights: Array<{ label: string; component: SubsystemComponent; note
     label: 'role: entry on construct: function — boundary element',
     note: 'orange overrides construct:color; anatomy inherited from the function',
     component: {
-      id: 'http-entry',
+      alias: 'http-entry',
       name: 'HTTP bridge :3045',
       construct: 'function',
       file: 'packages/subsystems-studio/src/bun/http-server.ts',
@@ -255,7 +255,7 @@ const nodeSpotlights: Array<{ label: string; component: SubsystemComponent; note
     label: 'construct: class — declaration anatomy',
     note: 'blue; drill-down renders the real class stub with its methods',
     component: {
-      id: 'cache',
+      alias: 'cache',
       name: 'SessionCache',
       construct: 'class',
       file: 'src/session/SessionCache.ts',
@@ -276,7 +276,7 @@ const nodeSpotlights: Array<{ label: string; component: SubsystemComponent; note
     label: 'construct: method — a function bound to its class',
     note: 'dotted symbol (SessionCache.put) is the identity; drill-down renders it inside a host-class stub',
     component: {
-      id: 'method-put',
+      alias: 'method-put',
       name: 'put',
       construct: 'method',
       file: 'src/session/SessionCache.ts',
@@ -293,7 +293,7 @@ const nodeSpotlights: Array<{ label: string; component: SubsystemComponent; note
     label: 'construct: store — state-block anatomy',
     note: 'green = the store construct:color; drill-down renders declare const state, never a class stub',
     component: {
-      id: 'store',
+      alias: 'store',
       name: 'Graph Store',
       construct: 'store',
       file: 'packages/subsystems-studio/src/bun/subsystem-model-store.ts',
@@ -306,7 +306,7 @@ const nodeSpotlights: Array<{ label: string; component: SubsystemComponent; note
     label: 'construct: external — actor outside every boundary',
     note: 'purple; no process → drawn outside all regions',
     component: {
-      id: 'agents',
+      alias: 'agents',
       name: 'agent clients',
       construct: 'external',
       file: '',
@@ -317,7 +317,7 @@ const nodeSpotlights: Array<{ label: string; component: SubsystemComponent; note
     label: 'role: service on construct: external — far-side boundary element',
     note: 'colored by its construct (external); identity via purl, no source at all',
     component: {
-      id: 'github',
+      alias: 'github',
       name: 'api.github.com',
       construct: 'external',
       file: '',
@@ -332,7 +332,7 @@ function NodeSpotlightsDemo() {
   const { mode } = useTheme();
   const constructColors = constructColorsFromPierreTheme(resolvePierreSyntaxThemeName(mode));
   const [activeIds, setActiveIds] = useState<Set<string>>(
-    () => new Set(nodeSpotlights.map((n) => n.component.id)),
+    () => new Set(nodeSpotlights.map((n) => n.component.alias)),
   );
   const toggle = (id: string) =>
     setActiveIds((prev) => {
@@ -344,7 +344,7 @@ function NodeSpotlightsDemo() {
       }
       return next;
     });
-  const visible = nodeSpotlights.filter((n) => activeIds.has(n.component.id));
+  const visible = nodeSpotlights.filter((n) => activeIds.has(n.component.alias));
 
   return (
     <div style={{ padding: 20, overflow: 'auto', height: '100vh', boxSizing: 'border-box', background: '#0f1216' }}>
@@ -358,7 +358,7 @@ function NodeSpotlightsDemo() {
           show:
         </span>
         {nodeSpotlights.map(({ component }) => {
-          const on = activeIds.has(component.id);
+          const on = activeIds.has(component.alias);
           const color = constructColors[component.construct];
           const chip = component.stereotype
             ? component.framework
@@ -369,9 +369,9 @@ function NodeSpotlightsDemo() {
               : component.construct;
           return (
             <button
-              key={component.id}
+              key={component.alias}
               type="button"
-              onClick={() => toggle(component.id)}
+              onClick={() => toggle(component.alias)}
               style={{
                 fontFamily: 'monospace',
                 fontSize: 11,
@@ -390,7 +390,7 @@ function NodeSpotlightsDemo() {
         })}
         <button
           type="button"
-          onClick={() => setActiveIds(new Set(nodeSpotlights.map((n) => n.component.id)))}
+          onClick={() => setActiveIds(new Set(nodeSpotlights.map((n) => n.component.alias)))}
           style={{ fontFamily: 'monospace', fontSize: 11, cursor: 'pointer', padding: '4px 10px', borderRadius: 999, border: '1px solid #2c313a', background: 'transparent', color: '#9ca3af' }}
         >
           all
@@ -410,7 +410,7 @@ function NodeSpotlightsDemo() {
         </div>
       )}
       {visible.map(({ label, component, note }) => (
-        <div key={component.id}>
+        <div key={component.alias}>
           <div style={{ fontFamily: 'monospace', fontSize: 11, color: '#6b7280', margin: '10px 2px 6px' }}>
             {label} — {note}
           </div>
@@ -490,7 +490,7 @@ const anatomyComponents: Array<{ label: string; component: SubsystemComponent; n
     label: 'store detail → state block',
     note: 'declare const lines — honest to module-level state; no class stub, no methods',
     component: {
-      id: 'store',
+      alias: 'store',
       name: 'Graph Store',
       construct: 'store',
       file: 'packages/subsystems-studio/src/bun/subsystem-model-store.ts',
@@ -510,7 +510,7 @@ const anatomyComponents: Array<{ label: string; component: SubsystemComponent; n
     label: 'class detail → class stub',
     note: 'the verifiable access mechanism — methods with typed params + returns',
     component: {
-      id: 'cache',
+      alias: 'cache',
       name: 'SessionCache',
       construct: 'class',
       file: 'src/session/SessionCache.ts',
@@ -534,7 +534,7 @@ const anatomyComponents: Array<{ label: string; component: SubsystemComponent; n
     label: 'function detail → signature',
     note: 'params + return type, callers/callees intentionally not rendered (edges carry them)',
     component: {
-      id: 'get',
+      alias: 'get',
       name: 'getSubsystemModel',
       construct: 'function',
       file: 'packages/subsystems-studio/src/bun/subsystem-model-store.ts',
@@ -553,7 +553,7 @@ const anatomyComponents: Array<{ label: string; component: SubsystemComponent; n
     label: 'type detail → interface fields',
     note: 'the IPC contract as an entry: anatomy inherited from the type',
     component: {
-        id: 'ipc-entry',
+        alias: 'ipc-entry',
       name: 'StudioMessages',
       construct: 'interface',
       file: 'packages/subsystems-studio/src/shared/contract.ts',
@@ -575,7 +575,7 @@ const anatomyComponents: Array<{ label: string; component: SubsystemComponent; n
     label: 'method detail → method in host-class stub',
     note: 'the class is context, the method is the node — same anatomy a standalone function gets, plus the owning class',
     component: {
-      id: 'anatomy-method',
+      alias: 'anatomy-method',
       name: 'put',
       construct: 'method',
       file: 'src/session/SessionCache.ts',
@@ -593,7 +593,7 @@ const anatomyComponents: Array<{ label: string; component: SubsystemComponent; n
     label: 'type_alias detail → braced alias',
     note: 'the alias renders as `type X = { … }` — the honest keyword form',
     component: {
-      id: 'anatomy-alias',
+      alias: 'anatomy-alias',
       name: 'AnalysisStatus',
       construct: 'type_alias',
       file: 'packages/subsystems-studio/src/bun/analysis.ts',
@@ -611,7 +611,7 @@ const anatomyComponents: Array<{ label: string; component: SubsystemComponent; n
     label: 'enum detail → enum declaration',
     note: 'members render inline — the runtime type',
     component: {
-      id: 'anatomy-enum',
+      alias: 'anatomy-enum',
       name: 'VerificationPhase',
       construct: 'enum',
       file: 'packages/subsystems-studio/src/bun/verify.ts',
@@ -634,7 +634,7 @@ function AnatomySpotlightsDemo() {
         anatomy spotlights — data (left) → the drill-down panel you get on click (right).
       </div>
       {anatomyComponents.map(({ label, component, note }) => (
-        <div key={component.id}>
+        <div key={component.alias}>
           <div style={{ fontFamily: 'monospace', fontSize: 11, color: '#6b7280', margin: '10px 2px 6px' }}>
             {label} — {note}
           </div>

package/src/stories/Subsystem/ComponentGraph/fixtures.ts

@@ -13,10 +13,10 @@ import type { GraphifyComponentDetail } from '../../../graphify';
 // Build a subsystem graph from a compact spec - helpers
 // ---------------------------------------------------------------------------
 export function components(
-  spec: Array<[id: string, name: string, construct: SubsystemComponent['construct'], file: string, purl: string, purpose?: string, symbol?: string, declaration?: GraphifyComponentDetail]>,
+  spec: Array<[alias: string, name: string, construct: SubsystemComponent['construct'], file: string, purl: string, purpose?: string, symbol?: string, declaration?: GraphifyComponentDetail]>,
 ): SubsystemComponent[] {
-  return spec.map(([id, name, construct, file, purl, purpose, symbol, declaration]) => ({
-    id,
+  return spec.map(([alias, name, construct, file, purl, purpose, symbol, declaration]) => ({
+    alias,
     name,
     construct,
     file,
@@ -135,7 +135,7 @@ export const readerDetail: GraphifyComponentDetail = {
 // ---------------------------------------------------------------------------
 export const investigateOnlyComponents: SubsystemComponent[] = [
   {
-    id: 'v1',
+    alias: 'v1',
     name: 'V1EventBridgeProcessor',
     construct: 'class',
     file: 'src/event-processing/V1EventBridge.ts',
@@ -144,7 +144,7 @@ export const investigateOnlyComponents: SubsystemComponent[] = [
     symbol: 'V1EventBridgeProcessor',
   },
   {
-    id: 'v2',
+    alias: 'v2',
     name: 'V2EventBridgeProcessor',
     construct: 'class',
     file: 'src/event-processing/V2EventBridge.ts',
@@ -153,7 +153,7 @@ export const investigateOnlyComponents: SubsystemComponent[] = [
     symbol: 'V2EventBridgeProcessor',
   },
   {
-    id: 'input',
+    alias: 'input',
     name: 'RepoNormalizedUniversalAgentSessionEvent',
     construct: 'interface',
     file: 'types/RepoNormalizedUniversalAgentSessionEvent.ts',
@@ -162,7 +162,7 @@ export const investigateOnlyComponents: SubsystemComponent[] = [
     symbol: 'RepoNormalizedUniversalAgentSessionEvent',
   },
   {
-    id: 'acc',
+    alias: 'acc',
     name: 'accumulateToAgentSessionEvents',
     construct: 'function',
     file: 'src/accumulateToAgentSessionEvents.ts',
@@ -171,7 +171,7 @@ export const investigateOnlyComponents: SubsystemComponent[] = [
     symbol: 'accumulateToAgentSessionEvents',
   },
   {
-    id: 'out',
+    alias: 'out',
     name: 'AgentSessionEvent',
     construct: 'interface',
     file: 'types/AgentSessionEvent.ts',

package/src/subsystem/ComponentDeclaration.tsx

@@ -116,7 +116,7 @@ export interface ComponentDeclarationProps {
   /** 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;
+  onVerify?: (componentAlias: string) => void;
   /** Live verification status for the selected component. */
   verification?: ComponentVerificationState | null;
   /** Start with the file path row visible (catalog / source-first views). */
@@ -411,7 +411,7 @@ export function ComponentDeclaration({
           disabled={verifyBusy}
           onClick={(e) => {
             e.stopPropagation();
-            onVerify(component.id);
+            onVerify(component.alias);
           }}
           style={{
             display: 'flex',

package/src/subsystem/ConstructsCatalog.tsx

@@ -11,7 +11,7 @@ import { memo, useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import type { ReactNode } from 'react';
 import { useTheme } from '@principal-ade/industry-theme';
 import { IndustryMarkdownSlide } from 'themed-markdown';
-import { ChevronDown, ChevronRight, ChevronUp, FileText, Folder } from 'lucide-react';
+import { ChevronDown, ChevronRight, FileText, Folder } from 'lucide-react';
 import {
   constructBadgeColor,
   constructBadgeLabel,
@@ -29,7 +29,7 @@ import { resolvePierreSyntaxThemeName } from '../pierre/pierreSyntaxTheme';
 
 export interface ConstructsCatalogProps {
   components: SubsystemComponent[];
-  onSelect?: (componentId: string) => void;
+  onSelect?: (componentAlias: string) => void;
   title?: string;
   hideSidebar?: boolean;
   description?: string;
@@ -39,7 +39,7 @@ export interface ConstructsCatalogProps {
   renderFileViewer?: (file: string, opts?: SubsystemOpenFileOptions) => ReactNode;
   renderFileView?: (component: SubsystemComponent) => ReactNode;
   onFileSelect?: (file: string) => void;
-  onVerifyComponent?: (componentId: string) => void;
+  onVerifyComponent?: (componentAlias: string) => void;
   componentVerification?: ComponentVerificationState | null;
 }
 
@@ -111,7 +111,7 @@ function resolveRelated(
   const clean = ref.replace(/\(\)$/, '');
   return components.find(
     (c) =>
-      c.id === clean ||
+      c.alias === clean ||
       c.name === clean ||
       c.symbol === clean ||
       c.symbol?.replace(/\(\)$/, '') === clean,
@@ -170,11 +170,11 @@ export function ConstructsCatalog({
       .map((x) => x.c);
   }, [components]);
 
-  const [visibleIds, setVisibleIds] = useState<string[]>(() =>
-    orderedComponents[0] ? [orderedComponents[0].id] : [],
+  const [visibleAliases, setVisibleAliases] = useState<string[]>(() =>
+    orderedComponents[0] ? [orderedComponents[0].alias] : [],
   );
-  const [focusedId, setFocusedId] = useState<string | null>(
-    () => orderedComponents[0]?.id ?? null,
+  const [focusedAlias, setFocusedAlias] = useState<string | null>(
+    () => orderedComponents[0]?.alias ?? null,
   );
   const [descriptionVisible, setDescriptionVisible] = useState(false);
   const [descToggleHover, setDescToggleHover] = useState(false);
@@ -186,12 +186,12 @@ export function ConstructsCatalog({
   const [drawer, setDrawer] = useState<{ file: string; startLine?: number } | null>(
     null,
   );
-  const focusedRef = useRef<string | null>(focusedId);
-  focusedRef.current = focusedId;
+  const focusedAliasRef = useRef<string | null>(focusedAlias);
+  focusedAliasRef.current = focusedAlias;
 
-  const visibleSet = useMemo(() => new Set(visibleIds), [visibleIds]);
+  const visibleSet = useMemo(() => new Set(visibleAliases), [visibleAliases]);
   const visibleComponents = useMemo(
-    () => orderedComponents.filter((c) => visibleSet.has(c.id)),
+    () => orderedComponents.filter((c) => visibleSet.has(c.alias)),
     [orderedComponents, visibleSet],
   );
 
@@ -213,7 +213,7 @@ export function ConstructsCatalog({
     }> = [];
     const index = new Map<string, number>();
     for (const c of visibleComponents) {
-      const key = c.purl || c.id;
+      const key = c.purl || c.alias;
       let at = index.get(key);
       if (at == null) {
         at = groups.length;
@@ -227,17 +227,17 @@ export function ConstructsCatalog({
   }, [visibleComponents]);
 
   useEffect(() => {
-    if (!focusedId) return;
-    document.getElementById(`construct-${focusedId}`)?.scrollIntoView({ block: 'nearest' });
-  }, [focusedId]);
+    if (!focusedAlias) return;
+    document.getElementById(`construct-${focusedAlias}`)?.scrollIntoView({ block: 'nearest' });
+  }, [focusedAlias]);
 
   useEffect(() => {
-    const last = visibleIds[visibleIds.length - 1];
+    const last = visibleAliases[visibleAliases.length - 1];
     if (!last) return;
     document
       .getElementById(`construct-signature-${last}`)
       ?.scrollIntoView({ block: 'nearest' });
-  }, [visibleIds]);
+  }, [visibleAliases]);
 
   // Keep the declaration whose file is open in view, so the source and its
   // signature stay legible together.
@@ -249,47 +249,47 @@ export function ConstructsCatalog({
       ) ?? orderedComponents.find((c) => c.file === drawer.file);
     if (!match) return;
     document
-      .getElementById(`construct-signature-${match.id}`)
+      .getElementById(`construct-signature-${match.alias}`)
       ?.scrollIntoView({ block: 'nearest' });
   }, [orderedComponents, drawer]);
 
-  // Drop ids that left the model; if nothing remains, show the first construct.
+  // Drop aliases that left the model; if nothing remains, show the first construct.
   useEffect(() => {
-    const ids = new Set(orderedComponents.map((c) => c.id));
-    setVisibleIds((prev) => {
-      const next = prev.filter((id) => ids.has(id));
+    const aliases = new Set(orderedComponents.map((c) => c.alias));
+    setVisibleAliases((prev) => {
+      const next = prev.filter((alias) => aliases.has(alias));
       if (next.length > 0 || orderedComponents.length === 0) return next;
-      return [orderedComponents[0]!.id];
+      return [orderedComponents[0]!.alias];
     });
-    setFocusedId((prev) => {
-      if (prev && ids.has(prev)) return prev;
-      return orderedComponents[0]?.id ?? null;
+    setFocusedAlias((prev) => {
+      if (prev && aliases.has(prev)) return prev;
+      return orderedComponents[0]?.alias ?? null;
     });
   }, [orderedComponents]);
 
   const toggle = useCallback(
-    (id: string) => {
-      setFocusedId(id);
-      setVisibleIds((prev) =>
-        prev.includes(id) ? prev.filter((x) => x !== id) : [...prev, id],
+    (alias: string) => {
+      setFocusedAlias(alias);
+      setVisibleAliases((prev) =>
+        prev.includes(alias) ? prev.filter((x) => x !== alias) : [...prev, alias],
       );
-      onSelect?.(id);
+      onSelect?.(alias);
     },
     [onSelect],
   );
 
   const show = useCallback(
-    (id: string) => {
-      setFocusedId(id);
-      setVisibleIds((prev) => (prev.includes(id) ? prev : [...prev, id]));
-      onSelect?.(id);
+    (alias: string) => {
+      setFocusedAlias(alias);
+      setVisibleAliases((prev) => (prev.includes(alias) ? prev : [...prev, alias]));
+      onSelect?.(alias);
     },
     [onSelect],
   );
 
   const focusAt = useCallback(
-    (id: string) => {
-      setFocusedId(id);
+    (alias: string) => {
+      setFocusedAlias(alias);
     },
     [],
   );
@@ -307,17 +307,17 @@ export function ConstructsCatalog({
    *  all when they're already shown — mirroring a construct row toggle. */
   const toggleFile = useCallback(
     (comps: SubsystemComponent[]) => {
-      const ids = comps.map((c) => c.id);
-      setVisibleIds((prev) => {
+      const aliases = comps.map((c) => c.alias);
+      setVisibleAliases((prev) => {
         const set = new Set(prev);
-        const allVisible = ids.every((id) => set.has(id));
-        ids.forEach((id) => (allVisible ? set.delete(id) : set.add(id)));
-        return orderedComponents.filter((c) => set.has(c.id)).map((c) => c.id);
+        const allVisible = aliases.every((alias) => set.has(alias));
+        aliases.forEach((alias) => (allVisible ? set.delete(alias) : set.add(alias)));
+        return orderedComponents.filter((c) => set.has(c.alias)).map((c) => c.alias);
       });
       const first = comps[0];
       if (first) {
-        setFocusedId(first.id);
-        onSelect?.(first.id);
+        setFocusedAlias(first.alias);
+        onSelect?.(first.alias);
       }
     },
     [orderedComponents, onSelect],
@@ -380,8 +380,8 @@ export function ConstructsCatalog({
             </li>
           );
         }
-        const ids = child.components.map((c) => c.id);
-        const allVisible = ids.length > 0 && ids.every((id) => visibleSet.has(id));
+        const aliases = child.components.map((c) => c.alias);
+        const allVisible = aliases.length > 0 && aliases.every((alias) => visibleSet.has(alias));
         const hovered = hoveredRow === child.path;
         const color = componentColor(child.components[0]!, pierreTheme);
         return (
@@ -438,7 +438,7 @@ export function ConstructsCatalog({
                   color: allVisible ? color : muted,
                 }}
               >
-                {ids.length}
+                {aliases.length}
               </span>
             </button>
           </li>
@@ -473,7 +473,7 @@ export function ConstructsCatalog({
     (ref: string) => {
       const comp = resolveRelated(components, ref);
       if (!comp) return;
-      show(comp.id);
+      show(comp.alias);
     },
     [components, show],
   );
@@ -505,13 +505,13 @@ export function ConstructsCatalog({
       if (orderedComponents.length === 0) return;
       const idx = Math.max(
         0,
-        orderedComponents.findIndex((c) => c.id === focusedRef.current),
+        orderedComponents.findIndex((c) => c.alias === focusedAliasRef.current),
       );
       const next =
         orderedComponents[
           (idx + delta + orderedComponents.length) % orderedComponents.length
         ]!;
-      focusAt(next.id);
+      focusAt(next.alias);
     },
     [orderedComponents, focusAt],
   );
@@ -537,15 +537,15 @@ export function ConstructsCatalog({
         moveFocus(-1);
       } else if (e.key === 'Home') {
         e.preventDefault();
-        if (orderedComponents[0]) focusAt(orderedComponents[0].id);
+        if (orderedComponents[0]) focusAt(orderedComponents[0].alias);
       } else if (e.key === 'End') {
         e.preventDefault();
         const last = orderedComponents[orderedComponents.length - 1];
-        if (last) focusAt(last.id);
+        if (last) focusAt(last.alias);
       } else if (e.key === ' ' || e.key === 'Enter') {
-        if (focusedRef.current) {
+        if (focusedAliasRef.current) {
           e.preventDefault();
-          toggle(focusedRef.current);
+          toggle(focusedAliasRef.current);
         }
       } else if (e.key === 'Escape' && drawer) {
         setDrawer(null);
@@ -646,16 +646,12 @@ export function ConstructsCatalog({
                         padding: 0,
                         border: 'none',
                         borderRadius: 4,
-                        background: descToggleHover ? theme.colors.border : 'transparent',
-                        color: descToggleHover ? theme.colors.text : muted,
+                        background: descriptionVisible || descToggleHover ? theme.colors.border : 'transparent',
+                        color: descriptionVisible || descToggleHover ? theme.colors.text : muted,
                         cursor: 'pointer',
                       }}
                     >
-                      {descriptionVisible ? (
-                        <ChevronUp size={14} />
-                      ) : (
-                        <ChevronDown size={14} />
-                      )}
+                      <FileText size={14} />
                     </button>
                   )}
                 </div>
@@ -728,7 +724,7 @@ export function ConstructsCatalog({
           role="listbox"
           aria-label="Constructs"
           aria-multiselectable="true"
-          aria-activedescendant={focusedId ? `construct-${focusedId}` : undefined}
+          aria-activedescendant={focusedAlias ? `construct-${focusedAlias}` : undefined}
           style={{
             listStyle: 'none',
             margin: 0,
@@ -739,8 +735,8 @@ export function ConstructsCatalog({
           }}
         >
           {orderedComponents.map((c) => {
-            const visible = visibleSet.has(c.id);
-            const focused = c.id === focusedId;
+            const visible = visibleSet.has(c.alias);
+            const focused = c.alias === focusedAlias;
             const color = componentColor(c, pierreTheme);
             const badgeColor = constructBadgeColor(c) ?? color;
             const badgeLabel = constructBadgeLabel(c);
@@ -757,19 +753,19 @@ export function ConstructsCatalog({
               !!c.file &&
               c.file === drawer.file &&
               c.declarationRef?.startLine === drawer.startLine;
-            const hovered = hoveredRow === c.id;
+            const hovered = hoveredRow === c.alias;
             return (
-              <li key={c.id} role="presentation">
+              <li key={c.alias} role="presentation">
                 <button
                   type="button"
-                  id={`construct-${c.id}`}
+                  id={`construct-${c.alias}`}
                   role="option"
                   aria-selected={visible}
-                  data-testid={`construct-row-${c.id}`}
-                  onClick={() => toggle(c.id)}
-                  onMouseEnter={() => setHoveredRow(c.id)}
+                  data-testid={`construct-row-${c.alias}`}
+                  onClick={() => toggle(c.alias)}
+                  onMouseEnter={() => setHoveredRow(c.alias)}
                   onMouseLeave={() =>
-                    setHoveredRow((h) => (h === c.id ? null : h))
+                    setHoveredRow((h) => (h === c.alias ? null : h))
                   }
                   style={{
                     display: 'flex',
@@ -938,8 +934,8 @@ export function ConstructsCatalog({
                     c.declarationRef?.startLine === drawer.startLine;
                   return (
                     <div
-                      key={c.id}
-                      id={`construct-signature-${c.id}`}
+                      key={c.alias}
+                      id={`construct-signature-${c.alias}`}
                       style={{
                         border: `1px solid ${lineOpen ? accentColor : theme.colors.border}`,
                         boxShadow: lineOpen ? `0 0 0 1px ${accentColor}` : undefined,
@@ -959,7 +955,7 @@ export function ConstructsCatalog({
                         showRepoIdentity={false}
                         fileBadgeChrome={!!fileViewer}
                         verification={
-                          componentVerification && focusedId === c.id
+                          componentVerification && focusedAlias === c.alias
                             ? componentVerification
                             : undefined
                         }