@jay-framework/dev-server 0.25.4 → 0.25.5

package/dist/index.d.ts

@@ -39,6 +39,19 @@ interface DevServerOptions {
     logLevel?: LogLevel;
     /** HTTP server for HMR WebSocket attachment (avoids default port 24678 collision) */
     httpServer?: Server;
+    /**
+     * Hosts the dev server's Vite host-check accepts, beyond localhost (DL#220). A list of hosts
+     * (Vite host-suffix syntax, e.g. `.example.dev`), or `true` to disable the check entirely — for
+     * cloud preview proxies. Merged with the `__VITE_ADDITIONAL_SERVER_ALLOWED_HOSTS` env var.
+     */
+    allowedHosts?: string[] | true;
+    /**
+     * Enable source-editing dev markers (DL#219). When true, the pre-render pipeline injects
+     * `jay-dev-src` / `jay-dev-item` attributes so the source-editing inspector can map a rendered
+     * pixel back to its jay-html source. Off by default — the markers change rendered output, so
+     * they are only emitted for AIditor / source-editing sessions.
+     */
+    sourceEditing?: boolean;
 }
 
 /**
@@ -277,7 +290,21 @@ interface CreateViteServerOptions {
     clearScreen?: boolean;
     /** HTTP server for HMR WebSocket (avoids default port 24678 collision) */
     httpServer?: Server;
+    /**
+     * Hosts Vite's dev-server host-check accepts, beyond localhost (DL#220). A list of hosts (Vite
+     * host-suffix syntax, e.g. `.example.dev`), or `true` to disable the check entirely. Merged with
+     * the `__VITE_ADDITIONAL_SERVER_ALLOWED_HOSTS` env var. `undefined`/empty → Vite's default.
+     */
+    allowedHosts?: string[] | true;
 }
+/**
+ * Resolves Vite's `server.allowedHosts` from the `.jay` config value and the
+ * `__VITE_ADDITIONAL_SERVER_ALLOWED_HOSTS` env var (Vite's own convention — honored natively only in
+ * Vite 6, so the nested Vite 5.4 needs us to read it). Returns `true` (disable check) if either source
+ * says so, a de-duplicated merged list otherwise, or `undefined` when neither is set (Vite keeps its
+ * localhost-only default). (DL#220)
+ */
+declare function resolveAllowedHosts(fromConfig: string[] | true | undefined, env: string | undefined): string[] | true | undefined;
 /**
  * Creates a Vite server configured for Jay Stack.
  *
@@ -297,4 +324,4 @@ declare function createViteForCli(options: {
     tsConfigFilePath?: string;
 }): Promise<ViteDevServer>;
 
-export { ACTION_ENDPOINT_BASE, type ActionBodyParserOptions, type ActionRouterOptions, type CreateViteServerOptions, DEV_SERVER_SERVICE, type DevServer, type DevServerOptions, type DevServerRoute, type DevServerRouteRegistrar, DevServerService, type FreezeEntry, FreezeStore, type RouteInfo, actionBodyParser, createActionRouter, createViteForCli, createViteServer, mkDevServer };
+export { ACTION_ENDPOINT_BASE, type ActionBodyParserOptions, type ActionRouterOptions, type CreateViteServerOptions, DEV_SERVER_SERVICE, type DevServer, type DevServerOptions, type DevServerRoute, type DevServerRouteRegistrar, DevServerService, type FreezeEntry, FreezeStore, type RouteInfo, actionBodyParser, createActionRouter, createViteForCli, createViteServer, mkDevServer, resolveAllowedHosts };

package/dist/index.js

@@ -7,7 +7,7 @@ import { createRequire } from "module";
 import "@jay-framework/compiler-shared";
 import * as path from "node:path";
 import path__default from "node:path";
-import { parseJayFile, JAY_IMPORT_RESOLVER, discoverHeadlessInstances, assignCoordinatesToJayHtml, parseAction, generateServerElementFile, parseContract, slowRenderTransform } from "@jay-framework/compiler-jay-html";
+import { parseJayFile, JAY_IMPORT_RESOLVER, discoverHeadlessInstances, assignCoordinatesToJayHtml, parseAction, generateServerElementFile, noteExportedTypesFileChanged, injectDevMarkers, parseContract, slowRenderTransform } from "@jay-framework/compiler-jay-html";
 import { getLogger, getDevLogger } from "@jay-framework/logger";
 import { createRequire as createRequire$1 } from "node:module";
 import * as fs from "node:fs";
@@ -1518,6 +1518,13 @@ function jayStackCompiler(options = {}) {
 function stripInlineActionBuilders(code, builderNames) {
   return transformJayStackBuilder(code, "action-strip.ts", "client", new Set(builderNames));
 }
+function resolveAllowedHosts(fromConfig, env) {
+  if (fromConfig === true) return true;
+  const envHosts = (env ?? "").split(",").map((host) => host.trim()).filter(Boolean);
+  if (envHosts.includes("true")) return true;
+  const merged = [...fromConfig ?? [], ...envHosts];
+  return merged.length ? Array.from(new Set(merged)) : void 0;
+}
 async function createViteServer(options) {
   const {
     projectRoot,
@@ -1526,14 +1533,21 @@ async function createViteServer(options) {
     jayRollupConfig = { tsConfigFilePath: path__default.join(projectRoot, "tsconfig.json") },
     logLevel = "info",
     clearScreen = true,
-    httpServer
+    httpServer,
+    allowedHosts
   } = options;
+  const resolvedAllowedHosts = resolveAllowedHosts(
+    allowedHosts,
+    process.env.__VITE_ADDITIONAL_SERVER_ALLOWED_HOSTS
+  );
   const vite = await createServer({
     // Don't start HTTP server - we use middleware mode
     server: {
       middlewareMode: true,
       hmr: httpServer ? { server: httpServer } : void 0,
-      watch: { ignored: ["**/build/**"] }
+      watch: { ignored: ["**/build/**"] },
+      // Omit the key entirely when unset so Vite keeps its localhost-only default (DL#220).
+      ...resolvedAllowedHosts !== void 0 && { allowedHosts: resolvedAllowedHosts }
     },
     // Use Jay Stack compiler for .jay-html and other custom transforms
     plugins: [
@@ -2018,8 +2032,9 @@ function buildPageReloadHmrScript() {
         });
       }`;
 }
-function buildFreezeScript(routePattern) {
+function buildFreezeScript(routePattern, sourceFile) {
   const routePatternLiteral = routePattern ? `'${routePattern}'` : "undefined";
+  const sourceFileLiteral = sourceFile ? JSON.stringify(sourceFile) : "undefined";
   return `
       // Page Freeze (DL#127, DL#128 iframe addendum)
       // Sticky embed mode: URL param sets a session cookie so in-iframe navigation preserves it
@@ -2074,13 +2089,152 @@ function buildFreezeScript(routePattern) {
           }
       }
 
+      // Source-editing inspector (DL#219). Resolves a viewport point/rect to the jay-dev-* source
+      // markers emitted when the dev server runs with sourceEditing on. Harmless without markers —
+      // it simply finds no jay-dev-src and replies node:null. Reply carries source LOCATORS (line
+      // ranges + route) plus runtime identities (forEach record id, region name + static props);
+      // the agent reads bound expressions / collection / if-conditions from the jay-html itself.
+      function __jayParseLines(s) {
+        if (!s) return null;
+        const parts = s.split(':');
+        return { from: parseInt(parts[0], 10), to: parseInt(parts[1], 10) };
+      }
+      function __jayLines(el) {
+        return __jayParseLines(el.getAttribute('jay-dev-src'));
+      }
+      // A significant enclosing frame: a forEach item root or a region boundary. Returns null for
+      // plain wrapper elements (the agent reconstructs those from source via node.lines).
+      function __jayFrame(el) {
+        const item = el.getAttribute('jay-dev-item');
+        if (item) return { kind: 'forEach', lines: __jayLines(el), itemId: item };
+        const region = el.getAttribute('jay-dev-region');
+        if (region) {
+          // Region lines live in jay-dev-region-src (the <jay:…> tag's range), distinct from the
+          // root element's own jay-dev-src.
+          const frame = { kind: 'region', lines: __jayParseLines(el.getAttribute('jay-dev-region-src')), name: region };
+          const rawProps = el.getAttribute('jay-dev-region-props');
+          if (rawProps) { try { frame.props = JSON.parse(decodeURIComponent(rawProps)); } catch (e) {} }
+          return frame;
+        }
+        return null;
+      }
+      // One-level HTML of an element: its open tag (authored attrs only, jay-* stripped), its direct
+      // children shown as empty tags (grandchildren elided with …), and its text — so the agent sees
+      // exactly what was clicked inside generated content without the whole subtree.
+      function __jayOneLevelHtml(el) {
+        if (!el || !el.tagName) return '';
+        const tag = el.tagName.toLowerCase();
+        let attrs = '';
+        for (let i = 0; i < el.attributes.length; i++) {
+          const a = el.attributes[i];
+          if (a.name.indexOf('jay-') === 0) continue; // strip jay-dev-* / jay-coordinate
+          attrs += ' ' + a.name + '="' + a.value + '"';
+        }
+        let inner = '';
+        const kids = el.childNodes || [];
+        for (let i = 0; i < kids.length; i++) {
+          const c = kids[i];
+          if (c.nodeType === 3) inner += (c.textContent || '');
+          else if (c.nodeType === 1) {
+            const ct = c.tagName.toLowerCase();
+            inner += '<' + ct + '>' + (c.childNodes && c.childNodes.length ? '…' : '') + '</' + ct + '>';
+          }
+        }
+        if (inner.length > 300) inner = inner.slice(0, 300) + '…';
+        return '<' + tag + attrs + '>' + inner + '</' + tag + '>';
+      }
+      function __jayResolveElement(el) {
+        if (!el) return null;
+        // Walk el up to (but excluding) <body>.
+        const entries = [];
+        let cur = el;
+        while (cur && cur.nodeType === 1 && cur.tagName && cur.tagName.toLowerCase() !== 'body') {
+          entries.push(cur);
+          cur = cur.parentElement;
+        }
+        // Source anchor = nearest element at/above el carrying a source marker (its line range).
+        let sourceEl = null;
+        for (let i = 0; i < entries.length; i++) {
+          if (entries[i].getAttribute('jay-dev-src')) { sourceEl = entries[i]; break; }
+        }
+        if (!sourceEl) return null;
+        // Stack = only the significant enclosing frames (forEach + region), innermost → outermost.
+        const stack = [];
+        for (let i = 0; i < entries.length; i++) {
+          const f = __jayFrame(entries[i]);
+          if (f) stack.push(f);
+        }
+        // node describes the ACTUAL element el (what the pointer hit / the rect chose). html — a
+        // one-level rendering (open tag with authored attrs, direct children as empty tags, inline
+        // text; grandchildren + long text elided) — is the single content field: it carries the tag,
+        // attributes (src/href/value), and value, bounded in size. lines come from the source anchor;
+        // for bound/generated content (an html-string value) el has no jay-dev-src of its own, so
+        // lines point to the ENCLOSING binding (the editable source) and contentFromBinding flags it.
+        const r = el.getBoundingClientRect();
+        const node = {
+          lines: __jayLines(sourceEl),
+          tag: el.tagName ? el.tagName.toLowerCase() : '',
+          html: __jayOneLevelHtml(el),
+          rect: { x: r.x, y: r.y, width: r.width, height: r.height },
+        };
+        const childEls = Array.prototype.slice.call(el.children || []);
+        const childrenGenerated =
+          childEls.length > 0 && childEls.every((c) => !c.getAttribute('jay-dev-src'));
+        if (!el.getAttribute('jay-dev-src') || childrenGenerated) {
+          node.contentFromBinding = true;
+        }
+        return { node, stack };
+      }
+      function __jayInspectPoint(x, y) {
+        return __jayResolveElement(document.elementFromPoint(x, y));
+      }
+      function __jayInspectRect(x, y, w, h) {
+        const sel = { left: x, top: y, right: x + w, bottom: y + h };
+        const marked = Array.prototype.slice.call(document.querySelectorAll('[jay-dev-src]'));
+        let best = null, bestArea = -1;
+        for (let i = 0; i < marked.length; i++) {
+          const el = marked[i];
+          const r = el.getBoundingClientRect();
+          const elArea = r.width * r.height;
+          if (elArea <= 0) continue;
+          const ix = Math.max(0, Math.min(sel.right, r.right) - Math.max(sel.left, r.left));
+          const iy = Math.max(0, Math.min(sel.bottom, r.bottom) - Math.max(sel.top, r.top));
+          // Rect rule (DL#219): keep elements the box mostly encloses (overlap over the ELEMENT's
+          // own area >= 0.8), then pick the LARGEST — the element the box was drawn around. A tight
+          // box only clears the threshold for the small element; a big box clears it for the
+          // container too, and largest-area returns the container (not its first child).
+          if ((ix * iy) / elArea >= 0.8 && elArea > bestArea) {
+            bestArea = elArea;
+            best = el;
+          }
+        }
+        if (best) return __jayResolveElement(best);
+        return __jayInspectPoint(x + w / 2, y + h / 2);
+      }
+
       if (__jayEmbedMode) {
         // Notify parent of the current route on load (DL#128 route addendum)
         window.parent.postMessage({ type: 'jay:route', route: window.location.pathname, routePattern: ${routePatternLiteral} }, '*');
 
-        // Embed mode: parent triggers freeze via postMessage
+        // Embed mode: parent triggers freeze / inspect via postMessage
         window.addEventListener('message', (e) => {
-          if (e.data?.type === 'jay:requestFreeze') __jayDoFreeze();
+          const d = e.data;
+          if (!d) return;
+          if (d.type === 'jay:requestFreeze') { __jayDoFreeze(); return; }
+          if (d.type === 'jay:inspectPoint' || d.type === 'jay:inspectRect') {
+            const result = d.type === 'jay:inspectPoint'
+              ? __jayInspectPoint(d.x, d.y)
+              : __jayInspectRect(d.x, d.y, d.width, d.height);
+            window.parent.postMessage({
+              type: 'jay:inspectResult',
+              requestId: d.requestId,
+              file: ${sourceFileLiteral},
+              route: window.location.pathname,
+              routePattern: ${routePatternLiteral},
+              node: result ? result.node : null,   // node.rect is the matched element's on-screen box
+              stack: result ? result.stack : [],
+            }, '*');
+          }
         });
       } else {
         // Standalone: Alt+S / Option+S keyboard shortcut
@@ -2105,7 +2259,7 @@ function buildAutomationWrap(options, mode) {
   }
   const appendLine = appendDom ? `
       target.appendChild(wrapped.element.dom);` : "";
-  const freezeScript = buildFreezeScript(options.routePattern);
+  const freezeScript = buildFreezeScript(options.routePattern, options.sourceFile);
   if (hasSlowViewState) {
     return `
       // Wrap with automation for dev tooling
@@ -4547,7 +4701,9 @@ function defaults(options) {
       pagesRoot: pagesRootFolder,
       buildFolder
     },
-    httpServer: options.httpServer
+    httpServer: options.httpServer,
+    allowedHosts: options.allowedHosts,
+    sourceEditing: options.sourceEditing
   };
 }
 let _renderDevErrorPage = async (res, info) => {
@@ -4908,7 +5064,8 @@ async function handlePreRenderRequest(vite, route, options, slowlyPhase, slowRen
     initialPartsResult.val.headlessInstanceComponents,
     partKeys,
     pageParams,
-    pageProps
+    pageProps,
+    options.sourceEditing
   );
   timing?.recordSlowRender(Date.now() - slowStart);
   if (!preRenderResult) {
@@ -5056,7 +5213,8 @@ async function handleClientOnlyRequest(vite, route, options, slowlyPhase, pagePa
     pluginsForPage,
     {
       enableAutomation: !options.disableAutomation,
-      routePattern: routeToExpressRoute(route)
+      routePattern: routeToExpressRoute(route),
+      sourceFile: path__default.relative(options.projectRootFolder, route.jayHtmlPath)
     }
   );
   if (options.buildFolder) {
@@ -5073,9 +5231,11 @@ async function handleClientOnlyRequest(vite, route, options, slowlyPhase, pagePa
 }
 async function sendResponse(vite, res, url, jayHtmlPath, sourceJayHtmlPath, pageParts, viewState, carryForward, clientTrackByMap, projectInit, pluginsForPage, options, routePattern, routeDir, slowViewState, timing, preLoadedContent, headTags, scripts, statusCode = 200) {
   let pageHtml;
+  const sourceFile = path__default.relative(options.projectRootFolder, sourceJayHtmlPath);
   try {
     const jayHtmlDir = path__default.dirname(jayHtmlPath);
-    const jayHtmlContent = preLoadedContent ?? await fs__default.readFile(jayHtmlPath, "utf-8");
+    const rawContent = preLoadedContent ?? await fs__default.readFile(jayHtmlPath, "utf-8");
+    const jayHtmlContent = options.sourceEditing ? injectDevMarkers(rawContent) : rawContent;
     pageHtml = await generateSSRPageHtml(
       vite,
       jayHtmlContent,
@@ -5096,7 +5256,8 @@ async function sendResponse(vite, res, url, jayHtmlPath, sourceJayHtmlPath, page
       {
         enableAutomation: !options.disableAutomation,
         slowViewState,
-        routePattern
+        routePattern,
+        sourceFile
       },
       void 0,
       headTags,
@@ -5116,7 +5277,8 @@ async function sendResponse(vite, res, url, jayHtmlPath, sourceJayHtmlPath, page
       {
         enableAutomation: !options.disableAutomation,
         slowViewState,
-        routePattern
+        routePattern,
+        sourceFile
       }
     );
   }
@@ -5187,8 +5349,9 @@ async function handleFrozenRequest(vite, route, options, freezeStore, slowRender
   }
   timing?.end();
 }
-async function preRenderJayHtml(route, slowViewState, headlessContracts, headlessInstanceComponents, partKeys = [], pageParams = {}, pageProps = { language: "en", url: "" }) {
-  const jayHtmlWithTemplates = await fs__default.readFile(route.jayHtmlPath, "utf-8");
+async function preRenderJayHtml(route, slowViewState, headlessContracts, headlessInstanceComponents, partKeys = [], pageParams = {}, pageProps = { language: "en", url: "" }, sourceEditing = false) {
+  const rawJayHtml = await fs__default.readFile(route.jayHtmlPath, "utf-8");
+  const jayHtmlWithTemplates = sourceEditing ? injectDevMarkers(rawJayHtml) : rawJayHtml;
   const sourceDir = path__default.dirname(route.jayHtmlPath);
   let contract;
   const contractPath = route.jayHtmlPath.replace(".jay-html", ".jay-contract");
@@ -5307,7 +5470,8 @@ async function mkDevServer(rawOptions) {
     base: publicBaseUrlPath,
     jayRollupConfig,
     logLevel: viteLogLevel,
-    httpServer: options.httpServer
+    httpServer: options.httpServer,
+    allowedHosts: options.allowedHosts
   });
   lifecycleManager.setViteServer(vite);
   await lifecycleManager.initialize();
@@ -5529,6 +5693,9 @@ function setupSlowRenderCacheInvalidation(vite, cache, pagesRootFolder, projectR
     }
   };
   vite.watcher.on("change", (changedPath) => {
+    if (/\.(ts|tsx|jay-contract)$/.test(changedPath)) {
+      noteExportedTypesFileChanged(changedPath);
+    }
     if (watchedFiles.has(changedPath)) {
       clearServerElementCache();
       cache.clear().then(() => {
@@ -5596,5 +5763,6 @@ export {
   createActionRouter,
   createViteForCli,
   createViteServer,
-  mkDevServer
+  mkDevServer,
+  resolveAllowedHosts
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jay-framework/dev-server",
-  "version": "0.25.4",
+  "version": "0.25.5",
   "type": "module",
   "license": "Apache-2.0",
   "main": "dist/index.js",
@@ -23,24 +23,24 @@
     "test:watch": "vitest"
   },
   "dependencies": {
-    "@jay-framework/compiler-jay-stack": "^0.25.4",
-    "@jay-framework/compiler-shared": "^0.25.4",
-    "@jay-framework/component": "^0.25.4",
-    "@jay-framework/fullstack-component": "^0.25.4",
-    "@jay-framework/logger": "^0.25.4",
-    "@jay-framework/runtime": "^0.25.4",
-    "@jay-framework/stack-client-runtime": "^0.25.4",
-    "@jay-framework/stack-route-scanner": "^0.25.4",
-    "@jay-framework/stack-server-build": "^0.25.4",
-    "@jay-framework/stack-server-runtime": "^0.25.4",
-    "@jay-framework/view-state-merge": "^0.25.4",
+    "@jay-framework/compiler-jay-stack": "^0.25.5",
+    "@jay-framework/compiler-shared": "^0.25.5",
+    "@jay-framework/component": "^0.25.5",
+    "@jay-framework/fullstack-component": "^0.25.5",
+    "@jay-framework/logger": "^0.25.5",
+    "@jay-framework/runtime": "^0.25.5",
+    "@jay-framework/stack-client-runtime": "^0.25.5",
+    "@jay-framework/stack-route-scanner": "^0.25.5",
+    "@jay-framework/stack-server-build": "^0.25.5",
+    "@jay-framework/stack-server-runtime": "^0.25.5",
+    "@jay-framework/view-state-merge": "^0.25.5",
     "busboy": "^1.6.0",
     "vite": "^5.0.11"
   },
   "devDependencies": {
-    "@jay-framework/dev-environment": "^0.25.4",
-    "@jay-framework/jay-cli": "^0.25.4",
-    "@jay-framework/stack-client-runtime": "^0.25.4",
+    "@jay-framework/dev-environment": "^0.25.5",
+    "@jay-framework/jay-cli": "^0.25.5",
+    "@jay-framework/stack-client-runtime": "^0.25.5",
     "@playwright/test": "^1.58.2",
     "@types/busboy": "^1.5.4",
     "@types/express": "^5.0.2",