@jay-framework/jay-stack-cli 0.23.1 → 0.24.0

package/agent-kit-template/developer/component-refs.md

@@ -124,6 +124,8 @@ This generates both a ViewState field and a ref.
 
 Refs are the **only supported path** from TypeScript to elements Jay renders. Direct `document` access bypasses the framework and can break rendering, updates, and performance.
 
+`jay-stack validate` warns on `document.querySelector`, `document.getElementById`, `document.createElement`, and `document.addEventListener` in page and component `.ts` files. Suppress with `// jay-dom: allow` on the same line when an exception is genuinely needed.
+
 ### Do
 
 - Declare elements in **jay-html** with `ref="..."`.
@@ -134,20 +136,135 @@ Refs are the **only supported path** from TypeScript to elements Jay renders. Di
 
 ### Avoid
 
-- `document.querySelector` / `getElementById` to find template elements
-- `document.createElement` + `appendChild` for UI that belongs in jay-html
-- `document.addEventListener('mousemove'|'mouseup')` for drags (use pointer capture instead)
+- `document.querySelector` / `getElementById` to find template elements — use refs
+- `document.createElement` + `appendChild` for UI that belongs in jay-html — use `forEach` with ViewState
+- `document.addEventListener` for global events — use the root ref pattern (below)
 
-### Rare `document` exceptions
+## Root ref pattern — replacing `document.addEventListener`
+
+Wrap the page content in a shell element with a ref. Use capture-phase listeners on the shell to intercept events before they reach children — functionally equivalent to `document.addEventListener`.
+
+### Setup
+
+```html
+<!-- jay-html -->
+<div ref="shell" class="page-shell">... entire page content ...</div>
+```
+
+```yaml
+# Contract
+- tag: shell
+  type: interactive
+  elementType: HTMLDivElement
+```
+
+### Global keyboard navigation
+
+Instead of `document.addEventListener('keydown', ...)`:
+
+```typescript
+.withInteractive(function Page(_props, refs) {
+    let keyboardNav = false;
+
+    refs.shell.onkeydown(({ event }) => {
+        if (event.key === 'Tab') keyboardNav = true;
+    });
+
+    refs.shell.onmousedown(() => {
+        keyboardNav = false;
+    });
+})
+```
+
+Events bubble up from children to the shell — a handler on the shell sees all keyboard and mouse events from the entire page.
+
+Use `refs.shell.addEventListener(type, handler, { capture: true })` only when you need to intercept events _before_ children handle them (e.g., preventing default on specific keys).
+
+### Focus management (scroll into view)
+
+Instead of `document.addEventListener('focusin', ...)`:
+
+```typescript
+refs.shell.onfocusin(({ event }) => {
+  if (!keyboardNav) return;
+  const el = event.target as HTMLElement;
+  refs.shell.exec$(() => {
+    el.scrollIntoView({ behavior: 'smooth', block: 'nearest' });
+  });
+});
+```
+
+### Detecting pointer leaving the page
+
+Instead of `document.addEventListener('mouseleave', ...)`:
 
-Use only when no ref can exist, with an inline comment:
+```typescript
+refs.shell.onpointerleave(({ event }) => {
+  // Pointer left the shell — equivalent to leaving the viewport
+  // if the shell covers the full viewport
+});
+```
+
+Ensure the shell has no margin/padding gap so it covers the full viewport. `pointer-events: auto` (the default) is sufficient.
+
+### Finding elements by class → use refs
+
+Instead of `document.querySelector('.site-header')`:
+
+```html
+<!-- jay-html -->
+<header ref="siteHeader" class="site-header">...</header>
+```
+
+```typescript
+refs.siteHeader.onclick(() => {
+  /* ... */
+});
+
+refs.siteHeader.exec$((el) => {
+  el.classList.add('is-hidden');
+});
+```
+
+### Dynamic lists → use forEach
 
-| Case                   | Example                                               |
-| ---------------------- | ----------------------------------------------------- |
-| Offscreen processing   | `document.createElement('canvas')` for image export   |
-| Coordinate hit-testing | `document.elementFromPoint` during cross-overlay drag |
-| Tests                  | `document.dispatchEvent` in Vitest                    |
+Instead of creating elements with `document.createElement` in a loop:
+
+```html
+<!-- jay-html -->
+<div forEach="cards" trackBy="id" class="card-grid">
+  <div class="card">
+    <img src="{imageUrl}" alt="{title}" />
+    <span>{title}</span>
+  </div>
+</div>
+```
+
+Update the ViewState to add/remove cards — the framework handles DOM creation.
+
+### Using `exec$` for native DOM APIs
+
+For DOM operations that refs don't wrap (scroll, focus, measurements), use `exec$` inside an event handler:
+
+```typescript
+refs.myInput.onclick(() => {
+  refs.myInput.exec$((el) => {
+    el.focus();
+    el.select();
+  });
+});
+
+refs.scrollContainer.exec$((el) => {
+  el.scrollTo({ top: 0, behavior: 'smooth' });
+});
+```
+
+### Rare `document` exceptions
 
-Global shortcuts or paste: prefer a root shell ref (`ref="appRoot"`) with capture listeners.
+Use only when no ref can exist, with `// jay-dom: allow` to suppress the validation warning:
 
-See also: `.cursor/skills/jay-dom-refs/SKILL.md` in the jay monorepo.
+| Case                   | Example                                                               |
+| ---------------------- | --------------------------------------------------------------------- |
+| Offscreen processing   | `document.createElement('canvas') // jay-dom: allow` for image export |
+| Coordinate hit-testing | `document.elementFromPoint(...) // jay-dom: allow` during drag        |
+| Tests                  | `document.dispatchEvent // jay-dom: allow` in Vitest                  |

package/dist/index.d.ts

@@ -17,9 +17,12 @@ interface JayConfig {
         publicFolder?: string;
         configBase?: string;
     };
+    site?: {
+        baseUrl?: string;
+    };
 }
 declare function loadConfig(): JayConfig;
-declare function getConfigWithDefaults(config: JayConfig): Required<JayConfig>;
+declare function getConfigWithDefaults(config: JayConfig): Required<Pick<JayConfig, 'devServer'>> & Pick<JayConfig, 'site'>;
 declare function updateConfig(updates: Partial<JayConfig>): void;
 
 export { type JayConfig, type StartDevServerOptions, getConfigWithDefaults, loadConfig, startDevServer, updateConfig };

package/dist/index.js

@@ -41,7 +41,8 @@ function loadConfig() {
       devServer: {
         ...DEFAULT_CONFIG.devServer,
         ...userConfig.devServer
-      }
+      },
+      site: userConfig.site
     };
   } catch (error) {
     getLogger().warn(`Failed to parse .jay YAML config file, using defaults: ${error}`);
@@ -56,7 +57,8 @@ function getConfigWithDefaults(config) {
       componentsBase: config.devServer?.componentsBase || DEFAULT_CONFIG.devServer.componentsBase,
       publicFolder: config.devServer?.publicFolder || DEFAULT_CONFIG.devServer.publicFolder,
       configBase: config.devServer?.configBase || DEFAULT_CONFIG.devServer.configBase
-    }
+    },
+    site: config.site
   };
 }
 function updateConfig(updates) {
@@ -69,6 +71,10 @@ function updateConfig(updates) {
       devServer: {
         ...existingConfig.devServer,
         ...updates.devServer
+      },
+      site: {
+        ...existingConfig.site,
+        ...updates.site
       }
     };
     const yamlContent = YAML.stringify(updatedConfig, { indent: 2 });
@@ -146,6 +152,13 @@ async function startDevServer(options = {}) {
   });
   app.use(server);
   const publicPath = path.resolve(resolvedConfig.devServer.publicFolder);
+  if (!fs.existsSync(path.join(publicPath, "sitemap.xml"))) {
+    app.get("/sitemap.xml", (_req, res) => {
+      res.type("application/xml").send(
+        '<?xml version="1.0" encoding="UTF-8"?>\n<!-- Sitemap is generated by the production server from the route manifest. -->\n<!-- Run jay-stack build && jay-stack serve to see the full sitemap. -->\n<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9" />\n'
+      );
+    });
+  }
   if (fs.existsSync(publicPath)) {
     app.use(express.static(publicPath));
   } else {
@@ -264,9 +277,11 @@ async function resolveProductionContext(projectPath, versionOverride) {
   const resolvedPath = path$1.resolve(projectPath || process.cwd());
   const jayConfigPath = path$1.join(resolvedPath, ".jay");
   let pagesBase = "./src/pages";
+  let siteBaseUrl;
   try {
     const jayConfig = YAML.parse(await fs$1.readFile(jayConfigPath, "utf-8"));
     pagesBase = jayConfig?.devServer?.pagesBase || pagesBase;
+    siteBaseUrl = jayConfig?.site?.baseUrl;
   } catch {
   }
   const version = versionOverride || await resolveVersionFromPackageJson(resolvedPath);
@@ -275,7 +290,8 @@ async function resolveProductionContext(projectPath, versionOverride) {
     pagesRoot: path$1.resolve(resolvedPath, pagesBase),
     buildRoot: path$1.join(resolvedPath, "build"),
     version,
-    tsConfigFilePath: path$1.join(resolvedPath, "tsconfig.json")
+    tsConfigFilePath: path$1.join(resolvedPath, "tsconfig.json"),
+    siteBaseUrl
   };
 }
 async function resolveVersionFromPackageJson(projectRoot) {
@@ -305,7 +321,8 @@ async function runBuild(projectPath, options) {
     buildRoot: ctx.buildRoot,
     concurrency: 4,
     tsConfigFilePath: ctx.tsConfigFilePath,
-    minify: options.minify
+    minify: options.minify,
+    siteBaseUrl: ctx.siteBaseUrl
   });
 }
 async function runServe(projectPath, options) {
@@ -319,7 +336,8 @@ async function runServe(projectPath, options) {
       port: parseInt(options.port, 10),
       projectRoot: ctx.resolvedPath,
       pagesRoot: ctx.pagesRoot,
-      tsConfigFilePath: ctx.tsConfigFilePath
+      tsConfigFilePath: ctx.tsConfigFilePath,
+      siteBaseUrl: ctx.siteBaseUrl
     });
   } else {
     const { startMainServer } = await import("@jay-framework/production-server");
@@ -358,7 +376,8 @@ async function runRebuild(projectPath, options) {
     buildRoot: ctx.buildRoot,
     version: ctx.version,
     target,
-    tsConfigFilePath: ctx.tsConfigFilePath
+    tsConfigFilePath: ctx.tsConfigFilePath,
+    siteBaseUrl: ctx.siteBaseUrl
   });
   if (result.errors.length > 0) {
     for (const err of result.errors) {
@@ -2366,6 +2385,96 @@ async function validatePackageJson(context, result) {
     });
   }
 }
+function isBareFunctionExport(exportName, context) {
+  const sourcePath = resolveExportSourceFile(exportName, context);
+  if (!sourcePath) return false;
+  let sourceCode;
+  try {
+    sourceCode = fs.readFileSync(sourcePath, "utf-8");
+  } catch {
+    return false;
+  }
+  const sourceFile = u.createSourceFile(
+    sourcePath,
+    sourceCode,
+    u.ScriptTarget.Latest,
+    true,
+    u.ScriptKind.TS
+  );
+  for (const statement of sourceFile.statements) {
+    if (u.isFunctionDeclaration(statement) && hasExportModifier(statement) && statement.name?.text === exportName) {
+      return true;
+    }
+  }
+  return false;
+}
+function resolveModulePathWithJsToTs(basePath) {
+  const result = resolveModulePath(basePath);
+  if (result) return result;
+  if (basePath.endsWith(".js")) {
+    return resolveModulePath(basePath.slice(0, -3) + ".ts");
+  }
+  return void 0;
+}
+function resolveExportSourceFile(exportName, context) {
+  const modulePath = context.manifest.module || "index";
+  const entryBase = path.join(context.pluginPath, modulePath);
+  const libEntryBase = path.join(context.pluginPath, "lib", modulePath);
+  const sourceEntry = resolveModulePath(entryBase) || resolveModulePath(libEntryBase);
+  if (!sourceEntry || !sourceEntry.endsWith(".ts")) return void 0;
+  return followExportChain(exportName, sourceEntry);
+}
+function followExportChain(exportName, filePath) {
+  let sourceCode;
+  try {
+    sourceCode = fs.readFileSync(filePath, "utf-8");
+  } catch {
+    return void 0;
+  }
+  const sourceFile = u.createSourceFile(
+    filePath,
+    sourceCode,
+    u.ScriptTarget.Latest,
+    true,
+    u.ScriptKind.TS
+  );
+  const starReexportModules = [];
+  for (const statement of sourceFile.statements) {
+    if (u.isExportDeclaration(statement) && statement.moduleSpecifier) {
+      if (!u.isStringLiteral(statement.moduleSpecifier)) continue;
+      const moduleSpec = statement.moduleSpecifier.text;
+      if (!statement.exportClause) {
+        starReexportModules.push(moduleSpec);
+        continue;
+      }
+      if (u.isNamedExports(statement.exportClause)) {
+        for (const element of statement.exportClause.elements) {
+          if (element.name.text === exportName) {
+            const resolvedBase = path.resolve(path.dirname(filePath), moduleSpec);
+            return resolveModulePathWithJsToTs(resolvedBase);
+          }
+        }
+      }
+    }
+    if (u.isFunctionDeclaration(statement) && hasExportModifier(statement)) {
+      if (statement.name?.text === exportName) return filePath;
+    }
+    if (u.isVariableStatement(statement) && hasExportModifier(statement)) {
+      for (const decl of statement.declarationList.declarations) {
+        if (u.isIdentifier(decl.name) && decl.name.text === exportName) return filePath;
+      }
+    }
+  }
+  for (const moduleSpec of starReexportModules) {
+    if (!moduleSpec.startsWith(".")) continue;
+    const resolvedBase = path.resolve(path.dirname(filePath), moduleSpec);
+    const resolved = resolveModulePathWithJsToTs(resolvedBase);
+    if (!resolved) continue;
+    const found = followExportChain(exportName, resolved);
+    if (found) return found;
+  }
+  return void 0;
+}
 async function validateDynamicContracts(context, result) {
   const { dynamic_contracts } = context.manifest;
   if (!dynamic_contracts) return;
@@ -2392,6 +2501,13 @@ async function validateDynamicContracts(context, result) {
             suggestion: `Create generator file at ${generatorPath}.ts`
           });
         }
+      } else if (isBareFunctionExport(config.generator, context)) {
+        result.errors.push({
+          type: "export-mismatch",
+          message: `Generator "${config.generator}" for ${prefix} is a bare function — it must be a DynamicContractGenerator object`,
+          location: "plugin.yaml dynamic_contracts",
+          suggestion: `Use makeContractGenerator().generateWith(...) from @jay-framework/fullstack-component instead of exporting a plain function`
+        });
       }
     }
     if (config.component) {
@@ -2721,6 +2837,65 @@ function checkRefElementTypes(jayHtml, file) {
   walkElement(jayHtml.body, []);
   return warnings;
 }
+function checkPageComponentExport(jayHtmlPath) {
+  const dirname = path.dirname(jayHtmlPath);
+  const compPath = path.join(dirname, "page.ts");
+  if (!fs.existsSync(compPath)) return null;
+  let content;
+  try {
+    content = fs.readFileSync(compPath, "utf-8");
+  } catch {
+    return null;
+  }
+  const exportName = "page";
+  const patterns = [
+    new RegExp(`export\\s*\\{[^}]*\\b${exportName}\\b[^}]*\\}`, "m"),
+    new RegExp(`export\\s+(?:async\\s+)?function\\s+${exportName}\\b`),
+    new RegExp(`export\\s+(?:const|let|var)\\s+${exportName}\\b`)
+  ];
+  if (patterns.some((p) => p.test(content))) return null;
+  return `${path.relative(dirname, compPath)} exists but does not export "${exportName}". Remove the file or add the export.`;
+}
+const DOCUMENT_ACCESS_PATTERNS = [
+  /document\.getElementById\b/,
+  /document\.querySelector\b/,
+  /document\.querySelectorAll\b/,
+  /document\.getElementsBy\w+/,
+  /document\.createElement\b/,
+  /document\.body\.appendChild\b/,
+  /document\.addEventListener\b/
+];
+const DOM_SUPPRESS_COMMENT = "jay-dom: allow";
+function checkDirectDocumentAccess(jayHtmlPath) {
+  const dirname = path.dirname(jayHtmlPath);
+  const basename = path.basename(jayHtmlPath, JAY_EXTENSION);
+  const candidates = [path.join(dirname, `${basename}.ts`), path.join(dirname, "page.ts")];
+  const compPath = candidates.find((p) => fs.existsSync(p));
+  if (!compPath) return [];
+  const compName = path.basename(compPath);
+  let content;
+  try {
+    content = fs.readFileSync(compPath, "utf-8");
+  } catch {
+    return [];
+  }
+  const warnings = [];
+  const lines = content.split("\n");
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (line.includes(DOM_SUPPRESS_COMMENT)) continue;
+    for (const pattern of DOCUMENT_ACCESS_PATTERNS) {
+      const match = pattern.exec(line);
+      if (match) {
+        warnings.push(
+          `${compName}:${i + 1} — Direct DOM access "${match[0]}" — use Jay refs instead. Suppress with // ${DOM_SUPPRESS_COMMENT} on the same line. See agent-kit/developer/component-refs.md`
+        );
+        break;
+      }
+    }
+  }
+  return warnings;
+}
 const PARSE_PARAM = /^\[(\[)?(\.\.\.)?([^\]]+)\]?\]$/;
 function extractRouteParams(filePath, pagesBase) {
   const relative = path.relative(pagesBase, filePath);
@@ -3143,6 +3318,18 @@ async function validateJayFiles(options = {}) {
           message: '<script type="application/jay-params"> is deprecated. Move the values into the YAML body of the headless component that uses them. See agent-kit/developer/routing.md for details.'
         });
       }
+      const pageExportError = checkPageComponentExport(jayFile);
+      if (pageExportError) {
+        errors.push({
+          file: relativePath,
+          message: pageExportError,
+          stage: "generate"
+        });
+      }
+      const domWarnings = checkDirectDocumentAccess(jayFile);
+      for (const msg of domWarnings) {
+        warnings.push({ file: relativePath, message: msg });
+      }
       const routeParamWarnings = checkRouteParams(parsedFile.val, jayFile, scanDir);
       for (const msg of routeParamWarnings) {
         warnings.push({ file: relativePath, message: msg });
@@ -3207,6 +3394,21 @@ async function validateJayFiles(options = {}) {
       }
     }
   }
+  const robotsTxtPath = path.resolve(projectRoot, "public/robots.txt");
+  if (!fs.existsSync(robotsTxtPath)) {
+    warnings.push({
+      file: "public/robots.txt",
+      message: "public/robots.txt not found — search engines may crawl pages you don't intend to expose.",
+      suggestion: "Create public/robots.txt with: User-agent: *\nAllow: /\nSitemap: https://your-domain.com/sitemap.xml"
+    });
+  }
+  if (!config.site?.baseUrl) {
+    warnings.push({
+      file: ".jay",
+      message: "site.baseUrl not configured — sitemap.xml will not be generated in production.",
+      suggestion: "Add to .jay config: site:\n  baseUrl: https://your-domain.com"
+    });
+  }
   const pluginValidators = await runPluginValidators(projectRoot, parsedFiles, errors, warnings);
   return {
     valid: errors.length === 0,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jay-framework/jay-stack-cli",
-  "version": "0.23.1",
+  "version": "0.24.0",
   "license": "Apache-2.0",
   "type": "module",
   "main": "dist/index.js",
@@ -25,14 +25,14 @@
   },
   "dependencies": {
     "@inquirer/prompts": "^8.5.2",
-    "@jay-framework/compiler-jay-html": "^0.23.1",
-    "@jay-framework/compiler-shared": "^0.23.1",
-    "@jay-framework/dev-server": "^0.23.1",
-    "@jay-framework/fullstack-component": "^0.23.1",
-    "@jay-framework/logger": "^0.23.1",
-    "@jay-framework/plugin-validator": "^0.23.1",
-    "@jay-framework/production-server": "^0.23.1",
-    "@jay-framework/stack-server-runtime": "^0.23.1",
+    "@jay-framework/compiler-jay-html": "^0.24.0",
+    "@jay-framework/compiler-shared": "^0.24.0",
+    "@jay-framework/dev-server": "^0.24.0",
+    "@jay-framework/fullstack-component": "^0.24.0",
+    "@jay-framework/logger": "^0.24.0",
+    "@jay-framework/plugin-validator": "^0.24.0",
+    "@jay-framework/production-server": "^0.24.0",
+    "@jay-framework/stack-server-runtime": "^0.24.0",
     "chalk": "^4.1.2",
     "commander": "^14.0.0",
     "express": "^5.0.1",
@@ -43,7 +43,7 @@
     "yaml": "^2.3.4"
   },
   "devDependencies": {
-    "@jay-framework/dev-environment": "^0.23.1",
+    "@jay-framework/dev-environment": "^0.24.0",
     "@types/express": "^5.0.2",
     "@types/node": "^22.15.21",
     "nodemon": "^3.0.3",