@topogram/cli 0.3.48 → 0.3.50

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

@@ -1,6 +1,7 @@
 // @ts-check
 
-import { getProjection } from "../shared.js";
+import { buildWebRealization } from "../../../realization/ui/index.js";
+import { buildDesignIntentCoverage, renderDesignIntentCss } from "./design-intent.js";
 
 function slugify(value) {
   return String(value || "page")
@@ -9,14 +10,8 @@ function slugify(value) {
     .replace(/^-+|-+$/g, "") || "page";
 }
 
-function titleForScreen(graph, screenId) {
-  for (const projection of graph.byKind.projection || []) {
-    const screen = (projection.uiScreens || []).find((entry) => entry.id === screenId);
-    if (screen?.title) {
-      return screen.title;
-    }
-  }
-  return screenId
+function titleForScreen(screenId) {
+  return String(screenId || "page")
     .split(/[_\-\s]+/)
     .filter(Boolean)
     .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
@@ -55,10 +50,12 @@ ${body}
 `;
 }
 
-function renderStyles() {
-  return `:root {
-  color: #182026;
-  background: #f6f8fb;
+function renderStyles(design) {
+  return `${renderDesignIntentCss(design)}
+
+:root {
+  color: var(--topogram-text-color);
+  background: var(--topogram-surface-background);
   font-family: Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
 }
 
@@ -70,14 +67,14 @@ body {
   display: flex;
   align-items: center;
   justify-content: space-between;
-  gap: 1rem;
+  gap: var(--topogram-space-unit);
   padding: 1rem 1.25rem;
-  border-bottom: 1px solid #d8e0ea;
-  background: #ffffff;
+  border-bottom: 1px solid var(--topogram-border-color);
+  background: var(--topogram-surface-card);
 }
 
 .brand {
-  color: #182026;
+  color: var(--topogram-text-color);
   font-weight: 700;
   text-decoration: none;
 }
@@ -89,27 +86,32 @@ nav {
 }
 
 nav a {
-  color: #0f5cc0;
+  color: var(--topogram-action-primary-background);
   text-decoration: none;
 }
 
 main {
   display: grid;
-  gap: 1rem;
+  gap: var(--topogram-space-unit);
   max-width: 56rem;
   margin: 0 auto;
-  padding: 2rem 1.25rem 4rem;
+  padding: var(--topogram-page-padding);
 }
 
 .panel {
-  border: 1px solid #d8e0ea;
-  border-radius: 8px;
-  background: #ffffff;
+  border: 1px solid var(--topogram-border-color);
+  border-radius: var(--topogram-radius-card);
+  background: var(--topogram-surface-card);
   padding: 1.25rem;
 }
 
 .muted {
-  color: #607284;
+  color: var(--topogram-muted-color);
+}
+
+a:focus-visible {
+  outline: var(--topogram-focus-outline);
+  outline-offset: 2px;
 }
 `;
 }
@@ -158,6 +160,67 @@ console.log(\`Checked \${htmlFiles.length} vanilla page(s).\`);
 `;
 }
 
+function buildVanillaGenerationCoverage(contract, files, routes) {
+  const diagnostics = [];
+  const designIntent = buildDesignIntentCoverage(contract, files, "styles.css");
+  diagnostics.push(...designIntent.diagnostics);
+  const screens = routes.map((route) => {
+    const contents = files[route.file] || "";
+    const rendered = Boolean(contents);
+    if (!rendered) {
+      diagnostics.push({
+        code: "screen_route_not_rendered",
+        severity: "error",
+        screen: route.screenId,
+        route: route.path,
+        message: `Screen '${route.screenId}' has route '${route.path}' but no vanilla HTML page was generated.`,
+        suggested_fix: "Check the vanilla web generator route emission for this screen."
+      });
+    }
+    return {
+      id: route.screenId,
+      route: route.path,
+      page: route.file,
+      rendered,
+      renderer: rendered ? "generator" : "missing",
+      component_usages: []
+    };
+  });
+  return {
+    type: "generation_coverage",
+    surface: "web",
+    generator: "topogram/vanilla-web",
+    projection: {
+      id: contract.projection.id,
+      name: contract.projection.name,
+      platform: contract.projection.platform
+    },
+    summary: {
+      routed_screens: screens.length,
+      rendered_screens: screens.filter((screen) => screen.rendered).length,
+      implementation_screens: 0,
+      generator_screens: screens.filter((screen) => screen.renderer === "generator").length,
+      component_usages: 0,
+      rendered_component_usages: 0,
+      diagnostics: diagnostics.length,
+      errors: diagnostics.filter((diagnostic) => diagnostic.severity === "error").length,
+      warnings: diagnostics.filter((diagnostic) => diagnostic.severity === "warning").length
+    },
+    design_intent: designIntent.coverage,
+    screens,
+    diagnostics
+  };
+}
+
+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(`Vanilla web generation coverage failed: ${details}`);
+}
+
 function renderDevScript() {
   return `import http from "node:http";
 import fs from "node:fs";
@@ -192,20 +255,19 @@ http.createServer((req, res) => {
 }
 
 export function generateVanillaWebApp(graph, options = {}) {
-  const projection = getProjection(graph, options.projectionId);
-  const routeEntries = projection.uiRoutes?.length
-    ? projection.uiRoutes
-    : [{ screenId: "home", path: "/" }];
-  const routes = routeEntries.map((route) => ({
-    screenId: route.screenId,
-    path: route.path,
-    title: titleForScreen(graph, route.screenId),
-    file: routeFileName(route.path)
+  const realization = buildWebRealization(graph, options);
+  const contract = realization.contract;
+  const routeScreens = (contract.screens || []).filter((screen) => Boolean(screen.route));
+  const routes = (routeScreens.length > 0 ? routeScreens : [{ id: "home", route: "/", title: "Home" }]).map((screen) => ({
+    screenId: screen.id,
+    path: screen.route || "/",
+    title: screen.title || titleForScreen(screen.id),
+    file: routeFileName(screen.route || "/")
   }));
   const nav = routes.map(({ title, file }) => ({ title, file }));
   const files = {
     "package.json": `${JSON.stringify({
-      name: projection.id,
+      name: contract.projection.id,
       private: true,
       version: "0.1.0",
       type: "module",
@@ -215,7 +277,7 @@ export function generateVanillaWebApp(graph, options = {}) {
         check: "node ./scripts/check.mjs"
       }
     }, null, 2)}\n`,
-    "styles.css": renderStyles(),
+    "styles.css": renderStyles(contract.design),
     "app.js": renderBrowserScript(),
     "scripts/build.mjs": renderBuildScript(),
     "scripts/check.mjs": renderCheckScript(),
@@ -229,11 +291,15 @@ export function generateVanillaWebApp(graph, options = {}) {
       body: `      <section class="panel">
         <p class="muted">Page ${index + 1} of ${routes.length}</p>
         <h1>${route.title}</h1>
-        <p>This page was generated from the <code>${projection.id}</code> Topogram web projection.</p>
+        <p>This page was generated from the <code>${contract.projection.id}</code> Topogram web projection.</p>
         <p class="muted">Generated timestamp: <span data-generated-at>pending</span></p>
       </section>`
     });
   });
 
+  const coverage = buildVanillaGenerationCoverage(contract, files, routes);
+  assertGenerationCoverage(coverage);
+  files["topogram/generation-coverage.json"] = `${JSON.stringify(coverage, null, 2)}\n`;
+  files["topogram/ui-web-contract.json"] = `${JSON.stringify(contract, null, 2)}\n`;
   return files;
 }

package/src/import/core/runner.js

@@ -2,6 +2,9 @@ import { IMPORT_TRACKS } from "./contracts.js";
 import { dedupeCandidateRecords, ensureTrailingNewline, idHintify, makeCandidateRecord } from "./shared.js";
 import { createImportContext } from "./context.js";
 import { getEnrichersForTrack, getExtractorsForTrack } from "./registry.js";
+import {
+  collectionPatternFromPresentations
+} from "../../ui/taxonomy.js";
 
 function parseImportTracks(fromValue) {
   if (!fromValue) {
@@ -95,25 +98,6 @@ function selectDetectionsForTrack(track, detections) {
   return detections;
 }
 
-function collectionPatternFromPresentations(presentations) {
-  if (presentations.includes("data_grid")) return "data_grid_view";
-  if (presentations.includes("table")) return "resource_table";
-  if (presentations.includes("cards")) return "resource_cards";
-  if (presentations.includes("board")) return "board_view";
-  if (presentations.includes("calendar")) return "calendar_view";
-  if (presentations.includes("gallery")) return "resource_cards";
-  return "search_results";
-}
-
-function presentationFromPattern(pattern) {
-  if (pattern === "data_grid_view") return "data_grid";
-  if (pattern === "resource_table") return "table";
-  if (pattern === "resource_cards") return "cards";
-  if (pattern === "board_view") return "board";
-  if (pattern === "calendar_view") return "calendar";
-  return "list";
-}
-
 function importedApiCapabilityIds(allCandidates) {
   return [...(allCandidates?.api?.capabilities || [])]
     .map((capability) => capability.id_hint)
@@ -181,6 +165,17 @@ function deriveUiComponentCandidates(candidates) {
       pattern,
       data_prop: "rows",
       data_source: loadCapability,
+      inferred_props: [{ name: "rows", type: "array", required: true, source: loadCapability }],
+      inferred_events: [],
+      inferred_region: "results",
+      inferred_pattern: pattern,
+      evidence: screen.provenance || [],
+      missing_decisions: [
+        "confirm component reuse boundary",
+        "confirm prop names and data source",
+        "confirm events and behavior",
+        "confirm supported regions and patterns"
+      ],
       notes: [
         "Imported component candidates are review-only.",
         "Confirm props, behavior, events, and reuse before adoption."
@@ -294,8 +289,11 @@ function reportMarkdown(track, candidates) {
     );
   }
   if (track === "ui") {
+    const componentLines = (candidates.components || []).map((component) =>
+      `- \`${component.id_hint}\` confidence ${component.confidence || "unknown"} pattern \`${component.pattern || component.inferred_pattern || "unknown"}\` region \`${component.region || component.inferred_region || "unknown"}\` evidence ${(component.evidence || component.provenance || []).length} missing decisions ${(component.missing_decisions || []).length}`
+    );
     return ensureTrailingNewline(
-      `# UI Import Report\n\n- Screens: ${candidates.screens.length}\n- Routes: ${candidates.routes.length}\n- Actions: ${candidates.actions.length}\n- Components: ${candidates.components.length}\n- Stacks: ${candidates.stacks.length ? candidates.stacks.join(", ") : "none"}\n`
+      `# UI Import Report\n\n- Screens: ${candidates.screens.length}\n- Routes: ${candidates.routes.length}\n- Actions: ${candidates.actions.length}\n- Components: ${candidates.components.length}\n- Stacks: ${candidates.stacks.length ? candidates.stacks.join(", ") : "none"}\n\n## Component Candidates\n\n${componentLines.length ? componentLines.join("\n") : "- none"}\n\n## Next Validation\n\n- Review candidates under \`topogram/candidates/app/ui/drafts/components/**\`.\n- Run \`topogram import plan <path>\` before adoption.\n- After adoption, run \`topogram check <path>\`, \`topogram component check <path>\`, and \`topogram component behavior <path>\`.\n`
     );
   }
   if (track === "verification") {
@@ -327,7 +325,15 @@ function componentCandidateFileName(component) {
 }
 
 function renderComponentCandidate(component) {
+  const evidenceCount = (component.evidence || component.provenance || []).length;
+  const missingDecisions = component.missing_decisions || [
+    "confirm component reuse boundary",
+    "confirm prop names and data source",
+    "confirm events and behavior"
+  ];
   return `component ${component.id_hint} {
+  # Import metadata: confidence ${component.confidence || "unknown"}; evidence ${evidenceCount}; inferred pattern ${component.pattern || component.inferred_pattern || "search_results"}; inferred region ${component.region || component.inferred_region || "results"}.
+  # Missing decisions: ${missingDecisions.join("; ")}.
   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
@@ -353,6 +359,26 @@ function uiComponentLinesForCandidates(componentCandidates, allCandidates) {
     });
 }
 
+function enrichUiComponentDataSources(uiCandidates, allCandidates) {
+  if (!uiCandidates || !Array.isArray(uiCandidates.components)) {
+    return uiCandidates;
+  }
+  return {
+    ...uiCandidates,
+    components: uiCandidates.components.map((component) => {
+      const dataSource = inferredDataSourceForComponent(component, allCandidates);
+      const dataProp = component.data_prop || "rows";
+      return {
+        ...component,
+        data_source: component.data_source || dataSource,
+        inferred_props: (component.inferred_props || []).map((prop) =>
+          prop.name === dataProp ? { ...prop, source: prop.source || dataSource } : prop
+        )
+      };
+    })
+  };
+}
+
 function draftUiProjectionFiles(context, candidates, allCandidates = {}) {
   const ui = candidates || { screens: [], routes: [], actions: [], stacks: [] };
   const screens = [...(ui.screens || [])].sort((a, b) => String(a.route_path || "").localeCompare(String(b.route_path || "")) || a.id_hint.localeCompare(b.id_hint));
@@ -477,6 +503,20 @@ ${capabilityHints.length > 0 ? capabilityHints.map((hint) => `    ${hint}`).join
     shell ${shell}
 ${presentations.includes("search") ? "    global_search true\n" : ""}${presentations.includes("multi_window") ? "    windowing multi_window\n" : ""}  }
 
+  ui_design {
+    density comfortable
+    tone operational
+    radius_scale medium
+    color_role primary accent
+    color_role danger critical
+    typography_role body readable
+    typography_role heading prominent
+    action_role primary prominent
+    action_role destructive danger
+    accessibility contrast aa
+    accessibility focus visible
+  }
+
   ui_screens {
 ${uiScreensBlock}
   }
@@ -616,6 +656,9 @@ export function runImportApp(inputPath, options = {}) {
   }
 
   if (candidates.ui) {
+    candidates.ui = enrichUiComponentDataSources(candidates.ui, candidates);
+    files["candidates/app/ui/candidates.json"] = `${JSON.stringify(candidates.ui, null, 2)}\n`;
+    files["candidates/app/ui/report.md"] = reportMarkdown("ui", candidates.ui);
     Object.assign(files, draftUiProjectionFiles(context, candidates.ui, candidates));
   }
 

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

@@ -1,5 +1,6 @@
 import { getProjection, uiProjectionCandidates } from "../../generator/surfaces/shared.js";
 import { buildComponentBehaviorRealizations } from "../../component-behavior.js";
+import { defaultPatternForScreen } from "../../ui/taxonomy.js";
 
 function toBooleanFlag(value, fallback = false) {
   if (value === "true") return true;
@@ -47,21 +48,6 @@ function ownershipFieldByCapability(graph) {
   return output;
 }
 
-function deriveDefaultPattern(screen, collectionEntries) {
-  if (screen.kind === "detail") return "detail_panel";
-  if (screen.kind === "form") return "edit_form";
-  if (screen.kind === "board") return "board_view";
-  if (screen.kind === "calendar") return "calendar_view";
-  if (screen.kind === "dashboard" || screen.kind === "analytics" || screen.kind === "report") return "summary_stats";
-  if (screen.kind === "feed" || screen.kind === "inbox") return "activity_feed";
-  const view = collectionEntries.find((entry) => entry.operation === "view")?.value;
-  if (view === "data_grid") return "data_grid_view";
-  if (view === "table") return "resource_table";
-  if (view === "cards" || view === "gallery") return "resource_cards";
-  if (screen.kind === "list") return "resource_table";
-  return null;
-}
-
 function componentById(graph, componentId) {
   return (graph.byKind.component || []).find((component) => component.id === componentId) || null;
 }
@@ -88,6 +74,50 @@ function regionContractFor(regionEntries, regionName) {
   return (regionEntries || []).find((entry) => entry.region === regionName) || null;
 }
 
+function buildDesignIntentContract(projection) {
+  const design = {
+    density: "comfortable",
+    tone: "operational",
+    radiusScale: "medium",
+    colorRoles: {},
+    typographyRoles: {},
+    actionRoles: {},
+    accessibility: {}
+  };
+
+  for (const entry of projection.uiDesign || []) {
+    if (entry.key === "density" && entry.role) {
+      design.density = entry.role;
+      continue;
+    }
+    if (entry.key === "tone" && entry.role) {
+      design.tone = entry.role;
+      continue;
+    }
+    if (entry.key === "radius_scale" && entry.role) {
+      design.radiusScale = entry.role;
+      continue;
+    }
+    if (entry.key === "color_role" && entry.role && entry.value) {
+      design.colorRoles[entry.role] = entry.value;
+      continue;
+    }
+    if (entry.key === "typography_role" && entry.role && entry.value) {
+      design.typographyRoles[entry.role] = entry.value;
+      continue;
+    }
+    if (entry.key === "action_role" && entry.role && entry.value) {
+      design.actionRoles[entry.role] = entry.value;
+      continue;
+    }
+    if (entry.key === "accessibility" && entry.role && entry.value) {
+      design.accessibility[entry.role] = entry.value;
+    }
+  }
+
+  return design;
+}
+
 export function buildComponentUsageContract(graph, entry, options = {}) {
   const componentId = entry.component?.id || null;
   const contract = componentId ? componentContractFor(graph, componentId) : null;
@@ -184,7 +214,7 @@ function buildUiScreenContract(graph, projection, screen, ownershipFields) {
   );
   const visibilityEntries = (projection.uiVisibility || []).filter((entry) => screenActionIds.has(entry.capability?.id));
   const patterns = new Set(regionEntries.map((entry) => entry.pattern).filter(Boolean));
-  const derivedDefaultPattern = deriveDefaultPattern(screen, collectionEntries);
+  const derivedDefaultPattern = defaultPatternForScreen(screen, collectionEntries);
   if (derivedDefaultPattern) {
     patterns.add(derivedDefaultPattern);
   }
@@ -286,6 +316,7 @@ export function buildUiSharedRealization(graph, options = {}) {
       realizes: projection.realizes,
       outputs: projection.outputs,
       components: buildComponentContractMap(graph, componentUsages),
+      design: buildDesignIntentContract(projection),
       appShell: buildAppShellContract(projection),
       navigation: buildNavigationContract(projection, screens),
       screens
@@ -305,6 +336,7 @@ export function buildUiSharedRealization(graph, options = {}) {
       realizes: projection.realizes,
       outputs: projection.outputs,
       components: buildComponentContractMap(graph, componentUsages),
+      design: buildDesignIntentContract(projection),
       appShell: buildAppShellContract(projection),
       navigation: buildNavigationContract(projection, screens),
       screens

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

@@ -1,8 +1,6 @@
 import { buildApiRealization } from "../api/index.js";
 import { generatorDefaultsMap, getProjection, sharedUiProjectionForWeb } from "../../generator/surfaces/shared.js";
 import {
-  buildComponentContractMap,
-  buildComponentUsageContract,
   buildUiSharedRealization
 } from "./build-ui-shared-realization.js";
 
@@ -38,6 +36,7 @@ export function buildWebRealization(graph, options = {}) {
         realizes: [],
         outputs: [],
         components: {},
+        design: null,
         screens: []
       };
   const concreteContract = buildUiSharedRealization(graph, { projectionId: projection.id });
@@ -70,30 +69,15 @@ export function buildWebRealization(graph, options = {}) {
     screenMap.set(screen.id, {
       ...existing,
       ...screen,
-      components: [...(existing.components || []), ...(screen.components || [])],
+      components: [...(existing.components || [])],
       regions: mergeByKey(existing.regions || [], screen.regions || [], (entry) => entry.region),
       patterns: [...new Set([...(existing.patterns || []), ...(screen.patterns || [])])]
     });
   }
-  for (const entry of projection.uiComponents || []) {
-    if (!screenMap.has(entry.screenId)) {
-      continue;
-    }
-    const screen = screenMap.get(entry.screenId);
-    if ((screen.components || []).some((usage) => componentUsageFingerprint(usage) === componentUsageFingerprintFromEntry(entry))) {
-      continue;
-    }
-    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;
   const navigation = projection.uiNavigation?.length || !sharedProjection ? concreteContract.navigation : sharedContract.navigation;
-  const componentContracts = {
-    ...(sharedContract.components || {}),
-    ...buildComponentContractMap(graph, projection.uiComponents || [])
-  };
+  const design = projection.uiDesign?.length || !sharedProjection ? concreteContract.design : sharedContract.design;
 
   const contract = {
     projection: {
@@ -109,7 +93,8 @@ export function buildWebRealization(graph, options = {}) {
       : null,
     generatorDefaults: generatorDefaultsMap(projection),
     outputs: projection.outputs,
-    components: componentContracts,
+    components: sharedProjection ? (sharedContract.components || {}) : (concreteContract.components || {}),
+    design: design || null,
     appShell: appShell || null,
     navigation: {
       groups: navigation?.groups || [],
@@ -171,21 +156,3 @@ function mergeByKey(left, right, keyFn) {
   for (const entry of right) output.set(keyFn(entry), { ...(output.get(keyFn(entry)) || {}), ...entry });
   return [...output.values()];
 }
-
-function componentUsageFingerprint(usage) {
-  return [
-    usage?.region || "",
-    usage?.component?.id || "",
-    ...(usage?.dataBindings || []).map((binding) => `data:${binding.prop}:${binding.source?.id || ""}`),
-    ...(usage?.eventBindings || []).map((binding) => `event:${binding.event}:${binding.action}:${binding.target?.id || ""}`)
-  ].join("|");
-}
-
-function componentUsageFingerprintFromEntry(entry) {
-  return [
-    entry?.region || "",
-    entry?.component?.id || "",
-    ...(entry?.dataBindings || []).map((binding) => `data:${binding.prop}:${binding.source?.id || ""}`),
-    ...(entry?.eventBindings || []).map((binding) => `event:${binding.event}:${binding.action}:${binding.target?.id || ""}`)
-  ].join("|");
-}

package/src/resolver/index.js

@@ -503,6 +503,7 @@ function buildProjectionPlan(statement) {
     uiVisibility: statement.uiVisibility,
     uiRoutes: statement.uiRoutes,
     uiWeb: statement.uiWeb,
+    uiDesign: statement.uiDesign,
     uiComponents: statement.uiComponents,
     dbTables: statement.dbTables,
     dbColumns: statement.dbColumns,
@@ -1269,6 +1270,17 @@ function parseProjectionUiAppShellBlock(statement) {
   }));
 }
 
+function parseProjectionUiDesignBlock(statement) {
+  return blockEntries(getFieldValue(statement, "ui_design")).map((entry) => ({
+    type: "ui_design_token",
+    key: tokenValue(entry.items[0]) || null,
+    role: tokenValue(entry.items[1]) || null,
+    value: tokenValue(entry.items[2]) || null,
+    raw: normalizeSequence(entry.items),
+    loc: entry.loc
+  }));
+}
+
 function parseProjectionUiNavigationBlock(statement) {
   return blockEntries(getFieldValue(statement, "ui_navigation")).map((entry) => {
     const directives = {};
@@ -1869,6 +1881,7 @@ export function normalizeStatement(statement, registry) {
         uiWeb: parseProjectionUiWebBlock(statement, registry),
         uiIos: parseProjectionUiIosBlock(statement, registry),
         uiAppShell: parseProjectionUiAppShellBlock(statement),
+        uiDesign: parseProjectionUiDesignBlock(statement),
         uiNavigation: parseProjectionUiNavigationBlock(statement),
         uiScreenRegions: parseProjectionUiScreenRegionsBlock(statement),
         uiComponents: parseProjectionUiComponentsBlock(statement, registry),