@jay-framework/design-system-validator 0.24.6 → 0.25.0

package/dist/tools.d.ts

@@ -17,6 +17,8 @@ declare const validateFontFallbacks: JayHtmlValidatorFn;
 
 declare const validateUndefinedVars: JayHtmlValidatorFn;
 
+declare const validateViewportHeight: JayHtmlValidatorFn;
+
 declare const ADD_MENU_GENERATED_REL = "agent-kit/aiditor/add-menu/design-system.generated.yaml";
 
 /**
@@ -98,4 +100,4 @@ declare const regenerateDesignSystemAddMenu: _jay_framework_fullstack_component.
     message: any;
 }, []>;
 
-export { ADD_MENU_GENERATED_REL, generateDesignSystemAgentKit, getDesignSystemSettingsStatus, loadDesignSystemAddMenuCatalog, regenerateDesignSystemAddMenu, runDesignSystemAnalysisAction as runDesignSystemAnalysis, saveDesignSystemAddMenuCatalog, validateComponents, validateContrast, validateFontFallbacks, validateStructure, validateTokens, validateUndefinedVars };
+export { ADD_MENU_GENERATED_REL, generateDesignSystemAgentKit, getDesignSystemSettingsStatus, loadDesignSystemAddMenuCatalog, regenerateDesignSystemAddMenu, runDesignSystemAnalysisAction as runDesignSystemAnalysis, saveDesignSystemAddMenuCatalog, validateComponents, validateContrast, validateFontFallbacks, validateStructure, validateTokens, validateUndefinedVars, validateViewportHeight };

package/dist/tools.js

@@ -189,16 +189,26 @@ function parseInlineStyles(style) {
   }
   return declarations;
 }
+function selectorTargetsRoot(root, selector) {
+  const trimmed = selector.trim();
+  if (trimmed === "html" || trimmed === ":root") return true;
+  try {
+    return root.closest(trimmed) === root;
+  } catch {
+    return false;
+  }
+}
 function buildSelectorCache(rules, root) {
   const cache = /* @__PURE__ */ new Map();
   for (const rule of rules) {
     if (cache.has(rule.selector)) continue;
+    const matched = /* @__PURE__ */ new Set();
     try {
-      const matches = root.querySelectorAll(rule.selector);
-      cache.set(rule.selector, new Set(matches));
+      for (const el of root.querySelectorAll(rule.selector)) matched.add(el);
     } catch {
-      cache.set(rule.selector, /* @__PURE__ */ new Set());
     }
+    if (selectorTargetsRoot(root, rule.selector)) matched.add(root);
+    cache.set(rule.selector, matched);
   }
   return cache;
 }
@@ -279,9 +289,7 @@ function resolveCascade(cssSources, root) {
       if (child.nodeType === 1) walk(child);
     }
   }
-  for (const child of root.childNodes) {
-    if (child.nodeType === 1) walk(child);
-  }
+  walk(root);
   return result;
 }
 function resolveCascadeByBreakpoint(cssSources, root) {
@@ -320,9 +328,7 @@ function resolveCascadeByBreakpoint(cssSources, root) {
     );
     const selectorCache = buildSelectorCache(rulesForBreakpoint, root);
     const breakpointResult = /* @__PURE__ */ new Map();
-    for (const child of root.childNodes) {
-      if (child.nodeType === 1) walk(child);
-    }
+    walk(root);
     result.set(breakpoint, breakpointResult);
   }
   return result;
@@ -1251,6 +1257,51 @@ See agent-kit/designer/design-system.md for usage guide.`
   }
   return findings;
 };
+const VIEWPORT_HEIGHT_UNIT = /\d*\.?\d+(vh|svh|lvh|dvh|vmax)\b/i;
+const TOP_LEVEL_TAGS = /* @__PURE__ */ new Set(["html", "body", "main"]);
+const PARENT_TAGS = /* @__PURE__ */ new Set(["body", "main"]);
+const OUT_OF_FLOW = /* @__PURE__ */ new Set(["fixed", "absolute", "sticky"]);
+const HEIGHT_PROPS = ["height", "min-height"];
+function tagOf(el) {
+  return (el?.rawTagName ?? "").toLowerCase();
+}
+function usesViewportHeight(value) {
+  return value != null && VIEWPORT_HEIGHT_UNIT.test(value);
+}
+function isTopLevel(el) {
+  if (TOP_LEVEL_TAGS.has(tagOf(el))) return true;
+  return PARENT_TAGS.has(tagOf(el.parentNode));
+}
+const validateViewportHeight = (ctx) => {
+  if (!ctx.css) return [];
+  if (!ctx.filePath.includes("/pages/") && !ctx.filePath.startsWith("src/pages/")) {
+    return [];
+  }
+  if (ctx.validationOverrides?.["design-system"]?.["allow-viewport-height"] === true) {
+    return [];
+  }
+  const base = resolveCascadeByBreakpoint([ctx.css], ctx.body).get(void 0);
+  if (!base) return [];
+  const findings = [];
+  for (const [el, styles] of base) {
+    if (!isTopLevel(el)) continue;
+    if (OUT_OF_FLOW.has(styles["position"]?.value?.trim().toLowerCase() ?? "")) continue;
+    const maxHeight = styles["max-height"]?.value?.trim();
+    const bounded = maxHeight != null && maxHeight.toLowerCase() !== "none" && !usesViewportHeight(maxHeight);
+    if (bounded) continue;
+    for (const property of HEIGHT_PROPS) {
+      const decl = styles[property];
+      if (!usesViewportHeight(decl?.value)) continue;
+      findings.push({
+        severity: "warning",
+        message: `Top-level container "${decl.selector}" sets ${property}: ${decl.value}. Googlebot renders into a very tall viewport (~12,000px), so viewport-height units expand this section and distort Search Console screenshots / mobile-usability reports.`,
+        suggestion: `Choose a fix by content type — text: chain height from a bounded ancestor; hero/visual: cap with max-height inside a mobile @media; overlay: this is safe, suppress with design-system: { allow-viewport-height: true }. Note: swapping vh → dvh/svh/lvh is NOT a fix (all resolve tall under Googlebot). See agent-kit/designer/jay-html-styling.md (and validation-guide.md for suppression).`,
+        element: `<${tagOf(el)}>`
+      });
+    }
+  }
+  return findings;
+};
 const PLUGIN_ATTRS = {
   pluginName: "design-system-validator",
   packageName: "@jay-framework/design-system-validator"
@@ -1871,5 +1922,6 @@ export {
   validateFontFallbacks,
   validateStructure,
   validateTokens,
-  validateUndefinedVars
+  validateUndefinedVars,
+  validateViewportHeight
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jay-framework/design-system-validator",
-  "version": "0.24.6",
+  "version": "0.25.0",
   "type": "module",
   "description": "Design system validation plugin for Jay Framework — validates jay-html CSS against DESIGN.md tokens",
   "license": "Apache-2.0",
@@ -37,25 +37,25 @@
     "@capsizecss/metrics": "^4.2.0",
     "@capsizecss/unpack": "^4.0.1",
     "@csstools/selector-specificity": "^5.0.0",
-    "@jay-framework/component": "^0.24.6",
-    "@jay-framework/fullstack-component": "^0.24.6",
-    "@jay-framework/plugin-validator": "^0.24.6",
-    "@jay-framework/stack-server-runtime": "^0.24.6",
+    "@jay-framework/component": "^0.25.0",
+    "@jay-framework/fullstack-component": "^0.25.0",
+    "@jay-framework/plugin-validator": "^0.25.0",
+    "@jay-framework/stack-server-runtime": "^0.25.0",
     "js-yaml": "^4.1.0",
     "postcss": "^8.5.6",
     "postcss-selector-parser": "^7.1.0"
   },
   "peerDependencies": {
-    "@jay-framework/compiler-jay-html": "^0.24.6",
-    "@jay-framework/compiler-shared": "^0.24.6"
+    "@jay-framework/compiler-jay-html": "^0.25.0",
+    "@jay-framework/compiler-shared": "^0.25.0"
   },
   "devDependencies": {
-    "@jay-framework/compiler-jay-html": "^0.24.6",
-    "@jay-framework/compiler-jay-stack": "^0.24.6",
-    "@jay-framework/compiler-shared": "^0.24.6",
-    "@jay-framework/dev-environment": "^0.24.6",
-    "@jay-framework/jay-cli": "^0.24.6",
-    "@jay-framework/jay-stack-cli": "^0.24.6",
+    "@jay-framework/compiler-jay-html": "^0.25.0",
+    "@jay-framework/compiler-jay-stack": "^0.25.0",
+    "@jay-framework/compiler-shared": "^0.25.0",
+    "@jay-framework/dev-environment": "^0.25.0",
+    "@jay-framework/jay-cli": "^0.25.0",
+    "@jay-framework/jay-stack-cli": "^0.25.0",
     "@types/js-yaml": "^4.0.9",
     "@types/node": "^22.15.21",
     "node-html-parser": "^6.1.0",

package/plugin.yaml

@@ -51,3 +51,7 @@ validators:
   - name: undefined-vars
     handler: validateUndefinedVars
     description: Flags CSS var(--name) references that are never defined as custom properties
+
+  - name: design-viewport-height
+    handler: validateViewportHeight
+    description: Flags unbounded viewport-height units (vh/svh/lvh/dvh/vmax) on top-level containers that distort Googlebot's tall-viewport render (Search Console screenshots / mobile-usability)