@topogram/cli 0.3.38 → 0.3.39

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@topogram/cli",
-  "version": "0.3.38",
+  "version": "0.3.39",
   "description": "Topogram CLI for checking Topogram workspaces and generating app bundles.",
   "license": "Apache-2.0",
   "repository": {

package/src/adoption/plan.js

@@ -6,7 +6,7 @@ import {
   reviewBoundaryForImportProposal
 } from "../policy/review-boundaries.js";
 
-const ADOPT_SELECTORS = new Set(["from-plan", "actors", "roles", "enums", "shapes", "entities", "capabilities", "docs", "journeys", "workflows", "verification", "ui"]);
+const ADOPT_SELECTORS = new Set(["from-plan", "actors", "roles", "enums", "shapes", "entities", "capabilities", "components", "docs", "journeys", "workflows", "verification", "ui"]);
 
 function stableSortedStrings(values) {
   return [...new Set((values || []).filter(Boolean))].sort();
@@ -355,6 +355,7 @@ export function selectorMatchesItem(selector, item) {
   if (selector === "shapes") return item.kind === "shape";
   if (selector === "entities") return item.kind === "entity";
   if (selector === "capabilities") return item.kind === "capability";
+  if (selector === "components") return item.kind === "component";
   if (selector === "docs") return item.track === "docs";
   if (selector === "journeys") return item.track === "docs" && String(item.canonical_rel_path || "").startsWith("docs/journeys/");
   if (selector === "workflows") return item.track === "workflows" || item.kind === "decision";

package/src/cli/catalog-alias.js

@@ -21,7 +21,7 @@ function messageFromError(error) {
 /**
  * @param {string} templateName
  * @param {string|null} [source]
- * @returns {{ templateName: string, provenance: { id: string, source: string, package: string, version: string, packageSpec: string }|null }}
+ * @returns {{ templateName: string, provenance: { id: string, source: string, package: string, version: string, packageSpec: string, includesExecutableImplementation: boolean }|null }}
  */
 export function resolveCatalogTemplateAlias(templateName, source = null) {
   if (!isCatalogAliasCandidate(templateName)) {
@@ -47,7 +47,8 @@ export function resolveCatalogTemplateAlias(templateName, source = null) {
         source: loaded.source,
         package: entry.package,
         version: entry.defaultVersion,
-        packageSpec
+        packageSpec,
+        includesExecutableImplementation: Boolean(entry.trust?.includesExecutableImplementation)
       }
     };
   } catch (error) {

package/src/cli.js

@@ -238,6 +238,14 @@ function printUsage(options = {}) {
   console.log("  topogram import status ./imported-topogram");
   console.log("  topogram import history ./imported-topogram --verify");
   console.log("");
+  console.log("Fresh install:");
+  console.log("  npm install --save-dev @topogram/cli");
+  console.log("  npx topogram doctor");
+  console.log("  npx topogram template list");
+  console.log("  npx topogram new ./my-app --template hello-web");
+  console.log("  cd ./my-app && npm install && npm run check && npm run generate");
+  console.log("  npm --prefix app run compile");
+  console.log("");
   console.log("Template and catalog discovery:");
   console.log("  topogram template list");
   console.log("  topogram catalog list");
@@ -327,7 +335,7 @@ function printUsage(options = {}) {
   console.log("Targets: json-schema, docs, docs-index, verification-plan, verification-checklist, shape-transform-graph, shape-transform-debug, api-contract-graph, api-contract-debug, ui-contract-graph, ui-contract-debug, ui-component-contract, component-conformance-report, component-behavior-report, ui-web-contract, ui-web-debug, sveltekit-app, swiftui-app, db-contract-graph, db-contract-debug, db-schema-snapshot, db-migration-plan, db-lifecycle-plan, db-lifecycle-bundle, environment-plan, environment-bundle, deployment-plan, deployment-bundle, runtime-smoke-plan, runtime-smoke-bundle, runtime-check-plan, runtime-check-bundle, compile-check-plan, compile-check-bundle, app-bundle-plan, app-bundle, native-parity-plan, native-parity-bundle, sql-migration, sql-schema, prisma-schema, drizzle-schema, persistence-scaffold, server-contract, hono-server, openapi, context-digest, context-diff, context-slice, context-bundle, context-report, context-task-mode");
   console.log("Workflows: import-app, scan-docs, reconcile, adoption-status, generate-docs, generate-journeys, refresh-docs, report-gaps");
   console.log("Import tracks: db, api, ui, workflows, verification");
-  console.log("Reconcile adopt selectors: from-plan, actors, roles, enums, shapes, entities, capabilities, docs, journeys, workflows, ui, bundle:<slug>, projection-review:<id>, ui-review:<id>, workflow-review:<id>, bundle-review:<slug>");
+  console.log("Reconcile adopt selectors: from-plan, actors, roles, enums, shapes, entities, capabilities, components, docs, journeys, workflows, ui, bundle:<slug>, projection-review:<id>, ui-review:<id>, workflow-review:<id>, bundle-review:<slug>");
 }
 
 function printNewHelp() {
@@ -336,6 +344,13 @@ function printNewHelp() {
   console.log("");
   console.log("Creates a new editable Topogram workspace from a template package or local template path.");
   console.log("");
+  console.log("Fresh install flow:");
+  console.log("  npm install --save-dev @topogram/cli");
+  console.log("  npx topogram template list");
+  console.log("  npx topogram new ./my-app --template hello-web");
+  console.log("  cd ./my-app && npm install && npm run check && npm run generate");
+  console.log("  npm --prefix app run compile");
+  console.log("");
   console.log("Examples:");
   console.log("  topogram new ./my-app");
   console.log("  topogram new --list-templates");
@@ -617,6 +632,12 @@ function printDoctorHelp() {
   console.log("");
   console.log("Checks local runtime, npm, public package access, CLI lockfile metadata, and catalog access.");
   console.log("");
+  console.log("Fresh install check:");
+  console.log("  npm install --save-dev @topogram/cli");
+  console.log("  npx topogram doctor");
+  console.log("  npx topogram template list");
+  console.log("  npx topogram new ./my-app --template hello-web");
+  console.log("");
   console.log("Related setup commands:");
   console.log("  topogram setup package-auth");
   console.log("  topogram setup catalog-auth");
@@ -5885,6 +5906,15 @@ function diagnosticForTemplateCreateFailure(message, templateSpec, step) {
       step
     });
   }
+  if (message.includes("contains implementation/") && message.includes("includesExecutableImplementation: true")) {
+    return templateCheckDiagnostic({
+      code: "template_implementation_undeclared",
+      message,
+      path: localTemplatePath(templateSpec, "topogram-template.json"),
+      suggestedFix: "Set includesExecutableImplementation to true after reviewing implementation/, or remove implementation/.",
+      step
+    });
+  }
   if (message.includes("is missing required string field") || message.includes("topogram-template.json")) {
     return templateCheckDiagnostic({
       code: "template_manifest_invalid",

package/src/generator/component-conformance.js

@@ -65,14 +65,71 @@ function projectionRealizesIds(projection) {
   return new Set((projection?.realizes || []).map((ref) => ref.id).filter(Boolean));
 }
 
-function projectionScreenMap(projection) {
+function ownProjectionScreenMap(projection) {
   return new Map((projection?.uiScreens || []).map((screen) => [screen.id, screen]));
 }
 
-function projectionRegionKeys(projection) {
+function ownProjectionRegionKeys(projection) {
   return new Set((projection?.uiScreenRegions || []).map((entry) => `${entry.screenId}:${entry.region}`));
 }
 
+function projectionById(graph) {
+  return byId(graph.byKind.projection || []);
+}
+
+function projectionContext(graph, projection) {
+  const projections = [];
+  const seen = new Set();
+  const projectionsById = projectionById(graph);
+
+  function visit(current) {
+    if (!current || seen.has(current.id)) {
+      return;
+    }
+    seen.add(current.id);
+    projections.push(current);
+    for (const ref of current.realizes || []) {
+      const target = projectionsById.get(ref.id);
+      if (target) {
+        visit(target);
+      }
+    }
+  }
+
+  visit(projection);
+  return projections;
+}
+
+function projectionScreenMap(graph, projection) {
+  const screens = new Map();
+  for (const contextProjection of projectionContext(graph, projection).reverse()) {
+    for (const [id, screen] of ownProjectionScreenMap(contextProjection)) {
+      screens.set(id, screen);
+    }
+  }
+  return screens;
+}
+
+function projectionRegionKeys(graph, projection) {
+  const regions = new Set();
+  for (const contextProjection of projectionContext(graph, projection)) {
+    for (const key of ownProjectionRegionKeys(contextProjection)) {
+      regions.add(key);
+    }
+  }
+  return regions;
+}
+
+function projectionContextRealizesIds(graph, projection) {
+  const ids = new Set();
+  for (const contextProjection of projectionContext(graph, projection)) {
+    for (const id of projectionRealizesIds(contextProjection)) {
+      ids.add(id);
+    }
+  }
+  return ids;
+}
+
 function checkRecord({
   code,
   severity,
@@ -122,9 +179,9 @@ function collectUsageChecks({ graph, projection, sourceProjection, usage, compon
   const eventNames = new Set(events.map((event) => event.id));
   const boundProps = new Set((usage.dataBindings || []).map((binding) => binding.prop).filter(Boolean));
   const statements = byId(graph.statements || []);
-  const screens = projectionScreenMap(sourceProjection);
-  const regionKeys = projectionRegionKeys(sourceProjection);
-  const realizedIds = projectionRealizesIds(sourceProjection);
+  const screens = projectionScreenMap(graph, sourceProjection);
+  const regionKeys = projectionRegionKeys(graph, sourceProjection);
+  const realizedIds = projectionContextRealizesIds(graph, sourceProjection);
 
   if (!component) {
     checks.push(checkRecord({
@@ -270,13 +327,13 @@ function collectUsageChecks({ graph, projection, sourceProjection, usage, compon
         checks.push(checkRecord({
           code: "component_event_action_not_in_projection",
           severity: "error",
-          message: `Event '${binding.event}' targets capability '${target.id}', but projection '${sourceProjection.id}' does not realize it.`,
+          message: `Event '${binding.event}' targets capability '${target.id}', but projection '${sourceProjection.id}' does not realize it through its UI context.`,
           projection,
           sourceProjection,
           component,
           usage,
           event: binding.event || null,
-          suggestedFix: `Add '${target.id}' to projection '${sourceProjection.id}' realizes or choose a capability already in this projection context.`
+          suggestedFix: `Add '${target.id}' to projection '${sourceProjection.id}' or an inherited shared projection realizes list, or choose a capability already in this projection context.`
         }));
       }
     } else {
@@ -491,8 +548,8 @@ export function generateComponentConformanceReport(graph, options = {}) {
         source_projection: entry.sourceProjection.id === entry.projection.id ? null : summarizeProjection(entry.sourceProjection),
         screen: {
           id: entry.usage.screenId || null,
-          kind: projectionScreenMap(entry.sourceProjection).get(entry.usage.screenId)?.kind || null,
-          title: projectionScreenMap(entry.sourceProjection).get(entry.usage.screenId)?.title || null
+          kind: projectionScreenMap(graph, entry.sourceProjection).get(entry.usage.screenId)?.kind || null,
+          title: projectionScreenMap(graph, entry.sourceProjection).get(entry.usage.screenId)?.title || null
         },
         region: entry.usage.region || null,
         component: summarizeComponent(component) || { id: componentId, name: componentId, category: null, version: null, status: null, source_path: null },

package/src/generator/surfaces/web/react-components.js

@@ -2,7 +2,7 @@
 
 /**
  * @typedef {{ id?: string, name?: string }} ComponentReference
- * @typedef {{ component?: ComponentReference, region?: string }} ComponentUsage
+ * @typedef {{ component?: ComponentReference, region?: string, pattern?: string }} ComponentUsage
  * @typedef {{ patterns?: string[] }} ComponentContract
  * @typedef {Record<string, ComponentContract>} ComponentContractMap
  * @typedef {{ itemsExpression?: string, componentContracts?: ComponentContractMap, useTypescript?: boolean }} RenderOptions
@@ -63,8 +63,22 @@ function componentPatterns(usage, componentContracts) {
  * @param {string} pattern
  * @returns {boolean}
  */
-function hasPattern(usage, componentContracts, pattern) {
-  return componentPatterns(usage, componentContracts).includes(pattern);
+function usagePattern(usage, componentContracts) {
+  return usage?.pattern || componentPatterns(usage, componentContracts)[0] || null;
+}
+
+export function reactComponentUsageSupport(usage, componentContracts) {
+  const pattern = usagePattern(usage, componentContracts);
+  return {
+    pattern,
+    supported: [
+      "summary_stats",
+      "board_view",
+      "calendar_view",
+      "resource_table",
+      "data_grid_view"
+    ].includes(pattern || "")
+  };
 }
 
 /**
@@ -198,16 +212,17 @@ function renderCalendar(usage, options) {
  */
 function renderUsage(usage, options) {
   const componentContracts = options.componentContracts || {};
-  if (hasPattern(usage, componentContracts, "summary_stats")) {
+  const { pattern } = reactComponentUsageSupport(usage, componentContracts);
+  if (pattern === "summary_stats") {
     return renderSummaryStats(usage, options);
   }
-  if (hasPattern(usage, componentContracts, "board_view")) {
+  if (pattern === "board_view") {
     return renderBoard(usage, options);
   }
-  if (hasPattern(usage, componentContracts, "calendar_view")) {
+  if (pattern === "calendar_view") {
     return renderCalendar(usage, options);
   }
-  if (hasPattern(usage, componentContracts, "resource_table") || hasPattern(usage, componentContracts, "data_grid_view")) {
+  if (pattern === "resource_table" || pattern === "data_grid_view") {
     return renderCollectionTable(usage, options);
   }
   return "";

package/src/generator/surfaces/web/react.js

@@ -1,6 +1,9 @@
 import { buildWebRealization } from "../../../realization/ui/index.js";
 import { getExampleImplementation } from "../../../example-implementation.js";
-import { renderReactComponentRegion } from "./react-components.js";
+import {
+  reactComponentUsageSupport,
+  renderReactComponentRegion
+} from "./react-components.js";
 import { renderApiClientModule, renderLookupModule, renderVisibilityModule } from "./shared.js";
 
 function componentNameForScreen(screenId) {
@@ -214,7 +217,21 @@ function buildReactGenerationCoverage(contract, files, routeScreens) {
       const componentUsages = screenComponentUsages(screen).map((usage) => {
         const componentId = usage.component?.id || null;
         const marker = componentId ? `data-topogram-component="${componentId}"` : null;
+        const support = reactComponentUsageSupport(usage, contract.components);
         const usageRendered = Boolean(marker && contents.includes(marker));
+        if (componentId && rendered && !support.supported) {
+          diagnostics.push({
+            code: "component_pattern_not_supported",
+            severity: "error",
+            screen: screen.id,
+            route: screen.route,
+            region: usage.region || null,
+            pattern: support.pattern || null,
+            component: componentId,
+            message: `Screen '${screen.id}' uses component '${componentId}' with unsupported React component pattern '${support.pattern || "(missing)"}'.`,
+            suggested_fix: "Use a supported component pattern for this generator or provide an implementation override."
+          });
+        }
         if (componentId && rendered && !usageRendered) {
           diagnostics.push({
             code: "component_usage_not_rendered",
@@ -230,6 +247,8 @@ function buildReactGenerationCoverage(contract, files, routeScreens) {
         return {
           component: componentId,
           region: usage.region || null,
+          pattern: support.pattern || null,
+          supported: support.supported,
           rendered: usageRendered,
           marker
         };
@@ -272,6 +291,15 @@ function buildReactGenerationCoverage(contract, files, routeScreens) {
   };
 }
 
+function assertGenerationCoverage(coverage) {
+  const errors = (coverage.diagnostics || []).filter((diagnostic) => diagnostic.severity === "error");
+  if (errors.length === 0) {
+    return;
+  }
+  const details = errors.map((diagnostic) => diagnostic.message).join("; ");
+  throw new Error(`React generation coverage failed: ${details}`);
+}
+
 function buildAppTsx(contract, webReference) {
   const navLinks = resolveNavLinks(contract, webReference);
   const brandName = contract.appShell?.brand || webReference.brandName;
@@ -528,7 +556,9 @@ button, .button-link { display: inline-flex; align-items: center; justify-conten
     files[screenPagePath(screen)] = buildReactScreenPage(screen, contract);
   }
 
-  files["src/lib/topogram/generation-coverage.json"] = `${JSON.stringify(buildReactGenerationCoverage(contract, files, routeScreens), null, 2)}\n`;
+  const coverage = buildReactGenerationCoverage(contract, files, routeScreens);
+  assertGenerationCoverage(coverage);
+  files["src/lib/topogram/generation-coverage.json"] = `${JSON.stringify(coverage, null, 2)}\n`;
   return files;
 }
 

package/src/generator/surfaces/web/sveltekit-components.js

@@ -2,7 +2,7 @@
 
 /**
  * @typedef {{ id?: string, name?: string }} ComponentReference
- * @typedef {{ component?: ComponentReference, region?: string }} ComponentUsage
+ * @typedef {{ component?: ComponentReference, region?: string, pattern?: string }} ComponentUsage
  * @typedef {{ patterns?: string[] }} ComponentContract
  * @typedef {Record<string, ComponentContract>} ComponentContractMap
  * @typedef {{ itemsExpression?: string, componentContracts?: ComponentContractMap, useTypescript?: boolean }} RenderOptions
@@ -54,8 +54,22 @@ function componentPatterns(usage, componentContracts) {
  * @param {string} pattern
  * @returns {boolean}
  */
-function hasPattern(usage, componentContracts, pattern) {
-  return componentPatterns(usage, componentContracts).includes(pattern);
+function usagePattern(usage, componentContracts) {
+  return usage?.pattern || componentPatterns(usage, componentContracts)[0] || null;
+}
+
+export function svelteKitComponentUsageSupport(usage, componentContracts) {
+  const pattern = usagePattern(usage, componentContracts);
+  return {
+    pattern,
+    supported: [
+      "summary_stats",
+      "board_view",
+      "calendar_view",
+      "resource_table",
+      "data_grid_view"
+    ].includes(pattern || "")
+  };
 }
 
 /**
@@ -184,16 +198,17 @@ function renderCalendar(usage, options) {
  */
 function renderUsage(usage, options) {
   const componentContracts = options.componentContracts || {};
-  if (hasPattern(usage, componentContracts, "summary_stats")) {
+  const { pattern } = svelteKitComponentUsageSupport(usage, componentContracts);
+  if (pattern === "summary_stats") {
     return renderSummaryStats(usage, options);
   }
-  if (hasPattern(usage, componentContracts, "board_view")) {
+  if (pattern === "board_view") {
     return renderBoard(usage, options);
   }
-  if (hasPattern(usage, componentContracts, "calendar_view")) {
+  if (pattern === "calendar_view") {
     return renderCalendar(usage, options);
   }
-  if (hasPattern(usage, componentContracts, "resource_table") || hasPattern(usage, componentContracts, "data_grid_view")) {
+  if (pattern === "resource_table" || pattern === "data_grid_view") {
     return renderCollectionTable(usage, options);
   }
   return "";

package/src/generator/surfaces/web/sveltekit.js

@@ -2,7 +2,10 @@ import { buildWebRealization } from "../../../realization/ui/index.js";
 import { lookupRouteSegment } from "../services/runtime-helpers.js";
 import { getExampleImplementation } from "../../../example-implementation.js";
 import { renderApiClientModule, renderLookupModule, renderVisibilityModule } from "./shared.js";
-import { renderSvelteKitComponentRegion } from "./sveltekit-components.js";
+import {
+  renderSvelteKitComponentRegion,
+  svelteKitComponentUsageSupport
+} from "./sveltekit-components.js";
 
 function routePathToSvelteKitDirectory(routePath) {
   if (!routePath || routePath === "/") {
@@ -186,7 +189,21 @@ function buildSvelteKitGenerationCoverage(contract, files, implementationScreenI
       const componentUsages = screenComponentUsages(screen).map((usage) => {
         const componentId = usage.component?.id || null;
         const marker = componentId ? `data-topogram-component="${componentId}"` : null;
+        const support = svelteKitComponentUsageSupport(usage, contract.components);
         const usageRendered = Boolean(marker && contents.includes(marker));
+        if (componentId && rendered && renderer !== "implementation" && !support.supported) {
+          diagnostics.push({
+            code: "component_pattern_not_supported",
+            severity: "error",
+            screen: screen.id,
+            route: screen.route,
+            region: usage.region || null,
+            pattern: support.pattern || null,
+            component: componentId,
+            message: `Screen '${screen.id}' uses component '${componentId}' with unsupported SvelteKit component pattern '${support.pattern || "(missing)"}'.`,
+            suggested_fix: "Use a supported component pattern for this generator or provide an implementation override."
+          });
+        }
         if (componentId && rendered && !usageRendered) {
           diagnostics.push({
             code: "component_usage_not_rendered",
@@ -202,6 +219,8 @@ function buildSvelteKitGenerationCoverage(contract, files, implementationScreenI
         return {
           component: componentId,
           region: usage.region || null,
+          pattern: support.pattern || null,
+          supported: support.supported,
           rendered: usageRendered,
           marker
         };
@@ -244,6 +263,15 @@ function buildSvelteKitGenerationCoverage(contract, files, implementationScreenI
   };
 }
 
+function assertGenerationCoverage(coverage) {
+  const errors = (coverage.diagnostics || []).filter((diagnostic) => diagnostic.severity === "error");
+  if (errors.length === 0) {
+    return;
+  }
+  const details = errors.map((diagnostic) => diagnostic.message).join("; ");
+  throw new Error(`SvelteKit generation coverage failed: ${details}`);
+}
+
 function resolveNavLinks(contract, webReference) {
   const contractLinks = (contract.navigation?.items || [])
     .filter((item) => item.visible && item.route && item.placement === "primary")
@@ -415,7 +443,9 @@ function buildSvelteKitScaffold(contract, apiContracts, options = {}) {
     }
   }
 
-  files["src/lib/topogram/generation-coverage.json"] = `${JSON.stringify(buildSvelteKitGenerationCoverage(contract, files, implementationScreenIds), null, 2)}\n`;
+  const coverage = buildSvelteKitGenerationCoverage(contract, files, implementationScreenIds);
+  assertGenerationCoverage(coverage);
+  files["src/lib/topogram/generation-coverage.json"] = `${JSON.stringify(coverage, null, 2)}\n`;
   files["src/lib/topogram/ui-web-contract.json"] = `${JSON.stringify(contract, null, 2)}\n`;
   return files;
 }

package/src/new-project.js

@@ -122,6 +122,7 @@ const SURFACE_ORDER = new Map([
  * @property {string} package
  * @property {string} version
  * @property {string} packageSpec
+ * @property {boolean} [includesExecutableImplementation]
  */
 
 /**
@@ -351,6 +352,13 @@ function validateTemplateRoot(templateRoot) {
         `Template '${manifest.id}' declares executable implementation code but is missing implementation/.`
       );
     }
+  } else {
+    const implementationRoot = path.join(templateRoot, "implementation");
+    if (fs.existsSync(implementationRoot) && fs.statSync(implementationRoot).isDirectory()) {
+      throw new Error(
+        `Template '${manifest.id}' contains implementation/ but ${TEMPLATE_MANIFEST} does not declare includesExecutableImplementation: true.`
+      );
+    }
   }
   return manifest;
 }
@@ -2076,6 +2084,16 @@ export function createNewProject({
   const projectRoot = path.resolve(targetPath);
   assertProjectOutsideEngine(projectRoot, engineRoot);
   const template = resolveTemplate(templateName, templatesRoot);
+  if (
+    templateProvenance &&
+    typeof templateProvenance.includesExecutableImplementation === "boolean" &&
+    templateProvenance.includesExecutableImplementation !== Boolean(template.manifest.includesExecutableImplementation)
+  ) {
+    throw new Error(
+      `Catalog entry '${templateProvenance.id}' declares includesExecutableImplementation: ${templateProvenance.includesExecutableImplementation}, ` +
+        `but template package '${template.packageSpec || template.requested}' declares includesExecutableImplementation: ${Boolean(template.manifest.includesExecutableImplementation)}.`
+    );
+  }
 
   ensureCreatableProjectRoot(projectRoot);
   copyTopogramWorkspace(template.root, projectRoot);

package/src/realization/ui/build-ui-shared-realization.js

@@ -84,12 +84,19 @@ function summarizeComponentRef(graph, componentId) {
   };
 }
 
-export function buildComponentUsageContract(graph, entry) {
+function regionContractFor(regionEntries, regionName) {
+  return (regionEntries || []).find((entry) => entry.region === regionName) || null;
+}
+
+export function buildComponentUsageContract(graph, entry, options = {}) {
   const componentId = entry.component?.id || null;
   const contract = componentId ? componentContractFor(graph, componentId) : null;
+  const region = options.region || null;
   return {
     type: "ui_component_usage",
     region: entry.region || null,
+    pattern: region?.pattern || null,
+    placement: region?.placement || null,
     component: componentId ? summarizeComponentRef(graph, componentId) : null,
     dataBindings: (entry.dataBindings || []).map((binding) => ({
       prop: binding.prop || null,
@@ -255,7 +262,9 @@ function buildUiScreenContract(graph, projection, screen, ownershipFields) {
       state: entry.state || null,
       variant: entry.variant || null
     })),
-    components: componentEntries.map((entry) => buildComponentUsageContract(graph, entry)),
+    components: componentEntries.map((entry) => buildComponentUsageContract(graph, entry, {
+      region: regionContractFor(regionEntries, entry.region)
+    })),
     patterns: [...patterns]
   };
 }

package/src/realization/ui/build-web-realization.js

@@ -83,7 +83,9 @@ export function buildWebRealization(graph, options = {}) {
     if ((screen.components || []).some((usage) => componentUsageFingerprint(usage) === componentUsageFingerprintFromEntry(entry))) {
       continue;
     }
-    screen.components = [...(screen.components || []), buildComponentUsageContract(graph, entry)];
+    screen.components = [...(screen.components || []), buildComponentUsageContract(graph, entry, {
+      region: (screen.regions || []).find((region) => region.region === entry.region) || null
+    })];
   }
 
   const appShell = projection.uiAppShell?.length || !sharedProjection ? concreteContract.appShell : sharedContract.appShell;

package/src/workflows.js

@@ -1464,6 +1464,27 @@ function renderCandidateUiReportDoc(screen, routes, actions) {
   return renderMarkdownDoc(metadata, body);
 }
 
+function renderCandidateComponent(component) {
+  const propName = component.data_prop || "rows";
+  const pattern = component.pattern || "search_results";
+  const region = component.region || "results";
+  return ensureTrailingNewline(
+    [
+      `component ${component.id_hint} {`,
+      `  name "${component.label || component.id_hint}"`,
+      '  description "Candidate reusable component inferred from imported UI evidence. Review props, behavior, events, and reuse before adoption."',
+      "  category collection",
+      "  props {",
+      `    ${propName} array required`,
+      "  }",
+      `  patterns [${pattern}]`,
+      `  regions [${region}]`,
+      "  status proposed",
+      "}"
+    ].join("\n")
+  );
+}
+
 function renderProjectionPatchDoc(patch) {
   const lines = [
     `# ${patch.projection_id} Patch Candidate`,
@@ -2393,6 +2414,7 @@ function getOrCreateCandidateBundle(bundles, conceptId, label) {
       enums: [],
       capabilities: [],
       shapes: [],
+      components: [],
       screens: [],
       uiRoutes: [],
       uiActions: [],
@@ -3160,6 +3182,18 @@ function buildBundleAdoptionPlan(bundle, canonicalShapeIndex) {
       canonical_rel_path: `verifications/${dashedTopogramId(entry.id_hint)}.tg`
     });
   }
+  for (const entry of bundle.components || []) {
+    steps.push({
+      action: "promote_component",
+      item: entry.id_hint,
+      target: null,
+      confidence: entry.confidence || "low",
+      inference_summary: entry.inference_summary || null,
+      related_capabilities: [entry.data_source].filter(Boolean),
+      source_path: `candidates/reconcile/model/bundles/${bundle.slug}/components/${entry.id_hint}.tg`,
+      canonical_rel_path: `components/${dashedTopogramId(entry.id_hint)}.tg`
+    });
+  }
   for (const screen of bundle.screens) {
     steps.push({
       action: "promote_ui_report",
@@ -3640,7 +3674,7 @@ function bestContextBundleForCandidate(bundles, candidate) {
 function buildCandidateModelBundles(graph, appImport, topogramRoot) {
   const dbCandidates = appImport.candidates.db || { entities: [], enums: [] };
   const apiCandidates = appImport.candidates.api || { capabilities: [] };
-  const uiCandidates = appImport.candidates.ui || { screens: [], routes: [], actions: [] };
+  const uiCandidates = appImport.candidates.ui || { screens: [], routes: [], actions: [], components: [] };
   const workflowCandidates = appImport.candidates.workflows || { workflows: [], workflow_states: [], workflow_transitions: [] };
   const verificationCandidates = appImport.candidates.verification || { verifications: [], scenarios: [], frameworks: [], scripts: [] };
   const docCandidates = appImport.candidates.docs || [];
@@ -3651,6 +3685,7 @@ function buildCandidateModelBundles(graph, appImport, topogramRoot) {
   const canonicalRoleIds = new Set((graph?.byKind.role || []).map((entry) => entry.id));
   const canonicalEntityIds = new Set((graph?.byKind.entity || []).map((entry) => entry.id));
   const canonicalEnumIds = new Set((graph?.byKind.enum || []).map((entry) => entry.id));
+  const canonicalComponentIds = new Set((graph?.byKind.component || []).map((entry) => entry.id));
   const canonicalUi = collectCanonicalUiSurface(graph || { byKind: { projection: [] } });
   const canonicalWorkflow = collectCanonicalWorkflowSurface(graph || { byKind: { decision: [] }, docs: [] });
   const canonicalDocsByKind = new Map();
@@ -3749,6 +3784,24 @@ function buildCandidateModelBundles(graph, appImport, topogramRoot) {
     const bundle = getOrCreateCandidateBundle(bundles, conceptId, bundleLabelFromConceptId(conceptId || entry.screen_id || entry.id_hint));
     bundle.uiActions.push(entry);
   }
+  function componentConceptId(entry) {
+    if (entry.entity_id || entry.concept_id) {
+      return entry.entity_id || entry.concept_id;
+    }
+    const screenStem = String(entry.screen_id || entry.id_hint || "")
+      .replace(/_(list|index|table|grid|results)$/, "")
+      .replace(/^list_/, "");
+    return `entity_${canonicalCandidateTerm(screenStem || entry.id_hint)}`;
+  }
+
+  for (const entry of uiCandidates.components || []) {
+    if (canonicalComponentIds.has(entry.id_hint)) {
+      continue;
+    }
+    const conceptId = componentConceptId(entry);
+    const bundle = getOrCreateCandidateBundle(bundles, conceptId, bundleLabelFromConceptId(conceptId || entry.screen_id || entry.id_hint));
+    bundle.components.push(entry);
+  }
   for (const entry of workflowCandidates.workflows || []) {
     if (canonicalWorkflow.workflow_docs.includes(entry.id_hint)) {
       continue;
@@ -3834,6 +3887,7 @@ function buildCandidateModelBundles(graph, appImport, topogramRoot) {
       bundle.enums.length > 0 ||
       bundle.capabilities.length > 0 ||
       bundle.shapes.length > 0 ||
+      bundle.components.length > 0 ||
       bundle.screens.length > 0 ||
       bundle.uiRoutes.length > 0 ||
       bundle.uiActions.length > 0 ||
@@ -3851,6 +3905,7 @@ function buildCandidateModelBundles(graph, appImport, topogramRoot) {
         enums: bundle.enums.sort((a, b) => a.id_hint.localeCompare(b.id_hint)),
         capabilities: bundle.capabilities.sort((a, b) => a.id_hint.localeCompare(b.id_hint)),
         shapes: bundle.shapes.sort((a, b) => a.id.localeCompare(b.id)),
+        components: bundle.components.sort((a, b) => a.id_hint.localeCompare(b.id_hint)),
         screens: bundle.screens.sort((a, b) => a.id_hint.localeCompare(b.id_hint)),
         uiRoutes: bundle.uiRoutes.sort((a, b) => a.id_hint.localeCompare(b.id_hint)),
         uiActions: bundle.uiActions.sort((a, b) => a.id_hint.localeCompare(b.id_hint)),
@@ -3952,6 +4007,9 @@ function buildCandidateModelFiles(graph, appImport, topogramRoot) {
     for (const entry of bundle.verifications || []) {
       files[`${bundleRoot}/verifications/${entry.id_hint}.tg`] = renderCandidateVerification(entry, entry.scenarios || []);
     }
+    for (const entry of bundle.components || []) {
+      files[`${bundleRoot}/components/${entry.id_hint}.tg`] = renderCandidateComponent(entry);
+    }
     for (const entry of bundle.docs) {
       if (entry.existing_canonical) {
         continue;
@@ -4021,6 +4079,8 @@ function canonicalRelativePathForItem(kind, item) {
       return `shapes/${dashedTopogramId(item)}.tg`;
     case "capability":
       return `capabilities/${dashedTopogramId(item)}.tg`;
+    case "component":
+      return `components/${dashedTopogramId(item)}.tg`;
     case "verification":
       return `verifications/${dashedTopogramId(item)}.tg`;
     default:
@@ -4048,6 +4108,8 @@ function candidateSourcePathForItem(bundle, kind, item) {
       return `${base}/shapes/${item}.tg`;
     case "capability":
       return `${base}/capabilities/${item}.tg`;
+    case "component":
+      return `${base}/components/${item}.tg`;
     case "verification":
       return `${base}/verifications/${item}.tg`;
     default:
@@ -4069,6 +4131,8 @@ function reasonForAdoptionItem(step) {
       return step.target ? `Promote this shape to support concept ${step.target}.` : "Promote this imported shape into canonical Topogram.";
     case "promote_capability":
       return "Promote this imported capability into canonical Topogram.";
+    case "promote_component":
+      return "Promote this imported reusable UI component into canonical Topogram.";
     case "merge_capability_into_existing_entity":
       return `Adopt this capability while preserving the existing canonical entity ${step.target}.`;
     case "promote_doc":
@@ -4114,6 +4178,9 @@ function recommendationForAdoptionItem(step) {
   if (step.action === "apply_projection_ownership_patch") {
     return `Update \`${step.target}\` with inferred ownership auth rules for ${(step.related_capabilities || []).map((item) => `\`${item}\``).join(", ") || "the related capabilities"}.`;
   }
+  if (step.action === "promote_component") {
+    return "Promote this reviewed component candidate before binding or reusing it from canonical projections.";
+  }
   if (!["promote_actor", "promote_role"].includes(step.action)) {
     return null;
   }
@@ -4232,6 +4299,7 @@ function buildAdoptionPlan(bundles) {
         step.action.includes("doc") ? "doc" :
         step.action.includes("decision") ? "decision" :
         step.action.includes("verification") ? "verification" :
+        step.action.includes("component") ? "component" :
         step.action.includes("ui_") ? "ui" :
         step.action.includes("actor") ? "actor" :
         step.action.includes("role") ? "role" :
@@ -4403,7 +4471,7 @@ function buildAdoptionPlan(bundles) {
   );
 }
 
-const ADOPT_SELECTORS = new Set(["from-plan", "actors", "roles", "enums", "shapes", "entities", "capabilities", "docs", "journeys", "workflows", "verification", "ui"]);
+const ADOPT_SELECTORS = new Set(["from-plan", "actors", "roles", "enums", "shapes", "entities", "capabilities", "components", "docs", "journeys", "workflows", "verification", "ui"]);
 
 function readAdoptionPlan(paths) {
   return readJsonIfExists(path.join(paths.topogramRoot, "candidates", "reconcile", "adoption-plan.json"));