@topogram/cli 0.3.51 → 0.3.53

package/src/project-config.js

@@ -18,14 +18,17 @@ import { validateProjectGeneratorPolicy } from "./generator-policy.js";
  */
 
 /**
- * @typedef {Object} RuntimeTopologyComponent
+ * @typedef {Object} RuntimeTopologyRuntime
  * @property {string} id
- * @property {"api"|"web"|"database"|"native"} type
+ * @property {"api_service"|"web_surface"|"ios_surface"|"android_surface"|"database"} kind
  * @property {string} projection
  * @property {GeneratorBinding} generator
  * @property {number|null} [port]
- * @property {string} [api]
- * @property {string} [database]
+ * @property {string} [uses_api]
+ * @property {string} [uses_database]
+ * @property {string} [type] Migration diagnostic only.
+ * @property {string} [api] Migration diagnostic only.
+ * @property {string} [database] Migration diagnostic only.
  * @property {Record<string, string>} [env]
  */
 
@@ -33,7 +36,7 @@ import { validateProjectGeneratorPolicy } from "./generator-policy.js";
  * @typedef {Object} ProjectConfig
  * @property {string} version
  * @property {Record<string, { path: string, ownership: "generated"|"maintained" }>} outputs
- * @property {{ components: RuntimeTopologyComponent[] }} topology
+ * @property {{ runtimes: RuntimeTopologyRuntime[], components?: any[] }} topology
  * @property {{ id?: string, module?: string, export?: string, implementation_module?: string, implementation_export?: string }} [implementation]
  */
 
@@ -103,6 +106,16 @@ function readJson(filePath) {
   return JSON.parse(fs.readFileSync(filePath, "utf8"));
 }
 
+/**
+ * @param {string} oldName
+ * @param {string} newName
+ * @param {string} example
+ * @returns {string}
+ */
+function renameDiagnostic(oldName, newName, example) {
+  return `${oldName} was renamed to ${newName}. Example fix: ${example}`;
+}
+
 /**
  * @param {string} root
  * @param {string} fileName
@@ -149,46 +162,46 @@ export function defaultProjectConfigForGraph(graph, implementation = null) {
   const runtimeReference = implementation?.runtime?.reference || {};
   /** @type {Array<Record<string, any>>} */
   const projections = graph.byKind.projection || [];
-  const apiProjection = projections.find((projection) => (projection.http || []).length > 0);
+  const apiProjection = projections.find((projection) => (projection.http || []).length > 0 || projection.type === "api_contract");
   const webProjection =
-    projections.find((projection) => projection.id === "proj_ui_web") ||
-    projections.find((projection) => projection.platform === "ui_web");
+    projections.find((projection) => projection.id === "proj_web") ||
+    projections.find((projection) => projection.type === "web_surface");
   const dbProjection =
     projections.find((projection) => projection.id === runtimeReference.localDbProjectionId) ||
-    projections.find((projection) => projection.platform === "db_postgres") ||
-    projections.find((projection) => projection.platform === "db_sqlite");
+    projections.find((projection) => projection.type === "db_contract");
   const ports = runtimeReference.ports || {};
-  const dbGenerator = dbProjection?.platform === "db_sqlite" ? "topogram/sqlite" : "topogram/postgres";
-  const dbComponentId = dbProjection?.platform === "db_sqlite" ? "app_sqlite" : "app_postgres";
-  /** @type {RuntimeTopologyComponent[]} */
-  const components = [
+  const dbProfile = (dbProjection?.generatorDefaults || []).find((/** @type {Record<string, any>} */ entry) => entry.key === "profile")?.value;
+  const dbGenerator = dbProfile === "sqlite_sql" ? "topogram/sqlite" : "topogram/postgres";
+  const dbRuntimeId = dbProfile === "sqlite_sql" ? "app_sqlite" : "app_postgres";
+  /** @type {RuntimeTopologyRuntime[]} */
+  const runtimes = [
     ...(apiProjection
       ? [{
           id: "app_api",
-          type: /** @type {"api"} */ ("api"),
+          kind: /** @type {"api_service"} */ ("api_service"),
           projection: apiProjection.id,
           generator: { id: "topogram/hono", version: "1" },
           port: ports.server || 3000,
-          ...(dbProjection ? { database: dbComponentId } : {})
+          ...(dbProjection ? { uses_database: dbRuntimeId } : {})
         }]
       : []),
     ...(webProjection
       ? [{
           id: "app_sveltekit",
-          type: /** @type {"web"} */ ("web"),
+          kind: /** @type {"web_surface"} */ ("web_surface"),
           projection: webProjection.id,
           generator: { id: "topogram/sveltekit", version: "1" },
           port: ports.web || 5173,
-          ...(apiProjection ? { api: "app_api" } : {})
+          ...(apiProjection ? { uses_api: "app_api" } : {})
         }]
       : []),
     ...(dbProjection
       ? [{
-          id: dbComponentId,
-          type: /** @type {"database"} */ ("database"),
+          id: dbRuntimeId,
+          kind: /** @type {"database"} */ ("database"),
           projection: dbProjection.id,
           generator: { id: dbGenerator, version: "1" },
-          port: dbProjection.platform === "db_sqlite" ? null : 5432
+          port: dbProfile === "sqlite_sql" ? null : 5432
         }]
       : [])
   ];
@@ -207,7 +220,41 @@ export function defaultProjectConfigForGraph(graph, implementation = null) {
       }
     },
     topology: {
-      components
+      runtimes
+    }
+  };
+}
+
+/**
+ * @param {string} kind
+ * @returns {string}
+ */
+function legacyRuntimeType(kind) {
+  if (kind === "api_service") return "api";
+  if (kind === "web_surface") return "web";
+  if (kind === "ios_surface" || kind === "android_surface") return "native";
+  return kind;
+}
+
+/**
+ * @param {any} config
+ * @returns {any}
+ */
+function normalizeProjectConfigRuntimeAliases(config) {
+  if (!config?.topology || !Array.isArray(config.topology.runtimes)) {
+    return config;
+  }
+  return {
+    ...config,
+    topology: {
+      ...config.topology,
+      __normalizedRuntimeAliases: true,
+      components: config.topology.runtimes.map((/** @type {RuntimeTopologyRuntime} */ runtime) => ({
+        ...runtime,
+        type: legacyRuntimeType(runtime.kind),
+        api: runtime.uses_api,
+        database: runtime.uses_database
+      }))
     }
   };
 }
@@ -223,6 +270,7 @@ export function loadProjectConfig(root) {
   }
   return {
     ...found,
+    config: normalizeProjectConfigRuntimeAliases(found.config),
     compatibility: false
   };
 }
@@ -242,7 +290,7 @@ export function projectConfigOrDefault(root, graph = null, implementation = null
     return null;
   }
   return {
-    config: defaultProjectConfigForGraph(graph, implementation),
+    config: normalizeProjectConfigRuntimeAliases(defaultProjectConfigForGraph(graph, implementation)),
     configPath: null,
     configDir: path.dirname(path.resolve(root)),
     compatibility: true
@@ -298,7 +346,7 @@ function validateOutputConfig(errors, config) {
  * @returns {string}
  */
 function componentLabel(component) {
-  return component?.id ? `Component '${component.id}'` : "Topology component";
+  return component?.id ? `Runtime '${component.id}'` : "Topology runtime";
 }
 
 /**
@@ -309,18 +357,27 @@ function componentLabel(component) {
  */
 function validateComponentShape(errors, component, seenIds) {
   if (!component || typeof component !== "object" || Array.isArray(component)) {
-    pushError(errors, "Topology component must be an object");
+    pushError(errors, "Topology runtime must be an object");
     return false;
   }
   if (typeof component.id !== "string" || !IDENTIFIER_PATTERN.test(component.id)) {
     pushError(errors, `${componentLabel(component)} id must match ${IDENTIFIER_PATTERN}`);
   } else if (seenIds.has(component.id)) {
-    pushError(errors, `Duplicate topology component id '${component.id}'`);
+    pushError(errors, `Duplicate topology runtime id '${component.id}'`);
   } else {
     seenIds.add(component.id);
   }
-  if (!["api", "web", "database", "native"].includes(component.type)) {
-    pushError(errors, `${componentLabel(component)} type must be api, web, database, or native`);
+  if (component.type != null) {
+    pushError(errors, `${componentLabel(component)} ${renameDiagnostic("'type'", "'kind'", `"kind": "api_service"`)}`);
+  }
+  if (component.database != null) {
+    pushError(errors, `${componentLabel(component)} ${renameDiagnostic("'database'", "'uses_database'", `"uses_database": "app_db"`)}`);
+  }
+  if (component.api != null) {
+    pushError(errors, `${componentLabel(component)} ${renameDiagnostic("'api'", "'uses_api'", `"uses_api": "app_api"`)}`);
+  }
+  if (!["api_service", "web_surface", "ios_surface", "android_surface", "database"].includes(component.kind)) {
+    pushError(errors, `${componentLabel(component)} kind must be api_service, web_surface, ios_surface, android_surface, or database`);
   }
   if (typeof component.projection !== "string" || component.projection.length === 0) {
     pushError(errors, `${componentLabel(component)} projection must be a non-empty string`);
@@ -346,7 +403,7 @@ function validateComponentShape(errors, component, seenIds) {
 
 /**
  * @param {ValidationError[]} errors
- * @param {RuntimeTopologyComponent} component
+ * @param {RuntimeTopologyRuntime} component
  * @param {Map<string, Record<string, any>>} projections
  * @param {{ configDir?: string|null, rootDir?: string|null }} [options]
  * @returns {void}
@@ -377,14 +434,14 @@ function validateComponentCompatibility(errors, component, projections, options
   if (manifest.version !== component.generator.version) {
     pushError(errors, `${componentLabel(component)} for projection '${projection.id}' generator '${manifest.id}' version '${component.generator.version}' is unsupported; expected '${manifest.version}'`);
   }
-  if (!isGeneratorCompatible(manifest, component.type, projection)) {
-    pushError(errors, `${componentLabel(component)} for projection '${projection.id}' generator '${manifest.id}@${manifest.version}' is incompatible with component surface '${component.type}' and projection platform '${projection.platform || "api"}'`);
+  if (!isGeneratorCompatible(manifest, component.kind, projection)) {
+    pushError(errors, `${componentLabel(component)} for projection '${projection.id}' generator '${manifest.id}@${manifest.version}' is incompatible with runtime kind '${component.kind}' and projection type '${projection.type || "api_contract"}'`);
   }
 }
 
 /**
  * @param {ValidationError[]} errors
- * @param {RuntimeTopologyComponent[]} components
+ * @param {RuntimeTopologyRuntime[]} components
  * @returns {void}
  */
 function validateTopologyReferences(errors, components) {
@@ -399,14 +456,14 @@ function validateTopologyReferences(errors, components) {
         usedPorts.set(component.port, component.id);
       }
     }
-    if (component.type === "api") {
-      if (component.database && byId.get(component.database)?.type !== "database") {
-        pushError(errors, `${componentLabel(component)} references missing database component '${component.database}'`);
+    if (component.kind === "api_service") {
+      if (component.uses_database && byId.get(component.uses_database)?.kind !== "database") {
+        pushError(errors, `${componentLabel(component)} references missing database runtime '${component.uses_database}'`);
       }
     }
-    if (component.type === "web") {
-      if (component.api && byId.get(component.api)?.type !== "api") {
-        pushError(errors, `${componentLabel(component)} references missing api component '${component.api}'`);
+    if (["web_surface", "ios_surface", "android_surface"].includes(component.kind)) {
+      if (component.uses_api && byId.get(component.uses_api)?.kind !== "api_service") {
+        pushError(errors, `${componentLabel(component)} references missing api runtime '${component.uses_api}'`);
       }
     }
   }
@@ -428,23 +485,26 @@ export function validateProjectConfig(config, graph = null, options = {}) {
     pushError(errors, "topogram.project.json version must be a non-empty string");
   }
   validateOutputConfig(errors, config);
-  if (!config.topology || typeof config.topology !== "object" || !Array.isArray(config.topology.components)) {
-    pushError(errors, "topogram.project.json topology.components must be an array");
+  if (config.topology?.components != null && config.topology.__normalizedRuntimeAliases !== true) {
+    pushError(errors, `topogram.project.json ${renameDiagnostic("'topology.components'", "'topology.runtimes'", `"topology": { "runtimes": [] }`)}`);
+  }
+  if (!config.topology || typeof config.topology !== "object" || !Array.isArray(config.topology.runtimes)) {
+    pushError(errors, "topogram.project.json topology.runtimes must be an array");
   } else {
     const seenIds = new Set();
-    for (const component of config.topology.components) {
+    for (const component of config.topology.runtimes) {
       validateComponentShape(errors, component, seenIds);
     }
-    const generatorPolicy = validateProjectGeneratorPolicy(config, options);
+    const generatorPolicy = validateProjectGeneratorPolicy(normalizeProjectConfigRuntimeAliases(config), options);
     for (const error of generatorPolicy.errors) {
       pushError(errors, error.message, error.loc);
     }
     if (graph) {
       const projections = projectionById(graph);
-      for (const component of config.topology.components) {
+      for (const component of config.topology.runtimes) {
         validateComponentCompatibility(errors, component, projections, options);
       }
-      validateTopologyReferences(errors, config.topology.components);
+      validateTopologyReferences(errors, config.topology.runtimes);
     }
   }
   return {

package/src/proofs/contract-audit.js

@@ -187,7 +187,7 @@ export function auditUiContractPair(leftContract, rightContract) {
   const appShellParity = stableStringify(left.appShell) === stableStringify(right.appShell);
 
   return {
-    seam: "ui_web_contract",
+    seam: "ui_surface_contract",
     semanticParity: screenDiffs.length === 0 && navigationParity && appShellParity,
     summary: {
       screenCount: left.screens.length,

package/src/proofs/ios-parity.js

@@ -1,7 +1,7 @@
 import { stableStringify } from "../format.js";
 import { normalizeScreens } from "./web-parity.js";
 
-/** Semantic fingerprint of screens slice embedded in Swift ui-web-contract JSON (matches web normalization). */
+/** Semantic fingerprint of screens slice embedded in Swift ui-surface-contract JSON (matches web normalization). */
 export function fingerprintIosEmbeddedUiContract(contract) {
   return stableStringify(normalizeScreens(contract));
 }

package/src/proofs/issues-parity.js

@@ -2,7 +2,7 @@ import { buildBackendParityEvidence } from "./backend-parity.js";
 import { buildWebParityEvidence } from "./web-parity.js";
 
 export function buildIssuesParityEvidence(graph) {
-  const web = buildWebParityEvidence(graph, "proj_ui_web__react", "proj_ui_web__sveltekit");
+  const web = buildWebParityEvidence(graph, "proj_web_surface__react", "proj_web_surface__sveltekit");
   return {
     web,
     runtime: buildBackendParityEvidence(graph, "proj_api")

package/src/realization/backend/build-backend-runtime-realization.js

@@ -28,8 +28,8 @@ export function getDefaultBackendDbProjection(graph, options = {}) {
   return (
     explicit ||
     preferred ||
-    candidates.find((projection) => projection.platform === "db_postgres") ||
-    candidates.find((projection) => projection.platform === "db_sqlite") ||
+    candidates.find((projection) => projection.platform === "db_contract") ||
+    candidates.find((projection) => projection.platform === "db_contract") ||
     candidates[0] ||
     null
   );

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

@@ -1,5 +1,5 @@
 import { getProjection, uiProjectionCandidates } from "../../generator/surfaces/shared.js";
-import { buildComponentBehaviorRealizations } from "../../component-behavior.js";
+import { buildWidgetBehaviorRealizations } from "../../widget-behavior.js";
 import { defaultPatternForScreen } from "../../ui/taxonomy.js";
 
 function toBooleanFlag(value, fallback = false) {
@@ -48,25 +48,25 @@ function ownershipFieldByCapability(graph) {
   return output;
 }
 
-function componentById(graph, componentId) {
-  return (graph.byKind.component || []).find((component) => component.id === componentId) || null;
+function widgetById(graph, widgetId) {
+  return (graph.byKind.widget || graph.byKind.component || []).find((widget) => widget.id === widgetId) || null;
 }
 
-function componentContractFor(graph, componentId) {
-  const component = componentById(graph, componentId);
-  return component?.componentContract || null;
+function widgetContractFor(graph, widgetId) {
+  const widget = widgetById(graph, widgetId);
+  return widget?.widgetContract || widget?.componentContract || null;
 }
 
-function summarizeComponentRef(graph, componentId) {
-  const component = componentById(graph, componentId);
-  if (!component) {
-    return { id: componentId, name: componentId, category: null, version: null };
+function summarizeWidgetRef(graph, widgetId) {
+  const widget = widgetById(graph, widgetId);
+  if (!widget) {
+    return { id: widgetId, name: widgetId, category: null, version: null };
   }
   return {
-    id: component.id,
-    name: component.name || component.id,
-    category: component.category || null,
-    version: component.version || null
+    id: widget.id,
+    name: widget.name || widget.id,
+    category: widget.category || null,
+    version: widget.version || null
   };
 }
 
@@ -118,16 +118,16 @@ function buildDesignIntentContract(projection) {
   return design;
 }
 
-export function buildComponentUsageContract(graph, entry, options = {}) {
-  const componentId = entry.component?.id || null;
-  const contract = componentId ? componentContractFor(graph, componentId) : null;
+export function buildWidgetUsageContract(graph, entry, options = {}) {
+  const widgetId = entry.widget?.id || entry.component?.id || null;
+  const contract = widgetId ? widgetContractFor(graph, widgetId) : null;
   const region = options.region || null;
   return {
-    type: "ui_component_usage",
+    type: "ui_widget_usage",
     region: entry.region || null,
     pattern: region?.pattern || null,
     placement: region?.placement || null,
-    component: componentId ? summarizeComponentRef(graph, componentId) : null,
+    widget: widgetId ? summarizeWidgetRef(graph, widgetId) : null,
     dataBindings: (entry.dataBindings || []).map((binding) => ({
       prop: binding.prop || null,
       source: binding.source || null
@@ -137,15 +137,15 @@ export function buildComponentUsageContract(graph, entry, options = {}) {
       action: binding.action || null,
       target: binding.target || null
     })),
-    behaviorRealizations: buildComponentBehaviorRealizations(contract, entry)
+    behaviorRealizations: buildWidgetBehaviorRealizations(contract, entry)
   };
 }
 
-export function buildComponentContractMap(graph, componentUsages) {
+export function buildWidgetContractMap(graph, widgetUsages) {
   return Object.fromEntries(
-    [...new Set(componentUsages.map((entry) => entry.component?.id).filter(Boolean))]
+    [...new Set(widgetUsages.map((entry) => entry.widget?.id || entry.component?.id).filter(Boolean))]
       .sort()
-      .map((componentId) => [componentId, componentContractFor(graph, componentId)])
+      .map((widgetId) => [widgetId, widgetContractFor(graph, widgetId)])
       .filter(([, contract]) => contract)
   );
 }
@@ -202,7 +202,7 @@ function buildUiScreenContract(graph, projection, screen, ownershipFields) {
   const actionEntries = (projection.uiActions || []).filter((entry) => entry.screenId === screen.id);
   const lookupEntries = (projection.uiLookups || []).filter((entry) => entry.screenId === screen.id);
   const regionEntries = (projection.uiScreenRegions || []).filter((entry) => entry.screenId === screen.id);
-  const componentEntries = (projection.uiComponents || []).filter((entry) => entry.screenId === screen.id);
+  const widgetEntries = (projection.uiComponents || []).filter((entry) => entry.screenId === screen.id);
   const screenActionIds = new Set(
     [
       screen.primaryAction?.id,
@@ -292,7 +292,7 @@ function buildUiScreenContract(graph, projection, screen, ownershipFields) {
       state: entry.state || null,
       variant: entry.variant || null
     })),
-    components: componentEntries.map((entry) => buildComponentUsageContract(graph, entry, {
+    widgets: widgetEntries.map((entry) => buildWidgetUsageContract(graph, entry, {
       region: regionContractFor(regionEntries, entry.region)
     })),
     patterns: [...patterns]
@@ -305,18 +305,18 @@ export function buildUiSharedRealization(graph, options = {}) {
 
   if (options.projectionId) {
     const projection = projections[0];
-    const componentUsages = projection.uiComponents || [];
+    const widgetUsages = projection.uiComponents || [];
     const screens = (projection.uiScreens || []).map((screen) => buildUiScreenContract(graph, projection, screen, ownershipFields));
     return {
       projection: {
         id: projection.id,
         name: projection.name || projection.id,
-        platform: projection.platform
+        type: projection.type || projection.platform
       },
       realizes: projection.realizes,
       outputs: projection.outputs,
-      components: buildComponentContractMap(graph, componentUsages),
-      design: buildDesignIntentContract(projection),
+      widgets: buildWidgetContractMap(graph, widgetUsages),
+      designTokens: buildDesignIntentContract(projection),
       appShell: buildAppShellContract(projection),
       navigation: buildNavigationContract(projection, screens),
       screens
@@ -325,18 +325,18 @@ export function buildUiSharedRealization(graph, options = {}) {
 
   const output = {};
   for (const projection of projections) {
-    const componentUsages = projection.uiComponents || [];
+    const widgetUsages = projection.uiComponents || [];
     const screens = (projection.uiScreens || []).map((screen) => buildUiScreenContract(graph, projection, screen, ownershipFields));
     output[projection.id] = {
       projection: {
         id: projection.id,
         name: projection.name || projection.id,
-        platform: projection.platform
+        type: projection.type || projection.platform
       },
       realizes: projection.realizes,
       outputs: projection.outputs,
-      components: buildComponentContractMap(graph, componentUsages),
-      design: buildDesignIntentContract(projection),
+      widgets: buildWidgetContractMap(graph, widgetUsages),
+      designTokens: buildDesignIntentContract(projection),
       appShell: buildAppShellContract(projection),
       navigation: buildNavigationContract(projection, screens),
       screens

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

@@ -26,19 +26,20 @@ export function buildWebRealization(graph, options = {}) {
   }
 
   const projection = getProjection(graph, options.projectionId);
+  const projectionType = projection.type || projection.platform;
   const surfaceHints =
-    projection.platform === "ui_ios" ? projection.uiIos || [] : projection.uiWeb || [];
+    projectionType === "ios_surface" ? projection.uiIos || [] : projection.uiWeb || [];
   const sharedProjection = sharedUiProjectionForWeb(graph, projection);
   const sharedContract = sharedProjection
     ? buildUiSharedRealization(graph, { projectionId: sharedProjection.id })
     : {
-        projection: null,
-        realizes: [],
-        outputs: [],
-        components: {},
-        design: null,
-        screens: []
-      };
+      projection: null,
+      realizes: [],
+      outputs: [],
+      widgets: {},
+      designTokens: null,
+      screens: []
+    };
   const concreteContract = buildUiSharedRealization(graph, { projectionId: projection.id });
 
   const routeMap = new Map((projection.uiRoutes || []).map((entry) => [entry.screenId, entry]));
@@ -59,17 +60,17 @@ export function buildWebRealization(graph, options = {}) {
     }
   }
 
-  const screenMap = new Map((sharedContract.screens || []).map((screen) => [screen.id, { ...screen, components: [...(screen.components || [])] }]));
+  const screenMap = new Map((sharedContract.screens || []).map((screen) => [screen.id, { ...screen, widgets: [...(screen.widgets || [])] }]));
   for (const screen of concreteContract.screens || []) {
     if (!screenMap.has(screen.id)) {
-      screenMap.set(screen.id, { ...screen, components: [...(screen.components || [])] });
+      screenMap.set(screen.id, { ...screen, widgets: [...(screen.widgets || [])] });
       continue;
     }
     const existing = screenMap.get(screen.id);
     screenMap.set(screen.id, {
       ...existing,
       ...screen,
-      components: [...(existing.components || [])],
+      widgets: [...(existing.widgets || [])],
       regions: mergeByKey(existing.regions || [], screen.regions || [], (entry) => entry.region),
       patterns: [...new Set([...(existing.patterns || []), ...(screen.patterns || [])])]
     });
@@ -77,24 +78,26 @@ export function buildWebRealization(graph, options = {}) {
 
   const appShell = projection.uiAppShell?.length || !sharedProjection ? concreteContract.appShell : sharedContract.appShell;
   const navigation = projection.uiNavigation?.length || !sharedProjection ? concreteContract.navigation : sharedContract.navigation;
-  const design = projection.uiDesign?.length || !sharedProjection ? concreteContract.design : sharedContract.design;
+  const designTokens = projection.uiDesign?.length || !sharedProjection ? concreteContract.designTokens : sharedContract.designTokens;
 
   const contract = {
+    type: "ui_surface_contract",
     projection: {
       id: projection.id,
       name: projection.name || projection.id,
-      platform: projection.platform
+      type: projection.type || projection.platform
     },
-    sharedProjection: sharedProjection
+    uiContract: sharedProjection
       ? {
           id: sharedProjection.id,
-          name: sharedProjection.name || sharedProjection.id
+          name: sharedProjection.name || sharedProjection.id,
+          type: sharedProjection.type || sharedProjection.platform
         }
       : null,
     generatorDefaults: generatorDefaultsMap(projection),
     outputs: projection.outputs,
-    components: sharedProjection ? (sharedContract.components || {}) : (concreteContract.components || {}),
-    design: design || null,
+    widgets: sharedProjection ? (sharedContract.widgets || {}) : (concreteContract.widgets || {}),
+    designTokens: designTokens || null,
     appShell: appShell || null,
     navigation: {
       groups: navigation?.groups || [],
@@ -108,8 +111,8 @@ export function buildWebRealization(graph, options = {}) {
     screens: [...screenMap.values()].map((screen) => ({
       ...screen,
       route: routeMap.get(screen.id)?.path || null,
-      web: Object.fromEntries((uiWebByScreen.get(screen.id) || []).map((entry) => [entry.directive, entry.value])),
-      actionWeb: Object.fromEntries(
+      surfaceHints: Object.fromEntries((uiWebByScreen.get(screen.id) || []).map((entry) => [entry.directive, entry.value])),
+      actionSurfaceHints: Object.fromEntries(
         [...screen.actions.screen, screen.actions.primary, screen.actions.secondary, screen.actions.destructive, screen.actions.terminal]
           .filter(Boolean)
           .map((action) => {
@@ -134,7 +137,7 @@ export function buildWebRealization(graph, options = {}) {
     apiContracts[capabilityId] = buildApiRealization(graph, { capabilityId });
   }
 
-  const isNativeUi = projection.platform === "ui_ios";
+  const isNativeUi = projectionType === "ios_surface";
 
   return {
     type: isNativeUi ? "native_ui_realization" : "web_app_realization",

package/src/reconcile/journeys.js

@@ -40,7 +40,7 @@ function collectJourneyGenerationContext(graph) {
   const rules = graph.byKind.rule || [];
   const projections = graph.byKind.projection || [];
   const uiSharedScreens = projections
-    .filter((projection) => projection.platform === "ui_shared")
+    .filter((projection) => projection.platform === "ui_contract")
     .flatMap((projection) => (projection.uiScreens || []).map((screen) => ({ ...screen, projectionId: projection.id })));
   const canonicalJourneys = (graph.docs || []).filter((doc) => doc.kind === "journey");
   const coveredEntityIds = new Set(canonicalJourneys.flatMap((doc) => doc.relatedEntities || []));