@jxsuite/server 0.37.1 → 1.1.0

package/src/dev-vars.ts

@@ -0,0 +1,61 @@
+/**
+ * Dev-vars — `<project>/.dev.vars` parsing (wrangler convention, specs/extensions.md §13).
+ *
+ * Secret VALUES never enter project.json; locally they live in the git-ignored .dev.vars file and
+ * the dev server merges them over process.env when constructing mount environments. The format is
+ * dotenv-shaped: KEY=VALUE lines, `#` comments, optional single/double quotes. The compiler CLI
+ * keeps its own tiny copy (db-push.ts) — the compiler cannot depend on this package.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+
+/**
+ * Parse .dev.vars text into a name → value record.
+ *
+ * @param {string} text
+ * @returns {Record<string, string>}
+ */
+export function parseDevVars(text: string): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const rawLine of text.split("\n")) {
+    const line = rawLine.trim();
+    if (line === "" || line.startsWith("#")) {
+      continue;
+    }
+    const eq = line.indexOf("=");
+    if (eq === -1) {
+      continue;
+    }
+    const key = line.slice(0, eq).trim();
+    let value = line.slice(eq + 1).trim();
+    if (
+      (value.startsWith('"') && value.endsWith('"')) ||
+      (value.startsWith("'") && value.endsWith("'"))
+    ) {
+      value = value.slice(1, -1);
+    }
+    if (key !== "") {
+      out[key] = value;
+    }
+  }
+  return out;
+}
+
+/**
+ * Load `<projectRoot>/.dev.vars`, or an empty record when absent.
+ *
+ * @param {string} projectRoot
+ * @returns {Record<string, string>}
+ */
+export function loadDevVars(projectRoot: string): Record<string, string> {
+  const path = resolve(projectRoot, ".dev.vars");
+  if (!existsSync(path)) {
+    return {};
+  }
+  try {
+    return parseDevVars(readFileSync(path, "utf8"));
+  } catch {
+    return {};
+  }
+}

package/src/dev.ts

@@ -0,0 +1,141 @@
+/**
+ * Dev-server CLI entry — what `jx dev` spawns under Bun in a standalone project.
+ *
+ * Usage: bun @jxsuite/server/dev [--root <dir>] [--port <n>]
+ *
+ * For a site project (a project.json at the root), the entry builds the site up front, serves the
+ * built pages from dist/ ahead of the static-source fallback, and rebuilds before each live-reload
+ * broadcast so the browser always reloads into fresh output. Argument parsing and the middleware
+ * factory are exported for tests; the server boot runs only when executed directly
+ * (import.meta.main).
+ *
+ * @module @jxsuite/server/dev
+ */
+
+import { existsSync, statSync } from "node:fs";
+import { join, normalize, resolve, sep } from "node:path";
+import { createDevServer } from "./server.ts";
+import { injectSSE } from "./watch.ts";
+
+export interface DevArgs {
+  port: number;
+  root: string;
+}
+
+/**
+ * Parse `--root`/`--port` (plus an optional positional root) into dev-server options.
+ *
+ * @param {string[]} argv - Raw arguments (process.argv.slice(2))
+ * @returns {DevArgs} Resolved root and port (default 3000)
+ */
+export function parseDevArgs(argv: string[]): DevArgs {
+  let root = ".";
+  let port = 3000;
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index]!;
+    if (arg === "--root") {
+      index += 1;
+      root = argv[index] ?? root;
+    } else if (arg === "--port") {
+      index += 1;
+      const parsed = Math.trunc(Number(argv[index] ?? ""));
+      if (Number.isFinite(parsed) && parsed >= 0) {
+        port = parsed;
+      }
+    } else if (!arg.startsWith("--")) {
+      root = arg;
+    }
+  }
+  return { port, root: resolve(root) };
+}
+
+/**
+ * Middleware serving built pages from `<root>/dist` for page-like GET requests. Directory URLs
+ * (with or without a trailing slash) map to their index.html; anything not present in dist falls
+ * through to the dev server's static-source handling.
+ *
+ * @param {string} root - Absolute project root
+ * @returns {(req: Request, url: URL) => Response | null}
+ */
+export function createDistMiddleware(
+  root: string,
+): (req: Request, url: URL) => Promise<Response | null> {
+  const distDir = join(root, "dist");
+  return async (req, url) => {
+    if (req.method !== "GET") {
+      return null;
+    }
+    const safe = normalize(decodeURIComponent(url.pathname)).replaceAll("\\", "/");
+    const candidate = resolve(distDir, `.${safe.startsWith("/") ? safe : `/${safe}`}`);
+    if (candidate !== distDir && !candidate.startsWith(distDir + sep)) {
+      return null;
+    }
+    let filePath: string | null = null;
+    if (existsSync(candidate)) {
+      filePath = statSync(candidate).isDirectory() ? join(candidate, "index.html") : candidate;
+    } else {
+      filePath = join(candidate, "index.html");
+    }
+    if (!filePath || !existsSync(filePath)) {
+      return null;
+    }
+    // Built pages get the live-reload client, like the server's own .html responses
+    if (filePath.endsWith(".html")) {
+      const html = await Bun.file(filePath).text();
+      return new Response(injectSSE(html), {
+        headers: { "Cache-Control": "no-cache", "Content-Type": "text/html; charset=utf-8" },
+      });
+    }
+    return new Response(Bun.file(filePath), { headers: { "Cache-Control": "no-cache" } });
+  };
+}
+
+export interface DevServerHandle {
+  port: number;
+  stop: () => void;
+}
+
+/**
+ * Boot the dev server for a root. Site projects (a project.json at the root) are built up front and
+ * rebuilt before every live-reload broadcast, with built pages served from dist/.
+ *
+ * @param {DevArgs} args - Resolved root and port
+ * @returns {Promise<DevServerHandle>} The listening server
+ */
+export async function startDev({ port, root }: DevArgs): Promise<DevServerHandle> {
+  const isSite = existsSync(join(root, "project.json"));
+
+  let building = Promise.resolve();
+  const rebuild = () => {
+    building = building.then(async () => {
+      const { buildSite } = await import("@jxsuite/compiler/site");
+      const result = await buildSite(root, { verbose: false });
+      if (result.errors.length > 0) {
+        for (const err of result.errors) {
+          console.error(`  build error: ${err}`);
+        }
+      }
+    });
+    return building;
+  };
+
+  if (isSite) {
+    console.log(`Building ${root}...`);
+    await rebuild();
+  }
+
+  return (await createDevServer({
+    port,
+    root,
+    ...(isSite && {
+      middleware: createDistMiddleware(root),
+      watch: { preReload: () => rebuild(), reloadOnAnyChange: true },
+    }),
+  })) as DevServerHandle;
+}
+
+if (import.meta.main) {
+  const { port, root } = parseDevArgs(process.argv.slice(2));
+  const server = await startDev({ port, root });
+  console.log(`Jx dev server running at http://localhost:${server.port} (root: ${root})`);
+}

package/src/jx-mounts.ts

@@ -0,0 +1,166 @@
+/**
+ * Jx-mounts — registry-driven `/_jx/*` dispatch for the dev server (specs/extensions.md §11).
+ *
+ * Extension classes with a `server` block mount the same fetch-style handlers here that the
+ * generated site worker mounts in production: one shared context object per project, handlers built
+ * once via the static `mount(options, ctx)` capability and dispatched by basePath prefix.
+ *
+ * Dev conveniences over the production worker:
+ *
+ * - `env` is process.env merged under the project's `.dev.vars` plus `JX_PROJECT_ROOT`;
+ * - Connector classes with `local: "<provider>"` are stood in by the registry's class for that
+ *   provider (e.g. D1 → sqlite at `<project>/.jx/data/<connection>.sqlite`);
+ * - Mount options set `autoSync: true`, so table schemas sync additively on first touch.
+ *
+ * The runtime is cached per project root and invalidated when project.json changes on disk.
+ */
+
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { resolve } from "node:path";
+import { buildProjectExtensionRegistry } from "@jxsuite/compiler/format-host";
+import { loadDevVars } from "./dev-vars.ts";
+import type { ExtensionRegistry } from "@jxsuite/schema/extension-registry";
+import type { FormatEntry } from "@jxsuite/schema/format-registry";
+import type { ProjectConfig } from "@jxsuite/schema/types";
+
+type MountHandler = (request: Request, env: Record<string, unknown>) => Promise<Response>;
+
+interface MountRuntime {
+  handlers: { basePath: string; handler: MountHandler }[];
+  env: Record<string, unknown>;
+}
+
+/** Per-project runtime cache, invalidated when project.json's mtime moves. */
+const runtimeCache = new Map<string, { mtime: number; runtime: Promise<MountRuntime | null> }>();
+
+/** Reset the runtime cache (test hook). */
+export function resetJxMounts(): void {
+  runtimeCache.clear();
+}
+
+/**
+ * Dispatch a `/_jx/*` request to the project's extension mounts.
+ *
+ * @param {Request} req
+ * @param {URL} url
+ * @param {string} projectRoot - Absolute project root (the active studio project, or the server
+ *   root)
+ * @returns {Promise<Response | null>} A response, or null when no mount claims the path
+ */
+export async function handleJxMounts(
+  req: Request,
+  url: URL,
+  projectRoot: string,
+): Promise<Response | null> {
+  if (!url.pathname.startsWith("/_jx/")) {
+    return null;
+  }
+  const runtime = await getRuntime(projectRoot);
+  if (!runtime) {
+    return null;
+  }
+  for (const { basePath, handler } of runtime.handlers) {
+    if (url.pathname === basePath || url.pathname.startsWith(`${basePath}/`)) {
+      return handler(req, runtime.env);
+    }
+  }
+  return null;
+}
+
+/** Load (or reuse) the mount runtime for a project root. */
+function getRuntime(projectRoot: string): Promise<MountRuntime | null> {
+  const projectJsonPath = resolve(projectRoot, "project.json");
+  if (!existsSync(projectJsonPath)) {
+    return Promise.resolve(null);
+  }
+  const { mtimeMs } = statSync(projectJsonPath);
+  const cached = runtimeCache.get(projectRoot);
+  if (cached && cached.mtime === mtimeMs) {
+    return cached.runtime;
+  }
+  const runtime = buildRuntime(projectRoot, projectJsonPath).catch((error) => {
+    console.warn(
+      `jx-mounts: failed to build extension mounts for ${projectRoot}:`,
+      error instanceof Error ? error.message : String(error),
+    );
+    return null;
+  });
+  runtimeCache.set(projectRoot, { mtime: mtimeMs, runtime });
+  return runtime;
+}
+
+/** Build the runtime: registry, sections, connector stand-ins, and the ordered mount handlers. */
+async function buildRuntime(
+  projectRoot: string,
+  projectJsonPath: string,
+): Promise<MountRuntime | null> {
+  const config = JSON.parse(readFileSync(projectJsonPath, "utf8")) as ProjectConfig;
+  const registry = await buildProjectExtensionRegistry(projectRoot, config);
+  const mounts = registry.serverMounts();
+  if (mounts.length === 0) {
+    return null;
+  }
+
+  const sections: Record<string, unknown> = {};
+  for (const contribution of registry.projectContributions()) {
+    const { key } = contribution.project!;
+    if (key in config) {
+      sections[key] = config[key];
+    }
+  }
+
+  const connectors = await resolveConnectorStandins(registry);
+  const env: Record<string, unknown> = {
+    ...process.env,
+    ...loadDevVars(projectRoot),
+    JX_PROJECT_ROOT: projectRoot,
+  };
+
+  // One shared mutable context, passed to every mount in order (specs/extensions.md §11).
+  const ctx: Record<string, unknown> = {};
+  const handlers: MountRuntime["handlers"] = [];
+  for (const entry of mounts) {
+    const { basePath } = entry.server!;
+    const handler = (await entry.call(
+      "mount",
+      { autoSync: true, basePath, connectors, sections },
+      ctx,
+    )) as MountHandler;
+    handlers.push({ basePath, handler });
+  }
+  return { env, handlers };
+}
+
+/**
+ * Resolve connector implementation classes keyed by provider id, applying the dev-server `local`
+ * stand-in rule: a connector declaring `local: "<provider>"` is served by the registry's class for
+ * that provider instead of its own (specs/extensions.md §12). Shared with the data-api push seam so
+ * section-owner deploySchema contributions (e.g. auth) see the same stand-ins as the mounts.
+ *
+ * @param {ExtensionRegistry} registry
+ * @returns {Promise<Record<string, unknown>>}
+ */
+export async function resolveConnectorStandins(
+  registry: ExtensionRegistry,
+): Promise<Record<string, unknown>> {
+  const entries = registry.connectors();
+  const out: Record<string, unknown> = {};
+  for (const entry of entries) {
+    const provider = String(entry.connector!.provider);
+    const { local } = entry.connector!;
+    const target =
+      typeof local === "string"
+        ? (entries.find((e) => e.connector!.provider === local) ?? entry)
+        : entry;
+    out[provider] = await implementationClass(target);
+  }
+  return out;
+}
+
+/** Import a connector entry's implementation module and pick the export named by its title. */
+async function implementationClass(entry: FormatEntry): Promise<unknown> {
+  const mod = await entry.implementation();
+  const title = (entry.classDef.title as string | undefined) ?? entry.name;
+  const fromDefault = (mod.default as Record<string, unknown> | undefined)?.[title];
+  return mod[title] ?? fromDefault ?? mod.default;
+}

package/src/project-server.ts

@@ -27,6 +27,7 @@
 
 import { isAbsolute, relative, resolve, sep } from "node:path";
 import { realpathSync } from "node:fs";
+import { handleJxMounts } from "./jx-mounts.ts";
 import { handleResolve, handleServerFunction } from "./resolve.ts";
 import { handleAiApi } from "./ai-api.ts";
 import { handleImportApi } from "./import-api.ts";
@@ -327,6 +328,15 @@ export function createProjectServer(options: CreateProjectServerOptions): Projec
         return new Response("No project", { status: 404 });
       }
 
+      // 4b. Extension server mounts (/_jx/data etc.) — registry-driven, same wire contract as
+      //     The generated site worker and the dev server (specs/extensions.md §11).
+      if (normPath.startsWith("/_jx/")) {
+        const mountRes = await handleJxMounts(req, url, root);
+        if (mountRes) {
+          return mountRes;
+        }
+      }
+
       // 5. Privileged HTTP routes (RCE-capable: dynamic import()). Gate with token + loopback
       //    Origin/Host BEFORE dispatch.
       if (

package/src/resolve.ts

@@ -2,9 +2,10 @@
 
 import { dirname, relative, resolve } from "node:path";
 import { errorMessage, parseClassDef } from "@jxsuite/schema/parse";
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, readFileSync, statSync } from "node:fs";
 import { createRequire } from "node:module";
-import { loadContentTypes } from "@jxsuite/compiler/content-loader";
+import { buildProjectExtensionRegistry } from "@jxsuite/compiler/format-host";
+import { loadProjectSections } from "@jxsuite/compiler/project-sections";
 import type { DynamicClass } from "@jxsuite/runtime/types";
 import type { JxClassDef, ProjectConfig } from "@jxsuite/schema/types";
 
@@ -35,15 +36,16 @@ interface ServerFunctionBody {
   [key: string]: unknown;
 }
 
+/** Per-project context cache, invalidated when project.json changes on disk. */
+const projectContextCache = new Map<string, { mtime: number; context: Record<string, unknown> }>();
+
 /**
- * Lazy-load project context (project.json + content types) for class instantiation.
+ * Lazy-load project context (project.json + extension-loaded sections) for class instantiation.
+ * Sections land under their section keys (e.g. `content` for the parser), matching the compiler's
+ * `_project` shape.
  *
  * @param {string} projectRoot
- * @returns {Promise<{
- *   config: Record<string, unknown>;
- *   contentTypes: Map<string, unknown[]>;
- *   root: string;
- * } | null>}
+ * @returns {Promise<Record<string, unknown> | null>} `{ config, root, ...sections }` or null
  */
 async function loadProjectContext(projectRoot: string) {
   const projectJsonPath = resolve(projectRoot, "project.json");
@@ -51,11 +53,17 @@ async function loadProjectContext(projectRoot: string) {
     return null;
   }
   try {
+    const { mtimeMs } = statSync(projectJsonPath);
+    const cached = projectContextCache.get(projectRoot);
+    if (cached && cached.mtime === mtimeMs) {
+      return cached.context;
+    }
     const config = JSON.parse(readFileSync(projectJsonPath, "utf8")) as ProjectConfig;
-    const contentTypes = config.contentTypes
-      ? await loadContentTypes(projectRoot, config)
-      : new Map();
-    return { config, contentTypes, root: projectRoot };
+    const registry = await buildProjectExtensionRegistry(projectRoot, config);
+    const sections = await loadProjectSections(projectRoot, config, registry);
+    const context = { config, root: projectRoot, ...sections };
+    projectContextCache.set(projectRoot, { context, mtime: mtimeMs });
+    return context;
   } catch {
     return null;
   }

package/src/server.ts

@@ -17,6 +17,7 @@ import { join, relative, resolve } from "node:path";
 import { buildAll } from "./build.ts";
 import { createCollabRegistry } from "./collab.ts";
 import { createWatcher, injectSSE } from "./watch.ts";
+import { handleJxMounts } from "./jx-mounts.ts";
 import { handleResolve, handleServerFunction } from "./resolve.ts";
 import { assertAccessible, handleStudioApi } from "./studio-api.ts";
 import { handleCodeApi } from "./code-api.ts";
@@ -268,6 +269,15 @@ export async function createDevServer(options: {
         return handleServerFunction(req, absRoot);
       }
 
+      // Extension server mounts (/_jx/data etc.) — registry-driven, same wire contract as the
+      // Generated site worker (specs/extensions.md §11).
+      if (path.startsWith("/_jx/")) {
+        const mountRes = await handleJxMounts(req, url, activeProjectRoot ?? absRoot);
+        if (mountRes) {
+          return mountRes;
+        }
+      }
+
       // Studio filesystem API
       if (enableStudio && path.startsWith("/__studio/")) {
         // Realtime co-editing: WebSocket upgrade or capability probe

package/src/studio-api.ts

@@ -11,7 +11,12 @@ import { basename, dirname, extname, isAbsolute, join, relative, resolve } from
 import { errorMessage } from "@jxsuite/schema/parse";
 import { mkdir, readFile, readdir, rename, stat, unlink, writeFile } from "node:fs/promises";
 import { existsSync, readFileSync, statSync } from "node:fs";
-import { buildProjectFormatRegistry } from "@jxsuite/compiler/format-host";
+import {
+  buildExtensionsPayload,
+  buildProjectExtensionRegistry,
+} from "@jxsuite/compiler/format-host";
+import { readBundledProjectSchemas } from "@jxsuite/compiler/schema-command";
+import { handleDataApi } from "./data-api.ts";
 import { applyRename } from "./refactor/apply.ts";
 import {
   bunExecutable,
@@ -20,6 +25,7 @@ import {
   outdatedPackages,
   setPackageVersions,
 } from "./packages.ts";
+import type { ExtensionRegistry } from "@jxsuite/schema/extension-registry";
 import type { FormatRegistry } from "@jxsuite/schema/format-registry";
 import type { ClassJsonDef } from "./types.ts";
 import type { DesignOptions } from "@jxsuite/create/generate";
@@ -113,18 +119,18 @@ function collectSlotDefs(node: unknown, out: SlotDef[] = []): SlotDef[] {
   return out;
 }
 
-// ─── Format registry (per project root, invalidated on project.json change) ──
+// ─── Extension registry (per project root, invalidated on project.json change) ──
 
-const formatRegistryCache = new Map<string, { mtime: number; registry: FormatRegistry }>();
+const extensionRegistryCache = new Map<string, { mtime: number; registry: ExtensionRegistry }>();
 
 /**
- * Build (or reuse) the format registry for a project root from its project.json imports map. An
- * empty registry is returned when there is no project.json — only .json files are handled then.
+ * Build (or reuse) a project's extension registry (built from its project.json `extensions` array).
+ * An empty registry is returned when there is no project.json — only .json files are handled then.
  *
  * @param {string} projectRoot
- * @returns {Promise<FormatRegistry>}
+ * @returns {Promise<ExtensionRegistry>}
  */
-async function getFormatRegistry(projectRoot: string): Promise<FormatRegistry> {
+async function getExtensionRegistry(projectRoot: string): Promise<ExtensionRegistry> {
   const projectJsonPath = resolve(projectRoot, "project.json");
   let mtime = 0;
   let projectConfig: ProjectConfig | undefined;
@@ -134,15 +140,21 @@ async function getFormatRegistry(projectRoot: string): Promise<FormatRegistry> {
   } catch {
     projectConfig = undefined;
   }
-  const cached = formatRegistryCache.get(projectRoot);
+  const cached = extensionRegistryCache.get(projectRoot);
   if (cached && cached.mtime === mtime) {
     return cached.registry;
   }
-  const registry = await buildProjectFormatRegistry(projectRoot, projectConfig);
-  formatRegistryCache.set(projectRoot, { mtime, registry });
+  const registry = await buildProjectExtensionRegistry(projectRoot, projectConfig);
+  extensionRegistryCache.set(projectRoot, { mtime, registry });
   return registry;
 }
 
+/** Format-dispatch view of {@link getExtensionRegistry} (parse/serialize/discover/load lookups). */
+async function getFormatRegistry(projectRoot: string): Promise<FormatRegistry> {
+  const registry = await getExtensionRegistry(projectRoot);
+  return registry.formats;
+}
+
 /**
  * Check that a path is under either the server root OR the active project root. This allows file
  * operations on external projects that have been explicitly activated via /__studio/activate.
@@ -260,6 +272,12 @@ export async function handleStudioApi(
 ) {
   const path = url.pathname;
 
+  // Data-domain owner console + secrets (names only) — delegated to data-api.ts.
+  const dataRes = await handleDataApi(req, url, root, activeProjectRoot);
+  if (dataRes) {
+    return dataRes;
+  }
+
   // Project metadata
   if (path === "/__studio/project" && req.method === "GET") {
     try {
@@ -1154,15 +1172,18 @@ export async function handleStudioApi(
   }
 
   // Format registry listing — lets the studio introspect available formats without
-  // Fetching each .class.json itself.
+  // Fetching each .class.json itself. The sibling `extensions` array carries each enabled
+  // Extension's manifest identity and project-section contributions (additive; the `formats`
+  // Shape is unchanged for compat).
   if (path === "/__studio/formats" && req.method === "GET") {
     const dir = url.searchParams.get("dir") || activeProjectRoot || root;
     const projectRoot = isAbsolute(dir) ? dir : resolve(root, dir);
     try {
       assertAccessible(projectRoot, root, activeProjectRoot);
-      const registry = await getFormatRegistry(projectRoot);
+      const registry = await getExtensionRegistry(projectRoot);
       return Response.json({
-        formats: registry.entries.map((e) => ({
+        extensions: buildExtensionsPayload(registry),
+        formats: registry.formats.entries.map((e) => ({
           capabilities: e.capabilities,
           documentKinds: e.documentKinds,
           exportTarget: e.exportTarget,
@@ -1178,6 +1199,25 @@ export async function handleStudioApi(
     }
   }
 
+  // Pre-bundled per-project entry schemas (project.schema.json / document.schema.json) for the
+  // Studio's editor — regenerated on demand when missing or older than project.json, then bundled
+  // Into self-contained compound documents so no relative $ref resolution is needed client-side.
+  if (path === "/__studio/project-schemas" && req.method === "GET") {
+    const dir = url.searchParams.get("dir") || activeProjectRoot || root;
+    const projectRoot = isAbsolute(dir) ? dir : resolve(root, dir);
+    try {
+      assertAccessible(projectRoot, root, activeProjectRoot);
+    } catch (error) {
+      return Response.json({ error: errorMessage(error) }, { status: 400 });
+    }
+    try {
+      const { document, project } = await readBundledProjectSchemas(projectRoot);
+      return Response.json({ document, project });
+    } catch (error) {
+      return Response.json({ error: errorMessage(error) }, { status: 500 });
+    }
+  }
+
   if (path === "/__studio/plugin-schema" && req.method === "GET") {
     const src = url.searchParams.get("src");
     const prototype = url.searchParams.get("prototype");

package/src/watch.ts

@@ -10,6 +10,7 @@ import type { FsEventPayload } from "./refactor/fs-events.ts";
 const DEFAULT_IGNORE = [
   "**/node_modules/**",
   "**/dist/**",
+  "**/.cache/**",
   "**/.git/**",
   "**/.jx/**",
   "**/.devenv/**",
@@ -62,7 +63,12 @@ export function injectSSE(html: string) {
  *
  * @param {string} root - Absolute path to watch
  * @param {BuildEntry[]} builds - Build entries (for selective rebuild)
- * @param {{ ignore?: string[]; debounce?: number; reloadOnAnyChange?: boolean }} [opts]
+ * @param {{
+ *   ignore?: string[];
+ *   debounce?: number;
+ *   reloadOnAnyChange?: boolean;
+ *   preReload?: (filename: string) => Promise<void> | void;
+ * }} [opts]
  * @returns {{
  *   broadcast: () => void;
  *   handleSSE: () => Response;
@@ -76,11 +82,14 @@ export function createWatcher(
     ignore?: string[];
     debounce?: number;
     reloadOnAnyChange?: boolean;
+    /** Runs before the reload broadcast — e.g. `jx dev` rebuilds the site here. */
+    preReload?: (filename: string) => Promise<void> | void;
   } = {},
 ) {
   const ignore = opts.ignore ?? DEFAULT_IGNORE;
   const debounceMs = opts.debounce ?? 50;
   const reloadOnAnyChange = opts.reloadOnAnyChange ?? false;
+  const { preReload } = opts;
 
   const clients = new Set<(msg: string) => void>();
   const encoder = new TextEncoder();
@@ -172,6 +181,13 @@ export function createWatcher(
 
     clearTimeout(timer ?? undefined);
     timer = setTimeout(async () => {
+      if (preReload) {
+        try {
+          await preReload(filename);
+        } catch (error) {
+          console.error(`[watch] preReload failed: ${(error as Error).message}`);
+        }
+      }
       if (builds.length > 0) {
         const result = await rebuild(builds, filename);
         if (!result.success) {