@topogram/cli 0.3.51 → 0.3.52

package/ARCHITECTURE.md

@@ -33,7 +33,7 @@ Topogram turns a `.tg` workspace into generated artifacts and apps through five
 Generator adapters
 - Own stack-specific realization such as React, SvelteKit, Hono, Express,
   Postgres, SQLite, Prisma, Drizzle, SwiftUI, or future Android files.
-- Consume normalized contracts, topology component metadata, and optional
+- Consume normalized contracts, topology runtime metadata, widget contracts, and optional
   implementation hooks.
 - Return generated files and diagnostics through the shared generator interface.
 
@@ -42,9 +42,9 @@ Workspace `implementation/`
 - Can include seed data, custom page renderers, repository implementations, and runtime-check specifics.
 - Must not be treated as engine contracts.
 
-`component` statements live in the semantic graph beside entities, capabilities,
-shapes, and projections. They produce `componentContract` resolver enrichment
-and can be emitted through the `ui-component-contract` generator target without
+`widget` statements live in the semantic graph beside entities, capabilities,
+shapes, and projections. They produce `widgetContract` resolver enrichment
+and can be emitted through the `ui-widget-contract` generator target without
 requiring an implementation provider.
 
 ## Stable Internal Contracts

package/CHANGELOG.md

@@ -36,17 +36,17 @@
 
 ## 0.3.13 - 2026-05-01
 
-- Add `topogram component check` as a user-facing alias for component
+- Add `topogram widget check` as a user-facing alias for component
   conformance reports. The command prints a human summary by default, supports
-  `--projection`, `--component`, and `--json`, and exits non-zero when
+  `--projection`, `--widget`, and `--json`, and exits non-zero when
   conformance errors are present.
 
 ## 0.3.12 - 2026-05-01
 
-- Add `component-conformance-report` generator target. The report compares
-  `projection.ui_components` usage against component contracts, includes
+- Add `widget-conformance-report` generator target. The report compares
+  `projection.widget_bindings` usage against component contracts, includes
   inherited shared-UI usages for concrete web projections, supports
-  `--projection` and `--component` filters, and reports repair-oriented checks
+  `--projection` and `--widget` filters, and reports repair-oriented checks
   for missing required props, event action context, component status, approvals,
   write scope, and projection/component impact.
 
@@ -159,7 +159,7 @@
   generators (board/release-notes/traceability), state-machine
   transitions, DoD rules, archive load/save, transition round-trips
   (rewrite + history sidecar), and release dry-run output.
-- Add `projection.ui_components` so projections explicitly own component
+- Add `projection.widget_bindings` so projections explicitly own component
   placement and wiring. Component usage validates screen, region, component,
   prop, event, data-source, and event-target references.
 - Remove `component.consumers` from the component grammar before external
@@ -168,7 +168,7 @@
 - Add structured component `behaviors { ... }` alongside the shorthand
   `behavior [...]`, with validation for supported stack-agnostic behavior
   kinds and behavior references to component props/events.
-- Emit `approvals` and normalized `behaviors` in `ui-component-contract`
+- Emit `approvals` and normalized `behaviors` in `ui-widget-contract`
   artifacts.
 - Include component usage metadata in generated UI contracts. Concrete web
   projections that realize a shared UI projection now inherit the shared
@@ -180,18 +180,18 @@
 
 - Add `component` statement kind for reusable UI/service component contracts
   (props, events, slots, patterns, regions, dependencies, consumers).
-- Add `ui-component-contract` generator target that emits stable JSON per
-  component or for the whole workspace; selectable via `--component <id>`.
+- Add `ui-widget-contract` generator target that emits stable JSON per
+  component or for the whole workspace; selectable via `--widget <id>`.
 - `context-diff` now emits a `components` section, and changed components
   fan out into `affected_generated_surfaces.projections` so consumer
   projections show up in diff payloads.
-- `context-slice --component <id>` returns a first-class component slice with
+- `context-slice --widget <id>` returns a first-class component slice with
   `focus.kind === "component"`, dependent shapes/projections/verifications,
   and a `component_surface` review boundary; the same selector flows through
   `verification-targets`, `change-plan`, `risk-summary`, `review-packet`,
   `proceed-decision`, `next-action`, `single-agent-plan`, and
   `resolved-workflow-context`.
-- `topogram generate ... --generate ui-component-contract --component <id>`
+- `topogram generate ... --generate ui-widget-contract --widget <id>`
   now errors loudly when the id does not match any component (previously it
   wrote a `null` artifact).
 - Component prop defaults preserve real values: `default true`, `default false`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@topogram/cli",
-  "version": "0.3.51",
+  "version": "0.3.52",
   "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", "components", "docs", "journeys", "workflows", "verification", "ui"]);
+const ADOPT_SELECTORS = new Set(["from-plan", "actors", "roles", "enums", "shapes", "entities", "capabilities", "widgets", "docs", "journeys", "workflows", "verification", "ui"]);
 
 function stableSortedStrings(values) {
   return [...new Set((values || []).filter(Boolean))].sort();
@@ -355,7 +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 === "widgets") return item.kind === "widget";
   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/agent-ops/query-builders.js

@@ -138,24 +138,29 @@ function stableOrderedUnion(values = []) {
   return result;
 }
 
+function targetWidgetId(target = {}) {
+  return target.widget_id || target.component_id || null;
+}
+
 function componentBehaviorArtifactPath(target = {}) {
-  if (target.target !== "component-behavior-report") {
+  if (target.target !== "widget-behavior-report") {
     return null;
   }
-  const suffix = [target.projection_id, target.component_id].filter(Boolean).join(".");
-  return suffix ? `${suffix}.component-behavior-report.json` : "component-behavior-report.json";
+  const suffix = [target.projection_id, targetWidgetId(target)].filter(Boolean).join(".");
+  return suffix ? `${suffix}.widget-behavior-report.json` : "widget-behavior-report.json";
 }
 
 function componentBehaviorQueryCommand(target = {}) {
-  if (target.target !== "component-behavior-report") {
+  if (target.target !== "widget-behavior-report") {
     return null;
   }
-  const parts = ["topogram", "query", "component-behavior", "./topogram"];
+  const parts = ["topogram", "query", "widget-behavior", "./topogram"];
   if (target.projection_id) {
     parts.push("--projection", target.projection_id);
   }
-  if (target.component_id) {
-    parts.push("--component", target.component_id);
+  const widgetId = targetWidgetId(target);
+  if (widgetId) {
+    parts.push("--widget", widgetId);
   }
   parts.push("--json");
   return parts.join(" ");
@@ -169,10 +174,10 @@ function recommendedArtifactQueriesFromGeneratorTargets(generatorTargets = []) {
     if (!command || seen.has(command)) continue;
     seen.add(command);
     queries.push({
-      query: "component-behavior",
+      query: "widget-behavior",
       target: target.target,
       projection_id: target.projection_id || null,
-      component_id: target.component_id || null,
+      widget_id: targetWidgetId(target),
       command
     });
   }
@@ -1340,9 +1345,9 @@ function projectionKindForImpact(projection) {
     (projection.uiWeb || []).length > 0 ||
     (projection.uiIos || []).length > 0 ||
     (projection.uiScreens || []).length > 0 ||
-    projection.platform === "ui_web" ||
-    projection.platform === "ui_ios" ||
-    projection.platform === "ui_shared"
+    projection.platform === "web_surface" ||
+    projection.platform === "ios_surface" ||
+    projection.platform === "ui_contract"
   ) {
     return "ui";
   }
@@ -1634,7 +1639,7 @@ function buildProjectionImpacts(graph, { sliceArtifact, diffArtifact }) {
         "selected_entity",
         (projection) => `Projection ${projection.id} is in scope because selected entity ${id} participates in that projection.`
       )) addImpact(impactMap, impact);
-    } else if (kind === "component") {
+    } else if (kind === "widget") {
       for (const impact of projectionImpactsFromComponent(graph, id)) addImpact(impactMap, impact);
     } else if (kind === "workflow") {
       for (const impact of projectionImpactsFromWorkflow(graph, id, true)) addImpact(impactMap, impact);
@@ -1656,11 +1661,15 @@ function buildGeneratorTargets(graph, projectionImpacts = [], diffArtifact = nul
   const targets = [];
   const addTarget = (target) => {
     if (!target?.target) return;
-    if (!target.projection_id && !target.component_id) return;
+    if (target.component_id && !target.widget_id) {
+      target.widget_id = target.component_id;
+      delete target.component_id;
+    }
+    if (!target.projection_id && !target.widget_id) return;
     if (!targets.some((entry) =>
       entry.target === target.target &&
       entry.projection_id === target.projection_id &&
-      entry.component_id === target.component_id
+      targetWidgetId(entry) === targetWidgetId(target)
     )) {
       targets.push(target);
     }
@@ -1668,16 +1677,16 @@ function buildGeneratorTargets(graph, projectionImpacts = [], diffArtifact = nul
 
   for (const entry of diffArtifact?.components || []) {
     addTarget({
-      target: "ui-component-contract",
-      component_id: entry.id,
+      target: "ui-widget-contract",
+      widget_id: entry.id,
       required: true,
-      reason: `Component ${entry.id} changed directly, so its component contract should be refreshed.`
+      reason: `Widget ${entry.id} changed directly, so its widget contract should be refreshed.`
     });
     addTarget({
-      target: "component-behavior-report",
-      component_id: entry.id,
+      target: "widget-behavior-report",
+      widget_id: entry.id,
       required: true,
-      reason: `Component ${entry.id} changed directly, so behavior realizations should be reviewed across affected projections.`
+      reason: `Widget ${entry.id} changed directly, so behavior realizations should be reviewed across affected projections.`
     });
   }
 
@@ -1708,7 +1717,7 @@ function buildGeneratorTargets(graph, projectionImpacts = [], diffArtifact = nul
       });
     }
 
-    if (projection.platform === "ui_shared") {
+    if (projection.platform === "ui_contract") {
       addTarget({
         target: "ui-contract-graph",
         projection_id: impact.projection_id,
@@ -1730,30 +1739,30 @@ function buildGeneratorTargets(graph, projectionImpacts = [], diffArtifact = nul
 
     for (const componentId of componentIds) {
       addTarget({
-        target: "ui-component-contract",
-        component_id: componentId,
+        target: "ui-widget-contract",
+        widget_id: componentId,
         projection_id: impact.projection_id,
         required: true,
-        reason: `Projection ${impact.projection_id} is affected by component ${componentId}, so the component contract should be refreshed.`
+        reason: `Projection ${impact.projection_id} is affected by widget ${componentId}, so the widget contract should be refreshed.`
       });
       addTarget({
-        target: "component-behavior-report",
-        component_id: componentId,
+        target: "widget-behavior-report",
+        widget_id: componentId,
         projection_id: impact.projection_id,
         required: true,
-        reason: `Projection ${impact.projection_id} is affected by component ${componentId}, so behavior data/event/action wiring should be reviewed.`
+        reason: `Projection ${impact.projection_id} is affected by widget ${componentId}, so behavior data/event/action wiring should be reviewed.`
       });
     }
 
-    if (projection.platform === "ui_web") {
+    if (projection.platform === "web_surface") {
       addTarget({
-        target: "ui-web-contract",
+        target: "ui-surface-contract",
         projection_id: impact.projection_id,
         required: true,
         reason: `Projection ${impact.projection_id} is a web UI surface, so the web UI contract should be refreshed.`
       });
       addTarget({
-        target: "ui-web-debug",
+        target: "ui-surface-debug",
         projection_id: impact.projection_id,
         required: false,
         reason: `Projection ${impact.projection_id} may benefit from UI web debug output during review.`
@@ -1768,7 +1777,7 @@ function buildGeneratorTargets(graph, projectionImpacts = [], diffArtifact = nul
       }
     }
 
-    if (projection.platform === "ui_ios") {
+    if (projection.platform === "ios_surface") {
       addTarget({
         target: "swiftui-app",
         projection_id: impact.projection_id,
@@ -1819,7 +1828,7 @@ function buildGeneratorTargets(graph, projectionImpacts = [], diffArtifact = nul
   return targets.sort((a, b) => {
     const projectionCompare = String(a.projection_id || "").localeCompare(String(b.projection_id || ""));
     if (projectionCompare !== 0) return projectionCompare;
-    const componentCompare = String(a.component_id || "").localeCompare(String(b.component_id || ""));
+    const componentCompare = String(targetWidgetId(a) || "").localeCompare(String(targetWidgetId(b) || ""));
     if (componentCompare !== 0) return componentCompare;
     return projectionCompare !== 0 ? projectionCompare : a.target.localeCompare(b.target);
   });