@tekyzinc/gsd-t 2.73.10 → 2.73.12

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 All notable changes to GSD-T are documented here. Updated with each release.
 
+## [2.73.12] - 2026-04-08
+
+### Added (review UI — isolated component preview + tier tabs)
+- **`/review/preview` endpoint** — mounts a single component in isolation via Vite module resolution. Framework-aware: auto-detects Vue/React/Svelte from package.json. Includes global styles and Vite HMR client. Components now render in the review iframe instead of showing a blank page.
+- **Tier tabs** — Elements | Widgets | Pages tabs in the sidebar filter components by tier. Counts update as items are queued. All tab shows everything.
+- **Framework detection** — review server reads project's package.json to determine mount strategy. Logs detected framework and global styles on startup.
+
+## [2.73.11] - 2026-04-08
+
+### Changed (reviewer — Playwright-first visual inspection)
+- **Playwright is now the PRIMARY reviewer method** — every contract-specified visual property is verified via `getComputedStyle()` in a real browser. Code review demoted to supplement for non-visual concerns (props, events, accessibility). CSS box math (cascade, specificity, flex/grid computation, relative units) can only be verified at render time, not from source code.
+
 ## [2.73.10] - 2026-04-08
 
 ### Added (orchestrator — parallel execution)

package/bin/design-orchestrator.js

@@ -365,25 +365,39 @@ ${componentList}
 ${measurementContext}
 ## Review Process
 
-**Step 1 — Code review (do this FIRST for ALL components):**
-For each component, read the design contract file and the source file. Check that every contract-specified value (colors, sizes, spacing, border-radius, font, layout, chart type, etc.) is correctly implemented in the code. This is your primary review — most issues are catchable from code alone.
-
-**Step 2 — Playwright spot-check (do this AFTER code review):**
-Use Playwright to render components at http://localhost:${ports.reviewPort}/ and verify:
-- Components render without errors and have correct dimensions
-- Chart types, orientations, and data structures are correct
-- Interactive elements respond correctly (hover, click, states)
-
-Focus Playwright on components where code review raised concerns or where visual behavior can't be verified from code alone (e.g., SVG rendering, computed layouts). You do NOT need to re-measure every CSS property — the orchestrator already ran Playwright measurements above.
+**Step 1 — Playwright visual inspection (PRIMARY — do this FIRST):**
+Every UI component is visual and MUST be visually inspected. For each component:
+1. Open http://localhost:${ports.reviewPort}/ in Playwright
+2. Navigate to / render the component using its selector
+3. For EVERY contract-specified visual property, use \`page.locator(selector).evaluate(el => getComputedStyle(el))\` to measure the actual computed value:
+   - **Box model**: width, height, padding, margin, gap, border-width, border-radius
+   - **Colors**: background-color, color, border-color (compare computed rgb/rgba values)
+   - **Typography**: font-family, font-size, font-weight, line-height, letter-spacing
+   - **Layout**: display, flex-direction, justify-content, align-items, grid-template-columns
+   - **Spacing**: gap, row-gap, column-gap, padding (all sides), margin (all sides)
+   - **Visual**: opacity, box-shadow, overflow, text-overflow
+4. Compare each measured value against the contract specification
+5. Check that the component renders without console errors
+6. For charts/SVGs: verify chart type, orientation, data structure, and proportions visually
+
+Code review alone CANNOT verify CSS box math — cascade, specificity, flex/grid computation, relative units, and parent constraints all affect the final rendered result. Only computed styles from a running browser are authoritative.
+
+**Step 2 — Code review (supplement for non-visual concerns):**
+Read the source file to check:
+- Prop interfaces match contract definitions
+- Event handlers and interactivity are wired correctly
+- Data binding and state management are correct
+- Accessibility attributes (aria-*, role) are present
+- Component structure matches contract hierarchy
 
 ## Output Format
 
-Output your findings between these markers. Each issue must have component, severity (critical/high/medium/low), and description with SPECIFIC contract vs. actual values:
+Output your findings between these markers. Each issue must have component, severity (critical/high/medium/low), and description with SPECIFIC contract value vs. actual computed value:
 
 [REVIEW_ISSUES]
 [
   {"component": "ComponentName", "severity": "critical", "description": "Contract specifies donut chart but rendered as pie chart (no inner radius)"},
-  {"component": "ComponentName", "severity": "high", "description": "Grid gap: contract 16px, actual 24px"}
+  {"component": "ComponentName", "severity": "high", "description": "Grid gap: contract 16px, computed 24px"}
 ]
 [/REVIEW_ISSUES]
 
@@ -395,9 +409,10 @@ If ALL components match their contracts, output:
 ## CRITICAL — Output Rules
 - Output MUST contain the [REVIEW_ISSUES] markers — the orchestrator parses your result from these markers. Without them, your review is lost.
 - You write ZERO code. You ONLY review.
+- You MUST run Playwright for every component. Skipping visual inspection is a review failure.
 - Be HARSH. Your value is in catching what the builder missed.
-- NEVER say "looks close" or "appears to match" — give SPECIFIC values.
-- Every contract property must be verified. Missing verification = missed issue.
+- NEVER say "looks close" or "appears to match" — give SPECIFIC computed values.
+- Every contract property must be verified via computed style. Missing verification = missed issue.
 - Severity guide: critical = wrong component type, missing element, broken render. high = wrong dimensions, colors, layout. medium = spacing/padding off. low = minor visual difference.`;
 }
 
@@ -421,15 +436,30 @@ function buildSingleItemReviewPrompt(phase, item, measurements, projectDir, port
 ${measurementContext}
 ## Review Process
 
-1. Read the design contract file — note every specified property value
-2. Read the source file — check that every contract-specified value is implemented correctly
-3. If needed, use Playwright to render at http://localhost:${ports.reviewPort}/ and verify visual behavior
+**Step 1 — Playwright visual inspection (PRIMARY):**
+This is a UI component — visual inspection is mandatory, not optional.
+1. Read the design contract file — note every specified visual property value
+2. Open http://localhost:${ports.reviewPort}/ in Playwright
+3. Render the component using its selector
+4. For EVERY contract-specified visual property, measure the actual computed value:
+   \`page.locator(selector).evaluate(el => getComputedStyle(el))\`
+   - Box model: width, height, padding, margin, gap, border-width, border-radius
+   - Colors: background-color, color, border-color (compare computed rgb/rgba)
+   - Typography: font-family, font-size, font-weight, line-height
+   - Layout: display, flex-direction, justify-content, align-items
+5. Compare each computed value against the contract specification
+6. For charts/SVGs: verify type, orientation, proportions visually
+
+Code review alone cannot verify CSS — cascade, specificity, flex/grid, and relative units all affect computed output.
+
+**Step 2 — Code review (non-visual concerns):**
+Read the source file to check prop interfaces, event handlers, data binding, and accessibility attributes.
 
 ## Output Format
 
 [REVIEW_ISSUES]
 [
-  {"component": "${item.componentName}", "severity": "high", "description": "Contract specifies X, code has Y"}
+  {"component": "${item.componentName}", "severity": "high", "description": "Contract specifies X, computed value is Y"}
 ]
 [/REVIEW_ISSUES]
 
@@ -439,8 +469,9 @@ If the component matches its contract, output:
 [/REVIEW_ISSUES]
 
 ## Rules
+- You MUST run Playwright. Skipping visual inspection is a review failure.
 - You write ZERO code. You ONLY review.
-- Be HARSH — specific values only, no "looks close."
+- Be HARSH — specific computed values only, no "looks close."
 - Output MUST contain [REVIEW_ISSUES] markers.`;
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tekyzinc/gsd-t",
-  "version": "2.73.10",
+  "version": "2.73.12",
   "description": "GSD-T: Contract-Driven Development for Claude Code — 56 slash commands with headless CI/CD mode, graph-powered code analysis, real-time agent dashboard, execution intelligence, task telemetry, doc-ripple enforcement, backlog management, impact analysis, test sync, milestone archival, and PRD generation",
   "author": "Tekyz, Inc.",
   "license": "MIT",

package/scripts/gsd-t-design-review-server.js

@@ -26,6 +26,78 @@ const TARGET = getArg("target", "http://localhost:5173");
 const PROJECT_DIR = getArg("project", process.cwd());
 const REVIEW_DIR = path.join(PROJECT_DIR, ".gsd-t", "design-review");
 
+// ── Framework detection ──────────────────────────────────────────────
+function detectFramework() {
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(PROJECT_DIR, "package.json"), "utf8"));
+    const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+    if (deps.vue || deps["vue-router"]) return "vue";
+    if (deps.react || deps["react-dom"]) return "react";
+    if (deps.svelte) return "svelte";
+    if (deps["@angular/core"]) return "angular";
+  } catch { /* no package.json */ }
+  return "vue"; // default
+}
+
+function findGlobalStyles() {
+  const candidates = [
+    "src/assets/main.css", "src/assets/index.css", "src/assets/global.css",
+    "src/styles/main.css", "src/styles/index.css", "src/styles/global.css",
+    "src/index.css", "src/main.css", "src/app.css",
+  ];
+  return candidates.filter(f => fs.existsSync(path.join(PROJECT_DIR, f)));
+}
+
+const FRAMEWORK = detectFramework();
+const GLOBAL_STYLES = findGlobalStyles();
+
+function generatePreviewHtml(componentPath) {
+  const linkTags = GLOBAL_STYLES.map(s => `  <link rel="stylesheet" href="/${s}">`).join("\n");
+
+  let mountScript;
+  if (FRAMEWORK === "vue") {
+    mountScript = `
+  <script type="module">
+    import { createApp } from 'vue'
+    import Component from '/${componentPath}'
+    const app = createApp(Component)
+    app.mount('#app')
+  </script>`;
+  } else if (FRAMEWORK === "react") {
+    mountScript = `
+  <script type="module">
+    import React from 'react'
+    import { createRoot } from 'react-dom/client'
+    import Component from '/${componentPath}'
+    createRoot(document.getElementById('app')).render(React.createElement(Component))
+  </script>`;
+  } else {
+    mountScript = `<script type="module">import '/${componentPath}'</script>`;
+  }
+
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Preview: ${path.basename(componentPath)}</title>
+  <script type="module" src="/@vite/client"></script>
+${linkTags}
+  <style>
+    * { margin: 0; padding: 0; box-sizing: border-box; }
+    body { background: #ffffff; min-height: 100vh; display: flex; align-items: center; justify-content: center; padding: 32px; font-family: -apple-system, BlinkMacSystemFont, sans-serif; }
+    #app { width: 100%; max-width: 800px; }
+    .preview-error { color: #ef4444; font-size: 14px; padding: 16px; border: 1px solid #ef4444; border-radius: 8px; }
+  </style>
+</head>
+<body>
+  <div id="app"></div>
+  ${mountScript}
+  <script src="/review/inject.js"></script>
+</body>
+</html>`;
+}
+
 // ── Ensure coordination directory ─────────────────────────────────────
 function ensureDir(dir) {
   try { fs.mkdirSync(dir, { recursive: true }); } catch { /* exists */ }
@@ -263,6 +335,35 @@ const server = http.createServer((req, res) => {
     return;
   }
 
+  // Component preview — mounts a single component in isolation via Vite
+  if (pathname === "/review/preview") {
+    const component = parsed.query.component;
+    if (!component) {
+      res.writeHead(400, { "Content-Type": "text/plain" });
+      res.end("Missing ?component= parameter");
+      return;
+    }
+    // Proxy this HTML through Vite so module imports resolve correctly
+    const html = generatePreviewHtml(component);
+    // Send to Vite's HTML transform endpoint via proxy
+    const proxyOpts = {
+      hostname: targetUrl.hostname,
+      port: targetUrl.port,
+      path: "/__gsd_preview",
+      method: "GET",
+      headers: { ...req.headers, host: `${targetUrl.hostname}:${targetUrl.port}` },
+    };
+    // Vite won't know this path — serve directly but let browser resolve modules from Vite
+    const buf = Buffer.from(html, "utf8");
+    res.writeHead(200, {
+      "Content-Type": "text/html",
+      "Content-Length": buf.length,
+      "Cache-Control": "no-cache",
+    });
+    res.end(buf);
+    return;
+  }
+
   // ── Review API ──────────────────────────────────────────────────
   if (pathname === "/review/api/status") {
     res.writeHead(200, { "Content-Type": "application/json", "Access-Control-Allow-Origin": "*" });
@@ -388,5 +489,9 @@ server.listen(PORT, () => {
   console.log(`${GREEN}  ✓${RESET} Review UI:  ${CYAN}http://localhost:${PORT}/review${RESET}`);
   console.log(`${GREEN}  ✓${RESET} Proxying:   ${DIM}${TARGET} → http://localhost:${PORT}/${RESET}`);
   console.log(`${GREEN}  ✓${RESET} Project:    ${DIM}${PROJECT_DIR}${RESET}`);
+  console.log(`${GREEN}  ✓${RESET} Framework:  ${DIM}${FRAMEWORK}${RESET}`);
+  if (GLOBAL_STYLES.length > 0) {
+    console.log(`${GREEN}  ✓${RESET} Styles:     ${DIM}${GLOBAL_STYLES.join(", ")}${RESET}`);
+  }
   console.log(`${DIM}  Coordination: ${REVIEW_DIR}${RESET}\n`);
 });

package/scripts/gsd-t-design-review.html

@@ -127,6 +127,39 @@
     border-bottom: 1px solid var(--border);
   }
 
+  /* ── Tier tabs ──────────────────────────────────── */
+  .tier-tabs {
+    display: flex;
+    padding: 4px;
+    gap: 2px;
+    border-bottom: 1px solid var(--border);
+    flex-shrink: 0;
+  }
+
+  .tier-tab {
+    flex: 1;
+    padding: 5px 4px;
+    font-size: 11px;
+    font-weight: 600;
+    text-align: center;
+    border: none;
+    border-radius: 4px;
+    background: transparent;
+    color: var(--text-dim);
+    cursor: pointer;
+    transition: all 0.1s;
+  }
+
+  .tier-tab:hover { color: var(--text-muted); background: var(--bg-hover); }
+  .tier-tab.active { color: white; background: var(--accent); }
+
+  .tier-tab .tier-count {
+    font-size: 9px;
+    font-weight: 400;
+    opacity: 0.7;
+    margin-left: 2px;
+  }
+
   .component-list {
     flex: 1;
     overflow-y: auto;
@@ -687,6 +720,12 @@
   <!-- Left sidebar: component list -->
   <div class="sidebar">
     <div class="sidebar-header">Components</div>
+    <div class="tier-tabs" id="tier-tabs">
+      <button class="tier-tab active" data-tier="all">All</button>
+      <button class="tier-tab" data-tier="element">Elements</button>
+      <button class="tier-tab" data-tier="widget">Widgets</button>
+      <button class="tier-tab" data-tier="page">Pages</button>
+    </div>
     <div class="component-list" id="component-list">
       <div class="waiting-overlay" id="waiting-state">
         <div class="spinner"></div>
@@ -750,7 +789,9 @@
 
   // ── State ─────────────────────────────────────────
   let queue = [];
-  let selectedIdx = -1;
+  let filteredQueue = [];  // queue filtered by active tier
+  let activeTier = "all";
+  let selectedIdx = -1;    // index into filteredQueue
   let inspectActive = false;
   const changes = new Map();     // componentId → [{path, property, oldValue, newValue}]
   const comments = new Map();   // componentId → string
@@ -783,6 +824,46 @@
   let currentTree = null;
   let selectedTreeKey = null;
   const propagateBadge = document.getElementById("propagate-badge");
+  const tierTabs = document.getElementById("tier-tabs");
+
+  // ── Tier tab handling ────────────────────────────
+  function filterByTier() {
+    if (activeTier === "all") {
+      filteredQueue = [...queue];
+    } else {
+      filteredQueue = queue.filter(item => item.type === activeTier);
+    }
+  }
+
+  function updateTierCounts() {
+    const counts = { all: queue.length, element: 0, widget: 0, page: 0 };
+    for (const item of queue) {
+      if (counts[item.type] !== undefined) counts[item.type]++;
+    }
+    tierTabs.querySelectorAll(".tier-tab").forEach(tab => {
+      const tier = tab.getAttribute("data-tier");
+      const count = counts[tier] || 0;
+      const label = tier === "all" ? "All" : tier.charAt(0).toUpperCase() + tier.slice(1) + "s";
+      tab.innerHTML = count > 0 ? `${label} <span class="tier-count">${count}</span>` : label;
+      // Hide tabs with 0 items (except All)
+      if (tier !== "all") {
+        tab.style.display = count > 0 ? "" : "none";
+      }
+    });
+  }
+
+  tierTabs.addEventListener("click", (e) => {
+    const tab = e.target.closest(".tier-tab");
+    if (!tab) return;
+    activeTier = tab.getAttribute("data-tier");
+    tierTabs.querySelectorAll(".tier-tab").forEach(t => t.classList.remove("active"));
+    tab.classList.add("active");
+    selectedIdx = -1;
+    filterByTier();
+    renderComponentList();
+    updateSubmitStats();
+    if (filteredQueue.length > 0) selectComponent(0);
+  });
 
   // ── SSE connection ────────────────────────────────
   function connectSSE() {
@@ -836,21 +917,15 @@
       submitBar.style.display = "flex";
       feedbackPanel.style.display = "block";
     }
+    filterByTier();
+    updateTierCounts();
     renderComponentList();
     updateSubmitStats();
 
     // Auto-select first if none selected
-    if (selectedIdx < 0 && queue.length > 0) {
+    if (selectedIdx < 0 && filteredQueue.length > 0) {
       selectComponent(0);
     }
-
-    // Load iframe with the app URL
-    if (queue.length > 0 && previewIframe.src === "about:blank") {
-      // Use the first component's route or default to "/"
-      const route = queue[0].route || "/";
-      previewIframe.src = route;
-      previewUrl.textContent = route;
-    }
   }
 
   function renderComponentList() {
@@ -859,16 +934,16 @@
       if (ch !== waitingState) ch.remove();
     });
 
-    queue.forEach((item, idx) => {
+    filteredQueue.forEach((item, idx) => {
       const itemChanges = changes.get(item.id) || [];
       const itemComment = comments.get(item.id) || "";
       let statusClass = "pending";
       if (itemChanges.length > 0 && itemComment) {
-        statusClass = "changed"; // has both changes and comments
+        statusClass = "changed";
       } else if (itemChanges.length > 0) {
         statusClass = "changed";
       } else if (itemComment) {
-        statusClass = "rejected"; // comment only = feedback
+        statusClass = "rejected";
       }
 
       const div = document.createElement("div");
@@ -885,53 +960,61 @@
 
   function selectComponent(idx) {
     // Save comment from current element before switching
-    if (selectedIdx >= 0 && queue[selectedIdx]) {
+    if (selectedIdx >= 0 && filteredQueue[selectedIdx]) {
       const comment = feedbackComment.value.trim();
-      if (comment) comments.set(queue[selectedIdx].id, comment);
-      else comments.delete(queue[selectedIdx].id);
+      if (comment) comments.set(filteredQueue[selectedIdx].id, comment);
+      else comments.delete(filteredQueue[selectedIdx].id);
     }
 
     selectedIdx = idx;
     renderComponentList();
 
-    const item = queue[idx];
+    const item = filteredQueue[idx];
     if (!item) return;
 
     // Always show component info in the inspector immediately
     renderComponentInfo(item);
 
-    // Scroll iframe to the component if it has a selector
-    if (item.selector && previewIframe.contentWindow) {
-      // Auto-enable inspect mode so the element gets highlighted
+    // Load isolated component preview in iframe
+    if (item.sourcePath) {
+      const previewSrc = `/review/preview?component=${encodeURIComponent(item.sourcePath)}`;
+      previewIframe.src = previewSrc;
+      previewUrl.textContent = item.sourcePath;
+    }
+
+    // Auto-enable inspect mode and request tree after iframe loads
+    const onPreviewLoad = () => {
+      previewIframe.removeEventListener("load", onPreviewLoad);
+
       if (!inspectActive) {
         inspectActive = true;
         inspectToggle.classList.add("active");
         previewHint.textContent = "Hover to inspect, click to lock selection";
+      }
+
+      if (previewIframe.contentWindow) {
         previewIframe.contentWindow.postMessage({ type: "gsdt-activate" }, "*");
       }
-      previewIframe.contentWindow.postMessage({
-        type: "gsdt-scroll-to",
-        selector: item.selector,
-      }, "*");
 
-      // Request component tree for hierarchical control
+      // Request component tree
       currentTree = null;
       selectedTreeKey = null;
       inspectorTree.innerHTML = "";
-      // Small delay to let scroll-to complete before querying tree
       setTimeout(() => {
         if (previewIframe.contentWindow) {
+          const selector = item.selector || "#app > *";
+          previewIframe.contentWindow.postMessage({
+            type: "gsdt-scroll-to",
+            selector: selector,
+          }, "*");
           previewIframe.contentWindow.postMessage({
             type: "gsdt-get-tree",
-            selector: item.selector,
+            selector: selector,
           }, "*");
         }
-      }, 300);
-    }
-
-    // Save comment from previous element before switching
-    const prevItem = selectedIdx >= 0 ? queue[selectedIdx] : null;
-    // (selectedIdx already updated above via renderComponentList, so use prevItem logic below)
+      }, 500);
+    };
+    previewIframe.addEventListener("load", onPreviewLoad);
 
     // Load existing comment for this element
     feedbackComment.value = comments.get(item.id) || "";
@@ -1179,7 +1262,7 @@
         }
 
         // Check if this property was changed
-        const compId = queue[selectedIdx]?.id;
+        const compId = filteredQueue[selectedIdx]?.id;
         const compChanges = changes.get(compId) || [];
         const existing = compChanges.find(c => c.path === currentElementPath && c.property === prop);
         if (existing) {
@@ -1327,7 +1410,7 @@
   // ── Property editing ──────────────────────────────
   function startEdit(valEl, prop) {
     const currentVal = valEl.getAttribute("data-original");
-    const compChanges = changes.get(queue[selectedIdx]?.id) || [];
+    const compChanges = changes.get(filteredQueue[selectedIdx]?.id) || [];
     const existing = compChanges.find(c => c.path === currentElementPath && c.property === prop);
     const displayVal = existing ? existing.newValue : currentVal;
 
@@ -1361,7 +1444,7 @@
         }, "*");
 
         // Track the change
-        const compId = queue[selectedIdx]?.id;
+        const compId = filteredQueue[selectedIdx]?.id;
         if (compId) {
           if (!changes.has(compId)) changes.set(compId, []);
           const list = changes.get(compId);
@@ -1445,7 +1528,7 @@
   // ── Ctrl/Cmd+Z to undo last change ──────────────────
   document.addEventListener("keydown", (e) => {
     if ((e.ctrlKey || e.metaKey) && e.key === "z" && !e.shiftKey) {
-      const compId = queue[selectedIdx]?.id;
+      const compId = filteredQueue[selectedIdx]?.id;
       if (!compId) return;
       const list = changes.get(compId);
       if (!list || list.length === 0) return;
@@ -1543,7 +1626,7 @@
 
   // ── Save comment on blur ────────────────────────────
   feedbackComment.addEventListener("blur", () => {
-    const item = queue[selectedIdx];
+    const item = filteredQueue[selectedIdx];
     if (!item) return;
     const comment = feedbackComment.value.trim();
     if (comment) comments.set(item.id, comment);
@@ -1575,10 +1658,10 @@
 
   submitAll.addEventListener("click", async () => {
     // Save current element's comment
-    if (selectedIdx >= 0 && queue[selectedIdx]) {
+    if (selectedIdx >= 0 && filteredQueue[selectedIdx]) {
       const comment = feedbackComment.value.trim();
-      if (comment) comments.set(queue[selectedIdx].id, comment);
-      else comments.delete(queue[selectedIdx].id);
+      if (comment) comments.set(filteredQueue[selectedIdx].id, comment);
+      else comments.delete(filteredQueue[selectedIdx].id);
     }
 
     // Check for non-actionable comments (documentation, not change requests)
@@ -1654,7 +1737,7 @@
   });
 
   undoAllChanges.addEventListener("click", () => {
-    const compId = queue[selectedIdx]?.id;
+    const compId = filteredQueue[selectedIdx]?.id;
     if (compId) {
       changes.delete(compId);
       renderChanges(compId);