@topogram/cli 0.3.34

package/src/import/extractors/ui/blazor.js

@@ -0,0 +1,227 @@
+import {
+  canonicalCandidateTerm,
+  dedupeCandidateRecords,
+  findImportFiles,
+  idHintify,
+  makeCandidateRecord,
+  relativeTo,
+  titleCase
+} from "../../core/shared.js";
+
+function shouldIgnoreFile(filePath) {
+  return /\/obj\/|\/bin\/|\/wwwroot\/|\/_Imports\.razor$/.test(filePath);
+}
+
+function parsePageRoutes(text) {
+  return [...String(text || "").matchAll(/@page\s+"([^"]+)"/g)].map((match) => match[1]);
+}
+
+function screenIdFromFile(filePath) {
+  const base = filePath.split("/").pop()?.replace(/\.razor(?:\.cs)?$/i, "") || "screen";
+  if (/^List$/i.test(base)) return "catalog_item_list";
+  if (/^Create$/i.test(base)) return "catalog_item_create";
+  if (/^Edit$/i.test(base)) return "catalog_item_edit";
+  if (/^Delete$/i.test(base)) return "catalog_item_delete";
+  if (/^Details$/i.test(base)) return "catalog_item_detail";
+  if (/^Logout$/i.test(base)) return "account_logout";
+  return idHintify(canonicalCandidateTerm(base.replace(/([a-z0-9])([A-Z])/g, "$1_$2")));
+}
+
+function screenKindFromId(screenId) {
+  if (/list/.test(screenId)) return "list";
+  if (/detail/.test(screenId)) return "detail";
+  if (/create|edit|delete/.test(screenId)) return "form";
+  if (/logout|login|account/.test(screenId)) return "auth";
+  return "flow";
+}
+
+function conceptIdFromScreenId(screenId) {
+  if (/catalog_item/.test(screenId)) return "surface_catalog_item";
+  if (/account|logout/.test(screenId)) return "surface_account";
+  return `surface_${screenId}`;
+}
+
+function entityIdFromScreenId(screenId) {
+  if (/catalog_item/.test(screenId)) return "entity_catalog-item";
+  return null;
+}
+
+function routePathForScreen(screenId, explicitRoutes) {
+  if (explicitRoutes.length > 0) return explicitRoutes[0];
+  if (screenId === "catalog_item_create") return "/admin/catalog-items/create";
+  if (screenId === "catalog_item_edit") return "/admin/catalog-items/:id/edit";
+  if (screenId === "catalog_item_delete") return "/admin/catalog-items/:id/delete";
+  if (screenId === "catalog_item_detail") return "/admin/catalog-items/:id";
+  if (screenId === "catalog_item_list") return "/admin";
+  if (screenId === "account_logout") return "/logout";
+  return `/${screenId.replace(/_/g, "-")}`;
+}
+
+function capabilityHintsForText(text) {
+  const source = String(text || "");
+  const hints = [];
+  if (/\bCatalogItemService\.List\s*\(/.test(source)) hints.push("cap_list_catalog_items");
+  if (/\bCatalogItemService\.GetById\s*\(/.test(source)) hints.push("cap_get_catalog_item");
+  if (/\bCatalogItemService\.Create\s*\(/.test(source)) hints.push("cap_create_catalog_item");
+  if (/\bCatalogItemService\.Edit\s*\(/.test(source)) hints.push("cap_update_catalog_item");
+  if (/\bCatalogItemService\.Delete\s*\(/.test(source)) hints.push("cap_delete_catalog_item");
+  if (/\bPostAsync\(\s*"User\/Logout"/.test(source) || /\bRouteOutside\(\s*"\/Identity\/Account\/Login"/.test(source)) {
+    hints.push("cap_sign_out_account");
+  }
+  return [...new Set(hints)];
+}
+
+function combinedComponentText(context, filePath, markupText) {
+  const codeBehindPath = `${filePath}.cs`;
+  const codeBehindText = context.helpers.readTextIfExists(codeBehindPath) || "";
+  return `${markupText || ""}\n${codeBehindText}`;
+}
+
+function blazorLayoutSummary(text) {
+  const source = String(text || "");
+  return {
+    shellKind:
+      /<AuthorizeRouteView\b/.test(source) ? "authenticated_app"
+      : /<Router\b/.test(source) ? "topbar"
+      : null,
+    patterns: [
+      ...new Set([
+        /<Router\b/.test(source) ? "route_table" : null,
+        /<AuthorizeRouteView\b/.test(source) ? "authenticated_routes" : null,
+        /<CascadingAuthenticationState\b/.test(source) ? "auth_state" : null
+      ].filter(Boolean))
+    ]
+  };
+}
+
+export const blazorUiExtractor = {
+  id: "ui.blazor",
+  track: "ui",
+  detect(context) {
+    const razorFiles = findImportFiles(context.paths, (filePath) => /\.razor$/i.test(filePath))
+      .filter((filePath) => !shouldIgnoreFile(filePath));
+    const score = razorFiles.length > 0 ? 86 : 0;
+    return {
+      score,
+      reasons: score > 0 ? ["Found Blazor .razor components and pages"] : []
+    };
+  },
+  extract(context) {
+    const razorFiles = findImportFiles(context.paths, (filePath) => /\.razor$/i.test(filePath))
+      .filter((filePath) => !shouldIgnoreFile(filePath));
+    const findings = [];
+    const candidates = { screens: [], routes: [], actions: [], stacks: [] };
+
+    for (const filePath of razorFiles) {
+      const text = context.helpers.readTextIfExists(filePath) || "";
+      const combinedText = combinedComponentText(context, filePath, text);
+      const relativePath = relativeTo(context.paths.repoRoot, filePath);
+      const explicitRoutes = parsePageRoutes(text);
+      const baseName = filePath.split("/").pop() || "";
+      const isShell = /\/App\.razor$/.test(filePath);
+      const isComponent = /\/Pages\/|\/Shared\//.test(filePath);
+      if (!isShell && !isComponent) continue;
+
+      if (isShell) {
+        const summary = blazorLayoutSummary(text);
+        if (summary.shellKind) {
+          candidates.actions.push(makeCandidateRecord({
+            kind: "ui_shell",
+            idHint: `blazor_${idHintify(summary.shellKind)}_shell`,
+            label: titleCase(summary.shellKind),
+            confidence: "medium",
+            sourceKind: "layout_code",
+            provenance: relativePath,
+            track: "ui",
+            shell_kind: summary.shellKind
+          }));
+        }
+        for (const pattern of summary.patterns) {
+          candidates.actions.push(makeCandidateRecord({
+            kind: "ui_navigation",
+            idHint: `blazor_${idHintify(pattern)}`,
+            label: pattern,
+            confidence: "medium",
+            sourceKind: "layout_code",
+            provenance: relativePath,
+            track: "ui",
+            navigation_pattern: pattern
+          }));
+        }
+        continue;
+      }
+
+      if (/^(MainLayout|NavMenu|RedirectToLogin|Spinner|Toast|CustomInputSelect)\.razor$/i.test(baseName)) continue;
+
+      const screenId = screenIdFromFile(filePath);
+      const conceptId = conceptIdFromScreenId(screenId);
+      const entityId = entityIdFromScreenId(screenId);
+      const routePath = routePathForScreen(screenId, explicitRoutes);
+      const provenance = relativePath;
+      const capabilityHints = capabilityHintsForText(combinedText);
+
+      candidates.screens.push(makeCandidateRecord({
+        kind: "screen",
+        idHint: screenId,
+        label: titleCase(screenId),
+        confidence: explicitRoutes.length > 0 ? "high" : "medium",
+        sourceKind: explicitRoutes.length > 0 ? "route_code" : "component_code",
+        provenance,
+        track: "ui",
+        entity_id: entityId,
+        concept_id: conceptId,
+        screen_kind: screenKindFromId(screenId),
+        route_path: routePath,
+        capability_hints: capabilityHints
+      }));
+
+      candidates.routes.push(makeCandidateRecord({
+        kind: "ui_route",
+        idHint: `${screenId}_route`,
+        label: routePath,
+        confidence: explicitRoutes.length > 0 ? "high" : "medium",
+        sourceKind: explicitRoutes.length > 0 ? "route_code" : "component_code",
+        provenance,
+        track: "ui",
+        screen_id: screenId,
+        entity_id: entityId,
+        concept_id: conceptId,
+        path: routePath
+      }));
+
+      for (const capabilityHint of capabilityHints) {
+        candidates.actions.push(makeCandidateRecord({
+          kind: "ui_action",
+          idHint: `${screenId}_${idHintify(capabilityHint)}`,
+          label: capabilityHint,
+          confidence: "medium",
+          sourceKind: "component_code",
+          provenance,
+          track: "ui",
+          screen_id: screenId,
+          entity_id: entityId,
+          concept_id: conceptId,
+          capability_hint: capabilityHint,
+          prominence: /create|update|delete|sign_out/.test(capabilityHint) ? "primary" : "secondary"
+        }));
+      }
+
+      findings.push({
+        kind: "blazor_component",
+        file: relativePath,
+        screen_id: screenId,
+        route_count: explicitRoutes.length
+      });
+    }
+
+    if (candidates.screens.length > 0) {
+      candidates.stacks.push("blazor");
+    }
+
+    candidates.screens = dedupeCandidateRecords(candidates.screens, (record) => record.id_hint);
+    candidates.routes = dedupeCandidateRecords(candidates.routes, (record) => record.id_hint);
+    candidates.actions = dedupeCandidateRecords(candidates.actions, (record) => record.id_hint);
+    candidates.stacks = [...new Set(candidates.stacks)].sort();
+    return { findings, candidates };
+  }
+};

package/src/import/extractors/ui/flutter-screens.js

@@ -0,0 +1,152 @@
+import {
+  canonicalCandidateTerm,
+  dedupeCandidateRecords,
+  findImportFiles,
+  idHintify,
+  makeCandidateRecord,
+  relativeTo,
+  titleCase
+} from "../../core/shared.js";
+
+function featureStemFromPath(filePath) {
+  return canonicalCandidateTerm(filePath.match(/\/features\/([^/]+)\//)?.[1] || "item");
+}
+
+function inferScreenId(filePath) {
+  const fileStem = filePath.split("/").pop()?.replace(/\.dart$/, "") || "screen";
+  const normalized = idHintify(fileStem);
+  return normalized.replace(/_screen$/, "");
+}
+
+function inferScreenKind(screenId) {
+  if (/detail/.test(screenId)) return "detail";
+  if (/create|edit/.test(screenId)) return "form";
+  if (/list/.test(screenId)) return "list";
+  return "flow";
+}
+
+function inferRoutePath(featureStem, screenId) {
+  if (screenId === `${featureStem}_list`) return `/${featureStem}s`;
+  if (screenId === `create_${featureStem}`) return `/${featureStem}s/new`;
+  if (screenId === `${featureStem}_detail`) return `/${featureStem}s/:id`;
+  return `/${screenId.replace(/_/g, "-")}`;
+}
+
+function inferCapabilityHints(featureStem, screenId, text) {
+  const hints = new Set();
+  if (/refresh|get[A-Z][A-Za-z0-9_]*List|Fetched\(/.test(text) || /ListView\.builder/.test(text)) {
+    hints.add(`cap_list_${featureStem}s`);
+  }
+  if (/create[A-Z]|FloatingActionButton|note_add|Icons\.add/.test(text) || /Mode\.create/.test(text) || /Create[A-Z]/.test(screenId)) {
+    hints.add(`cap_create_${featureStem}`);
+  }
+  if (/update[A-Z]|Mode\.update|Icons\.edit/.test(text) || /edit/.test(screenId)) {
+    hints.add(`cap_update_${featureStem}`);
+  }
+  if (/delete[A-Z]|Icons\.delete|DeleteDialog/.test(text)) {
+    hints.add(`cap_delete_${featureStem}`);
+  }
+  if (/detail/.test(screenId) || /Navigator\.push/.test(text)) {
+    hints.add(`cap_list_${featureStem}s`);
+  }
+  return [...hints];
+}
+
+function parseScreenFile(filePath, text, repoRoot) {
+  const widgetMatch = String(text || "").match(/class\s+([A-Za-z_][A-Za-z0-9_]*)\s+extends\s+(?:StatefulWidget|StatelessWidget)/);
+  if (!widgetMatch) return null;
+  const featureStem = featureStemFromPath(filePath);
+  const screenId = inferScreenId(filePath);
+  const routePath = inferRoutePath(featureStem, screenId);
+  const entityId = `entity_${featureStem}`;
+  const provenance = `${relativeTo(repoRoot, filePath)}#${widgetMatch[1]}`;
+  const capabilityHints = inferCapabilityHints(featureStem, screenId, text);
+  return {
+    screen: makeCandidateRecord({
+      kind: "screen",
+      idHint: screenId,
+      label: titleCase(screenId),
+      confidence: "high",
+      sourceKind: "route_code",
+      provenance,
+      track: "ui",
+      entity_id: entityId,
+      concept_id: entityId,
+      screen_kind: inferScreenKind(screenId),
+      route_path: routePath,
+      capability_hints: capabilityHints
+    }),
+    route: makeCandidateRecord({
+      kind: "ui_route",
+      idHint: `${screenId}_route`,
+      label: routePath,
+      confidence: "high",
+      sourceKind: "route_code",
+      provenance,
+      track: "ui",
+      screen_id: screenId,
+      entity_id: entityId,
+      concept_id: entityId,
+      path: routePath
+    }),
+    actions: capabilityHints.map((capabilityHint) => makeCandidateRecord({
+      kind: "ui_action",
+      idHint: `${screenId}_${idHintify(capabilityHint)}`,
+      label: capabilityHint,
+      confidence: "medium",
+      sourceKind: "route_code",
+      provenance,
+      track: "ui",
+      screen_id: screenId,
+      entity_id: entityId,
+      concept_id: entityId,
+      capability_hint: capabilityHint,
+      prominence: "primary"
+    }))
+  };
+}
+
+export const flutterScreensUiExtractor = {
+  id: "ui.flutter-screens",
+  track: "ui",
+  detect(context) {
+    const files = findImportFiles(
+      context.paths,
+      (filePath) => /\/lib\/features\/.+\/presentation\/screens\/.+_screen\.dart$/i.test(filePath)
+    );
+    const score = files.length > 0 ? 84 : 0;
+    return {
+      score,
+      reasons: score > 0 ? ["Found Flutter feature presentation screens"] : []
+    };
+  },
+  extract(context) {
+    const files = findImportFiles(
+      context.paths,
+      (filePath) => /\/lib\/features\/.+\/presentation\/screens\/.+_screen\.dart$/i.test(filePath)
+    );
+    const findings = [];
+    const candidates = { screens: [], routes: [], actions: [], stacks: [] };
+    for (const filePath of files) {
+      const text = context.helpers.readTextIfExists(filePath) || "";
+      const parsed = parseScreenFile(filePath, text, context.paths.repoRoot);
+      if (!parsed) continue;
+      findings.push({
+        kind: "flutter_screen",
+        file: relativeTo(context.paths.repoRoot, filePath),
+        screen_id: parsed.screen.id_hint
+      });
+      candidates.screens.push(parsed.screen);
+      candidates.routes.push(parsed.route);
+      candidates.actions.push(...parsed.actions);
+    }
+    if (candidates.screens.length > 0) {
+      candidates.stacks.push("flutter_material");
+    }
+    candidates.screens = dedupeCandidateRecords(candidates.screens, (record) => record.id_hint);
+    candidates.routes = dedupeCandidateRecords(candidates.routes, (record) => record.id_hint);
+    candidates.actions = dedupeCandidateRecords(candidates.actions, (record) => record.id_hint);
+    candidates.stacks = [...new Set(candidates.stacks)].sort();
+    return { findings, candidates };
+  }
+};

package/src/import/extractors/ui/maui-xaml.js

@@ -0,0 +1,135 @@
+import {
+  canonicalCandidateTerm,
+  dedupeCandidateRecords,
+  findImportFiles,
+  idHintify,
+  makeCandidateRecord,
+  relativeTo,
+  titleCase
+} from "../../core/shared.js";
+
+function screenIdFromClass(className) {
+  return idHintify(canonicalCandidateTerm(className.replace(/Page$/, "").replace(/([a-z0-9])([A-Z])/g, "$1_$2")));
+}
+
+function entityIdFromScreen(screenId) {
+  if (/^todo_(item|list)$/.test(screenId)) return "entity_todo-item";
+  if (/main/.test(screenId)) return "entity_item";
+  return `entity_${canonicalCandidateTerm(screenId)}`;
+}
+
+function parseShellContent(text) {
+  const screens = [];
+  for (const match of String(text || "").matchAll(/ShellContent[^>]*Title="([^"]+)"[^>]*ContentTemplate="\{DataTemplate\s+views:([A-Za-z_][A-Za-z0-9_]*)\}"[^>]*Route="([^"]+)"/g)) {
+    screens.push({
+      title: match[1],
+      pageClass: match[2],
+      route: match[3]
+    });
+  }
+  return screens;
+}
+
+function parseCommands(text) {
+  return [...String(text || "").matchAll(/Command="\{Binding\s+([A-Za-z_][A-Za-z0-9_]*)\}"/g)]
+    .map((entry) => entry[1]);
+}
+
+function parseClickedHandlers(text) {
+  return [...String(text || "").matchAll(/Clicked="([A-Za-z_][A-Za-z0-9_]*)"/g)]
+    .map((entry) => entry[1]);
+}
+
+function capabilityHintForHandler(screenId, handlerName) {
+  const normalized = String(handlerName || "").replace(/^On/, "").replace(/Clicked$|ButtonClicked$|SelectionChanged$/g, "").toLowerCase();
+  if (/save/.test(normalized)) return `cap_update_${canonicalCandidateTerm(screenId)}`;
+  if (/delete/.test(normalized)) return `cap_delete_${canonicalCandidateTerm(screenId)}`;
+  if (/add/.test(normalized)) return `cap_create_${canonicalCandidateTerm(screenId)}`;
+  if (/selection/.test(normalized)) return `cap_get_${canonicalCandidateTerm(screenId)}`;
+  if (/cancel/.test(normalized)) return null;
+  return `cap_${idHintify(normalized)}_${canonicalCandidateTerm(screenId)}`;
+}
+
+export const mauiXamlUiExtractor = {
+  id: "ui.maui-xaml",
+  track: "ui",
+  detect(context) {
+    const xamlFiles = findImportFiles(context.paths, (filePath) => /\.xaml$/i.test(filePath));
+    const score = xamlFiles.some((filePath) => /ContentPage|Shell/.test(context.helpers.readTextIfExists(filePath) || "")) ? 82 : 0;
+    return {
+      score,
+      reasons: score > 0 ? ["Found .NET MAUI XAML views and shell content"] : []
+    };
+  },
+  extract(context) {
+    const shellFiles = findImportFiles(context.paths, (filePath) => /AppShell\.xaml$/i.test(filePath));
+    const viewFiles = findImportFiles(context.paths, (filePath) => /\/Views\/.+\.xaml$/i.test(filePath));
+    const findings = [];
+    const candidates = { screens: [], routes: [], actions: [], stacks: [] };
+    const shellEntries = shellFiles.flatMap((filePath) => parseShellContent(context.helpers.readTextIfExists(filePath) || ""));
+    const shellByPage = new Map(shellEntries.map((entry) => [entry.pageClass, entry]));
+
+    for (const filePath of viewFiles) {
+      const text = context.helpers.readTextIfExists(filePath) || "";
+      const className = text.match(/x:Class="[^"]+\.([A-Za-z_][A-Za-z0-9_]*)"/)?.[1] || filePath.split("/").pop()?.replace(/\.xaml$/, "") || "page";
+      const shellEntry = shellByPage.get(className);
+      const screenId = screenIdFromClass(className);
+      const routePath = shellEntry ? `/${shellEntry.route.replace(/^\/+/, "")}` : `/${screenId.replace(/_/g, "-")}`;
+      const provenance = `${relativeTo(context.paths.repoRoot, filePath)}#${className}`;
+      const entityId = entityIdFromScreen(screenId);
+      candidates.screens.push(makeCandidateRecord({
+        kind: "screen",
+        idHint: screenId,
+        label: shellEntry?.title || titleCase(screenId),
+        confidence: "high",
+        sourceKind: "route_code",
+        provenance,
+        track: "ui",
+        entity_id: entityId,
+        concept_id: entityId,
+        screen_kind: "flow",
+        route_path: routePath
+      }));
+      candidates.routes.push(makeCandidateRecord({
+        kind: "ui_route",
+        idHint: `${screenId}_route`,
+        label: routePath,
+        confidence: "high",
+        sourceKind: "route_code",
+        provenance,
+        track: "ui",
+        screen_id: screenId,
+        entity_id: entityId,
+        concept_id: entityId,
+        path: routePath
+      }));
+      for (const commandName of [...parseCommands(text), ...parseClickedHandlers(text)]) {
+        const capabilityHint = capabilityHintForHandler(screenId, commandName);
+        candidates.actions.push(makeCandidateRecord({
+          kind: "ui_action",
+          idHint: `${screenId}_${idHintify(commandName)}`,
+          label: commandName,
+          confidence: "medium",
+          sourceKind: "route_code",
+          provenance,
+          track: "ui",
+          screen_id: screenId,
+          entity_id: entityId,
+          concept_id: entityId,
+          capability_hint: capabilityHint,
+          prominence: "primary"
+        }));
+      }
+      findings.push({ kind: "maui_xaml_view", file: relativeTo(context.paths.repoRoot, filePath), screen_id: screenId });
+    }
+
+    if (candidates.screens.length > 0) {
+      candidates.stacks.push("maui_xaml");
+    }
+    candidates.screens = dedupeCandidateRecords(candidates.screens, (record) => record.id_hint);
+    candidates.routes = dedupeCandidateRecords(candidates.routes, (record) => record.id_hint);
+    candidates.actions = dedupeCandidateRecords(candidates.actions, (record) => record.id_hint);
+    candidates.stacks = [...new Set(candidates.stacks)].sort();
+    return { findings, candidates };
+  }
+};

package/src/import/extractors/ui/next-app-router.js

@@ -0,0 +1,83 @@
+import { dedupeCandidateRecords, inferNextAppRoutes, makeCandidateRecord, nextScreenIdForRoute, nextScreenKindForRoute, uiCapabilityHintsForNextRoute, entityIdForNextRoute, conceptIdForNextRoute, relativeTo, titleCase, idHintify } from "../../core/shared.js";
+
+export const nextAppRouterUiExtractor = {
+  id: "ui.next-app-router",
+  track: "ui",
+  detect(context) {
+    const routes = inferNextAppRoutes(context.paths.workspaceRoot, context.helpers);
+    return {
+      score: routes.length > 0 ? 100 : 0,
+      reasons: routes.length > 0 ? ["Found Next.js App Router pages"] : []
+    };
+  },
+  extract(context) {
+    const routes = inferNextAppRoutes(context.paths.workspaceRoot, context.helpers);
+    const findings = [];
+    const candidates = { screens: [], routes: [], actions: [], stacks: [] };
+    if (routes.length > 0) {
+      findings.push({
+        kind: "next_app_routes",
+        file: relativeTo(context.paths.repoRoot, `${context.paths.workspaceRoot}/app`),
+        routes: routes.map((route) => route.path)
+      });
+      candidates.stacks.push("next_app_router");
+      for (const route of routes) {
+        if (route.kind !== "page") continue;
+        const provenance = `${relativeTo(context.paths.repoRoot, route.file)}#${route.path}`;
+        const screenId = nextScreenIdForRoute(route.path);
+        const screenKind = nextScreenKindForRoute(route.path);
+        const capabilityHints = uiCapabilityHintsForNextRoute(route.path);
+        const entityId = entityIdForNextRoute(route.path);
+        const conceptId = conceptIdForNextRoute(route.path);
+        candidates.screens.push(makeCandidateRecord({
+          kind: "screen",
+          idHint: screenId,
+          label: titleCase(screenId),
+          confidence: "medium",
+          sourceKind: "route_code",
+          provenance,
+          track: "ui",
+          entity_id: entityId,
+          concept_id: conceptId,
+          screen_kind: screenKind,
+          route_path: route.path,
+          capability_hints: capabilityHints
+        }));
+        candidates.routes.push(makeCandidateRecord({
+          kind: "ui_route",
+          idHint: `${screenId}_route`,
+          label: route.path,
+          confidence: "medium",
+          sourceKind: "route_code",
+          provenance,
+          track: "ui",
+          screen_id: screenId,
+          entity_id: entityId,
+          concept_id: conceptId,
+          path: route.path
+        }));
+        if (capabilityHints.primary_action) {
+          candidates.actions.push(makeCandidateRecord({
+            kind: "ui_action",
+            idHint: `${screenId}_${idHintify(capabilityHints.primary_action)}`,
+            label: capabilityHints.primary_action,
+            confidence: "low",
+            sourceKind: "route_code",
+            provenance,
+            track: "ui",
+            screen_id: screenId,
+            entity_id: entityId,
+            concept_id: conceptId,
+            capability_hint: capabilityHints.primary_action,
+            prominence: screenKind === "list" ? "primary" : "secondary"
+          }));
+        }
+      }
+    }
+    candidates.screens = dedupeCandidateRecords(candidates.screens, (record) => record.id_hint);
+    candidates.routes = dedupeCandidateRecords(candidates.routes, (record) => record.id_hint);
+    candidates.actions = dedupeCandidateRecords(candidates.actions, (record) => record.id_hint);
+    candidates.stacks = [...new Set(candidates.stacks)].sort();
+    return { findings, candidates };
+  }
+};