@topogram/cli 0.3.51 → 0.3.52

package/src/generator/adapters.d.ts

@@ -1,4 +1,5 @@
 export const BUNDLED_GENERATOR_ADAPTERS: any[];
 export function getBundledGeneratorAdapter(generatorId: string): any;
 export function resolveGeneratorForComponent(component: any, options?: { rootDir?: string | null; configDir?: string | null }): { manifest: any; adapter: any };
+export function generateWithRuntimeGenerator(context: any): { files: Record<string, string>; artifacts?: any; diagnostics?: any[] };
 export function generateWithComponentGenerator(context: any): { files: Record<string, string>; artifacts?: any; diagnostics?: any[] };

package/src/generator/adapters.js

@@ -29,7 +29,7 @@ import { generateServerContract } from "./surfaces/services/server-contract.js";
 import { generateStatelessServer } from "./surfaces/services/stateless.js";
 import { generateReactApp } from "./surfaces/web/react.js";
 import { generateSvelteKitApp } from "./surfaces/web/sveltekit.js";
-import { generateUiWebContract } from "./surfaces/web/ui-web-contract.js";
+import { generateUiSurfaceContract } from "./surfaces/web/ui-surface-contract.js";
 import { generateVanillaWebApp } from "./surfaces/web/vanilla.js";
 
 /**
@@ -40,7 +40,8 @@ import { generateVanillaWebApp } from "./surfaces/web/vanilla.js";
  * @typedef {Object} GeneratorContext
  * @property {Record<string, any>} graph
  * @property {Record<string, any>} projection
- * @property {Record<string, any>} component
+ * @property {Record<string, any>} runtime
+ * @property {Record<string, any>} component Internal runtime alias.
  * @property {Record<string, any>|null} [topology]
  * @property {Record<string, any>} [contracts]
  * @property {Record<string, any>|null} [implementation]
@@ -82,12 +83,21 @@ function requiredManifest(generatorId) {
   return manifest;
 }
 
+/**
+ * @param {GeneratorContext} context
+ * @returns {string}
+ */
+function runtimeFor(context) {
+  return context.runtime || context.component || {};
+}
+
 /**
  * @param {GeneratorContext} context
  * @returns {string}
  */
 function projectionIdFor(context) {
-  return context.projection?.id || context.component?.projection?.id || context.options?.projectionId;
+  const runtime = runtimeFor(context);
+  return context.projection?.id || runtime.projection?.id || context.options?.projectionId;
 }
 
 /**
@@ -97,12 +107,14 @@ function projectionIdFor(context) {
  */
 function serverOptions(context, profile) {
   const projectionId = projectionIdFor(context);
-  const dbProjectionId = context.component?.databaseComponent?.projection?.id || context.options?.dbProjectionId;
+  const runtime = runtimeFor(context);
+  const dbProjectionId = runtime.databaseComponent?.projection?.id || context.options?.dbProjectionId;
   return {
     ...(context.options || {}),
     projectionId,
     dbProjectionId,
-    component: context.component,
+    component: runtime,
+    runtime,
     topology: context.topology,
     contracts: context.contracts,
     implementation: context.implementation,
@@ -115,10 +127,12 @@ function serverOptions(context, profile) {
  * @returns {Record<string, any>}
  */
 function commonOptions(context) {
+  const runtime = runtimeFor(context);
   return {
     ...(context.options || {}),
     projectionId: projectionIdFor(context),
-    component: context.component,
+    component: runtime,
+    runtime,
     topology: context.topology,
     contracts: context.contracts,
     implementation: context.implementation
@@ -131,26 +145,28 @@ function commonOptions(context) {
  */
 function buildContractsForContext(context) {
   const projectionId = projectionIdFor(context);
-  if (context.component.type === "web") {
+  const runtime = runtimeFor(context);
+  const surface = runtime.type || runtime.kind;
+  if (surface === "web" || surface === "web_surface") {
     return {
-      uiWeb: generateUiWebContract(context.graph, { ...(context.options || {}), projectionId })
+      uiSurface: generateUiSurfaceContract(context.graph, { ...(context.options || {}), projectionId })
     };
   }
-  if (context.component.type === "api") {
+  if (surface === "api" || surface === "api_service") {
     return {
       server: generateServerContract(context.graph, { ...(context.options || {}), projectionId }),
       api: generateApiContractGraph(context.graph, {})
     };
   }
-  if (context.component.type === "database") {
+  if (surface === "database") {
     return {
       db: generateDbContractGraph(context.graph, { ...(context.options || {}), projectionId }),
       lifecyclePlan: generateDbLifecyclePlan(context.graph, { ...(context.options || {}), projectionId })
     };
   }
-  if (context.component.type === "native") {
+  if (surface === "native" || surface === "ios_surface" || surface === "android_surface") {
     return {
-      uiWeb: generateUiWebContract(context.graph, { ...(context.options || {}), projectionId })
+      uiSurface: generateUiSurfaceContract(context.graph, { ...(context.options || {}), projectionId })
     };
   }
   return {};
@@ -161,7 +177,8 @@ export const BUNDLED_GENERATOR_ADAPTERS = [
   {
     manifest: requiredManifest("topogram/hono"),
     generate(context) {
-      if (context.component && !context.component.databaseComponent) {
+      const runtime = runtimeFor(context);
+      if (runtime && !runtime.databaseComponent) {
         return fileResult(generateStatelessServer(context.graph, serverOptions(context, "hono")));
       }
       return fileResult(generateHonoServer(context.graph, serverOptions(context, "hono")));
@@ -170,7 +187,8 @@ export const BUNDLED_GENERATOR_ADAPTERS = [
   {
     manifest: requiredManifest("topogram/express"),
     generate(context) {
-      if (context.component && !context.component.databaseComponent) {
+      const runtime = runtimeFor(context);
+      if (runtime && !runtime.databaseComponent) {
         return fileResult(generateStatelessServer(context.graph, serverOptions(context, "express")));
       }
       return fileResult(generateExpressServer(context.graph, serverOptions(context, "express")));
@@ -246,24 +264,24 @@ function selectPackageExport(moduleValue, exportName) {
 
 /**
  * @param {GeneratorManifest} manifest
- * @param {Record<string, any>} component
+ * @param {Record<string, any>} runtime
  * @param {{ rootDir?: string|null, configDir?: string|null }} [options]
  * @returns {GeneratorAdapter}
  */
-function loadPackageGeneratorAdapter(manifest, component, options = {}) {
-  const packageName = manifest.package || component?.generator?.package;
+function loadPackageGeneratorAdapter(manifest, runtime, options = {}) {
+  const packageName = manifest.package || runtime?.generator?.package;
   if (!packageName) {
-    throw new Error(`Component '${component?.id || "unknown"}' generator '${manifest.id}@${manifest.version}' is package-backed but does not declare a package.`);
+    throw new Error(`Runtime '${runtime?.id || "unknown"}' generator '${manifest.id}@${manifest.version}' is package-backed but does not declare a package.`);
   }
   const rootDir = options.configDir || options.rootDir || process.cwd();
   const diagnostics = generatorPolicyDiagnosticsForBindings(
     loadGeneratorPolicy(rootDir),
     [{
-      componentId: String(component?.id || "unknown"),
-      componentType: String(component?.type || manifest.surface || "unknown"),
-      projection: String(component?.projection?.id || component?.projection || "unknown"),
-      generatorId: String(component?.generator?.id || manifest.id),
-      version: String(component?.generator?.version || manifest.version),
+      componentId: String(runtime?.id || "unknown"),
+      componentType: String(runtime?.kind || runtime?.type || manifest.surface || "unknown"),
+      projection: String(runtime?.projection?.id || runtime?.projection || "unknown"),
+      generatorId: String(runtime?.generator?.id || manifest.id),
+      version: String(runtime?.generator?.version || manifest.version),
       packageName
     }],
     "generator-adapter"
@@ -281,15 +299,15 @@ function loadPackageGeneratorAdapter(manifest, component, options = {}) {
     moduleValue = requireFromProject(rootDir)(packageName);
   } catch (error) {
     const installHint = packageGeneratorInstallHint(packageName);
-    throw new Error(`Component '${component?.id || "unknown"}' generator package '${packageName}' could not be loaded from '${rootDir}': ${error instanceof Error ? error.message : String(error)}${installHint ? `. ${installHint}` : ""}`);
+    throw new Error(`Runtime '${runtime?.id || "unknown"}' generator package '${packageName}' could not be loaded from '${rootDir}': ${error instanceof Error ? error.message : String(error)}${installHint ? `. ${installHint}` : ""}`);
   }
   const adapter = selectPackageExport(moduleValue, manifest.export);
   if (!adapter || typeof adapter.generate !== "function") {
-    throw new Error(`Component '${component?.id || "unknown"}' generator package '${packageName}' must export an adapter with a generate(context) function.`);
+    throw new Error(`Runtime '${runtime?.id || "unknown"}' generator package '${packageName}' must export an adapter with a generate(context) function.`);
   }
   const adapterManifest = adapter.manifest || manifest;
   if (adapterManifest.id !== manifest.id || adapterManifest.version !== manifest.version) {
-    throw new Error(`Component '${component?.id || "unknown"}' generator package '${packageName}' adapter manifest '${adapterManifest.id}@${adapterManifest.version}' does not match '${manifest.id}@${manifest.version}'.`);
+    throw new Error(`Runtime '${runtime?.id || "unknown"}' generator package '${packageName}' adapter manifest '${adapterManifest.id}@${adapterManifest.version}' does not match '${manifest.id}@${manifest.version}'.`);
   }
   return {
     manifest,
@@ -300,35 +318,35 @@ function loadPackageGeneratorAdapter(manifest, component, options = {}) {
 }
 
 /**
- * @param {Record<string, any>} component
+ * @param {Record<string, any>} runtime
  * @param {{ rootDir?: string|null, configDir?: string|null }} [options]
  * @returns {{ manifest: GeneratorManifest, adapter: GeneratorAdapter }}
  */
-export function resolveGeneratorForComponent(component, options = {}) {
-  const generatorId = component?.generator?.id;
-  const resolved = resolveGeneratorManifestForBinding(component?.generator, options);
+export function resolveGeneratorForComponent(runtime, options = {}) {
+  const generatorId = runtime?.generator?.id;
+  const resolved = resolveGeneratorManifestForBinding(runtime?.generator, options);
   const manifest = resolved.manifest || getGeneratorManifest(generatorId);
   if (!manifest) {
     const detail = resolved.errors.length > 0 ? ` ${resolved.errors.join(" ")}` : "";
-    throw new Error(`Component '${component?.id || "unknown"}' uses unknown generator '${generatorId || "unknown"}'.${detail}`);
+    throw new Error(`Runtime '${runtime?.id || "unknown"}' uses unknown generator '${generatorId || "unknown"}'.${detail}`);
   }
   if (manifest.planned) {
-    throw new Error(`Component '${component?.id || "unknown"}' uses planned generator '${manifest.id}', which is not implemented yet.`);
+    throw new Error(`Runtime '${runtime?.id || "unknown"}' uses planned generator '${manifest.id}', which is not implemented yet.`);
   }
-  if (component.generator?.version !== manifest.version) {
-    throw new Error(`Component '${component?.id || "unknown"}' generator '${manifest.id}' version '${component.generator?.version}' is unsupported; expected '${manifest.version}'.`);
+  if (runtime.generator?.version !== manifest.version) {
+    throw new Error(`Runtime '${runtime?.id || "unknown"}' generator '${manifest.id}' version '${runtime.generator?.version}' is unsupported; expected '${manifest.version}'.`);
   }
   const manifestValidation = validateGeneratorManifest(manifest);
   if (!manifestValidation.ok) {
     throw new Error(manifestValidation.errors.join("\n"));
   }
   if (manifest.source === "package") {
-    return { manifest, adapter: loadPackageGeneratorAdapter(manifest, component, options) };
+    return { manifest, adapter: loadPackageGeneratorAdapter(manifest, runtime, options) };
   }
   const adapter = getBundledGeneratorAdapter(manifest.id);
   if (!adapter) {
-    const installHint = packageGeneratorInstallHint(component?.generator?.package || manifest.package);
-    throw new Error(`Component '${component?.id || "unknown"}' generator '${manifest.id}@${manifest.version}' is not available. Package-backed generators must be installed before generation.${installHint ? ` ${installHint}` : ""}`);
+    const installHint = packageGeneratorInstallHint(runtime?.generator?.package || manifest.package);
+    throw new Error(`Runtime '${runtime?.id || "unknown"}' generator '${manifest.id}@${manifest.version}' is not available. Package-backed generators must be installed before generation.${installHint ? ` ${installHint}` : ""}`);
   }
   return { manifest, adapter };
 }
@@ -337,13 +355,20 @@ export function resolveGeneratorForComponent(component, options = {}) {
  * @param {Omit<GeneratorContext, "contracts"> & { contracts?: Record<string, any> }} context
  * @returns {GeneratorResult}
  */
-export function generateWithComponentGenerator(context) {
-  const { manifest, adapter } = resolveGeneratorForComponent(context.component, context.options || {});
+export function generateWithRuntimeGenerator(context) {
+  const runtime = runtimeFor(context);
+  const { manifest, adapter } = resolveGeneratorForComponent(runtime, context.options || {});
   const contracts = context.contracts || buildContractsForContext(context);
   return adapter.generate({
     ...context,
+    runtime,
+    component: runtime,
     projection: context.projection,
     manifest,
     contracts
   });
 }
+
+export function generateWithComponentGenerator(context) {
+  return generateWithRuntimeGenerator(context);
+}

package/src/generator/check.js

@@ -109,17 +109,17 @@ function loadInstalledAdapter(packageName, rootDir, manifest) {
  * @returns {Record<string, any>}
  */
 function smokeProjection(manifest) {
-  const platform = manifest.projectionPlatforms[0] || "";
+  const type = manifest.projectionTypes[0] || "";
   if (manifest.surface === "api") {
     return {
       id: "proj_generator_check_api",
-      platform: "api",
-      http: [{ method: "GET", path: "/generator-check", capabilityId: "cap_generator_check", success: 200 }]
+      type: "api_contract",
+      endpoints: [{ method: "GET", path: "/generator-check", capabilityId: "cap_generator_check", success: 200 }]
     };
   }
   return {
     id: `proj_generator_check_${manifest.surface}`,
-    platform
+    type
   };
 }
 
@@ -131,8 +131,8 @@ function smokeProjection(manifest) {
 function smokeContracts(manifest, projection) {
   if (manifest.surface === "web" || manifest.surface === "native") {
     return {
-      uiWeb: {
-        projection: { id: projection.id, platform: projection.platform },
+      uiSurface: {
+        projection: { id: projection.id, type: projection.type },
         appShell: { brand: "Generator Check" },
         screens: [
           { id: "screen_generator_check_home", title: "Generator Check", route: "/" },
@@ -148,22 +148,22 @@ function smokeContracts(manifest, projection) {
   if (manifest.surface === "api") {
     return {
       server: {
-        projection: { id: projection.id, platform: "api" },
-        routes: projection.http,
+        projection: { id: projection.id, type: "api_contract" },
+        routes: projection.endpoints,
         preconditions: [],
         responses: []
       },
-      api: { projections: [{ id: projection.id, http: projection.http }] }
+      api: { projections: [{ id: projection.id, endpoints: projection.endpoints }] }
     };
   }
   if (manifest.surface === "database") {
     return {
       db: {
-        projection: { id: projection.id, platform: projection.platform },
+        projection: { id: projection.id, type: projection.type },
         tables: []
       },
       lifecyclePlan: {
-        projection: { id: projection.id, platform: projection.platform },
+        projection: { id: projection.id, type: projection.type },
         migrations: [],
         seeds: []
       }
@@ -177,8 +177,15 @@ function smokeContracts(manifest, projection) {
  * @returns {Record<string, any>}
  */
 function smokeComponent(manifest) {
+  const runtimeKindBySurface = {
+    api: "api_service",
+    web: "web_surface",
+    native: "ios_surface",
+    database: "database"
+  };
   return {
-    id: `component_generator_check_${manifest.surface}`,
+    id: `runtime_generator_check_${manifest.surface}`,
+    kind: runtimeKindBySurface[manifest.surface] || manifest.surface,
     type: manifest.surface,
     projection: `proj_generator_check_${manifest.surface}`,
     generator: {

package/src/generator/context/diff.js

@@ -6,7 +6,7 @@ import {
   maintainedProofMetadata,
   relatedCapabilitiesForEntity,
   relatedProjectionsForCapability,
-  relatedProjectionsForComponent,
+  relatedProjectionsForWidget,
   relatedProjectionsForEntity,
   stableSortedStrings,
   summarizeById,
@@ -79,7 +79,7 @@ function changedIdsForDiffSections(diff) {
     "rules",
     "workflows",
     "projections",
-    "components",
+    "widgets",
     "journeys",
     "verifications",
     "domains",
@@ -100,16 +100,16 @@ function collectAffectedProjectionIds(graph, baselineGraph, diff) {
   const changedCapabilities = stableSortedStrings((diff.capabilities || []).map((entry) => entry.id));
   const changedEntities = stableSortedStrings((diff.entities || []).map((entry) => entry.id));
   const changedProjections = stableSortedStrings((diff.projections || []).map((entry) => entry.id));
-  const changedComponentProjections = stableSortedStrings((diff.components || []).flatMap((entry) => {
+  const changedWidgetProjections = stableSortedStrings((diff.widgets || []).flatMap((entry) => {
     if (entry.classification === "additive") {
-      return relatedProjectionsForComponent(graph, entry.id);
+      return relatedProjectionsForWidget(graph, entry.id);
     }
     if (entry.classification === "removed") {
-      return relatedProjectionsForComponent(baselineGraph, entry.id);
+      return relatedProjectionsForWidget(baselineGraph, entry.id);
     }
     return [
-      ...relatedProjectionsForComponent(graph, entry.id),
-      ...relatedProjectionsForComponent(baselineGraph, entry.id)
+      ...relatedProjectionsForWidget(graph, entry.id),
+      ...relatedProjectionsForWidget(baselineGraph, entry.id)
     ];
   }));
 
@@ -117,7 +117,7 @@ function collectAffectedProjectionIds(graph, baselineGraph, diff) {
     ...changedProjections,
     ...changedCapabilities.flatMap((id) => relatedProjectionsForCapability(graph, id)),
     ...changedEntities.flatMap((id) => relatedProjectionsForEntity(graph, id)),
-    ...changedComponentProjections
+    ...changedWidgetProjections
   ]);
 }
 
@@ -183,7 +183,7 @@ export function generateContextDiff(graph, options = {}) {
     rules: diffMaps(normalizeTargetMap(graph, "rule"), normalizeTargetMap(baselineGraph, "rule")),
     workflows: diffMaps(normalizeTargetMap(graph, "workflow"), normalizeTargetMap(baselineGraph, "workflow")),
     projections: diffMaps(normalizeTargetMap(graph, "projection"), normalizeTargetMap(baselineGraph, "projection")),
-    components: diffMaps(normalizeTargetMap(graph, "component"), normalizeTargetMap(baselineGraph, "component")),
+    widgets: diffMaps(normalizeTargetMap(graph, "widget"), normalizeTargetMap(baselineGraph, "widget")),
     journeys: diffMaps(normalizeTargetMap(graph, "journey"), normalizeTargetMap(baselineGraph, "journey")),
     verifications: diffMaps(normalizeTargetMap(graph, "verification"), normalizeTargetMap(baselineGraph, "verification")),
     domains: diffMaps(normalizeTargetMap(graph, "domain"), normalizeTargetMap(baselineGraph, "domain")),

package/src/generator/context/domain-coverage.js

@@ -9,14 +9,15 @@ import {
   summarizeDomain
 } from "./shared.js";
 
-function platformsFromProjections(projections) {
-  const platforms = new Set();
+function projectionTypesFromProjections(projections) {
+  const projectionTypes = new Set();
   for (const projection of projections) {
-    if (projection?.platform) {
-      platforms.add(projection.platform);
+    const projectionType = projection?.type || projection?.platform;
+    if (projectionType) {
+      projectionTypes.add(projectionType);
     }
   }
-  return [...platforms].sort();
+  return [...projectionTypes].sort();
 }
 
 export function generateDomainCoverage(graph, options = {}) {
@@ -45,17 +46,17 @@ export function generateDomainCoverage(graph, options = {}) {
     );
   }
 
-  const platforms = platformsFromProjections(projectionStatements);
+  const projectionTypes = projectionTypesFromProjections(projectionStatements);
   const matrix = {};
   for (const capabilityId of capabilities) {
     matrix[capabilityId] = {};
-    for (const platform of platforms) {
+    for (const projectionType of projectionTypes) {
       const realized = projectionStatements.some(
         (projection) =>
-          projection.platform === platform &&
+          (projection.type || projection.platform) === projectionType &&
           (projection.realizes || []).some((entry) => entry.id === capabilityId)
       );
-      matrix[capabilityId][platform] = realized;
+      matrix[capabilityId][projectionType] = realized;
     }
   }
 
@@ -64,7 +65,7 @@ export function generateDomainCoverage(graph, options = {}) {
     version: 1,
     focus: { kind: "domain", id: domain.id },
     summary: summarizeDomain(domain),
-    platforms,
+    projectionTypes,
     capabilities,
     entities,
     rules,

package/src/generator/context/domain-page.js

@@ -94,13 +94,13 @@ export function generateDomainPage(graph, options = {}) {
   lines.push(renderMembersSection(graph, "Verifications", relatedVerificationsForDomain(graph, domain.id), "verification"));
   lines.push("");
 
-  if (coverage.platforms.length) {
-    lines.push("## Per-platform coverage");
+  if (coverage.projectionTypes.length) {
+    lines.push("## Per-type coverage");
     lines.push("");
-    const headers = ["Capability", ...coverage.platforms];
+    const headers = ["Capability", ...coverage.projectionTypes];
     const rows = coverage.capabilities.map((capabilityId) => {
-      const cells = coverage.platforms.map((platform) =>
-        coverage.coverage_matrix[capabilityId]?.[platform] ? "✓" : "—"
+      const cells = coverage.projectionTypes.map((projectionType) =>
+        coverage.coverage_matrix[capabilityId]?.[projectionType] ? "✓" : "—"
       );
       return [`\`${capabilityId}\``, ...cells];
     });
@@ -108,7 +108,7 @@ export function generateDomainPage(graph, options = {}) {
     lines.push("");
     lines.push(`Projections involved: ${coverage.projections.map((id) => `\`${id}\``).join(", ") || "none"}`);
   } else {
-    lines.push("## Per-platform coverage");
+    lines.push("## Per-type coverage");
     lines.push("");
     lines.push("No projections currently realize capabilities in this domain.");
   }

package/src/generator/context/shared.js

@@ -168,7 +168,7 @@ function summarizeStatement(statement) {
         reviewBoundary: reviewBoundaryForEntityPolicy(statement),
         ownership_boundary: defaultOwnershipBoundary()
       };
-    case "component":
+    case "widget":
       return summarizeComponent(statement);
     case "shape":
       return {
@@ -396,8 +396,12 @@ export function relatedProjectionsForShape(graph, shapeId) {
   return stableSortedStrings([...directProjectionIds, ...viaCapabilities]);
 }
 
+export function widgetById(graph, widgetId) {
+  return (graph?.byKind?.widget || graph?.byKind?.component || []).find((widget) => widget.id === widgetId) || null;
+}
+
 export function componentById(graph, componentId) {
-  return (graph?.byKind?.component || []).find((component) => component.id === componentId) || null;
+  return widgetById(graph, componentId);
 }
 
 function projectionById(graph, projectionId) {
@@ -430,36 +434,44 @@ function downstreamProjectionIds(graph, projectionIds) {
   return stableSortedStrings([...visited]);
 }
 
-export function relatedComponentsForProjection(graph, projection) {
+export function relatedWidgetsForProjection(graph, projection) {
   const directIds = (projection?.uiComponents || []).map((entry) => entry.component?.id).filter(Boolean);
   const inheritedIds = realizedProjectionIds(projection)
     .map((projectionId) => projectionById(graph, projectionId))
     .filter(Boolean)
-    .flatMap((realizedProjection) => relatedComponentsForProjection(graph, realizedProjection));
+    .flatMap((realizedProjection) => relatedWidgetsForProjection(graph, realizedProjection));
   return stableSortedStrings([...directIds, ...inheritedIds]);
 }
 
-export function relatedShapesForComponent(component) {
-  if (!component) return [];
+export function relatedComponentsForProjection(graph, projection) {
+  return relatedWidgetsForProjection(graph, projection);
+}
+
+export function relatedShapesForWidget(widget) {
+  if (!widget) return [];
   const ids = [
-    ...(component.events || []).map((event) => event.shape?.id),
-    ...(component.lookups || [])
+    ...(widget.events || []).map((event) => event.shape?.id),
+    ...(widget.lookups || [])
       .filter((lookup) => lookup?.target?.kind === "shape" || String(lookup?.id || "").startsWith("shape_"))
       .map((lookup) => lookup.id),
-    ...(component.dependencies || [])
+    ...(widget.dependencies || [])
       .filter((dependency) => referenceKind(dependency) === "shape")
       .map((dependency) => dependency.id)
   ];
   return stableSortedStrings(ids);
 }
 
-export function relatedProjectionsForComponent(graph, componentId) {
-  const component = componentById(graph, componentId);
-  if (!component) return [];
+export function relatedShapesForComponent(component) {
+  return relatedShapesForWidget(component);
+}
+
+export function relatedProjectionsForWidget(graph, widgetId) {
+  const widget = widgetById(graph, widgetId);
+  if (!widget) return [];
   const explicitProjectionIds = stableSortedStrings((graph?.byKind?.projection || [])
-    .filter((projection) => (projection.uiComponents || []).some((entry) => entry.component?.id === componentId))
+    .filter((projection) => (projection.uiComponents || []).some((entry) => entry.component?.id === widgetId))
     .map((projection) => projection.id));
-  const dependencyProjectionIds = stableSortedStrings((component.dependencies || []).flatMap((dependency) => {
+  const dependencyProjectionIds = stableSortedStrings((widget.dependencies || []).flatMap((dependency) => {
     const kind = referenceKind(dependency);
     if (kind === "projection") {
       return [dependency.id];
@@ -475,18 +487,22 @@ export function relatedProjectionsForComponent(graph, componentId) {
     }
     return [];
   }));
-  const componentPatterns = new Set(component.patterns || []);
-  const componentRegions = new Set(component.regions || []);
+  const widgetPatterns = new Set(widget.patterns || []);
+  const widgetRegions = new Set(widget.regions || []);
   const viaUiRegions = stableSortedStrings((graph?.byKind?.projection || [])
     .filter((projection) => (projection.uiScreenRegions || []).some((region) =>
-      (region.pattern && componentPatterns.has(region.pattern)) ||
-      (region.region && componentRegions.has(region.region))
+      (region.pattern && widgetPatterns.has(region.pattern)) ||
+      (region.region && widgetRegions.has(region.region))
     ))
     .map((projection) => projection.id));
 
   return downstreamProjectionIds(graph, stableSortedStrings([...explicitProjectionIds, ...dependencyProjectionIds, ...viaUiRegions]));
 }
 
+export function relatedProjectionsForComponent(graph, componentId) {
+  return relatedProjectionsForWidget(graph, componentId);
+}
+
 function referenceKind(reference) {
   if (reference?.target?.kind) {
     return reference.target.kind;
@@ -539,7 +555,7 @@ export function workspaceInventory(graph) {
     journeys: stableSortedStrings((graph.docs || []).filter((doc) => doc.kind === "journey").map((doc) => doc.id)),
     entities: stableSortedStrings((graph.byKind.entity || []).map((item) => item.id)),
     projections: stableSortedStrings((graph.byKind.projection || []).map((item) => item.id)),
-    components: stableSortedStrings((graph.byKind.component || []).map((item) => item.id)),
+    widgets: stableSortedStrings((graph.byKind.widget || graph.byKind.component || []).map((item) => item.id)),
     verifications: stableSortedStrings((graph.byKind.verification || []).map((item) => item.id)),
     domains: stableSortedStrings((graph.byKind.domain || []).map((item) => item.id)),
     pitches: stableSortedStrings((graph.byKind.pitch || []).map((item) => item.id)),
@@ -556,7 +572,7 @@ export function ensureContextSelection(options = {}) {
     options.capabilityId ? ["capability", options.capabilityId] : null,
     options.workflowId ? ["workflow", options.workflowId] : null,
     options.projectionId ? ["projection", options.projectionId] : null,
-    options.componentId ? ["component", options.componentId] : null,
+    (options.widgetId || options.componentId) ? ["widget", options.widgetId || options.componentId] : null,
     options.entityId ? ["entity", options.entityId] : null,
     options.journeyId ? ["journey", options.journeyId] : null,
     options.surfaceId ? ["surface", options.surfaceId] : null,
@@ -571,7 +587,7 @@ export function ensureContextSelection(options = {}) {
 
   if (selectors.length !== 1) {
     throw new Error(
-      "Context selection requires exactly one of --capability, --workflow, --projection, --component, --entity, --journey, --surface, --domain, --pitch, --requirement, --acceptance, --task, --bug, or --document"
+      "Context selection requires exactly one of --capability, --workflow, --projection, --widget, --entity, --journey, --surface, --domain, --pitch, --requirement, --acceptance, --task, --bug, or --document"
     );
   }