@valbuild/server 0.97.3 → 0.97.4

package/dist/valbuild-server.esm.js

@@ -1,19 +1,19 @@
-import { newQuickJSWASMModule } from 'quickjs-emscripten';
 import ts from 'typescript';
 import { result, pipe } from '@valbuild/core/fp';
-import { FILE_REF_PROP, FILE_REF_SUBTYPE_TAG, VAL_EXTENSION, derefPatch, Internal, Schema, extractValModules, ImageSchema, DEFAULT_CONTENT_HOST } from '@valbuild/core';
+import { FILE_REF_PROP, FILE_REF_SUBTYPE_TAG, VAL_EXTENSION, derefPatch, extractValModules, Internal, ImageSchema, DEFAULT_CONTENT_HOST } from '@valbuild/core';
 import { deepEqual, isNotRoot, PatchError, parseAndValidateArrayIndex, applyPatch, JSONOps, deepClone, sourceToPatchPath } from '@valbuild/core/patch';
 import * as path from 'path';
 import path__default from 'path';
 import fs, { promises } from 'fs';
-import { transform } from 'sucrase';
-import { VAL_CSS_PATH, VAL_APP_ID, VAL_OVERLAY_ID } from '@valbuild/ui';
+import vm from 'node:vm';
+import { Module } from 'node:module';
 import { resolveSchemaSourceFixForError, getErrorMessageFromUnknownJson, Patch, ParentRef, VAL_ENABLE_COOKIE_NAME, VAL_STATE_COOKIE, VAL_SESSION_COOKIE, Api } from '@valbuild/shared/internal';
 import { createUIRequestHandler } from '@valbuild/ui/server';
 import crypto$1 from 'crypto';
 import { z } from 'zod';
 import sizeOf from 'image-size';
 import { fromError } from 'zod-validation-error';
+import { transform } from 'sucrase';
 import http from 'http';
 import https from 'https';
 
@@ -798,7 +798,7 @@ const ops = new TSOps(document => {
 });
 
 // TODO: rename to patchValFiles since we may write multiple files
-const patchValFile = async (id, rootDir, patch, sourceFileHandler, runtime) => {
+const patchValFile = async (id, rootDir, patch, sourceFileHandler) => {
   // const timeId = randomUUID();
   // console.time("patchValFile" + timeId);
   const filePath = sourceFileHandler.resolveSourceModulePath(getSyntheticContainingPath(rootDir), `.${id.replace(".val.ts", ".val").replace(".val.js", ".val").replace(".val.jsx", ".val").replace(".val.tsx", ".val")}`);
@@ -849,143 +849,6 @@ const patchSourceFile = (sourceFile, patch) => {
   return applyPatch(sourceFile, ops, patch);
 };
 
-const readValFile = async (moduleFilePath, rootDirPath, runtime, options) => {
-  const context = runtime.newContext();
-
-  // avoid failures when console.log is called
-  const logHandle = context.newFunction("log", () => {
-    // do nothing
-  });
-  const consoleHandle = context.newObject();
-  context.setProp(consoleHandle, "log", logHandle);
-  context.setProp(context.global, "console", consoleHandle);
-  consoleHandle.dispose();
-  logHandle.dispose();
-
-  // avoid failures when process.env is called
-  const envHandle = context.newObject();
-  const processHandle = context.newObject();
-  context.setProp(processHandle, "env", envHandle);
-  context.setProp(context.global, "process", processHandle);
-  const optionsHandle = context.newObject();
-  if (options) {
-    if (options.validate !== undefined) {
-      context.setProp(optionsHandle, "validate", context.newNumber(+options.validate));
-    }
-    if (options.source !== undefined) {
-      context.setProp(optionsHandle, "source", context.newNumber(+options.source));
-    }
-    if (options.schema !== undefined) {
-      context.setProp(optionsHandle, "schema", context.newNumber(+options.schema));
-    }
-  }
-  context.setProp(context.global, "__VAL_OPTIONS__", optionsHandle);
-  envHandle.dispose();
-  processHandle.dispose();
-  optionsHandle.dispose();
-  try {
-    const modulePath = `.${moduleFilePath.replace(".val.js", ".val").replace(".val.ts", ".val").replace(".val.tsx", ".val").replace(".val.jsx", ".val")}`;
-    const code = `import * as valModule from ${JSON.stringify(modulePath)};
-import { Internal } from "@valbuild/core";
-
-globalThis.valModule = { 
-  path: valModule?.default && Internal.getValPath(valModule?.default),
-  schema: !!globalThis['__VAL_OPTIONS__'].schema ? valModule?.default && Internal.getSchema(valModule?.default)?.["executeSerialize"]() : undefined,
-  source: !!globalThis['__VAL_OPTIONS__'].source ? valModule?.default && Internal.getSource(valModule?.default) : undefined,
-  validation: !!globalThis['__VAL_OPTIONS__'].validate ? valModule?.default && (Internal.validate ? Internal.validate(valModule.default, Internal.getValPath(valModule?.default) || "/",
-    Internal.getSource(valModule?.default)) : Internal.getSchema(valModule?.default)?.validate(
-    Internal.getValPath(valModule?.default) || "/",
-    Internal.getSource(valModule?.default)
-  )) : undefined,
-  defaultExport: !!valModule?.default,
-};
-`;
-    const result = context.evalCode(code, getSyntheticContainingPath(rootDirPath));
-    const fatalErrors = [];
-    if (result.error) {
-      const error = result.error.consume(context.dump);
-      console.error(`Fatal error reading val file: ${moduleFilePath}. Error: ${error.message}\n`, error.stack);
-      return {
-        path: moduleFilePath,
-        errors: {
-          invalidModulePath: moduleFilePath,
-          fatal: [{
-            message: `${error.name || "Unknown error"}: ${error.message || "<no message>"}`,
-            stack: error.stack
-          }]
-        }
-      };
-    } else {
-      result.value.dispose();
-      const valModule = context.getProp(context.global, "valModule").consume(context.dump);
-      if (
-      // if one of these are set it is a Val module, so must validate
-      (valModule === null || valModule === void 0 ? void 0 : valModule.path) !== undefined || (valModule === null || valModule === void 0 ? void 0 : valModule.schema) !== undefined || (valModule === null || valModule === void 0 ? void 0 : valModule.source) !== undefined) {
-        if (valModule.path !== moduleFilePath) {
-          fatalErrors.push(`Wrong c.define path! Expected: '${moduleFilePath}', found: '${valModule.path}'`);
-        } else if ((valModule === null || valModule === void 0 ? void 0 : valModule.schema) === undefined && options.schema) {
-          fatalErrors.push(`Expected val path: '${moduleFilePath}' to have a schema`);
-        } else if ((valModule === null || valModule === void 0 ? void 0 : valModule.source) === undefined && options.source) {
-          fatalErrors.push(`Expected val path: '${moduleFilePath}' to have a source`);
-        }
-      }
-      let errors = false;
-      if (fatalErrors.length > 0) {
-        errors = {
-          invalidModulePath: valModule.path !== moduleFilePath ? moduleFilePath : undefined,
-          fatal: fatalErrors.map(message => ({
-            message
-          }))
-        };
-      }
-      if (valModule !== null && valModule !== void 0 && valModule.validation) {
-        errors = {
-          ...(errors ? errors : {}),
-          validation: valModule.validation
-        };
-      }
-      return {
-        path: valModule.path || moduleFilePath,
-        // NOTE: we use path here, since SerializedModuleContent (maybe bad name?) can be used for whole modules as well as subparts of modules
-        source: valModule.source,
-        schema: valModule.schema,
-        errors
-      };
-    }
-  } finally {
-    context.dispose();
-  }
-};
-
-const getCompilerOptions = (rootDir, parseConfigHost) => {
-  const tsConfigPath = path__default.resolve(rootDir, "tsconfig.json");
-  const jsConfigPath = path__default.resolve(rootDir, "jsconfig.json");
-  let configFilePath;
-  if (parseConfigHost.fileExists(jsConfigPath)) {
-    configFilePath = jsConfigPath;
-  } else if (parseConfigHost.fileExists(tsConfigPath)) {
-    configFilePath = tsConfigPath;
-  } else {
-    throw Error(`Could not read config from: "${tsConfigPath}" nor "${jsConfigPath}". Root dir: "${rootDir}"`);
-  }
-  const {
-    config,
-    error
-  } = ts.readConfigFile(configFilePath, parseConfigHost.readFile.bind(parseConfigHost));
-  if (error) {
-    if (typeof error.messageText === "string") {
-      throw Error(`Could not parse config file: ${configFilePath}. Error: ${error.messageText}`);
-    }
-    throw Error(`Could not parse config file: ${configFilePath}. Error: ${error.messageText.messageText}`);
-  }
-  const optionsOverrides = undefined;
-  const parsedConfigFile = ts.parseJsonConfigFileContent(config, parseConfigHost, rootDir, optionsOverrides, configFilePath);
-  if (parsedConfigFile.errors.length > 0) {
-    throw Error(`Could not parse config file: ${configFilePath}. Errors: ${parsedConfigFile.errors.map(e => e.messageText).join("\n")}`);
-  }
-  return parsedConfigFile.options;
-};
-
 class ValSourceFileHandler {
   constructor(projectRoot, compilerOptions, host = {
     ...ts.sys,
@@ -1033,326 +896,204 @@ class ValSourceFileHandler {
   }
 }
 
-const JsFileLookupMapping = [
-// NOTE: first one matching will be used
-[".cjs.d.ts", [".esm.js", ".mjs.js"]], [".cjs.js", [".esm.js", ".mjs.js"]], [".cjs", [".mjs"]], [".d.ts", [".js", ".esm.js", ".mjs.js"]]];
-const MAX_CACHE_SIZE = 100 * 1024 * 1024; // 100 mb
-const MAX_OBJECT_KEY_SIZE = 2 ** 27; // https://stackoverflow.com/questions/13367391/is-there-a-limit-on-length-of-the-key-string-in-js-object
-
-class ValModuleLoader {
-  constructor(projectRoot, compilerOptions,
-  // TODO: remove this?
-  sourceFileHandler, host = {
-    ...ts.sys,
-    writeFile: (fileName, data, encoding) => {
-      fs.mkdirSync(path__default.dirname(fileName), {
-        recursive: true
-      });
-      fs.writeFileSync(fileName, typeof data === "string" ? data : new Uint8Array(data), encoding);
-    },
-    rmFile: fs.rmSync,
-    readBuffer: fileName => {
-      try {
-        return fs.readFileSync(fileName);
-      } catch {
-        return undefined;
-      }
-    }
-  }, disableCache = false) {
-    this.projectRoot = projectRoot;
-    this.compilerOptions = compilerOptions;
-    this.sourceFileHandler = sourceFileHandler;
-    this.host = host;
-    this.disableCache = disableCache;
-    this.cache = {};
-    this.cacheSize = 0;
+const getCompilerOptions = (rootDir, parseConfigHost) => {
+  const tsConfigPath = path__default.resolve(rootDir, "tsconfig.json");
+  const jsConfigPath = path__default.resolve(rootDir, "jsconfig.json");
+  let configFilePath;
+  if (parseConfigHost.fileExists(jsConfigPath)) {
+    configFilePath = jsConfigPath;
+  } else if (parseConfigHost.fileExists(tsConfigPath)) {
+    configFilePath = tsConfigPath;
+  } else {
+    throw Error(`Could not read config from: "${tsConfigPath}" nor "${jsConfigPath}". Root dir: "${rootDir}"`);
   }
-  getModule(modulePath) {
-    if (!modulePath) {
-      throw Error(`Illegal module path: "${modulePath}"`);
-    }
-    const code = this.host.readFile(modulePath);
-    if (!code) {
-      throw Error(`Could not read file "${modulePath}"`);
-    }
-    let compiledCode;
-    if (this.cache[code] && !this.disableCache) {
-      // TODO: use hash instead of code as key
-      compiledCode = this.cache[code];
-    } else {
-      compiledCode = transform(code, {
-        filePath: modulePath,
-        disableESTransforms: true,
-        transforms: ["typescript"]
-      }).code;
-      if (!this.disableCache) {
-        if (this.cacheSize > MAX_CACHE_SIZE) {
-          console.warn("Cache size exceeded, clearing cache");
-          this.cache = {};
-          this.cacheSize = 0;
-        }
-        if (code.length < MAX_OBJECT_KEY_SIZE) {
-          this.cache[code] = compiledCode;
-          this.cacheSize += code.length + compiledCode.length; // code is mostly ASCII so 1 byte per char
-        }
-      }
+  const {
+    config,
+    error
+  } = ts.readConfigFile(configFilePath, parseConfigHost.readFile.bind(parseConfigHost));
+  if (error) {
+    if (typeof error.messageText === "string") {
+      throw Error(`Could not parse config file: ${configFilePath}. Error: ${error.messageText}`);
     }
-    return compiledCode;
+    throw Error(`Could not parse config file: ${configFilePath}. Error: ${error.messageText.messageText}`);
   }
-  resolveModulePath(containingFilePath, requestedModuleName) {
-    var _this$host$realpath, _this$host;
-    let sourceFileName = this.sourceFileHandler.resolveSourceModulePath(containingFilePath, requestedModuleName);
-    if (requestedModuleName === "@vercel/stega") {
-      sourceFileName = this.sourceFileHandler.resolveSourceModulePath(containingFilePath, "@vercel/stega").replace("stega/dist", "stega/dist/esm");
-    }
-    const matches = this.findMatchingJsFile(sourceFileName);
-    if (matches.match === false) {
-      let debugInfo = "";
-      if (sourceFileName.includes("val.config")) {
-        debugInfo = `\n@valbuild directory scan:\n${this.host.readDirectory("/", ["js", "ts", "json"], [], ["**/@valbuild/*"]).join("\n")}`;
-      }
-      throw Error(`Could not find matching js file for module "${requestedModuleName}" requested by: "${containingFilePath}". Tried:\n${matches.tried.join("\n")}${debugInfo}`);
-    }
-    const filePath = matches.match;
-    // resolve all symlinks (preconstruct for example symlinks the dist folder)
-    const followedPath = ((_this$host$realpath = (_this$host = this.host).realpath) === null || _this$host$realpath === void 0 ? void 0 : _this$host$realpath.call(_this$host, filePath)) ?? filePath;
-    if (!followedPath) {
-      throw Error(`File path was empty: "${filePath}", containing file: "${containingFilePath}", requested module: "${requestedModuleName}"`);
-    }
-    return followedPath;
+  const optionsOverrides = undefined;
+  const parsedConfigFile = ts.parseJsonConfigFileContent(config, parseConfigHost, rootDir, optionsOverrides, configFilePath);
+  if (parsedConfigFile.errors.length > 0) {
+    throw Error(`Could not parse config file: ${configFilePath}. Errors: ${parsedConfigFile.errors.map(e => e.messageText).join("\n")}`);
   }
-  findMatchingJsFile(filePath) {
-    let requiresReplacements = false;
-    for (const [currentEnding] of JsFileLookupMapping) {
-      if (filePath.endsWith(currentEnding)) {
-        requiresReplacements = true;
-        break;
-      }
-    }
-    // avoid unnecessary calls to fileExists if we don't need to replace anything
-    if (!requiresReplacements) {
-      if (this.host.fileExists(filePath)) {
-        return {
-          match: filePath
-        };
-      }
-    }
-    const tried = [];
-    for (const [currentEnding, replacements] of JsFileLookupMapping) {
-      if (filePath.endsWith(currentEnding)) {
-        for (const replacement of replacements) {
-          const newFilePath = filePath.slice(0, -currentEnding.length) + replacement;
-          if (this.host.fileExists(newFilePath)) {
-            return {
-              match: newFilePath
-            };
-          } else {
-            tried.push(newFilePath);
-          }
-        }
-      }
+  return parsedConfigFile.options;
+};
+
+/**
+ * Loads the project's root `val.modules.ts` (or `.js`) using Node's `vm`
+ * module and returns its default export (a `ValModules` registry).
+ *
+ * This is a recursive CommonJS loader: the root modules file and every
+ * relative `*.val.ts` / `val.config.ts` it (dynamically) imports are
+ * transpiled to CommonJS and evaluated in a `vm` sandbox. Bare specifiers
+ * (e.g. `@valbuild/core`) are resolved with the real Node `require` so the
+ * user modules share the exact same `@valbuild/core` instance that
+ * `extractValModules` uses.
+ *
+ * Mirrors the pattern already used by the CLI's `evalValConfigFile`.
+ *
+ * SECURITY: The `vm` context is NOT a security sandbox. It deliberately exposes
+ * `process` and a `require` that falls back to the real Node resolver (so user
+ * modules share the same `@valbuild/core` instance). This loader must therefore
+ * only ever be used to evaluate the project's own first-party, trusted files
+ * (`val.modules` and the local `*.val.ts`/`val.config.ts` it imports) — i.e. the
+ * same trust level as running the project's build. It must never be used to
+ * evaluate untrusted or third-party modules.
+ */
+function loadValModules(projectRoot) {
+  const valModulesPath = findValModulesPath(projectRoot);
+  if (!valModulesPath) {
+    throw Error(`Could not find 'val.modules.ts' nor 'val.modules.js' in project root: '${projectRoot}'`);
+  }
+  const compilerOptions = getCompilerOptions(projectRoot, ts.sys);
+  const cache = {};
+  const loaded = loadModule(valModulesPath, cache, compilerOptions);
+  const valModules = loaded.exports.default;
+  if (!valModules) {
+    throw Error(`Val modules file at path: '${valModulesPath}' must have a default export. Got: ${valModules}`);
+  }
+  return valModules;
+}
+function findValModulesPath(projectRoot) {
+  for (const fileName of ["val.modules.ts", "val.modules.js"]) {
+    const candidate = path__default.join(projectRoot, fileName);
+    if (fs.existsSync(candidate)) {
+      return candidate;
     }
-    return {
-      match: false,
-      tried: tried.concat(filePath)
-    };
   }
+  return null;
 }
+const RESOLVE_EXTENSIONS = [".ts", ".tsx", ".js", ".jsx", ".cjs", ".mjs"];
 
-async function newValQuickJSRuntime(quickJSModule, moduleLoader, {
-  maxStackSize = 1024 * 20,
-  // maximum stack size that works: 1024 * 640 * 8
-  memoryLimit = 1024 * 640 // 640 mbs
-} = {}) {
-  const runtime = quickJSModule.newRuntime();
-  runtime.setMaxStackSize(maxStackSize);
-  runtime.setMemoryLimit(memoryLimit);
-  runtime.setModuleLoader(modulePath => {
-    try {
-      // Special cases to avoid loading the React packages since currently React does not have a ESM build:
-      // TODO: this is not stable, find a better way to do this
-      if (modulePath === "@valbuild/react") {
-        return {
-          value: "export const useVal = () => { throw Error(`Cannot use 'useVal' in this type of file`) }; export function ValProvider() { throw Error(`Cannot use 'ValProvider' in this type of file`) }; export function ValRichText() { throw Error(`Cannot use 'ValRichText' in this type of file`)};"
-        };
-      }
-      if (modulePath === "@valbuild/react/internal") {
-        return {
-          value: `
-const useVal = () => { throw Error('Cannot use \\'useVal\\' in this type of file') };
-export function ValProvider() { throw Error('Cannot use \\'ValProvider\\' in this type of file') }; 
-export function ValRichText() { throw Error('Cannot use \\'ValRichText\\' in this type of file')};`
-        };
-      }
-      if (modulePath === "@valbuild/ui") {
-        return {
-          value: `
-export const ValOverlay = () => {
-  throw Error("Cannot use 'ValOverlay' in this type of file")
-};
-export const VAL_CSS_PATH = "${VAL_CSS_PATH}";
-export const VAL_APP_PATH = "${VAL_CSS_PATH}";
-export const VAL_APP_ID = "${VAL_APP_ID}";
-export const VAL_OVERLAY_ID = "${VAL_OVERLAY_ID}";
-export const IS_DEV = false;
-export const VERSION = "0.0.0";
-`
-        };
-      }
-      if (modulePath === "@valbuild/react/stega") {
-        return {
-          value: "export const useVal = () => { throw Error(`Cannot use 'useVal' in this type of file`) };export const fetchVal = () => { throw Error(`Cannot use 'fetchVal' in this type of file`) }; export const autoTagJSX = () => { /* ignore */ }; export const stegaClean = () => { throw Error(`Cannot use 'stegaClean' in this type of file`) }; export const stegaDecodeStrings = () => { throw Error(`Cannot use 'stegaDecodeStrings' in this type of file`) };  export const stegaEncode = () => { throw Error(`Cannot use 'stegaEncode' in this type of file`) }; export const raw = () => { throw Error(`Cannot use 'raw' in this type of file`) }; export const attrs = () => { throw Error(`Cannot use 'attrs' in this type of file`) }; "
-        };
+// Specifiers that user val files must not actually use. We stub them so that
+// importing is fine, but using a value throws a clear error. Real @valbuild
+// packages are resolved via the real require, so when they (legitimately)
+// import react/next internally those go through Node, not this stub.
+function isStubbedSpecifier(spec) {
+  return spec === "react" || spec.startsWith("react/") || spec === "next" || spec.startsWith("next/") || spec === "@valbuild/ui" || spec === "@valbuild/react" || spec.startsWith("@valbuild/react/");
+}
+function makeStub(spec) {
+  const throwing = prop => () => {
+    throw Error(`Cannot use '${prop}' from '${spec}' in this type of file`);
+  };
+  const handler = {
+    get(_target, prop) {
+      if (prop === "__esModule") {
+        return true;
       }
-      if (modulePath.startsWith("next/navigation")) {
-        return {
-          value: "export const usePathname = () => { throw Error(`Cannot use 'usePathname' in this type of file`) }; export const useRouter = () => { throw Error(`Cannot use 'useRouter' in this type of file`) }; export default new Proxy({}, { get() { return () => { throw new Error(`Cannot import 'next' in this file`) } } } );"
-        };
+      if (typeof prop === "symbol") {
+        return undefined;
       }
-      if (modulePath.startsWith("next")) {
-        return {
-          value: "export default new Proxy({}, { get() { return () => { throw new Error(`Cannot import 'next' in this file`) } } } );"
-        };
+      // React.createContext is sometimes called at module top-level; return a
+      // proxy-returning function so evaluation does not crash on import.
+      if (prop === "createContext") {
+        return () => new Proxy({}, handler);
       }
-      if (modulePath.startsWith("react/jsx-runtime")) {
-        return {
-          value: "export const jsx = () => { throw Error(`Cannot use 'jsx' in this type of file`) }; export const Fragment = () => { throw Error(`Cannot use 'Fragment' in this type of file`) }; export default new Proxy({}, { get() { return () => { throw new Error(`Cannot import 'react' in this file`) } } } ); export const jsxs = () => { throw Error(`Cannot use 'jsxs' in this type of file`) };"
-        };
+      if (prop === "default") {
+        return stub;
       }
-      if (modulePath.startsWith("react")) {
-        return {
-          value: `
-export const createContext = () => new Proxy({}, { get() { return () => { throw new Error('Cannot use \\'createContext\\' in this file') } } } );
-export const useTransition = () => { throw Error('Cannot use \\'useTransition\\' in this type of file') }; 
-
-export default new Proxy({}, { 
-  get(target, props) { 
-    // React.createContext might be called on top-level
-    if (props === 'createContext') {
-      return createContext;
-    }
-    return () => {
-      throw new Error('Cannot import \\'react\\' in this file');
+      return throwing(prop);
     }
+  };
+  const stub = new Proxy({}, handler);
+  return stub;
+}
+function loadModule(absPath, cache, compilerOptions) {
+  const cached = cache[absPath];
+  if (cached) {
+    return cached;
+  }
+  const code = fs.readFileSync(absPath, "utf-8");
+  const transpiled = ts.transpileModule(code, {
+    compilerOptions: {
+      target: ts.ScriptTarget.ES2020,
+      module: ts.ModuleKind.CommonJS,
+      esModuleInterop: true,
+      jsx: ts.JsxEmit.ReactJSX
+    },
+    fileName: absPath
+  });
+  const moduleObj = {
+    exports: {}
+  };
+  // Insert into the cache before evaluating so cyclic imports resolve.
+  cache[absPath] = moduleObj;
+  const dirName = path__default.dirname(absPath);
+  const realRequire = Module.createRequire(absPath);
+  const customRequire = spec => {
+    var _ts$resolveModuleName;
+    if (isStubbedSpecifier(spec)) {
+      return makeStub(spec);
+    }
+    if (spec.startsWith(".") || path__default.isAbsolute(spec)) {
+      const resolved = resolveRelative(dirName, spec);
+      if (!resolved) {
+        throw Error(`Could not resolve module '${spec}' from '${absPath}'`);
+      }
+      return loadModule(resolved, cache, compilerOptions).exports;
+    }
+    // Non-relative specifier: it might be a tsconfig path alias (e.g. "_/val.config")
+    // pointing at a local source file, or an actual node_modules package.
+    const tsResolved = (_ts$resolveModuleName = ts.resolveModuleName(spec, absPath, compilerOptions, ts.sys).resolvedModule) === null || _ts$resolveModuleName === void 0 ? void 0 : _ts$resolveModuleName.resolvedFileName;
+    if (tsResolved && !tsResolved.includes("/node_modules/") && !tsResolved.endsWith(".d.ts")) {
+      return loadModule(tsResolved, cache, compilerOptions).exports;
+    }
+    // Real node_modules package – use the real require so user modules share
+    // the same @valbuild/core instance as extractValModules.
+    return realRequire(spec);
+  };
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const sandbox = {
+    exports: moduleObj.exports,
+    module: moduleObj,
+    require: customRequire,
+    __filename: absPath,
+    __dirname: dirName,
+    console,
+    process
+  };
+  sandbox.global = sandbox;
+  sandbox.globalThis = sandbox;
+  const context = vm.createContext(sandbox);
+  const script = new vm.Script(transpiled.outputText, {
+    filename: absPath
+  });
+  script.runInContext(context);
+  return moduleObj;
+}
+function resolveRelative(dirName, spec) {
+  const base = path__default.resolve(dirName, spec);
+  // Exact file (with extension)
+  if (fs.existsSync(base) && fs.statSync(base).isFile()) {
+    return base;
   }
-})`
-        };
-      }
-      if (modulePath.includes("/ValNextProvider")) {
-        return {
-          value: "export const ValNextProvider = new Proxy({}, { get() { return () => { throw new Error(`Cannot import 'ValNextProvider' in this file`) } } } )"
-        };
-      }
-      if (modulePath.includes("/ValContext")) {
-        return {
-          value: "export const useValEvents = () => { throw Error(`Cannot use 'useValEvents' in this type of file`) }; export const ValContext = new Proxy({}, { get() { return () => { throw new Error(`Cannot import 'ValContext' in this file`) } } } ) export const ValEvents = new Proxy({}, { get() { return () => { throw new Error(`Cannot import 'ValEvents' in this file`) } } } )"
-        };
-      }
-      if (modulePath.includes("/ValImage")) {
-        return {
-          value: "export const ValImage = new Proxy({}, { get() { return () => { throw new Error(`Cannot import 'ValImage' in this file`) } } } )"
-        };
-      }
-      if (modulePath.includes("/ValApp")) {
-        return {
-          value: "export const ValApp = new Proxy({}, { get() { return () => { throw new Error(`Cannot import 'ValApp' in this file`) } } } )"
-        };
-      }
-      if (modulePath.includes("/ValModulesClient")) {
-        return {
-          value: "export const ValModulesClient = new Proxy({}, { get() { return () => { throw new Error(`Cannot import 'ValModulesClient' in this file`) } } } ); export const useRegisterValModules = () => { throw new Error(`Cannot use 'useRegisterValModules' in this type of file`) };"
-        };
-      }
-      return {
-        value: moduleLoader.getModule(modulePath)
-      };
-    } catch {
-      return {
-        error: Error(`Could not resolve module: '${modulePath}'`)
-      };
+  // Probe extensions (handles `./x.val` -> `./x.val.ts`)
+  for (const ext of RESOLVE_EXTENSIONS) {
+    const candidate = base + ext;
+    if (fs.existsSync(candidate)) {
+      return candidate;
     }
-  }, (baseModuleName, requestedName) => {
-    try {
-      if (requestedName === "@valbuild/react") {
-        return {
-          value: requestedName
-        };
-      }
-      if (requestedName === "@valbuild/react/stega") {
-        return {
-          value: requestedName
-        };
-      }
-      if (requestedName === "@valbuild/react/internal") {
-        return {
-          value: requestedName
-        };
-      }
-      if (requestedName === "@valbuild/ui") {
-        return {
-          value: requestedName
-        };
-      }
-      if (requestedName.startsWith("next/navigation")) {
-        return {
-          value: requestedName
-        };
-      }
-      if (requestedName.startsWith("next")) {
-        return {
-          value: requestedName
-        };
-      }
-      if (requestedName.startsWith("react/jsx-runtime")) {
-        return {
-          value: requestedName
-        };
-      }
-      if (requestedName.startsWith("react")) {
-        return {
-          value: requestedName
-        };
-      }
-      if (requestedName.includes("/ValNextProvider")) {
-        return {
-          value: requestedName
-        };
-      }
-      if (requestedName.includes("/ValContext")) {
-        return {
-          value: requestedName
-        };
-      }
-      if (requestedName.includes("/ValImage")) {
-        return {
-          value: requestedName
-        };
-      }
-      if (requestedName.includes("/ValApp")) {
-        return {
-          value: requestedName
-        };
-      }
-      if (requestedName.includes("/ValModulesClient")) {
-        return {
-          value: requestedName
-        };
+  }
+  // Directory index
+  if (fs.existsSync(base) && fs.statSync(base).isDirectory()) {
+    for (const ext of RESOLVE_EXTENSIONS) {
+      const candidate = path__default.join(base, "index" + ext);
+      if (fs.existsSync(candidate)) {
+        return candidate;
       }
-      const modulePath = moduleLoader.resolveModulePath(baseModuleName, requestedName);
-      return {
-        value: modulePath
-      };
-    } catch (e) {
-      console.debug(`Could not resolve ${requestedName} in ${baseModuleName}`, e);
-      return {
-        value: requestedName
-      };
     }
-  });
-  return runtime;
+  }
+  return null;
 }
 
-async function createService(projectRoot, opts, host = {
+async function createService(projectRoot, host = {
   ...ts.sys,
   writeFile: (fileName, data, encoding) => {
     fs.mkdirSync(path__default.dirname(fileName), {
@@ -1368,48 +1109,73 @@ async function createService(projectRoot, opts, host = {
       return undefined;
     }
   }
-}, loader) {
+}) {
   const compilerOptions = getCompilerOptions(projectRoot, host);
   const sourceFileHandler = new ValSourceFileHandler(projectRoot, compilerOptions, host);
-  const module = await newQuickJSWASMModule();
-  const runtime = await newValQuickJSRuntime(module, loader || new ValModuleLoader(projectRoot, compilerOptions, sourceFileHandler, host, opts.disableCache === undefined ? process.env.NODE_ENV === "development" ? false : true : opts.disableCache));
-  return new Service(projectRoot, sourceFileHandler, runtime);
+  const valModules = loadValModules(projectRoot);
+  const extracted = await extractValModules(valModules);
+  return new Service(projectRoot, sourceFileHandler, extracted);
 }
 class Service {
-  constructor(projectRoot, sourceFileHandler, runtime) {
+  constructor(projectRoot, sourceFileHandler, extracted) {
     this.sourceFileHandler = sourceFileHandler;
-    this.runtime = runtime;
+    this.extracted = extracted;
     this.projectRoot = projectRoot;
   }
+
+  /**
+   * The module file paths that are registered in the project's val.modules.
+   */
+  getModuleFilePaths() {
+    return Object.keys(this.extracted.sources);
+  }
   async get(moduleFilePath, modulePath, options) {
-    const valModule = await readValFile(moduleFilePath, this.projectRoot, this.runtime, options ?? {
-      validate: true,
-      source: true,
-      schema: true
-    });
-    if (valModule.source && valModule.schema) {
-      const resolved = Internal.resolvePath(modulePath, valModule.source, valModule.schema);
-      const sourcePath = resolved.path ? [moduleFilePath, resolved.path].join(".") : moduleFilePath;
+    const opts = options ?? {
+      validate: true
+    };
+    const source = this.extracted.sources[moduleFilePath];
+    const schema = this.extracted.schemas[moduleFilePath];
+    const serializedSchema = this.extracted.serializedSchemas[moduleFilePath];
+    const moduleError = this.extracted.moduleErrors.find(e => e.path === moduleFilePath);
+    if (source === undefined || schema === undefined || serializedSchema === undefined) {
+      return {
+        path: moduleFilePath,
+        errors: {
+          invalidModulePath: moduleFilePath,
+          fatal: [{
+            message: (moduleError === null || moduleError === void 0 ? void 0 : moduleError.message) ?? `Module '${moduleFilePath}' was not found in val.modules`
+          }]
+        }
+      };
+    }
+    const validation = opts.validate ? schema["executeValidate"](moduleFilePath, source) : false;
+    const resolved = Internal.resolvePath(modulePath, source, serializedSchema);
+    const sourcePath = resolved.path ? [moduleFilePath, resolved.path].join(".") : moduleFilePath;
+    if (!validation && !moduleError) {
       return {
         path: sourcePath,
-        schema: resolved.schema instanceof Schema ? resolved.schema["executeSerialize"]() : resolved.schema,
         source: resolved.source,
-        errors: valModule.errors && valModule.errors.validation ? {
-          validation: valModule.errors.validation || undefined,
-          fatal: valModule.errors.fatal || undefined
-        } : valModule.errors ? {
-          fatal: valModule.errors.fatal || undefined
-        } : false
+        schema: resolved.schema,
+        errors: false
       };
-    } else {
-      return valModule;
     }
+    return {
+      path: sourcePath,
+      source: resolved.source,
+      schema: resolved.schema,
+      errors: {
+        validation: validation || undefined,
+        fatal: moduleError ? [{
+          message: moduleError.message
+        }] : undefined
+      }
+    };
   }
   async patch(moduleFilePath, patch) {
-    await patchValFile(moduleFilePath, this.projectRoot, patch, this.sourceFileHandler, this.runtime);
+    await patchValFile(moduleFilePath, this.projectRoot, patch, this.sourceFileHandler);
   }
   dispose() {
-    this.runtime.dispose();
+    // No-op: the vm-based loader holds no disposable resources.
   }
 }
 
@@ -1559,6 +1325,14 @@ class ValOps {
   async getSchemas() {
     return this.initSources().then(result => result.schemas);
   }
+  async getSerializedSchemas() {
+    const schemas = await this.getSchemas();
+    const serialized = {};
+    for (const [moduleFilePathS, schema] of Object.entries(schemas)) {
+      serialized[moduleFilePathS] = schema["executeSerialize"]();
+    }
+    return serialized;
+  }
   async getModuleErrors() {
     return this.initSources().then(result => result.moduleErrors);
   }
@@ -1583,6 +1357,7 @@ class ValOps {
       if (patch.appliedAt) {
         continue;
       }
+      let hasSourceFileOps = false;
       for (const op of patch.patch) {
         if (op.op === "file") {
           const filePath = op.filePath;
@@ -1593,6 +1368,13 @@ class ValOps {
           };
           continue;
         }
+        hasSourceFileOps = true;
+      }
+      // Once per patch, NOT once per op: prepare() re-looks-up the patch by id
+      // and applies the whole thing for every entry, so a patch with two source
+      // ops used to be applied twice. Idempotent for "replace", destructive for
+      // array add/remove/move.
+      if (hasSourceFileOps) {
         const path = patch.path;
         if (!patchesByModule[path]) {
           patchesByModule[path] = [];
@@ -1712,6 +1494,26 @@ class ValOps {
     };
   }
 
+  /**
+   * Every module's source, with the pending patches applied.
+   *
+   * `getSources(analysis)` returns ONLY the modules that had patches, which is
+   * not enough to validate with: cross-module checks (keyOf, router routes)
+   * resolve against other modules' sources and report spurious errors when they
+   * are absent. `/sources/~` overlays the two for exactly this reason.
+   */
+  async getSourcesWithPatchesApplied(analysis) {
+    const unpatched = await this.getSources();
+    const patched = await this.getSources(analysis);
+    return {
+      sources: {
+        ...unpatched.sources,
+        ...patched.sources
+      },
+      errors: patched.errors
+    };
+  }
+
   // #region validateSources
   async validateSources(schemas, sources, patchesByModule) {
     const errors = {};
@@ -1987,13 +1789,28 @@ class ValOps {
   }
 
   // #region prepareCommit
-  async prepare(patchAnalysis) {
+  /**
+   * Applies the pending patches to the source files so they can be committed.
+   *
+   * @param options.continueOnError Diagnosis only. By default a patch that
+   * cannot be applied aborts the rest of that module's chain, which is what
+   * /save requires: the commit is refused and nothing is written. With this
+   * flag the failing patch is recorded in `unappliablePatches` and the chain
+   * continues on the unchanged source file, so a single run reports *every*
+   * unappliable patch instead of only the first one per module. The commit is
+   * still refused (`hasErrors` stays true) - this only makes the report
+   * complete.
+   */
+  async prepare(patchAnalysis, options) {
+    const continueOnError = (options === null || options === void 0 ? void 0 : options.continueOnError) ?? false;
     const {
       patchesByModule,
       fileLastUpdatedByPatchId
     } = patchAnalysis;
     const patchedSourceFiles = {};
     const previousSourceFiles = {};
+    const partiallyPatchedSourceFiles = {};
+    const unappliablePatches = {};
     const applySourceFilePatches = async (path, patches) => {
       const sourceFileRes = await this.getSourceFile(path);
       const errors = [];
@@ -2018,9 +1835,18 @@ class ValOps {
       } of patches) {
         const patchData = patchAnalysis.patches.find(p => p.patchId === patchId);
         if (!patchData) {
+          const message = `Analysis required non-existing patch: ${patchId}`;
           errors.push({
-            message: `Analysis required non-existing patch: ${patchId}`
+            message
           });
+          unappliablePatches[patchId] = {
+            moduleFilePath: path,
+            message
+          };
+          triedPatches.push(patchId);
+          if (continueOnError) {
+            continue;
+          }
           break;
         }
         const patch = patchData.patch;
@@ -2046,12 +1872,29 @@ class ValOps {
             }, null, 2));
             errors.push(patchRes.error);
           }
+          unappliablePatches[patchId] = {
+            moduleFilePath: path,
+            message: formatPatchSourceError(patchRes.error)
+          };
           triedPatches.push(patchId);
+          if (continueOnError) {
+            // Continue from the unchanged source file: the failing patch made
+            // no change, so the rest of the chain applies on top of the state
+            // it had before it. This mirrors what the client already does in
+            // ValSyncEngine.getPatchedSource.
+            continue;
+          }
           break;
         }
         appliedPatches.push(patchId);
         tsSourceFile = patchRes.value;
       }
+      if (errors.length > 0 && continueOnError) {
+        // Diagnosis: expose what the source file would look like with the
+        // appliable patches applied, so a caller can diff it even though the
+        // commit is (correctly) refused.
+        partiallyPatchedSourceFiles[path] = unescape(tsSourceFile.getText(tsSourceFile).replace(/\\u/g, "%u"));
+      }
       if (errors.length === 0) {
         var _this$options;
         // https://github.com/microsoft/TypeScript/issues/36174
@@ -2137,8 +1980,10 @@ class ValOps {
       hasErrors,
       sourceFilePatchErrors,
       binaryFilePatchErrors,
+      unappliablePatches,
       patchedSourceFiles,
       previousSourceFiles,
+      partiallyPatchedSourceFiles,
       patchedBinaryFilesDescriptors,
       appliedPatches,
       skippedPatches,
@@ -2147,6 +1992,18 @@ class ValOps {
     return res;
   }
 
+  /**
+   * Reads a project file as text at whatever revision this ops instance points
+   * at: the deployed commit in http mode, the working tree in fs mode.
+   *
+   * Public counterpart of `getSourceFile`, for the CLI's debug snapshot. The
+   * snapshot has to capture the exact text `prepare` patches, which in http mode
+   * is NOT the local working copy.
+   */
+  async readProjectFile(path) {
+    return this.getSourceFile(path);
+  }
+
   // #region createPatch
   async createPatch(path, patch, patchId, parentRef, sessionId, authorId) {
     const saveRes = await this.saveSourceFilePatch(path, patch, patchId, parentRef, authorId, sessionId);
@@ -2183,6 +2040,16 @@ function isFileSource(value) {
   }
   return false;
 }
+function formatPatchSourceError(error) {
+  if ("message" in error) {
+    return error.message;
+  } else if (Array.isArray(error)) {
+    return error.map(formatPatchSourceError).join("\n");
+  } else {
+    const _exhaustiveCheck = error;
+    return "Unknown patch source error: " + JSON.stringify(_exhaustiveCheck);
+  }
+}
 function getFieldsForType(type) {
   if (type === "file") {
     return ["mimeType"];
@@ -3460,14 +3327,22 @@ const NonceResponse = z.object({
 class ValOpsHttp extends ValOps {
   constructor(contentUrl, project, commitSha,
   // TODO: CommitSha
-  branch, apiKey, valModules, options) {
+  branch,
+  /**
+   * An api key (how the app itself authenticates) or a personal access token
+   * (how the CLI authenticates after `val login`). Same two shapes as
+   * getSettings / uploadRemoteFile / getPresignedAuthNonce.
+   */
+  auth, valModules, options) {
     super(valModules, options);
     this.contentUrl = contentUrl;
     this.project = project;
     this.commitSha = commitSha;
     this.branch = branch;
-    this.authHeaders = {
-      Authorization: `Bearer ${apiKey}`
+    this.authHeaders = "pat" in auth ? {
+      "x-val-pat": auth.pat
+    } : {
+      Authorization: `Bearer ${auth.apiKey}`
     };
     this.root = (options === null || options === void 0 ? void 0 : options.root) ?? "";
   }
@@ -3793,8 +3668,31 @@ class ValOpsHttp extends ValOps {
         allErrors.push(...res.errors);
       }
     }
+    // Chunking is a query-string-length workaround, NOT a filter: the content
+    // api returns every applicable patch per request regardless of which
+    // patch_ids we ask for. Concatenating the chunks therefore repeats the
+    // whole chain once per chunk, and prepare() applies each patch that many
+    // times - which corrupts arrays (a "remove" runs N times) and fails the
+    // commit with "Array index out of bounds". Only bites above chunkSize
+    // pending patches, so it stays invisible until a project accumulates them.
+    //
+    // Dedupe by patch id, keeping first occurrence so the api's ordering is
+    // preserved, and keep only what was asked for. Correct whether or not the
+    // api filters on its side.
+    const requestedPatchIds = new Set(patchIds);
+    const seenPatchIds = new Set();
+    const patches = allPatches.filter(patch => {
+      if (!requestedPatchIds.has(patch.patchId)) {
+        return false;
+      }
+      if (seenPatchIds.has(patch.patchId)) {
+        return false;
+      }
+      seenPatchIds.add(patch.patchId);
+      return true;
+    });
     return {
-      patches: allPatches,
+      patches,
       errors: Object.keys(allErrors).length > 0 ? allErrors : undefined
     };
   }
@@ -3889,7 +3787,7 @@ class ValOpsHttp extends ValOps {
       return {
         patches,
         error: {
-          message: "Could not your changes. It is most likely due to a network issue. Check your network connection and please try again."
+          message: "Could not get your changes. It is most likely due to a network issue. Check your network connection and please try again."
         }
       };
     } catch (err) {
@@ -4516,7 +4414,9 @@ const ValServer = (valModules, options, callbacks) => {
       config: options.config
     });
   } else if (options.mode === "http") {
-    serverOps = new ValOpsHttp(options.valContentUrl, options.project, options.commit, options.branch, options.apiKey, valModules, {
+    serverOps = new ValOpsHttp(options.valContentUrl, options.project, options.commit, options.branch, {
+      apiKey: options.apiKey
+    }, valModules, {
       formatter: options.formatter,
       root: options.root,
       config: options.config
@@ -6740,16 +6640,6 @@ const ValServer = (valModules, options, callbacks) => {
     }
   };
 };
-function formatPatchSourceError(error) {
-  if ("message" in error) {
-    return error.message;
-  } else if (Array.isArray(error)) {
-    return error.map(formatPatchSourceError).join("\n");
-  } else {
-    const _exhaustiveCheck = error;
-    return "Unknown patch source error: " + JSON.stringify(_exhaustiveCheck);
-  }
-}
 function verifyCallbackReq(stateCookie, queryParams) {
   if (typeof stateCookie !== "string") {
     return {
@@ -7203,8 +7093,28 @@ async function readCommit(gitDir, branchName) {
 }
 function createValApiRouter(route, valServerPromise, convert) {
   const uiRequestHandler = createUIRequestHandler();
+  // valServerPromise is created at module-eval time, but only awaited per request.
+  // Without this no-op catch, a config error (e.g. proxy mode without a project)
+  // rejects with no handler attached, which becomes an unhandledRejection and kills
+  // the dev server. The error is still reported per request by the try/catch below.
+  valServerPromise.catch(() => {
+    // handled below
+  });
   return async req => {
-    const valServer = await valServerPromise;
+    let valServer;
+    try {
+      valServer = await valServerPromise;
+    } catch (err) {
+      const error = {
+        message: "Val: could not start the Val server",
+        details: err instanceof Error ? err.message : String(err)
+      };
+      console.error(error.message + ": " + error.details);
+      return convert({
+        status: 500,
+        json: error
+      });
+    }
     const url = new URL(req.url);
     if (!url.pathname.startsWith(route)) {
       const error = {
@@ -7417,6 +7327,132 @@ function getCookies(req, cookiesDef) {
   return z.object(cookiesDef).safeParse(input);
 }
 
+const JsFileLookupMapping = [
+// NOTE: first one matching will be used
+[".cjs.d.ts", [".esm.js", ".mjs.js"]], [".cjs.js", [".esm.js", ".mjs.js"]], [".cjs", [".mjs"]], [".d.ts", [".js", ".esm.js", ".mjs.js"]]];
+const MAX_CACHE_SIZE = 100 * 1024 * 1024; // 100 mb
+const MAX_OBJECT_KEY_SIZE = 2 ** 27; // https://stackoverflow.com/questions/13367391/is-there-a-limit-on-length-of-the-key-string-in-js-object
+
+class ValModuleLoader {
+  constructor(projectRoot, compilerOptions,
+  // TODO: remove this?
+  sourceFileHandler, host = {
+    ...ts.sys,
+    writeFile: (fileName, data, encoding) => {
+      fs.mkdirSync(path__default.dirname(fileName), {
+        recursive: true
+      });
+      fs.writeFileSync(fileName, typeof data === "string" ? data : new Uint8Array(data), encoding);
+    },
+    rmFile: fs.rmSync,
+    readBuffer: fileName => {
+      try {
+        return fs.readFileSync(fileName);
+      } catch {
+        return undefined;
+      }
+    }
+  }, disableCache = false) {
+    this.projectRoot = projectRoot;
+    this.compilerOptions = compilerOptions;
+    this.sourceFileHandler = sourceFileHandler;
+    this.host = host;
+    this.disableCache = disableCache;
+    this.cache = {};
+    this.cacheSize = 0;
+  }
+  getModule(modulePath) {
+    if (!modulePath) {
+      throw Error(`Illegal module path: "${modulePath}"`);
+    }
+    const code = this.host.readFile(modulePath);
+    if (!code) {
+      throw Error(`Could not read file "${modulePath}"`);
+    }
+    let compiledCode;
+    if (this.cache[code] && !this.disableCache) {
+      // TODO: use hash instead of code as key
+      compiledCode = this.cache[code];
+    } else {
+      compiledCode = transform(code, {
+        filePath: modulePath,
+        disableESTransforms: true,
+        transforms: ["typescript"]
+      }).code;
+      if (!this.disableCache) {
+        if (this.cacheSize > MAX_CACHE_SIZE) {
+          console.warn("Cache size exceeded, clearing cache");
+          this.cache = {};
+          this.cacheSize = 0;
+        }
+        if (code.length < MAX_OBJECT_KEY_SIZE) {
+          this.cache[code] = compiledCode;
+          this.cacheSize += code.length + compiledCode.length; // code is mostly ASCII so 1 byte per char
+        }
+      }
+    }
+    return compiledCode;
+  }
+  resolveModulePath(containingFilePath, requestedModuleName) {
+    var _this$host$realpath, _this$host;
+    let sourceFileName = this.sourceFileHandler.resolveSourceModulePath(containingFilePath, requestedModuleName);
+    if (requestedModuleName === "@vercel/stega") {
+      sourceFileName = this.sourceFileHandler.resolveSourceModulePath(containingFilePath, "@vercel/stega").replace("stega/dist", "stega/dist/esm");
+    }
+    const matches = this.findMatchingJsFile(sourceFileName);
+    if (matches.match === false) {
+      let debugInfo = "";
+      if (sourceFileName.includes("val.config")) {
+        debugInfo = `\n@valbuild directory scan:\n${this.host.readDirectory("/", ["js", "ts", "json"], [], ["**/@valbuild/*"]).join("\n")}`;
+      }
+      throw Error(`Could not find matching js file for module "${requestedModuleName}" requested by: "${containingFilePath}". Tried:\n${matches.tried.join("\n")}${debugInfo}`);
+    }
+    const filePath = matches.match;
+    // resolve all symlinks (preconstruct for example symlinks the dist folder)
+    const followedPath = ((_this$host$realpath = (_this$host = this.host).realpath) === null || _this$host$realpath === void 0 ? void 0 : _this$host$realpath.call(_this$host, filePath)) ?? filePath;
+    if (!followedPath) {
+      throw Error(`File path was empty: "${filePath}", containing file: "${containingFilePath}", requested module: "${requestedModuleName}"`);
+    }
+    return followedPath;
+  }
+  findMatchingJsFile(filePath) {
+    let requiresReplacements = false;
+    for (const [currentEnding] of JsFileLookupMapping) {
+      if (filePath.endsWith(currentEnding)) {
+        requiresReplacements = true;
+        break;
+      }
+    }
+    // avoid unnecessary calls to fileExists if we don't need to replace anything
+    if (!requiresReplacements) {
+      if (this.host.fileExists(filePath)) {
+        return {
+          match: filePath
+        };
+      }
+    }
+    const tried = [];
+    for (const [currentEnding, replacements] of JsFileLookupMapping) {
+      if (filePath.endsWith(currentEnding)) {
+        for (const replacement of replacements) {
+          const newFilePath = filePath.slice(0, -currentEnding.length) + replacement;
+          if (this.host.fileExists(newFilePath)) {
+            return {
+              match: newFilePath
+            };
+          } else {
+            tried.push(newFilePath);
+          }
+        }
+      }
+    }
+    return {
+      match: false,
+      tried: tried.concat(filePath)
+    };
+  }
+}
+
 /**
  * An implementation of methods in the various ts.*Host interfaces
  * that uses ValFS to resolve modules and read/write files.
@@ -7531,10 +7567,10 @@ async function checkRemoteRef(remoteHost, ref, projectRoot, schema, metadata) {
       error: `File path is missing in remote ref: ${ref}`
     };
   }
-  if (!relativeFilePath.startsWith("public/val/")) {
+  if (!relativeFilePath.startsWith("public/")) {
     return {
       status: "error",
-      error: `File path must be within the public/val/ directory (e.g. public/val/path/to/file.txt). Got: ${relativeFilePath}`
+      error: `File path must be within the public/ directory (e.g. public/path/to/file.txt). Got: ${relativeFilePath}`
     };
   }
   const coreVersion = Internal.VERSION.core || "unknown";
@@ -7687,6 +7723,11 @@ async function downloadFileFromRemote(ref, filePath) {
   });
 }
 
+// A remaining error may optionally carry a more specific `sourcePath` than the
+// one the fix was created from. This is used by gallery checks, where a single
+// record-level fix expands into per-entry errors that should point at the
+// individual entry (e.g. `?p="/public/val/logo.png"`) rather than the record.
+
 // TODO: find a better name? transformFixesToPatch?
 async function createFixPatch(config, apply, sourcePath, validationError, remoteFiles, moduleSource, moduleSchema) {
   const remainingErrors = [];
@@ -7893,10 +7934,10 @@ async function createFixPatch(config, apply, sourcePath, validationError, remote
         });
         continue;
       }
-      if (!filePath.startsWith("public/val/")) {
+      if (!filePath.startsWith("public/")) {
         remainingErrors.push({
           ...validationError,
-          message: "Unexpected error while downloading remote (invalid file path - must start with public/val/)",
+          message: "Unexpected error while downloading remote (invalid file path - must start with public/)",
           fixes: undefined
         });
         continue;
@@ -7981,7 +8022,11 @@ async function createFixPatch(config, apply, sourcePath, validationError, remote
             } else {
               remainingErrors.push({
                 ...validationError,
-                message: `Image metadata for '${entryKey}' is incorrect (width: ${stored.width ?? "<empty>"} vs ${actualMetadata.width}, height: ${stored.height ?? "<empty>"} vs ${actualMetadata.height}, mimeType: ${stored.mimeType ?? "<empty>"} vs ${actualMetadata.mimeType}). Use --fix to update.`
+                message: `Image metadata for '${entryKey}' is incorrect (width: ${stored.width ?? "<empty>"} vs ${actualMetadata.width}, height: ${stored.height ?? "<empty>"} vs ${actualMetadata.height}, mimeType: ${stored.mimeType ?? "<empty>"} vs ${actualMetadata.mimeType}). Use --fix to update.`,
+                sourcePath: Internal.createValPathOfItem(sourcePath, entryKey),
+                // Gallery entries are keyed by their file path; surface the
+                // error on the key rather than the derived metadata value.
+                keyError: true
               });
             }
           }
@@ -8002,7 +8047,11 @@ async function createFixPatch(config, apply, sourcePath, validationError, remote
             } else {
               remainingErrors.push({
                 ...validationError,
-                message: `File metadata for '${entryKey}' has incorrect mimeType: '${stored.mimeType ?? "<empty>"}' vs '${actualMetadata.mimeType}'. Use --fix to update.`
+                message: `File metadata for '${entryKey}' has incorrect mimeType: '${stored.mimeType ?? "<empty>"}' vs '${actualMetadata.mimeType}'. Use --fix to update.`,
+                sourcePath: Internal.createValPathOfItem(sourcePath, entryKey),
+                // Gallery entries are keyed by their file path; surface the
+                // error on the key rather than the derived metadata value.
+                keyError: true
               });
             }
           }
@@ -8160,4 +8209,262 @@ async function getFileMetadata(projectRoot, validationError) {
   return extractFileMetadata(fileRef);
 }
 
-export { Service, ValFSHost, ValModuleLoader, ValSourceFileHandler, createFixPatch, createService, createValApiRouter, createValServer, decodeJwt, encodeJwt, formatSyntaxErrorTree, getCompilerOptions, getExpire, getPersonalAccessTokenPath, getSettings, parsePersonalAccessTokenFile, patchSourceFile, safeReadGit, uploadRemoteFile };
+function getModulePathRange(modulePath, modulePathMap,
+// Which part of an object/record member to point at. For an object property
+// the resolved node's own range is the *key* (property name); the *value*
+// range is stored under `children.val`. Array elements, leaf literals and
+// `c.image`/`c.file` `_ref`/`metadata` nodes have no `val` child, so "value"
+// falls back to the node's own range for those. Defaults to "key" to preserve
+// existing callers.
+target = "key") {
+  var _range$children;
+  // Handle empty or invalid module paths gracefully
+  if (!modulePath || typeof modulePath !== "string") {
+    return undefined;
+  }
+  let segments;
+  try {
+    // Quote-aware splitter that correctly handles keys containing dots
+    // (e.g. file refs like `"/public/val/images/logo.png"`), unlike a naive
+    // split on ".". Throws on malformed input (e.g. unbalanced quotes).
+    segments = Internal.splitModulePath(modulePath);
+  } catch {
+    // Return undefined if the module path is malformed. This can happen when
+    // there are upstream errors in schema serialization.
+    return undefined;
+  }
+  if (segments.length === 0) {
+    return undefined;
+  }
+  let range = modulePathMap[segments[0]];
+  for (const pathSegment of segments.slice(1)) {
+    var _range;
+    if (!range) {
+      break;
+    }
+    range = (_range = range) === null || _range === void 0 || (_range = _range.children) === null || _range === void 0 ? void 0 : _range[pathSegment];
+  }
+  if (!range) {
+    return undefined;
+  }
+  const valueRange = target === "value" ? (_range$children = range.children) === null || _range$children === void 0 ? void 0 : _range$children.val : undefined;
+  const resolved = valueRange ?? range;
+  return resolved.start && resolved.end && {
+    start: resolved.start,
+    end: resolved.end
+  };
+}
+
+/**
+ * The line/character range of `node`'s own text (leading trivia excluded).
+ *
+ * NOTE: do not compute the start as `end.character - node.getWidth()`. That
+ * identity only holds while the node stays on a single line - for a multi-line
+ * node (an object inside an array, a `c.image` metadata argument, ...) it
+ * reports the *closing* line and a negative character.
+ */
+function rangeOf(node, sourceFile) {
+  return {
+    start: sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile)),
+    end: sourceFile.getLineAndCharacterOfPosition(node.getEnd())
+  };
+}
+function createModulePathMap(sourceFile) {
+  for (const child of sourceFile.getChildren().flatMap(child => child.getChildren())) {
+    if (ts.isExportAssignment(child)) {
+      const contentNode = child.expression && ts.isCallExpression(child.expression) && child.expression.arguments[2];
+      if (contentNode) {
+        return traverse(contentNode, sourceFile);
+      }
+    }
+  }
+}
+function traverse(node, sourceFile) {
+  if (ts.isStringLiteral(node) || ts.isNumericLiteral(node)) {
+    return {
+      "": {
+        children: {},
+        ...rangeOf(node, sourceFile)
+      }
+    };
+  }
+  if (ts.isObjectLiteralExpression(node)) {
+    return traverseObjectLiteral(node, sourceFile);
+  }
+  if (ts.isArrayLiteralExpression(node)) {
+    return traverseArrayLiteral(node, sourceFile);
+  }
+  if (ts.isCallExpression(node)) {
+    return traverseCallExpression(node, sourceFile);
+  }
+}
+function traverseCallExpression(node, sourceFile) {
+  if (ts.isPropertyAccessExpression(node.expression)) {
+    if (node.expression.expression.getText(sourceFile) === "c" && (node.expression.name.getText(sourceFile) === "file" || node.expression.name.getText(sourceFile) === "image")) {
+      const val = {
+        children: {},
+        ...rangeOf(node, sourceFile)
+      };
+      if (node.arguments[0]) {
+        const _ref = {
+          children: {},
+          ...rangeOf(node.arguments[0], sourceFile)
+        };
+        if (!node.arguments[1]) {
+          return {
+            val,
+            _ref
+          };
+        }
+        return {
+          val,
+          _ref,
+          metadata: {
+            children: {},
+            ...rangeOf(node.arguments[1], sourceFile)
+          }
+        };
+      }
+    }
+  }
+}
+function traverseArrayLiteral(node, sourceFile) {
+  return node.elements.reduce((acc, element, index) => {
+    if (ts.isExpression(element)) {
+      return {
+        ...acc,
+        [index]: {
+          children: traverse(element, sourceFile),
+          ...rangeOf(element, sourceFile)
+        }
+      };
+    }
+    return acc;
+  }, {});
+}
+function traverseObjectLiteral(node, sourceFile) {
+  return node.properties.reduce((acc, property) => {
+    if (ts.isPropertyAssignment(property)) {
+      const key = property.name && (ts.isIdentifier(property.name) || ts.isStringLiteral(property.name)) && property.name.text;
+      const value = property.initializer;
+      if (key) {
+        const val = {
+          children: {},
+          ...rangeOf(property.initializer, sourceFile)
+        };
+        return {
+          ...acc,
+          [key]: {
+            children: {
+              val,
+              ...traverse(value, sourceFile)
+            },
+            ...rangeOf(property.name, sourceFile)
+          }
+        };
+      }
+    }
+    return acc;
+  }, {});
+}
+
+/**
+ * Replays a `val debug` snapshot: applies its patches the way /save does and
+ * validates the result.
+ *
+ * A snapshot is a minimal Val project (the modules the patches touch plus the
+ * ones they reference, a generated val.modules.ts, and the patch chain under
+ * .val/patches), so replaying it is just a ValOpsFS pointed at the directory -
+ * no snapshot-specific code paths, which is the point: if the replay reproduces
+ * the bug, the bug is in the ordinary code.
+ */
+
+async function replaySnapshot(snapshotDir) {
+  const root = path__default.resolve(snapshotDir);
+  if (!fs.existsSync(path__default.join(root, "val.modules.ts"))) {
+    throw new Error(`Not a Val debug snapshot: no val.modules.ts in ${root}. ` + `Unzip the snapshot first.`);
+  }
+  const valModules = loadValModules(root);
+  const serverOps = new ValOpsFS(process.env.VAL_CONTENT_URL || DEFAULT_CONTENT_HOST, root, valModules,
+  // The snapshot's own val.config, as evaluated by loadValModules - no need to
+  // re-read it, and this way the replay uses exactly the config the snapshot
+  // carries (files.directory in particular).
+  {
+    config: valModules.config
+  });
+  const patchesRes = await serverOps.fetchPatches({
+    patchIds: undefined,
+    excludePatchOps: false
+  });
+  if (patchesRes.error) {
+    throw new Error(`Could not read the snapshot's patches: ${patchesRes.error.message}`);
+  }
+  if (patchesRes.errors && patchesRes.errors.length > 0) {
+    for (const err of patchesRes.errors) {
+      console.error(`Snapshot patch could not be read: ${err.message}`);
+    }
+  }
+  const analysis = {
+    ...serverOps.analyzePatches(patchesRes.patches),
+    ...patchesRes
+  };
+  const prepared = await serverOps.prepare(analysis, {
+    continueOnError: true
+  });
+  const sources = await serverOps.getSourcesWithPatchesApplied(analysis);
+  const schemas = await serverOps.getSchemas();
+  const validation = await serverOps.validateSources(schemas, sources.sources, analysis.patchesByModule);
+  const patchedSourceFiles = {};
+  for (const [moduleFilePath, contents] of Object.entries(prepared.patchedSourceFiles)) {
+    if (contents !== null) {
+      patchedSourceFiles[moduleFilePath] = contents;
+    }
+  }
+  Object.assign(patchedSourceFiles, prepared.partiallyPatchedSourceFiles);
+  return {
+    patches: patchesRes.patches.map(patch => {
+      var _prepared$unappliable;
+      return {
+        patchId: patch.patchId,
+        moduleFilePath: patch.path,
+        createdAt: patch.createdAt,
+        authorId: patch.authorId,
+        error: (_prepared$unappliable = prepared.unappliablePatches[patch.patchId]) === null || _prepared$unappliable === void 0 ? void 0 : _prepared$unappliable.message
+      };
+    }),
+    unappliablePatches: prepared.unappliablePatches,
+    sourceFilePatchErrors: Object.fromEntries(Object.entries(prepared.sourceFilePatchErrors).map(([key, errors]) => [key, errors.map(formatPatchSourceError)])),
+    binaryFilePatchErrors: prepared.binaryFilePatchErrors,
+    validationErrors: validation.errors,
+    patchedSourceFiles,
+    hasErrors: prepared.hasErrors
+  };
+}
+
+/**
+ * Compares a replay against the report captured when the snapshot was taken, so
+ * "reproduced the customer's bug" is distinguishable from "behaves differently
+ * on this version".
+ */
+function compareWithCapturedReport(result, capturedReport) {
+  const capturedIds = Object.keys(capturedReport.unappliablePatches ?? {});
+  const nowIds = Object.keys(result.unappliablePatches);
+  const stillFailing = capturedIds.filter(patchId => nowIds.includes(patchId));
+  const nowApplying = capturedIds.filter(patchId => !nowIds.includes(patchId));
+  const newlyFailing = nowIds.filter(patchId => !capturedIds.includes(patchId));
+  return {
+    stillFailing,
+    nowApplying,
+    newlyFailing,
+    reproduced: capturedIds.length > 0 && nowApplying.length === 0 && newlyFailing.length === 0
+  };
+}
+function readCapturedReport(snapshotDir) {
+  const reportPath = path__default.join(path__default.resolve(snapshotDir), "report.json");
+  if (!fs.existsSync(reportPath)) {
+    return null;
+  }
+  return JSON.parse(fs.readFileSync(reportPath, "utf-8"));
+}
+
+export { Service, ValFSHost, ValModuleLoader, ValOpsFS, ValOpsHttp, ValSourceFileHandler, compareWithCapturedReport, createFixPatch, createModulePathMap, createService, createValApiRouter, createValServer, decodeJwt, encodeJwt, formatPatchSourceError, formatSyntaxErrorTree, getCompilerOptions, getExpire, getModulePathRange, getPersonalAccessTokenPath, getSettings, loadValModules, parsePersonalAccessTokenFile, patchSourceFile, readCapturedReport, replaySnapshot, safeReadGit, uploadRemoteFile };