unspaghettit 0.2.0 → 0.3.0

package/src/features/behavior-model/presentation/components/BehaviorGraph.svelte

@@ -0,0 +1,370 @@
+<script lang="ts">
+  import { onDestroy, onMount } from 'svelte';
+  import type { Feature } from '$features/behavior-model/domain/entities/Feature';
+  import {
+    ALL_BEHAVIOR_GRAPH_EDGE_KINDS,
+    ALL_BEHAVIOR_GRAPH_NODE_TYPES,
+    buildBehaviorGraph,
+    deriveBehaviorGraphView,
+    filterBehaviorGraphView,
+    type BehaviorGraphEdgeKind
+  } from '$features/behavior-model/domain/services/BehaviorGraphModel';
+  import {
+    behaviorGraphEdgeTheme,
+    behaviorGraphNodeTheme
+  } from '$features/behavior-model/presentation/view-models/BehaviorGraphTheme';
+  import {
+    VisBehaviorGraphRenderer,
+    type VisNetworkRuntime
+  } from '$features/behavior-model/presentation/adapters/VisBehaviorGraphRenderer';
+  import type { Project } from '$features/projects/domain/entities/Project';
+
+  type Props = {
+    feature?: Feature;
+    features?: readonly Feature[];
+    project?: Project;
+  };
+  let { feature, features, project }: Props = $props();
+
+  let search = $state('');
+  let selectedId = $state<string | null>(null);
+  let selectedEdgeId = $state<string | null>(null);
+  let labelsVisible = $state(false);
+  let physicsSettled = $state(false);
+  let stabilizationProgress = $state(0);
+  let graphContainer = $state<HTMLDivElement | null>(null);
+  let renderer: VisBehaviorGraphRenderer | null = null;
+
+  let enabledKinds = $state<Record<BehaviorGraphEdgeKind, boolean>>({
+    contains: true,
+    reads: true,
+    writes: true,
+    emits: true,
+    transitions: true,
+    asserts: true,
+    uses: true,
+    handles: true
+  });
+
+  const sourceFeatures = $derived(features ?? (feature ? [feature] : []));
+  const graphTitle = $derived(project?.name ?? feature?.name ?? 'Behavior graph');
+  const graphSubtitle = $derived(
+    project
+      ? `The whole project behavior map across ${sourceFeatures.length} feature${sourceFeatures.length === 1 ? '' : 's'} from the shared Unspa hub.`
+      : 'A connected map of the executable behavior model from the shared Unspa hub.'
+  );
+  const backHref = $derived(project ? `/projects/${project.id}` : feature ? `/features/${feature.id}` : '/projects');
+  const backLabel = $derived(project ? 'Back to project' : 'Back to editor');
+
+  const rawGraph = $derived(buildBehaviorGraph(sourceFeatures, project));
+  const graph = $derived(deriveBehaviorGraphView(rawGraph));
+  const filteredGraph = $derived(
+    filterBehaviorGraphView(graph, {
+      search,
+      enabledKinds
+    })
+  );
+
+  const selectedNode = $derived(selectedId ? graph.nodeById.get(selectedId) ?? null : null);
+  const selectedEdge = $derived(
+    selectedEdgeId ? filteredGraph.edges.find((edge) => edge.id === selectedEdgeId) ?? null : null
+  );
+  const selectedEdgeFrom = $derived(selectedEdge ? graph.nodeById.get(selectedEdge.from) ?? null : null);
+  const selectedEdgeTo = $derived(selectedEdge ? graph.nodeById.get(selectedEdge.to) ?? null : null);
+  const centralNodes = $derived([...graph.nodes].sort((a, b) => b.degree - a.degree).slice(0, 6));
+  const countsByType = $derived.by(() => {
+    const counts = new Map<string, number>();
+    for (const node of graph.nodes) counts.set(node.type, (counts.get(node.type) ?? 0) + 1);
+    return counts;
+  });
+
+  const renderGraph = (): void => {
+    renderer?.render({
+      graph: filteredGraph,
+      selectedId,
+      selectedEdgeId,
+      labelsVisible,
+      nodeTheme: behaviorGraphNodeTheme,
+      edgeTheme: behaviorGraphEdgeTheme
+    });
+  };
+
+  const toggleKind = (kind: BehaviorGraphEdgeKind): void => {
+    enabledKinds = { ...enabledKinds, [kind]: !enabledKinds[kind] };
+  };
+
+  const resetView = (): void => {
+    selectedId = null;
+    selectedEdgeId = null;
+    search = '';
+    renderer?.fit();
+  };
+
+  const focusNode = (nodeId: string): void => {
+    selectedId = nodeId;
+    selectedEdgeId = null;
+    renderer?.select(nodeId, null);
+  };
+
+  $effect(() => {
+    filteredGraph.nodes;
+    filteredGraph.edges;
+    labelsVisible;
+    selectedId;
+    selectedEdgeId;
+    renderGraph();
+  });
+
+  onMount(() => {
+    let disposed = false;
+    const handleResize = (): void => renderer?.fit();
+    void (async () => {
+      const runtime = (await import('vis-network/standalone')) as VisNetworkRuntime;
+      if (disposed || !graphContainer) return;
+      renderer = new VisBehaviorGraphRenderer(runtime, graphContainer, {
+        onSelectedNodeChange: (id) => {
+          selectedId = id;
+        },
+        onSelectedEdgeChange: (id) => {
+          selectedEdgeId = id;
+        },
+        onStabilizationProgress: (progress) => {
+          stabilizationProgress = progress;
+        },
+        onSettledChange: (settled) => {
+          physicsSettled = settled;
+        }
+      });
+      renderGraph();
+      window.addEventListener('resize', handleResize);
+    })();
+    return () => {
+      disposed = true;
+      window.removeEventListener('resize', handleResize);
+    };
+  });
+
+  onDestroy(() => {
+    renderer?.destroy();
+    renderer = null;
+  });
+</script>
+
+<section class="space-y-4">
+  <div class="overflow-hidden rounded-lg border border-slate-200 bg-white shadow-sm shadow-slate-950/5">
+    <div class="border-b border-slate-200 bg-slate-950 px-4 py-4 text-white">
+      <div class="flex flex-wrap items-start justify-between gap-4">
+        <div class="min-w-0">
+          <p class="text-xs font-semibold uppercase tracking-wide text-cyan-200">Behavior Graph</p>
+          <h2 class="mt-1 truncate text-2xl font-semibold">{graphTitle}</h2>
+          <p class="mt-1 max-w-3xl text-sm leading-6 text-slate-300">{graphSubtitle}</p>
+        </div>
+        <a
+          href={backHref}
+          class="rounded-md border border-white/20 px-3 py-2 text-sm font-medium text-white hover:bg-white/10"
+        >
+          {backLabel}
+        </a>
+      </div>
+    </div>
+
+    <div class="grid gap-0 lg:grid-cols-[minmax(0,1fr)_320px]">
+      <div class="min-w-0 border-b border-slate-200 lg:border-b-0 lg:border-r">
+        <div class="flex flex-wrap items-center gap-3 border-b border-slate-200 bg-slate-50 px-4 py-3">
+          <input
+            type="search"
+            bind:value={search}
+            placeholder="Search nodes"
+            class="w-full rounded-md border border-slate-300 bg-white px-3 py-2 text-sm outline-none focus:border-brand-700 sm:w-64"
+          />
+          <button
+            type="button"
+            class="rounded-md border border-slate-300 px-3 py-2 text-sm font-medium text-slate-700 hover:bg-white"
+            onclick={() => renderer?.relayout(filteredGraph.nodes.length)}
+          >
+            Re-layout
+          </button>
+          <button
+            type="button"
+            class="rounded-md border border-slate-300 px-3 py-2 text-sm font-medium text-slate-700 hover:bg-white"
+            onclick={() => renderer?.fit()}
+          >
+            Fit
+          </button>
+          <div class="flex rounded-md border border-slate-300 bg-white p-1">
+            <button
+              type="button"
+              class="rounded px-2.5 py-1 text-sm font-semibold text-slate-700 hover:bg-slate-50"
+              aria-label="Zoom out"
+              onclick={() => renderer?.zoomBy(0.72)}
+            >
+              -
+            </button>
+            <button
+              type="button"
+              class="rounded px-2.5 py-1 text-sm font-semibold text-slate-700 hover:bg-slate-50"
+              aria-label="Zoom in"
+              onclick={() => renderer?.zoomBy(1.38)}
+            >
+              +
+            </button>
+          </div>
+          <button
+            type="button"
+            class="rounded-md border border-slate-300 px-3 py-2 text-sm font-medium text-slate-700 hover:bg-white"
+            onclick={resetView}
+          >
+            Reset
+          </button>
+          <button
+            type="button"
+            class="rounded-md border border-slate-300 px-3 py-2 text-sm font-medium {labelsVisible ? 'bg-slate-900 text-white' : 'text-slate-700 hover:bg-white'}"
+            onclick={() => (labelsVisible = !labelsVisible)}
+          >
+            Labels
+          </button>
+          <div class="flex flex-wrap gap-1">
+            {#each ALL_BEHAVIOR_GRAPH_EDGE_KINDS as kind}
+              <button
+                type="button"
+                class="rounded-full border px-2.5 py-1 text-xs font-medium {enabledKinds[kind]
+                  ? 'border-slate-300 bg-white text-slate-800'
+                  : 'border-slate-200 bg-slate-100 text-slate-400'}"
+                onclick={() => toggleKind(kind)}
+              >
+                {behaviorGraphEdgeTheme[kind].label}
+              </button>
+            {/each}
+          </div>
+        </div>
+
+        <div class="graph-canvas relative">
+          <div
+            bind:this={graphContainer}
+            class="h-[76vh] min-h-[720px] w-full"
+            aria-label={`Interactive behavior graph for ${graphTitle}`}
+          ></div>
+          <div class="pointer-events-none absolute bottom-3 left-3 rounded-md border border-slate-200 bg-white/88 px-3 py-2 text-xs text-slate-600 shadow-sm backdrop-blur">
+            ForceAtlas2 settles the graph, then physics stops for smooth panning. Wheel, pinch, or +/- to zoom.
+          </div>
+          {#if !physicsSettled && stabilizationProgress < 100}
+            <div class="pointer-events-none absolute left-1/2 top-3 w-64 -translate-x-1/2 rounded-md border border-slate-200 bg-white/90 p-3 text-xs text-slate-600 shadow-sm backdrop-blur">
+              <div class="flex justify-between font-medium text-slate-800">
+                <span>Stabilizing layout</span>
+                <span>{stabilizationProgress}%</span>
+              </div>
+              <div class="mt-2 h-1.5 overflow-hidden rounded-full bg-slate-200">
+                <div class="h-full rounded-full bg-brand-500 transition-all" style={`width:${stabilizationProgress}%`}></div>
+              </div>
+            </div>
+          {/if}
+        </div>
+      </div>
+
+      <aside class="space-y-4 p-4">
+        <div>
+          <h3 class="text-sm font-semibold text-slate-950">Graph Summary</h3>
+          <div class="mt-3 grid grid-cols-2 gap-2 text-sm">
+            <div class="rounded-md bg-slate-100 p-3">
+              <div class="text-2xl font-semibold text-slate-950">{graph.nodes.length}</div>
+              <div class="text-xs text-slate-500">nodes</div>
+            </div>
+            <div class="rounded-md bg-slate-100 p-3">
+              <div class="text-2xl font-semibold text-slate-950">{graph.edges.length}</div>
+              <div class="text-xs text-slate-500">edges</div>
+            </div>
+          </div>
+        </div>
+
+        <div>
+          <h3 class="text-sm font-semibold text-slate-950">Node Types</h3>
+          <div class="mt-2 flex flex-wrap gap-1.5">
+            {#each ALL_BEHAVIOR_GRAPH_NODE_TYPES as type}
+              {#if countsByType.get(type)}
+                <span
+                  class="inline-flex items-center gap-1 rounded-full border border-slate-200 bg-white px-2 py-1 text-xs text-slate-700"
+                >
+                  <span
+                    class="h-2 w-2 rounded-full"
+                    style={`background:${behaviorGraphNodeTheme[type].fill}`}
+                  ></span>
+                  {behaviorGraphNodeTheme[type].label} {countsByType.get(type)}
+                </span>
+              {/if}
+            {/each}
+          </div>
+        </div>
+
+        <div>
+          <h3 class="text-sm font-semibold text-slate-950">Central Nodes</h3>
+          <div class="mt-2 space-y-2">
+            {#each centralNodes as node}
+              <button
+                type="button"
+                class="w-full rounded-md border border-slate-200 bg-white px-3 py-2 text-left hover:border-brand-300 hover:bg-brand-50"
+                onclick={() => focusNode(node.id)}
+              >
+                <span class="block truncate text-sm font-medium text-slate-900">{node.label}</span>
+                <span class="text-xs text-slate-500">{behaviorGraphNodeTheme[node.type].label} / {node.degree} links</span>
+              </button>
+            {/each}
+          </div>
+        </div>
+
+        <div class="rounded-md border border-slate-200 bg-slate-50 p-3">
+          {#if selectedNode}
+            <p class="text-xs font-semibold uppercase tracking-wide text-slate-500">
+              {behaviorGraphNodeTheme[selectedNode.type].label}
+            </p>
+            <h3 class="mt-1 text-base font-semibold text-slate-950">{selectedNode.label}</h3>
+            {#if selectedNode.detail}
+              <p class="mt-2 text-sm leading-6 text-slate-600">{selectedNode.detail}</p>
+            {/if}
+            <p class="mt-2 text-xs text-slate-500">{selectedNode.degree} graph links</p>
+            {#if selectedNode.href}
+              <a class="mt-3 inline-flex text-sm font-medium text-brand-700 hover:underline" href={selectedNode.href}>
+                Open in editor
+              </a>
+            {/if}
+          {:else if selectedEdge}
+            <p class="text-xs font-semibold uppercase tracking-wide text-slate-500">
+              {behaviorGraphEdgeTheme[selectedEdge.kind].label}
+            </p>
+            <h3 class="mt-1 text-base font-semibold text-slate-950">{selectedEdge.label ?? 'Behavior link'}</h3>
+            <p class="mt-2 text-sm leading-6 text-slate-600">
+              {selectedEdgeFrom?.label ?? selectedEdge.from} -> {selectedEdgeTo?.label ?? selectedEdge.to}
+            </p>
+            <p class="mt-2 text-xs text-slate-500">Click another node or edge to move the highlighted neighborhood.</p>
+          {:else}
+            <h3 class="text-sm font-semibold text-slate-950">Explore the Map</h3>
+            <p class="mt-2 text-sm leading-6 text-slate-600">
+              Click a node or edge to highlight its linked behavior. Hover highlighting is disabled so
+              the canvas stays lighter on slower laptops.
+            </p>
+          {/if}
+        </div>
+      </aside>
+    </div>
+  </div>
+</section>
+
+<style>
+  .graph-canvas {
+    background:
+      radial-gradient(circle at 50% 45%, rgba(34, 211, 238, 0.12), transparent 34rem),
+      radial-gradient(circle at 15% 20%, rgba(14, 116, 144, 0.08), transparent 22rem),
+      linear-gradient(#f8fafc, #eef6fb);
+  }
+
+  .graph-canvas::before {
+    position: absolute;
+    inset: 0;
+    pointer-events: none;
+    content: '';
+    background-image:
+      linear-gradient(rgba(15, 23, 42, 0.045) 1px, transparent 1px),
+      linear-gradient(90deg, rgba(15, 23, 42, 0.045) 1px, transparent 1px);
+    background-size: 28px 28px;
+    mask-image: radial-gradient(circle at center, black 0, black 55%, transparent 100%);
+  }
+</style>

package/src/features/behavior-model/presentation/components/FeatureHeader.svelte

@@ -110,11 +110,19 @@
     {/if}
   </div>
 
-  <div class="flex shrink-0 flex-wrap items-center gap-2 rounded-xl border border-slate-200 bg-white p-1.5 shadow-sm shadow-slate-950/5">
-    <div class="flex rounded-lg border border-hairline bg-white p-1">
-      <button
-        type="button"
-        title={undoTitle}
+  <div class="flex shrink-0 flex-wrap items-center gap-2 rounded-xl border border-slate-200 bg-white p-1.5 shadow-sm shadow-slate-950/5">
+    <div class="flex rounded-lg border border-hairline bg-white p-1">
+      <a
+        href={`/features/${feature.id}/graph`}
+        title="Open behavior graph"
+        aria-label="Open behavior graph"
+        class="rounded-md px-2 py-1.5 text-xs font-medium text-slate-700 hover:bg-slate-50"
+      >
+        Graph
+      </a>
+      <button
+        type="button"
+        title={undoTitle}
         aria-label={undoTitle}
         class="rounded-md px-2 py-1.5 text-xs font-medium text-slate-700 hover:bg-slate-50 disabled:cursor-not-allowed disabled:opacity-40"
         disabled={!featureStore.canUndo}

package/src/features/behavior-model/presentation/view-models/BehaviorGraphTheme.ts

@@ -0,0 +1,43 @@
+import type {
+  BehaviorGraphEdgeKind,
+  BehaviorGraphNodeType
+} from '$features/behavior-model/domain/services/BehaviorGraphModel';
+
+export type BehaviorGraphNodeTheme = {
+  readonly label: string;
+  readonly fill: string;
+  readonly stroke: string;
+};
+
+export type BehaviorGraphEdgeTheme = {
+  readonly label: string;
+  readonly color: string;
+};
+
+export const behaviorGraphNodeTheme: Record<BehaviorGraphNodeType, BehaviorGraphNodeTheme> = {
+  feature: { label: 'Feature', fill: '#0f172a', stroke: '#020617' },
+  surface: { label: 'Surface', fill: '#0e7490', stroke: '#155e75' },
+  action: { label: 'Action', fill: '#2563eb', stroke: '#1d4ed8' },
+  state: { label: 'State', fill: '#7c3aed', stroke: '#6d28d9' },
+  event: { label: 'Event', fill: '#db2777', stroke: '#be185d' },
+  parameter: { label: 'Parameter', fill: '#0891b2', stroke: '#0e7490' },
+  rule: { label: 'Rule', fill: '#ea580c', stroke: '#c2410c' },
+  effect: { label: 'Effect', fill: '#16a34a', stroke: '#15803d' },
+  invariant: { label: 'Invariant', fill: '#ca8a04', stroke: '#a16207' },
+  scenario: { label: 'Scenario', fill: '#475569', stroke: '#334155' },
+  persona: { label: 'Persona', fill: '#0f766e', stroke: '#115e59' },
+  resource: { label: 'Resource', fill: '#4f46e5', stroke: '#4338ca' },
+  entity: { label: 'Entity', fill: '#9333ea', stroke: '#7e22ce' },
+  valueSet: { label: 'Value set', fill: '#64748b', stroke: '#475569' }
+};
+
+export const behaviorGraphEdgeTheme: Record<BehaviorGraphEdgeKind, BehaviorGraphEdgeTheme> = {
+  contains: { label: 'Contains', color: '#94a3b8' },
+  reads: { label: 'Reads', color: '#7c3aed' },
+  writes: { label: 'Writes', color: '#16a34a' },
+  emits: { label: 'Emits', color: '#db2777' },
+  transitions: { label: 'Transitions', color: '#0891b2' },
+  asserts: { label: 'Asserts', color: '#ca8a04' },
+  uses: { label: 'Uses', color: '#475569' },
+  handles: { label: 'Handles', color: '#2563eb' }
+};

package/src/features/builder-mode/domain/BuilderModeDashboard.ts

@@ -20,6 +20,10 @@ export type BuilderModeFeature = {
   readonly maturityPercentage: number;
   readonly implementationPercentage: number | null;
   readonly suggestions: readonly BuilderModeSuggestion[];
+  // The surface this feature (action) lives on. A surface is a higher-level
+  // grouping — the Builder lists features under their surface as a heading.
+  readonly surfaceId: string;
+  readonly surfaceName: string;
 };
 
 export type BuilderModeCoreFeature = {
@@ -137,7 +141,9 @@ export const buildBuilderModeDashboard = (
             implementationPercentage,
             // Per-action advice was deterministic noise; suggestions now live at
             // the feature level as the model's Evolutions.
-            suggestions: []
+            suggestions: [],
+            surfaceId: String(surface.id),
+            surfaceName: surface.name
           };
         })
       );

package/src/features/builder-mode/presentation/components/BuilderModeDashboard.svelte

@@ -1,7 +1,7 @@
 <script lang="ts">
   import { onDestroy, onMount, tick } from 'svelte';
   import { page } from '$app/state';
-  import { replaceState } from '$app/navigation';
+  import { afterNavigate, replaceState } from '$app/navigation';
   import { fade, fly, slide } from 'svelte/transition';
   import { flip } from 'svelte/animate';
   import { cubicOut } from 'svelte/easing';
@@ -10,6 +10,7 @@
   import { humanizeTagText } from '$shared/domain/Tags';
   import GameScore from './GameScore.svelte';
   import { builderModeStore } from '$features/builder-mode/presentation/stores/builderModeStore.svelte';
+  import { registerViewLinkResolver } from '$shared/presentation/toast/viewLinkResolver';
   import type {
     BuilderModeFeature,
     BuilderModeSuggestion
@@ -191,6 +192,7 @@
   });
 
   let unsubscribeSync: (() => void) | null = null;
+  let unregisterViewLink: (() => void) | null = null;
 
   // Keep tag colors resolvable in this view: load the palette and feed it the
   // tag types as the dashboard surfaces them (same handshake the expert pages
@@ -219,28 +221,54 @@
     if (url.search !== before) replaceState(`${url.pathname}${url.search}`, {});
   });
 
+  // The other half of the URL ↔ selection binding, but driven by real
+  // navigations only — the activity-toast "View" links into the Builder and
+  // browser back/forward. Crucially NOT a reactive `page.url` effect: that
+  // raced the writer above (on a card click it would run before the writer
+  // had reflected the new selection into the URL, read the stale empty query,
+  // and revert the click). `afterNavigate` fires on link clicks / popstate but
+  // NOT on the writer's `replaceState`, so there's no race. The initial load
+  // (`from` is null) is left to onMount's restore.
+  afterNavigate((nav) => {
+    if (!nav.from) return;
+    const params = page.url.searchParams;
+    builderModeStore.applySelection(params.get('project'), params.get('core'));
+  });
+
   onMount(() => {
     // Restore selection from the URL before the sync effect runs.
     const params = page.url.searchParams;
-    const pid = params.get('project');
-    const cid = params.get('core');
-    if (pid) {
-      builderModeStore.selectProject(pid);
-      if (cid) builderModeStore.selectCoreFeature(cid);
-    }
+    const initialProject = params.get('project');
+    builderModeStore.applySelection(initialProject, params.get('core'));
     urlRestored = true;
 
-    void builderModeStore.refresh();
+    // Teach the activity-toast to deep-link into the Builder while it's open
+    // (falling back to the Expert route when an entity isn't shown here).
+    unregisterViewLink = registerViewLinkResolver((kind, id) =>
+      builderModeStore.deepLinkFor(kind, id)
+    );
+
+    // Deep-linked to one project → load just that project (the rest of the
+    // list fills in lazily if the user goes back to all projects). No project
+    // in the URL → load the full list up front.
+    if (initialProject) {
+      void builderModeStore.loadProjectOnly(initialProject);
+    } else {
+      void builderModeStore.refresh();
+    }
     void builderModeStore.refreshTagPalette();
     unsubscribeSync = builderModeStore.subscribeSync((event) => {
-      // Refresh on any change that can move what the Builder shows: project /
-      // feature edits and implementation-status reports (the Built dials).
+      // Scoped, in-place update — rebuild only the affected project's card
+      // (like the Expert view's refetchOne) instead of the whole dashboard,
+      // so scroll / selection / the queue widget / expanded descriptions are
+      // preserved. The store decides project vs feature scope and only does a
+      // full refresh for a genuinely new entity.
       if (
         event.kind === 'project' ||
         event.kind === 'feature' ||
         event.kind === 'implementation-status'
       ) {
-        void builderModeStore.refreshSilent();
+        void builderModeStore.applySyncEvent(event);
       }
     });
   });
@@ -248,6 +276,8 @@
   onDestroy(() => {
     unsubscribeSync?.();
     unsubscribeSync = null;
+    unregisterViewLink?.();
+    unregisterViewLink = null;
   });
 
   // Floating build-queue widget: minimized (bubble) vs expanded (panel).
@@ -438,7 +468,7 @@
       {@const selectedProject = builderModeStore.selectedProject}
       <div class="space-y-6">
         <button type="button" class={ghostPill} onclick={() => builderModeStore.deselectProject()}>
-          ← All projects ({builderModeStore.dashboard.projects.length})
+          ← All projects ({builderModeStore.projectCount})
         </button>
 
         <section class="overflow-hidden rounded-2xl border border-slate-700/60 bg-linear-to-b from-slate-800/45 to-slate-900 shadow-xl shadow-black/20">
@@ -533,6 +563,7 @@
                             onRemove={(tag) => builderModeStore.removeCoreFeatureTag(coreFeature.id, tag)}
                             onRename={(from, to) => builderModeStore.renameTag(from, to)}
                             typeOptions={builderModeStore.allTagTypes}
+                            collapsible
                             class="relative z-20 mt-2"
                           />
                         </div>
@@ -611,9 +642,22 @@
               </div>
             {:else}
               {@const coreFeatureId = builderModeStore.selectedCoreFeature.id}
-              <div class="space-y-3">
-                {#each builderModeStore.visibleSelectedFeatures as feature, i (feature.id)}
-                  {@render FeatureCard(coreFeatureId, feature, i)}
+              <div class="space-y-4">
+                {#each builderModeStore.visibleSelectedSurfaces as surface (surface.surfaceId)}
+                  <div class="space-y-2">
+                    <!-- A surface is a higher-level grouping; its features
+                         (actions) are the specified leaves listed under it.
+                         Always shown so the surface level is visible even when a
+                         core feature has a single surface. -->
+                    <div class="flex items-center gap-2 px-1 pt-1">
+                      <span class="text-[11px] font-semibold uppercase tracking-wide text-slate-500">{surface.surfaceName}</span>
+                      <span class="h-px flex-1 bg-slate-800" aria-hidden="true"></span>
+                      <span class="text-[10px] tabular-nums text-slate-600">{surface.features.length}</span>
+                    </div>
+                    {#each surface.features as feature, i (feature.id)}
+                      {@render FeatureCard(coreFeatureId, feature, i)}
+                    {/each}
+                  </div>
                 {/each}
               </div>
             {/if}
@@ -630,7 +674,7 @@
           <div class="flex shrink-0 items-center gap-3">
             {@render ActiveTagFilter()}
             <p class="text-xs text-slate-500">
-              {builderModeStore.filteredProjects.length}{builderModeStore.searchActive || builderModeStore.tagActive ? ` of ${builderModeStore.dashboard.projects.length}` : ' total'}
+              {builderModeStore.filteredProjects.length}{builderModeStore.searchActive || builderModeStore.tagActive ? ` of ${builderModeStore.projectCount}` : ' total'}
             </p>
           </div>
         </div>
@@ -666,6 +710,7 @@
                       onRemove={(tag) => builderModeStore.removeProjectTag(project.id, tag)}
                       onRename={(from, to) => builderModeStore.renameTag(from, to)}
                       typeOptions={builderModeStore.allTagTypes}
+                      collapsible
                       class="relative z-20"
                     />
                   </div>
@@ -677,6 +722,23 @@
               </article>
             </li>
           {/each}
+          <!-- Placeholders for projects still streaming in (progressive load).
+               Only while not searching/filtering, where the visible set equals
+               the loaded set. -->
+          {#if builderModeStore.pendingProjectCount > 0 && !builderModeStore.searchActive && !builderModeStore.tagActive}
+            {#each Array.from({ length: builderModeStore.pendingProjectCount }) as _, i (`pending-${i}`)}
+              <li class="builder-skeleton__card" aria-hidden="true">
+                <div class="flex items-center justify-between gap-3">
+                  <span class="builder-skeleton__shape h-2.5 w-3/5 rounded-full"></span>
+                  <span class="builder-skeleton__shape h-4 w-14 rounded-full"></span>
+                </div>
+                <div class="flex justify-center gap-10 pt-5">
+                  <span class="builder-skeleton__shape size-11 rounded-full"></span>
+                  <span class="builder-skeleton__shape size-11 rounded-full"></span>
+                </div>
+              </li>
+            {/each}
+          {/if}
         </ul>
       </section>
     {/if}