@topogram/cli 0.3.63 → 0.3.65

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

@@ -5,6 +5,7 @@ import {
   renderReactWidgetRegion
 } from "./react-widgets.js";
 import { buildDesignIntentCoverage, renderDesignIntentCss } from "./design-intent.js";
+import { escapeAttr, escapeHtml } from "./html-escape.js";
 import { renderApiClientModule, renderLookupModule, renderVisibilityModule } from "./shared.js";
 
 function componentNameForScreen(screenId) {
@@ -309,25 +310,26 @@ function assertGenerationCoverage(coverage) {
 function buildAppTsx(contract, webReference) {
   const navLinks = resolveNavLinks(contract, webReference);
   const brandName = contract.appShell?.brand || webReference.brandName;
+  const safeBrandName = escapeHtml(brandName);
   const footerEnabled = contract.appShell?.footer && contract.appShell.footer !== "none";
   const shellMode = contract.appShell?.shell || "topbar";
   const windowingMode = contract.appShell?.windowing || "single_window";
   const navigationPatterns = (contract.navigation?.patterns || []).join(" ");
   const hasCommandPalette = (contract.navigation?.patterns || []).includes("command_palette");
-  const navItems = navLinks.map((link) => `            <Link to="${link.route}">${link.label}</Link>`).join("\n");
+  const navItems = navLinks.map((link) => `            <Link to="${escapeAttr(link.route)}">${escapeHtml(link.label)}</Link>`).join("\n");
   const routeScreens = contract.screens.filter((screen) => screen.route && componentNameForScreen(screen.id) !== "EditorialSettingsPage");
   const importLines = routeScreens
     .map((screen) => `import { ${componentNameForScreen(screen.id)} } from "./pages/${componentNameForScreen(screen.id)}";`)
     .join("\n");
   const routeLines = routeScreens
-    .map((screen) => `            <Route path="${screen.route}" element={<${componentNameForScreen(screen.id)} />} />`)
+    .map((screen) => `            <Route path="${escapeAttr(screen.route)}" element={<${componentNameForScreen(screen.id)} />} />`)
     .join("\n");
 
   const shellFrame =
     shellMode === "split_view"
       ? `        <div className="app-workspace">
           <aside className="app-sidebar">
-            <Link className="brand" to="/">${brandName}</Link>
+            <Link className="brand" to="/">${safeBrandName}</Link>
             <nav className="app-nav-links">
 ${navItems}
             </nav>
@@ -335,7 +337,7 @@ ${hasCommandPalette ? `            <button className="command-palette-button" ty
           </aside>
           <div className="app-main-shell">
             <header className="app-nav compact">
-              <div className="brand-mark">${brandName}</div>
+              <div className="brand-mark">${safeBrandName}</div>
 ${hasCommandPalette ? `              <button className="command-palette-button" type="button">Command Palette</button>` : ""}
             </header>
             <main>
@@ -348,7 +350,7 @@ ${routeLines}
         </div>`
       : shellMode === "bottom_tabs"
         ? `        <header className="app-nav">
-          <Link className="brand" to="/">${brandName}</Link>
+          <Link className="brand" to="/">${safeBrandName}</Link>
 ${hasCommandPalette ? `          <button className="command-palette-button" type="button">Command Palette</button>` : ""}
         </header>
         <main>
@@ -361,7 +363,7 @@ ${routeLines}
 ${navItems}
         </nav>`
         : `        <header className="app-nav${shellMode === "menu_bar" ? " menu-bar" : ""}">
-          <Link className="brand" to="/">${brandName}</Link>
+          <Link className="brand" to="/">${safeBrandName}</Link>
           <nav className="app-nav-links">
 ${navItems}
           </nav>
@@ -381,7 +383,7 @@ ${importLines}
 export default function App() {
   return (
     <BrowserRouter>
-      <div className="app-shell" data-shell="${shellMode}" data-windowing="${windowingMode}" data-navigation-patterns="${navigationPatterns}">
+      <div className="app-shell" data-shell="${escapeAttr(shellMode)}" data-windowing="${escapeAttr(windowingMode)}" data-navigation-patterns="${escapeAttr(navigationPatterns)}">
 ${shellFrame}
 ${footerEnabled ? `        <footer className="app-footer">
           <span>Generated from Topogram</span>
@@ -463,7 +465,7 @@ export default defineConfig({
   <head>
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <title>${webReference.brandName}</title>
+    <title>${escapeHtml(webReference.brandName)}</title>
   </head>
   <body>
     <div id="root"></div>

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

@@ -3,6 +3,7 @@ import { lookupRouteSegment } from "../services/runtime-helpers.js";
 import { getExampleImplementation } from "../../../example-implementation.js";
 import { renderApiClientModule, renderLookupModule, renderVisibilityModule } from "./shared.js";
 import { buildDesignIntentCoverage, renderDesignIntentCss } from "./design-intent.js";
+import { escapeAttr, escapeHtml } from "./html-escape.js";
 import {
   renderSvelteKitWidgetRegion,
   svelteKitWidgetUsageSupport
@@ -324,6 +325,7 @@ function buildSvelteKitScaffold(contract, apiContracts, options = {}) {
   const files = {};
 
   const brandName = contract.appShell?.brand || webReference.brandName;
+  const safeBrandName = escapeHtml(brandName);
   const navLinks = resolveNavLinks(contract, webReference);
   const footerEnabled = contract.appShell?.footer && contract.appShell.footer !== "none";
   const shellMode = contract.appShell?.shell || "topbar";
@@ -384,14 +386,14 @@ function buildSvelteKitScaffold(contract, apiContracts, options = {}) {
   files["src/app.css"] =
     `${renderDesignIntentCss(contract.designTokens)}\n` +
     ":root {\n  font-family: system-ui, sans-serif;\n  color: var(--topogram-text-color);\n  background: var(--topogram-surface-background);\n}\nbody {\n  margin: 0;\n}\na {\n  color: var(--topogram-action-primary-background);\n  text-decoration: none;\n}\na:hover {\n  text-decoration: underline;\n}\nmain {\n  max-width: 72rem;\n  margin: 0 auto;\n  padding: var(--topogram-page-padding);\n}\n.app-shell {\n  min-height: 100vh;\n}\n.app-workspace {\n  display: grid;\n  grid-template-columns: 18rem minmax(0, 1fr);\n  min-height: 100vh;\n}\n.app-main-shell {\n  min-width: 0;\n}\n.app-sidebar {\n  position: sticky;\n  top: 0;\n  align-self: start;\n  min-height: 100vh;\n  display: grid;\n  align-content: start;\n  gap: var(--topogram-space-unit);\n  padding: 1.25rem 1rem;\n  border-right: 1px solid rgba(24, 32, 38, 0.08);\n  background: rgba(255, 255, 255, 0.86);\n  backdrop-filter: blur(12px);\n}\n.app-nav {\n  position: sticky;\n  top: 0;\n  z-index: 10;\n  display: flex;\n  align-items: center;\n  justify-content: space-between;\n  gap: var(--topogram-space-unit);\n  padding: 1rem 1.25rem;\n  border-bottom: 1px solid rgba(24, 32, 38, 0.08);\n  background: rgba(255, 255, 255, 0.9);\n  backdrop-filter: blur(12px);\n}\n.app-nav-links,\n.app-nav nav,\n.app-tabbar {\n  display: flex;\n  gap: 0.75rem;\n  flex-wrap: wrap;\n}\n.app-nav.menu-bar {\n  border-bottom-style: dashed;\n}\n.app-nav.compact {\n  justify-content: flex-end;\n}\n.app-tabbar {\n  position: sticky;\n  bottom: 0;\n  z-index: 10;\n  justify-content: space-around;\n  padding: 0.85rem 1rem calc(0.85rem + env(safe-area-inset-bottom, 0px));\n  border-top: 1px solid rgba(24, 32, 38, 0.08);\n  background: rgba(255, 255, 255, 0.92);\n  backdrop-filter: blur(12px);\n}\n.brand {\n  font-weight: 700;\n  letter-spacing: 0.01em;\n}\n.brand-mark {\n  font-weight: 700;\n  color: var(--topogram-muted-color);\n}\n.command-palette-button {\n  background: var(--topogram-text-color);\n  color: white;\n  border: none;\n  border-radius: var(--topogram-radius-pill);\n  padding: var(--topogram-control-padding);\n  font: inherit;\n  cursor: pointer;\n}\n.app-footer {\n  max-width: 72rem;\n  margin: 0 auto;\n  padding: 0 1.25rem 2rem;\n  color: var(--topogram-muted-color);\n}\n.card {\n  background: var(--topogram-surface-card);\n  border-radius: var(--topogram-radius-card);\n  padding: 1.25rem;\n  box-shadow: 0 12px 30px rgba(24, 32, 38, 0.08);\n}\n.hero {\n  display: grid;\n  gap: var(--topogram-space-unit);\n}\n.grid {\n  display: grid;\n  gap: var(--topogram-space-unit);\n}\n.grid.two {\n  grid-template-columns: repeat(auto-fit, minmax(16rem, 1fr));\n}\n.filters {\n  display: grid;\n  gap: 0.75rem;\n  grid-template-columns: repeat(auto-fit, minmax(12rem, 1fr));\n  margin: 1rem 0 1.25rem;\n}\nlabel {\n  display: grid;\n  gap: 0.35rem;\n  font-size: 0.95rem;\n}\ninput,\ntextarea,\nbutton,\nselect {\n  font: inherit;\n}\ninput,\ntextarea,\nselect {\n  width: 100%;\n  box-sizing: border-box;\n  border: 1px solid #c9d4e2;\n  border-radius: var(--topogram-radius-control);\n  padding: var(--topogram-control-padding);\n  background: white;\n}\ntextarea {\n  min-height: 8rem;\n  resize: vertical;\n}\nbutton,\n.button-link {\n  display: inline-flex;\n  align-items: center;\n  justify-content: center;\n  gap: 0.35rem;\n  border: none;\n  border-radius: var(--topogram-radius-pill);\n  padding: var(--topogram-control-padding);\n  background: var(--topogram-action-primary-background);\n  color: var(--topogram-action-primary-color);\n  font-weight: 600;\n  cursor: pointer;\n}\nbutton:focus-visible,\n.button-link:focus-visible,\na:focus-visible,\ninput:focus-visible,\ntextarea:focus-visible,\nselect:focus-visible {\n  outline: var(--topogram-focus-outline);\n  outline-offset: 2px;\n}\n.button-link.secondary {\n  background: #e9eef6;\n  color: var(--topogram-text-color);\n}\n.button-row {\n  display: flex;\n  gap: 0.75rem;\n  flex-wrap: wrap;\n  align-items: center;\n}\n.stack {\n  display: grid;\n  gap: var(--topogram-space-unit);\n}\n\n.resource-list {\n  list-style: none;\n  padding: 0;\n  margin: 1rem 0 0;\n  display: grid;\n  gap: 0.75rem;\n}\n\n.resource-list li {\n  display: flex;\n  justify-content: space-between;\n  align-items: flex-start;\n  gap: var(--topogram-space-unit);\n  padding: 1rem;\n  border: 1px solid #e0e8f1;\n  border-radius: var(--topogram-radius-card);\n  background: var(--topogram-surface-subtle);\n}\n.table-wrap {\n  margin-top: 1rem;\n  overflow-x: auto;\n  border: 1px solid var(--topogram-border-color);\n  border-radius: var(--topogram-radius-card);\n  background: white;\n}\n.resource-table {\n  width: 100%;\n  border-collapse: collapse;\n  min-width: 42rem;\n}\n.resource-table th,\n.resource-table td {\n  padding: 0.85rem 1rem;\n  text-align: left;\n  border-bottom: 1px solid #e7edf5;\n  vertical-align: top;\n}\n.resource-table th {\n  font-size: 0.85rem;\n  letter-spacing: 0.04em;\n  text-transform: uppercase;\n  color: #516173;\n  background: #f8fbff;\n}\n.resource-table tbody tr:hover {\n  background: #fbfdff;\n}\n.data-grid {\n  min-width: 64rem;\n  font-size: 0.95rem;\n}\n.data-grid thead th {\n  position: sticky;\n  top: 0;\n  z-index: 1;\n  background: #eef5ff;\n}\n.data-grid-shell {\n  box-shadow: inset 0 0 0 1px rgba(15, 92, 192, 0.04);\n}\n.cell-stack,\n.resource-meta,\n.definition-list {\n  display: grid;\n  gap: 0.5rem;\n}\n.cell-secondary {\n  color: var(--topogram-muted-color);\n  font-size: 0.92rem;\n}\n.definition-list {\n  grid-template-columns: minmax(8rem, 12rem) 1fr;\n  align-items: start;\n}\n.definition-list dt {\n  font-weight: 600;\n  color: #516173;\n}\n.definition-list dd {\n  margin: 0;\n}\n.badge {\n  display: inline-flex;\n  align-items: center;\n  padding: 0.25rem 0.6rem;\n  border-radius: var(--topogram-radius-pill);\n  background: #eef4ff;\n  color: var(--topogram-action-primary-background);\n  font-size: 0.85rem;\n  font-weight: 600;\n}\n.muted {\n  color: var(--topogram-muted-color);\n}\n.empty-state {\n  padding: 1rem 0;\n}\n.widget-card {\n  border: 1px solid var(--topogram-border-color);\n  border-radius: var(--topogram-radius-card);\n  background: var(--topogram-surface-subtle);\n  padding: 1rem;\n  margin-top: 1rem;\n}\n.widget-header {\n  display: flex;\n  align-items: center;\n  justify-content: space-between;\n  gap: var(--topogram-space-unit);\n  flex-wrap: wrap;\n}\n.widget-eyebrow {\n  margin: 0 0 0.25rem;\n  color: var(--topogram-muted-color);\n  font-size: 0.75rem;\n  font-weight: 700;\n  letter-spacing: 0.08em;\n  text-transform: uppercase;\n}\n.widget-card h2,\n.widget-card h3 {\n  margin: 0;\n}\n.widget-table-wrap {\n  margin-top: 1rem;\n}\n.summary-grid {\n  display: grid;\n  grid-template-columns: repeat(auto-fit, minmax(8rem, 1fr));\n  gap: 0.75rem;\n}\n.summary-grid div,\n.board-column {\n  border: 1px solid #e0e8f1;\n  border-radius: var(--topogram-radius-control);\n  background: white;\n  padding: 0.85rem;\n}\n.summary-grid strong {\n  display: block;\n  font-size: 1.5rem;\n}\n.summary-grid span,\n.calendar-list span {\n  color: var(--topogram-muted-color);\n  font-size: 0.9rem;\n}\n.board-grid {\n  display: grid;\n  grid-template-columns: repeat(auto-fit, minmax(10rem, 1fr));\n  gap: 0.75rem;\n  margin-top: 1rem;\n}\n.board-card,\n.calendar-card {\n  display: grid;\n  gap: 0.25rem;\n  border: 1px solid #e0e8f1;\n  border-radius: var(--topogram-radius-control);\n  background: #f8fbff;\n  padding: 0.75rem;\n}\n.calendar-list {\n  display: grid;\n  gap: 0.75rem;\n  margin-top: 1rem;\n}\nsmall.route-hint {\n  display: block;\n  color: var(--topogram-muted-color);\n  margin-top: 0.25rem;\n}\n@media (max-width: 900px) {\n  .app-workspace {\n    grid-template-columns: 1fr;\n  }\n  .app-sidebar {\n    position: static;\n    min-height: auto;\n    border-right: none;\n    border-bottom: 1px solid rgba(24, 32, 38, 0.08);\n  }\n}\n@media (max-width: 640px) {\n  .definition-list {\n    grid-template-columns: 1fr;\n  }\n  .resource-list li {\n    flex-direction: column;\n  }\n  .resource-table {\n    min-width: 36rem;\n  }\n  .app-nav {\n    flex-wrap: wrap;\n  }\n}\n";
-  const navMarkup = navLinks.map((link) => `      <a href="${link.route}">${link.label}</a>`).join("\n");
+  const navMarkup = navLinks.map((link) => `      <a href="${escapeAttr(link.route)}">${escapeHtml(link.label)}</a>`).join("\n");
   const shellLayout =
     shellMode === "split_view"
-      ? `<div class="app-workspace">\n  <aside class="app-sidebar">\n    <a class="brand" href="/">${brandName}</a>\n    <nav class="app-nav-links">\n${navMarkup}\n    </nav>\n${hasCommandPalette ? `    <button class="command-palette-button" type="button">Command Palette</button>\n` : ""}  </aside>\n  <div class="app-main-shell">\n    <header class="app-nav compact">\n      <div class="brand-mark">${brandName}</div>\n${hasCommandPalette ? `      <button class="command-palette-button" type="button">Command Palette</button>\n` : ""}    </header>\n\n    <slot />\n  </div>\n</div>`
+      ? `<div class="app-workspace">\n  <aside class="app-sidebar">\n    <a class="brand" href="/">${safeBrandName}</a>\n    <nav class="app-nav-links">\n${navMarkup}\n    </nav>\n${hasCommandPalette ? `    <button class="command-palette-button" type="button">Command Palette</button>\n` : ""}  </aside>\n  <div class="app-main-shell">\n    <header class="app-nav compact">\n      <div class="brand-mark">${safeBrandName}</div>\n${hasCommandPalette ? `      <button class="command-palette-button" type="button">Command Palette</button>\n` : ""}    </header>\n\n    <slot />\n  </div>\n</div>`
       : shellMode === "bottom_tabs"
-        ? `<header class="app-nav">\n  <a class="brand" href="/">${brandName}</a>\n${hasCommandPalette ? `  <button class="command-palette-button" type="button">Command Palette</button>\n` : ""}</header>\n\n<slot />\n\n<nav class="app-tabbar">\n${navMarkup}\n</nav>`
-        : `<header class="app-nav${shellMode === "menu_bar" ? " menu-bar" : ""}">\n  <a class="brand" href="/">${brandName}</a>\n  <nav class="app-nav-links">\n${navMarkup}\n  </nav>\n${hasCommandPalette ? `  <button class="command-palette-button" type="button">Command Palette</button>\n` : ""}</header>\n\n<slot />`;
-  files["src/routes/+layout.svelte"] = `<script${useTypescript ? ' lang="ts"' : ""}>\n  import "../app.css";\n</script>\n\n<div class="app-shell" data-shell="${shellMode}" data-windowing="${windowingMode}" data-navigation-patterns="${navigationPatterns}">\n  ${shellLayout}\n${footerEnabled ? `\n  <footer class="app-footer">\n    <span>Generated from Topogram</span>\n  </footer>` : ""}\n</div>\n`;
+        ? `<header class="app-nav">\n  <a class="brand" href="/">${safeBrandName}</a>\n${hasCommandPalette ? `  <button class="command-palette-button" type="button">Command Palette</button>\n` : ""}</header>\n\n<slot />\n\n<nav class="app-tabbar">\n${navMarkup}\n</nav>`
+        : `<header class="app-nav${shellMode === "menu_bar" ? " menu-bar" : ""}">\n  <a class="brand" href="/">${safeBrandName}</a>\n  <nav class="app-nav-links">\n${navMarkup}\n  </nav>\n${hasCommandPalette ? `  <button class="command-palette-button" type="button">Command Palette</button>\n` : ""}</header>\n\n<slot />`;
+  files["src/routes/+layout.svelte"] = `<script${useTypescript ? ' lang="ts"' : ""}>\n  import "../app.css";\n</script>\n\n<div class="app-shell" data-shell="${escapeAttr(shellMode)}" data-windowing="${escapeAttr(windowingMode)}" data-navigation-patterns="${escapeAttr(navigationPatterns)}">\n  ${shellLayout}\n${footerEnabled ? `\n  <footer class="app-footer">\n    <span>Generated from Topogram</span>\n  </footer>` : ""}\n</div>\n`;
   files["src/routes/+page.svelte"] = webRenderers.renderHomePage({
     useTypescript,
     demoPrimaryEnvVar,

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

@@ -2,6 +2,7 @@
 
 import { buildWebRealization } from "../../../realization/ui/index.js";
 import { buildDesignIntentCoverage, renderDesignIntentCss } from "./design-intent.js";
+import { escapeAttr, escapeHtml } from "./html-escape.js";
 
 function slugify(value) {
   return String(value || "page")
@@ -26,19 +27,20 @@ function routeFileName(routePath) {
 }
 
 function renderHtml({ title, nav, body }) {
+  const safeTitle = escapeHtml(title);
   return `<!doctype html>
 <html lang="en">
   <head>
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1" />
-    <title>${title}</title>
+    <title>${safeTitle}</title>
     <link rel="stylesheet" href="./styles.css" />
   </head>
   <body>
     <header class="app-header">
       <a class="brand" href="./index.html">Topogram Hello</a>
       <nav>
-${nav.map((item) => `        <a href="./${item.file}">${item.title}</a>`).join("\n")}
+${nav.map((item) => `        <a href="./${escapeAttr(item.file)}">${escapeHtml(item.title)}</a>`).join("\n")}
       </nav>
     </header>
     <main>
@@ -285,13 +287,15 @@ export function generateVanillaWebApp(graph, options = {}) {
   };
 
   routes.forEach((route, index) => {
+    const safeTitle = escapeHtml(route.title);
+    const safeProjectionId = escapeHtml(contract.projection.id);
     files[route.file] = renderHtml({
       title: route.title,
       nav,
       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>${contract.projection.id}</code> Topogram web projection.</p>
+        <h1>${safeTitle}</h1>
+        <p>This page was generated from the <code>${safeProjectionId}</code> Topogram web projection.</p>
         <p class="muted">Generated timestamp: <span data-generated-at>pending</span></p>
       </section>`
     });

package/src/generator/widget-conformance/behavior-report.js

@@ -0,0 +1,258 @@
+// @ts-check
+
+import { stableUnique } from "./projection-context.js";
+import { generateWidgetConformanceReport } from "./report.js";
+
+/**
+ * @param {import("./types.d.ts").WidgetUsageReport} usage
+ * @param {import("./types.d.ts").WidgetBehavior} behavior
+ * @param {any} index
+ * @returns {any}
+ */
+export function behaviorReportKey(usage, behavior, index) {
+  return [usage.key, behavior.kind || "behavior", String(index)].join(":");
+}
+
+/**
+ * @param {import("./types.d.ts").WidgetBehavior} behavior
+ * @returns {any}
+ */
+export function capabilityIdsFromBehavior(behavior) {
+  const ids = /** @type {string[]} */ ([]);
+  for (const dependency of behavior.dataDependencies || []) {
+    if (dependency.source?.kind === "capability" && dependency.source.id) {
+      ids.push(dependency.source.id);
+    }
+  }
+  for (const action of behavior.actions || []) {
+    if (action.capability?.id) {
+      ids.push(action.capability.id);
+    }
+    for (const effect of action.effects || []) {
+      if (effect.capability?.id) {
+        ids.push(effect.capability.id);
+      }
+    }
+  }
+  for (const effect of behavior.effects || []) {
+    if (effect.capability?.id) {
+      ids.push(effect.capability.id);
+    }
+  }
+  return stableUnique(ids);
+}
+
+/**
+ * @param {import("./types.d.ts").WidgetBehavior} behavior
+ * @returns {any}
+ */
+export function effectTypesFromBehavior(behavior) {
+  const effects = behavior.effects || [];
+  if (effects.length === 0) {
+    return ["none"];
+  }
+  return stableUnique(effects.map(/** @param {any} effect */ (effect) => effect.type || "unknown"));
+}
+
+/**
+ * @param {import("./types.d.ts").WidgetConformanceReport} conformanceReport
+ * @param {import("./types.d.ts").WidgetUsageReport} usage
+ * @param {import("./types.d.ts").WidgetBehavior} behavior
+ * @returns {any}
+ */
+export function checksForBehavior(conformanceReport, usage, behavior) {
+  return (conformanceReport.checks || [])
+    .filter(/** @param {any} check */ (check) =>
+      check.code?.startsWith("widget_behavior_") &&
+      check.projection === usage.projection?.id &&
+      check.widget === usage.widget?.id &&
+      check.screen === usage.screen?.id &&
+      check.region === usage.region &&
+      (!check.behavior || check.behavior === behavior.kind)
+    )
+    .map(/** @param {any} check */ (check) => ({
+      code: check.code,
+      severity: check.severity,
+      message: check.message,
+      event: check.event || null,
+      behavior: check.behavior || behavior.kind || null,
+      suggested_fix: check.suggested_fix || null
+    }));
+}
+
+/**
+ * @param {import("./types.d.ts").WidgetUsageReport[]} behaviorRows
+ * @returns {any}
+ */
+export function behaviorHighlights(behaviorRows) {
+  const highlights = /** @type {any[]} */ ([]);
+  for (const row of behaviorRows) {
+    if (row.behavior.status === "partial") {
+      highlights.push({
+        severity: "warning",
+        code: "widget_behavior_partial",
+        message: `Behavior '${row.behavior.kind}' is partially realized for widget '${row.widget.id}' on screen '${row.screen.id}'.`,
+        projection: row.projection.id,
+        widget: row.widget.id,
+        screen: row.screen.id,
+        region: row.region,
+        behavior: row.behavior.kind,
+        suggested_fix: "Bind the required behavior data, events, or capability actions in the projection widget_bindings entry."
+      });
+    }
+    for (const emittedEvent of row.emits || []) {
+      if (!emittedEvent.bound) {
+        highlights.push({
+          severity: "warning",
+          code: "widget_behavior_event_unbound",
+          message: `Behavior '${row.behavior.kind}' emits event '${emittedEvent.event}', but this widget usage does not bind it.`,
+          projection: row.projection.id,
+          widget: row.widget.id,
+          screen: row.screen.id,
+          region: row.region,
+          event: emittedEvent.event || null,
+          behavior: row.behavior.kind,
+          suggested_fix: `Add 'event ${emittedEvent.event} navigate <screen>' or 'event ${emittedEvent.event} action <capability>' to the projection widget_bindings entry.`
+        });
+      }
+    }
+    for (const action of row.actions || []) {
+      if (!action.bound) {
+        const target = action.capability?.id || action.event || "(unknown)";
+        highlights.push({
+          severity: "warning",
+          code: "widget_behavior_action_unbound",
+          message: `Behavior '${row.behavior.kind}' declares action '${target}', but this widget usage does not bind it.`,
+          projection: row.projection.id,
+          widget: row.widget.id,
+          screen: row.screen.id,
+          region: row.region,
+          event: action.event || null,
+          capability: action.capability?.id || null,
+          behavior: row.behavior.kind,
+          suggested_fix: action.capability?.id
+            ? `Add 'event <widget_event> action ${action.capability.id}' to the projection widget_bindings entry.`
+            : `Add 'event ${action.event} action <capability>' or 'event ${action.event} navigate <screen>' to the projection widget_bindings entry.`
+        });
+      }
+    }
+  }
+  return highlights;
+}
+
+/**
+ * @param {any} rows
+ * @param {any} keyFn
+ * @param {any} itemFn
+ * @returns {any}
+ */
+export function groupBehaviorRows(rows, keyFn, itemFn = null) {
+  const groups = new Map();
+  for (const row of rows) {
+    for (const key of keyFn(row)) {
+      if (!groups.has(key)) {
+        groups.set(key, []);
+      }
+      groups.get(key).push(row);
+    }
+  }
+  return [...groups.entries()]
+    .sort(([a], [b]) => a.localeCompare(b))
+    .map(([id, entries]) => ({
+      id,
+      total_behaviors: entries.length,
+      realized: entries.filter(/** @param {any} entry */ (entry) => entry.behavior.status === "realized").length,
+      partial: entries.filter(/** @param {any} entry */ (entry) => entry.behavior.status === "partial").length,
+      declared: entries.filter(/** @param {any} entry */ (entry) => entry.behavior.status === "declared").length,
+      behaviors: entries.map(/** @param {any} entry */ (entry) => itemFn ? itemFn(entry) : entry.key).sort()
+    }));
+}
+
+/**
+ * @param {import("./types.d.ts").WidgetGraph} graph
+ * @param {import("./types.d.ts").WidgetOptions} options
+ * @returns {any}
+ */
+export function generateWidgetBehaviorReport(graph, options = {}) {
+  const conformanceReport = generateWidgetConformanceReport(graph, options);
+  const behaviorRows = /** @type {any[]} */ ([]);
+
+  for (const usage of conformanceReport.projection_usages || []) {
+    for (const [index, behavior] of (usage.behavior_realizations || []).entries()) {
+      const diagnostics = checksForBehavior(conformanceReport, usage, behavior);
+      behaviorRows.push({
+        key: behaviorReportKey(usage, behavior, index),
+        projection: usage.projection,
+        source_projection: usage.source_projection,
+        screen: usage.screen,
+        region: usage.region,
+        widget: usage.widget,
+        behavior: {
+          kind: behavior.kind || null,
+          source: behavior.source || null,
+          status: behavior.status || "declared",
+          directives: behavior.directives || {}
+        },
+        data_dependencies: behavior.dataDependencies || [],
+        emits: behavior.emits || [],
+        actions: behavior.actions || [],
+        effects: behavior.effects || [],
+        capabilities: capabilityIdsFromBehavior(behavior),
+        effect_types: effectTypesFromBehavior(behavior),
+        diagnostics,
+        check_codes: diagnostics.map(/** @param {any} check */ (check) => check.code)
+      });
+    }
+  }
+
+  const highlights = behaviorHighlights(behaviorRows);
+  const affectedCapabilities = stableUnique(behaviorRows.flatMap(/** @param {any} row */ (row) => row.capabilities));
+
+  return {
+    type: "widget_behavior_report",
+    filters: conformanceReport.filters,
+    summary: {
+      total_usages: conformanceReport.summary.total_usages,
+      total_behaviors: behaviorRows.length,
+      realized: behaviorRows.filter(/** @param {any} row */ (row) => row.behavior.status === "realized").length,
+      partial: behaviorRows.filter(/** @param {any} row */ (row) => row.behavior.status === "partial").length,
+      declared: behaviorRows.filter(/** @param {any} row */ (row) => row.behavior.status === "declared").length,
+      warnings: conformanceReport.summary.warnings,
+      errors: conformanceReport.summary.errors,
+      affected_widgets: conformanceReport.summary.affected_widgets,
+      affected_projections: conformanceReport.summary.affected_projections,
+      affected_capabilities: affectedCapabilities
+    },
+    groups: {
+      widgets: groupBehaviorRows(
+        behaviorRows,
+        /** @param {any} row */ (row) => [row.widget.id].filter(Boolean),
+        /** @param {any} row */ (row) => row.key
+      ),
+      screens: groupBehaviorRows(
+        behaviorRows,
+        /** @param {any} row */ (row) => [row.screen.id].filter(Boolean),
+        /** @param {any} row */ (row) => row.key
+      ),
+      capabilities: groupBehaviorRows(
+        behaviorRows,
+        /** @param {any} row */ (row) => row.capabilities,
+        /** @param {any} row */ (row) => row.key
+      ),
+      effects: groupBehaviorRows(
+        behaviorRows,
+        /** @param {any} row */ (row) => row.effect_types,
+        /** @param {any} row */ (row) => row.key
+      )
+    },
+    behaviors: behaviorRows,
+    highlights,
+    checks: conformanceReport.checks.filter(/** @param {any} check */ (check) => check.code?.startsWith("widget_behavior_")),
+    write_scope: conformanceReport.write_scope,
+    impact: {
+      projections: conformanceReport.impact.projections,
+      widgets: conformanceReport.impact.widgets,
+      capabilities: affectedCapabilities
+    }
+  };
+}