@corva/dc-platform-shared 0.0.0-58393c2 → 0.0.0-59520c5

package/vite/corva-vite-config.mjs

@@ -0,0 +1,843 @@
+// The Vite equivalent of getWebpackConfig: one shared build for every DC app, extended per app
+// through `overrides`. Ships unbundled - it is a Node-side config Vite loads as ESM, so rollup
+// must not touch it.
+import { randomUUID } from 'node:crypto';
+import { builtinModules, createRequire } from 'node:module';
+import { existsSync, readdirSync, readFileSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
+import { join, relative, resolve } from 'node:path';
+
+import dotenv from 'dotenv';
+import { expand } from 'dotenv-expand';
+import react from '@vitejs/plugin-react';
+import license from 'rollup-plugin-license';
+import { viteStaticCopy } from 'vite-plugin-static-copy';
+import presetEnv from 'postcss-preset-env';
+import { defineConfig, mergeConfig } from 'vitest/config';
+
+import { rejectUnscopedCssPlugin } from './unscoped-css.mjs';
+
+const require = createRequire(import.meta.url);
+
+const {
+  CORVA_API_ENVS,
+  CORVA_API_ENV_VARIABLES,
+  CORVA_GLOBAL_DEPENDENCIES,
+} = require('../cjs/devcenter/webpack/constants.js');
+const validateDependencies = require('../cjs/devcenter/webpack/validators/index.js');
+const { updateDotEnv } = require('../cjs/devcenter/webpack/utils/serializeDotEnv.js');
+
+// this file ships unbundled at <package>/vite/, so the package root is one level up and
+// @corva/ui sits next to it in the app's node_modules/@corva
+const PLATFORM_SHARED_DIR = join(import.meta.dirname, '..');
+// NOTE: These imports are always bundled, never taken from the platform globals
+const SKIP_IN_EXTERNALS = ['react/jsx-runtime', 'highcharts/'];
+
+// webpack's css-loader appended a per-build uuid to every local class name, so two DC apps sharing a
+// dashboard could not overwrite each other's styles. Vite hashes path + name + source instead, which
+// is identical for two apps scaffolded from the same template.
+const BUILD_ID = randomUUID().slice(-5);
+
+const isLegalIdentifier = value => /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(value);
+
+const toLegalIdentifier = value => {
+  const identifier = value.replace(/[^A-Za-z0-9_$]/g, '_');
+
+  return isLegalIdentifier(identifier) ? identifier : `_${identifier}`;
+};
+
+const toGlobalSegmentAccess = segment =>
+  /^\d+$/.test(segment) ? `[${segment}]` : `[${JSON.stringify(segment)}]`;
+
+const getSegmentedGlobalAssignmentPrefix = appIdentifier => {
+  const [rootSegment, ...segments] = appIdentifier.split('.');
+  const rootAccessor = `this[${JSON.stringify(rootSegment)}]`;
+
+  if (segments.length === 0) {
+    return `${rootAccessor}=`;
+  }
+
+  let currentAccessor = rootAccessor;
+  const initializers = [`${rootAccessor}=${rootAccessor}||{}`];
+
+  segments.slice(0, -1).forEach(segment => {
+    currentAccessor += toGlobalSegmentAccess(segment);
+    initializers.push(`${currentAccessor}=${currentAccessor}||{}`);
+  });
+
+  currentAccessor += toGlobalSegmentAccess(segments[segments.length - 1]);
+
+  return `${initializers.join(',')},${currentAccessor}=`;
+};
+
+const getGlobalAssignmentPrefixes = globalName =>
+  [
+    ...new Set([
+      isLegalIdentifier(globalName) ? `var ${globalName}=` : '',
+      isLegalIdentifier(globalName)
+        ? `this.${globalName}=`
+        : `this[${JSON.stringify(globalName)}]=`,
+      `this[${JSON.stringify(globalName)}]=`,
+      getSegmentedGlobalAssignmentPrefix(globalName),
+    ]),
+  ].filter(Boolean);
+
+const normalizeIifeGlobalAssignment = (jsContent, appIdentifier, emittedGlobalName) => {
+  const normalizedAssignment = `this[${JSON.stringify(appIdentifier)}]=`;
+
+  if (jsContent.includes(normalizedAssignment)) {
+    return jsContent;
+  }
+
+  const assignmentPrefix = getGlobalAssignmentPrefixes(emittedGlobalName).find(prefix =>
+    jsContent.includes(prefix),
+  );
+
+  if (assignmentPrefix) {
+    return jsContent.replace(assignmentPrefix, normalizedAssignment);
+  }
+
+  // Rolldown doesn't emit a global assignment for IIFE output — inject one.
+  // Terser rewrites `(function(){})()` → `!function(){}()` when the result is discarded.
+  // Replacing `!` with the assignment (`this["name"]=function(){}()`) is valid JS
+  // because after `=` the `function` keyword is an expression, not a declaration.
+  if (jsContent.trimStart().startsWith('!function')) {
+    return jsContent.replace('!function', `${normalizedAssignment}function`);
+  }
+
+  return normalizedAssignment + jsContent;
+};
+
+// webpack's `output.publicPath: 'auto'` read the bundle's own <script> src once, at bundle
+// init, and served every emitted asset from next to it. Same expression, same moment.
+const ASSET_BASE_EXPR =
+  '(function(){var d=document,s=d.currentScript;if(!s||s.tagName.toUpperCase()!=="SCRIPT"){' +
+  'var a=d.getElementsByTagName("script");s=a[a.length-1];}' +
+  'return((s&&s.src)||d.baseURI).replace(/[^/]*(?:[?#].*)?$/,"");})()';
+
+// url() in the extracted CSS carries this marker instead of a path (see renderBuiltUrl); the
+// marker is spliced out into a concatenation with the base, so the injected stylesheet points
+// at the CDN directory rather than at the host document's.
+const ASSET_MARKER = '__CORVA_ASSET__';
+
+const createCssInjection = cssContent =>
+  `(function(){var B=${ASSET_BASE_EXPR};var s=document.createElement('style');s.textContent=${JSON.stringify(
+    cssContent,
+  ).replaceAll(ASSET_MARKER, '"+B+"')};document.head.appendChild(s)})();`;
+
+// The platform loads a single file, so the emitted stylesheets are folded back into it.
+const finalizeJsBundle = ({ outDir, cssFileNames, appIdentifier, emittedGlobalName }) => {
+  const jsPath = join(outDir, 'app.js');
+  const css = cssFileNames
+    .map(fileName => readFileSync(join(outDir, fileName), 'utf-8'))
+    .join('');
+  // normalise first: the fallbacks read the head of the bundle, so a stylesheet
+  // sitting in front of it would take the global assignment for itself
+  const jsContent = normalizeIifeGlobalAssignment(
+    readFileSync(jsPath, 'utf-8'),
+    appIdentifier,
+    emittedGlobalName,
+  );
+
+  writeFileSync(jsPath, css ? createCssInjection(css) + jsContent : jsContent);
+
+  cssFileNames.forEach(fileName => unlinkSync(join(outDir, fileName)));
+};
+
+// webpack emitted binaries as files (`asset/resource`, publicPath resolved at runtime) and
+// inlined only SVGs under svg-url-loader's 10 KB limit. Vite's library mode inlines every asset
+// whatever `assetsInlineLimit` says — `?no-inline` is the one thing it still honours, so the
+// same split is restored by tagging the id.
+const EMITTED_ASSET_RE = /\.(png|jpe?g|gif|webp|avif|woff2?|eot|ttf|otf|mp4|webm|ogg|mp3|wav|glb|gltf)$/i;
+const SVG_INLINE_LIMIT = 10000;
+
+const emitAssetsAsFilesPlugin = () => {
+  const resolving = new Set();
+
+  return {
+    name: 'corva-emit-assets-as-files',
+    // before vite:resolve, which would otherwise resolve the asset id first and never let this
+    // hook see it
+    enforce: 'pre',
+    async resolveId(source, importer, options) {
+      if (source.includes('?') || (!EMITTED_ASSET_RE.test(source) && !/\.svg$/i.test(source))) {
+        return null;
+      }
+
+      const key = `${importer}\u0000${source}`;
+
+      if (resolving.has(key)) {
+        return null;
+      }
+
+      resolving.add(key);
+
+      try {
+        const resolved = await this.resolve(source, importer, options);
+
+        if (!resolved || resolved.external) {
+          return null;
+        }
+
+        if (/\.svg$/i.test(resolved.id) && statSync(resolved.id).size < SVG_INLINE_LIMIT) {
+          return null;
+        }
+
+        return `${resolved.id}?no-inline`;
+      } finally {
+        resolving.delete(key);
+      }
+    },
+  };
+};
+
+const getCorvaApiEnvVariables = () => {
+  const apiEnv = process.env.CORVA_API_ENV || CORVA_API_ENVS.production;
+
+  if (Object.hasOwn(CORVA_API_ENVS, apiEnv)) {
+    return CORVA_API_ENV_VARIABLES[apiEnv];
+  }
+
+  console.error(`CORVA_API_ENV should be one of [${Object.keys(CORVA_API_ENVS).join(', ')}]`);
+
+  return process.exit(1);
+};
+
+// react-refresh can only swap React components, and a hot update of anything else reaches the
+// screen only when a component happens to re-read it while rendering. Measured on this app: all 7
+// component edits applied live, while all 7 edits to a module behind a memo boundary or consumed
+// while the app boots (a template default, a colour table, getStateColor) left the old value on
+// screen with `hmr update` in the terminal and no hint that it was stale. Nothing in the module
+// graph tells the two apart, so the honest rule is: components fast-refresh, every other module
+// under src reloads the page. A developer never has to guess whether an edit arrived.
+const COMPONENT_FILE_RE = /\.[jt]sx$/;
+const SCRIPT_FILE_RE = /\.[cm]?[jt]s$/;
+
+const reloadOnNonComponentEditPlugin = pwd => ({
+  name: 'corva-reload-on-non-component-edit',
+  handleHotUpdate({ file, server }) {
+    if (!file.startsWith(join(pwd, 'src')) || COMPONENT_FILE_RE.test(file) || !SCRIPT_FILE_RE.test(file)) {
+      return undefined;
+    }
+
+    server.config.logger.info(`page reload ${relative(pwd, file)} (not a component)`, { timestamp: true });
+    server.ws.send({ type: 'full-reload' });
+
+    return [];
+  },
+});
+
+// webpack tapped this after every compile: it warns when the installed @corva/ui is behind the
+// one published on npm. It is written as a webpack plugin, so it gets the single hook it taps,
+// and it is required here rather than at the top of the file because it reads @corva/ui's
+// package.json off the cwd as it loads, which has nothing to do with a build or a test run.
+const corvaUiVersionPlugin = () => ({
+  name: 'corva-ui-version',
+  configureServer() {
+    const checkCorvaUiVersion = require('../cjs/devcenter/webpack/plugins/checkCorvaUIVersion.js');
+    let warnWhenOutdated;
+
+    checkCorvaUiVersion({
+      hooks: { afterCompile: { tapPromise: (name, hook) => { warnWhenOutdated = hook; } } },
+    });
+
+    warnWhenOutdated({ getLogger: () => console });
+  },
+});
+
+// webpack's dev server ran react-error-overlay (through @pmmmwh/react-refresh-webpack-plugin),
+// which put every uncaught error and rejection on the screen. Vite's overlay only shows what
+// its own pipeline throws, so a platform call rejecting mid-render left the DevCenter sitting
+// on its loader with nothing but a console entry.
+// The auth branch is the one rejection that must not stop at an overlay: @corva/ui redirects to
+// /login itself for anything that goes through apiCore, but the DevCenter's first call is
+// jsonApi.getCurrentUser, whose 401 leaves useProvideAuth through an uncaught rejection, so a
+// session that is missing or expired never reaches the login screen.
+const RUNTIME_ERRORS_ID = 'virtual:corva-dev-runtime-errors';
+
+const AUTH_RECOVERY_MODULE = '@corva/ui/clients/api/AuthRecovery';
+
+const RUNTIME_ERRORS_SOURCE = `
+import { AuthRecovery } from '${AUTH_RECOVERY_MODULE}';
+
+const show = error => {
+  document.querySelectorAll('vite-error-overlay').forEach(overlay => overlay.close());
+  document.body.appendChild(
+    new (customElements.get('vite-error-overlay'))({
+      message: error?.message ?? String(error),
+      stack: error?.stack ?? '',
+    }),
+  );
+};
+
+// Browsers fire this when a ResizeObserver callback schedules another layout pass. It is a
+// notice, not a failure, and webpack-dev-server's overlay filtered it out too; showing it puts a
+// full-screen overlay over a working app.
+const isBenign = error => /ResizeObserver loop/.test(error?.message ?? String(error ?? ''));
+
+window.addEventListener('error', event => {
+  const error = event.error ?? event.message;
+
+  if (!isBenign(error)) show(error);
+});
+
+window.addEventListener('unhandledrejection', event => {
+  const authRecovery = AuthRecovery.getInstance();
+
+  if (authRecovery.isRefreshableAuthError(event.reason)) {
+    authRecovery.handleAuthFailure(event.reason);
+    return;
+  }
+
+  if (!isBenign(event.reason)) show(event.reason);
+});
+`;
+
+const runtimeErrorsPlugin = () => ({
+  name: 'corva-dev-runtime-errors',
+  resolveId(id) {
+    return id === RUNTIME_ERRORS_ID ? `\0${RUNTIME_ERRORS_ID}` : null;
+  },
+  load(id) {
+    return id === `\0${RUNTIME_ERRORS_ID}` ? RUNTIME_ERRORS_SOURCE : null;
+  },
+  transformIndexHtml: () => [
+    {
+      tag: 'script',
+      attrs: { type: 'module', src: `/@id/__x00__${RUNTIME_ERRORS_ID}` },
+      injectTo: 'body',
+    },
+  ],
+});
+
+// webpack's dev config added this entry point whenever the app depends on
+// mapbox-gl: it reads the access token off @corva/ui and publishes the
+// configured instance as window['mapbox-gl'].
+// A virtual module rather than a direct node_modules URL: mapbox-gl's dist is
+// CJS, so it only imports cleanly once Vite's resolver and dep optimizer see it.
+const MAPBOX_DEV_SETUP_ID = 'virtual:corva-mapbox-dev-setup';
+
+const mapboxDevSetupPlugin = () => ({
+  name: 'corva-mapbox-dev-setup',
+  resolveId(id) {
+    return id === MAPBOX_DEV_SETUP_ID ? `\0${MAPBOX_DEV_SETUP_ID}` : null;
+  },
+  load(id) {
+    return id === `\0${MAPBOX_DEV_SETUP_ID}`
+      ? "import '@corva/dc-platform-shared/cjs/devcenter/webpack/MapboxGlDevSetupEntryPoint.js';"
+      : null;
+  },
+  transformIndexHtml: () => [
+    {
+      tag: 'script',
+      attrs: { type: 'module', src: `/@id/__x00__${MAPBOX_DEV_SETUP_ID}` },
+      injectTo: 'body',
+    },
+  ],
+});
+
+// The DevCenter dev page edits the app's .env through this endpoint.
+const dotEnvEndpointPlugin = appDirectory => ({
+  name: 'corva-dotenv-endpoint',
+  configureServer(server) {
+    server.middlewares.use('/dotenv', (req, res, next) => {
+      if (req.method !== 'PATCH') {
+        return next();
+      }
+
+      const envPath = resolve(appDirectory, '.env');
+      const chunks = [];
+
+      req.on('data', chunk => chunks.push(chunk));
+      req.on('end', () => {
+        let update;
+
+        // webpack's dev server parsed the body with express.json(), which answers
+        // 400 on a malformed one; parsing it here would take the server down
+        try {
+          update = JSON.parse(Buffer.concat(chunks));
+        } catch {
+          res.statusCode = 400;
+          res.end();
+
+          return;
+        }
+
+        const currentEnv = existsSync(envPath) ? readFileSync(envPath, 'utf-8') : '';
+
+        writeFileSync(envPath, updateDotEnv(currentEnv, update));
+        res.statusCode = 200;
+        res.end();
+      });
+    });
+  },
+});
+
+// Vitest runs its dependency optimizer with `noDiscovery: true`, so a dependency is pre-bundled
+// only if it is listed. Unlisted, every test file re-evaluates that dependency's entire module
+// graph in its own isolated context — @corva/ui alone is 2022 ESM files — and a 169-file suite
+// takes 105 s where jest took 21 s (jest required one CJS module tree per worker). Pre-bundling
+// the dependencies the app imports brings the same suite to 23 s.
+const BARE_IMPORT_RE =
+  /(?:import|export)[^'"\n]*?from\s*['"]([^'"]+)['"]|\bimport\(\s*['"]([^'"]+)['"]\s*\)|\brequire\(\s*['"]([^'"]+)['"]\s*\)/g;
+const NAMESPACE_IMPORT_RE = /import\s*\*\s*as\s+([A-Za-z_$][\w$]*)\s*from\s*['"]([^'"]+)['"]/g;
+// react and the test renderers stay external whatever their package says: a copy inside the
+// pre-bundle is a second React instance, and the two cannot see each other's hooks or renderer
+// registry ("Could not auto-detect a React renderer")
+const TEST_EXTERNAL_DEP_RE = /^(react|react-dom|react-test-renderer)($|\/)|^@testing-library\//;
+
+const packageRoot = specifier =>
+  (specifier.startsWith('@') ? specifier.split('/').slice(0, 2) : [specifier.split('/')[0]]).join('/');
+
+const readPackageJson = (pwd, specifier) => {
+  const manifest = join(pwd, 'node_modules', packageRoot(specifier), 'package.json');
+
+  return existsSync(manifest) ? JSON.parse(readFileSync(manifest, 'utf-8')) : null;
+};
+
+// Only a dependency vite pre-bundles as ESM can be included: a CJS one reaches the app through
+// vite's interop, which changes what a `vi.mock` factory has to return and whether `new Dep()`
+// still constructs. This is the same decision vite records as `needsInterop`, read off the
+// package the way vite resolves its entry: `exports`/`type` win, then `module`, and a package
+// with a real `main` and nothing else is CJS.
+const isEsmPackage = (pwd, specifier) => {
+  const packageJson = readPackageJson(pwd, specifier);
+
+  if (!packageJson) {
+    return false;
+  }
+
+  if (packageJson.type === 'module' || JSON.stringify(packageJson.exports || {}).includes('"import"')) {
+    return true;
+  }
+
+  const main = packageJson.main && join(pwd, 'node_modules', packageRoot(specifier), packageJson.main);
+
+  return Boolean(packageJson.module) && !(main && (existsSync(main) || existsSync(`${main}.js`) || existsSync(join(main, 'index.js'))));
+};
+
+// the optimizer needs an entry file to bundle; 85 of @corva/ui's component folders ship only
+// index.d.ts, and `@corva/ui`'s own `main` points at a directory that is not published
+const hasEntryFile = (pwd, appRequire, specifier) => {
+  try {
+    return /\.(js|mjs|cjs)$/.test(appRequire.resolve(specifier));
+  } catch {
+    const base = join(pwd, 'node_modules', specifier);
+
+    return existsSync(`${base}.js`) || existsSync(join(base, 'index.js'));
+  }
+};
+
+const scanAppImports = pwd => {
+  const specifiers = new Set();
+  const spied = new Set();
+
+  const collect = dir => {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      const full = join(dir, entry.name);
+
+      if (entry.isDirectory()) {
+        collect(full);
+      } else if (/\.(js|jsx|ts|tsx|mjs|cjs)$/.test(entry.name)) {
+        const code = readFileSync(full, 'utf-8');
+
+        for (const match of code.matchAll(BARE_IMPORT_RE)) {
+          specifiers.add(match[1] || match[2] || match[3]);
+        }
+
+        // `import * as utils from 'x'` + `vi.spyOn(utils, 'y')`: a pre-bundled module hands the
+        // test a real, sealed ESM namespace and the spy throws
+        for (const match of code.matchAll(NAMESPACE_IMPORT_RE)) {
+          if (new RegExp(`spyOn\\(\\s*${match[1]}\\s*,`).test(code)) {
+            spied.add(match[2]);
+          }
+        }
+      }
+    }
+  };
+
+  collect(join(pwd, 'src'));
+
+  return { specifiers: [...specifiers], spied };
+};
+
+// The dev server pre-bundles whatever it discovers while serving a request, and the app's entry
+// is behind a dynamic import in the DevCenter harness, so discovery only starts once the browser
+// asks for the app: it then bundles the dependencies mid-session and force-reloads the page
+// ("optimized dependencies changed. reloading"). Listing them up front makes the first load one
+// pass instead of two — 4.6 s to a rendered app becomes 2.0 s on a 169-file app, cold cache.
+// Interop does not matter here the way it does for tests, so this list is everything importable.
+const getDevOptimizeDeps = (pwd, { specifiers }) => {
+  const appRequire = createRequire(join(pwd, 'package.json'));
+
+  return specifiers
+    .filter(specifier => /^@?[\w.-]/.test(specifier) && !specifier.startsWith('@/'))
+    .filter(specifier => !builtinModules.includes(specifier.replace(/^node:/, '')))
+    .filter(specifier => hasEntryFile(pwd, appRequire, specifier))
+    .sort();
+};
+
+const getTestOptimizeDeps = (pwd, { specifiers, spied }) => {
+  const appRequire = createRequire(join(pwd, 'package.json'));
+
+  return specifiers
+    .filter(specifier => /^@?[\w.-]/.test(specifier) && !specifier.startsWith('@/'))
+    .filter(specifier => !builtinModules.includes(specifier.replace(/^node:/, '')))
+    .filter(specifier => !TEST_EXTERNAL_DEP_RE.test(specifier))
+    .filter(specifier => !spied.has(specifier))
+    .filter(specifier => isEsmPackage(pwd, specifier) && hasEntryFile(pwd, appRequire, specifier))
+    .sort();
+};
+
+const DEP_CSS_ID = '\0corva-test-dep-css';
+const NODE_BUILTIN_PREFIX = '\0corva-test-node-builtin:';
+
+const testDepBundlePlugin = pwd => {
+  const appRequire = createRequire(join(pwd, 'package.json'));
+
+  return {
+    name: 'corva-test-dep-bundle',
+    resolveId(source, importer) {
+      // the shim below imports the real builtin
+      if (importer?.startsWith(NODE_BUILTIN_PREFIX)) {
+        return { id: source, external: true };
+      }
+
+      // React 17 publishes no exports map, so Node cannot resolve a bare `react/jsx-runtime`
+      // left in a pre-bundled chunk
+      if (source === 'react/jsx-runtime') {
+        return appRequire.resolve(source);
+      }
+
+      // jest mapped every stylesheet to a stub object; Node cannot load a .css file at all
+      if (/\.(css|scss|sass|less)(\?|$)/.test(source)) {
+        return DEP_CSS_ID;
+      }
+
+      // these tests run in Node, so a dependency that reads a builtin (debug -> tty,
+      // fflate -> worker_threads) gets the real one instead of the browser stub that throws
+      const builtin = source.replace(/^node:/, '');
+
+      return builtinModules.includes(builtin) ? `${NODE_BUILTIN_PREFIX}${builtin}` : null;
+    },
+    load(id) {
+      if (id === DEP_CSS_ID) {
+        return 'export default {};';
+      }
+
+      if (id.startsWith(NODE_BUILTIN_PREFIX)) {
+        const builtin = id.slice(NODE_BUILTIN_PREFIX.length);
+
+        return `export * from 'node:${builtin}';\nexport { default } from 'node:${builtin}';`;
+      }
+
+      return null;
+    },
+  };
+};
+
+export const createViteConfig = ({ pwd, overrides = {} }) => {
+  expand(dotenv.config({ path: resolve(pwd, '.env'), quiet: true }));
+
+  const packageJson = JSON.parse(readFileSync(resolve(pwd, 'package.json'), 'utf-8'));
+  const manifestJson = JSON.parse(readFileSync(resolve(pwd, 'manifest.json'), 'utf-8'));
+
+  const appKey = manifestJson.application.key;
+  const version = packageJson.version;
+  const appIdentifier = `${appKey.replace(/\./g, '_')}-${version}`;
+  const appIifeName = toLegalIdentifier(appIdentifier);
+
+  const globalDependencies = Object.keys(CORVA_GLOBAL_DEPENDENCIES);
+  const externalPatterns = globalDependencies.map(
+    libName => new RegExp(`(^${libName}$|^${libName}/)([^]+)?`),
+  );
+
+  const isExternal = source =>
+    // a stylesheet cannot be read off a window global: webpack bundled `mapbox-gl/dist/mapbox-gl.css`
+    // and so does this, and `this["mapbox-gl"].dist["mapbox-gl.css"]` is not even valid JS
+    !source.endsWith('.css') &&
+    !SKIP_IN_EXTERNALS.some(skipped => source.startsWith(skipped)) &&
+    externalPatterns.some(pattern => pattern.test(source));
+
+  // Package names are not valid JS identifiers, so every global is read off `this`.
+  // The name has to match on a package boundary, as isExternal does: matching on a
+  // bare prefix maps react-dom/client onto react and emits `this["react"]-dom.client`.
+  const toGlobal = id => {
+    const dep = globalDependencies.find(libName => id === libName || id.startsWith(`${libName}/`));
+
+    if (!dep) {
+      throw new Error(`Unknown dependency: ${id}`);
+    }
+
+    if (dep === id) {
+      return `this["${dep}"].default || this["${dep}"]`;
+    }
+
+    return `this["${dep}"]${id
+      .slice(dep.length)
+      .split('/')
+      .filter(Boolean)
+      .map(segment => `.${segment}`)
+      .join('')}`;
+  };
+
+  const getAlias = () => {
+    // jest resolved '~' to src for both templates; keep it in the build too
+    const defaultAlias = { '~': resolve(pwd, 'src') };
+    const tsconfigPath = resolve(pwd, 'tsconfig.json');
+
+    if (!existsSync(tsconfigPath)) {
+      return defaultAlias;
+    }
+
+    // tsconfig.json is JSONC, which JSON.parse rejects; a comment in it must not
+    // take the build down
+    let compilerOptions;
+
+    try {
+      ({ compilerOptions } = JSON.parse(readFileSync(tsconfigPath, 'utf-8')));
+    } catch {
+      console.warn(`Could not read compilerOptions.paths from ${tsconfigPath}; only '~' is aliased.`);
+
+      return defaultAlias;
+    }
+
+    // tsc resolves every `paths` value against `baseUrl`, not against the tsconfig's own directory
+    const pathsRoot = resolve(pwd, compilerOptions?.baseUrl || '.');
+
+    return {
+      ...defaultAlias,
+      ...Object.fromEntries(
+        Object.entries(compilerOptions?.paths || {})
+          // `"react": ["./node_modules/@types/react"]` tells tsc where the types live; as a runtime
+          // alias it points the bundler at a package with no code, and every `react/...` subpath
+          // then fails to resolve
+          .filter(([, [value]]) => !/(^|\/)@types\//.test(value))
+          .map(([key, [value]]) => (
+            key.endsWith('/*')
+              // keep the `/*` boundary: a bare `@` prefix-matches @types/react, @corva/ui and
+              // every other scoped package and rewrites them into src/
+              ? [`${key.slice(0, -1)}`, `${resolve(pathsRoot, value.replace('/*', ''))}/`]
+              : [key, resolve(pathsRoot, value)]
+          )),
+      ),
+    };
+  };
+
+  const appImports = scanAppImports(pwd);
+
+  const resolveConfig = ({ command }) => {
+    validateDependencies({ packageJson });
+
+    const config = {
+      root: pwd,
+      // vite's default asset list has no 3D model types, so without this it tries to parse a .glb
+      // as a module and fails with `stream did not contain valid UTF-8`
+      assetsInclude: ['**/*.glb', '**/*.gltf'],
+      optimizeDeps: {
+        // the harness module's own import belongs in this pass: discovered later, it becomes a
+        // second pre-bundled chunk in which AuthRecovery and apiCore's circular import
+        // initialises the wrong way round and apiCore's top-level getInstance() throws
+        include: [...getDevOptimizeDeps(pwd, appImports), AUTH_RECOVERY_MODULE],
+      },
+      server: {
+        host: process.env.HOST || 'app.local.corva.ai',
+        port: Number(process.env.PORT) || 8080,
+        // the local-debug flow loads this bundle into the platform from another origin, which
+        // webpack allowed with `allowedHosts: 'all'` plus a permissive CORS header. Without the
+        // same here the HMR socket is refused and the bundle stops live-reloading.
+        allowedHosts: true,
+        cors: true,
+      },
+      css: {
+        modules: {
+          localsConvention: 'camelCase',
+          generateScopedName: `[name]--[local]__[hash:base64:10]__${BUILD_ID}`,
+        },
+        // webpack's postcss-loader ran preset-env with no options, i.e. stage 2; a narrower
+        // stage silently stops transpiling CSS features the app already relies on
+        postcss: { plugins: [presetEnv()] },
+      },
+      plugins: [react(), dotEnvEndpointPlugin(pwd), rejectUnscopedCssPlugin(pwd)],
+      // webpack ran with `resolve.symlinks: false`; a yarn-linked @corva/ui has to keep
+      // resolving through the link, not through its real path
+      resolve: { alias: getAlias(), preserveSymlinks: true },
+      test: {
+        watch: false,
+        globals: true,
+        // jest mapped every CSS module through identity-obj-proxy, so `styles.foo` was the string
+        // 'foo' and a test could assert on `.foo`. vitest 4's default strategy hands back
+        // `_foo_<hash>` instead, which silently breaks those assertions.
+        css: { modules: { classNameStrategy: 'non-scoped' } },
+        // vitest transforms and imports a file's module graph the first time a worker touches it,
+        // where babel-jest served it from its cache. Under a full parallel run that first touch can
+        // outlast vitest's 5s default and fail a test that does no async work at all - it passes
+        // alone on a dev machine and times out on a CI runner.
+        testTimeout: 20000,
+        // jest ran with resetMocks: true; vitest defaults it to false
+        mockReset: true,
+        // measured on a 169-file app before the pre-bundle below: threads 105 s, the default
+        // forks pool 114 s, vmThreads 950 s
+        pool: 'threads',
+        deps: {
+          optimizer: {
+            client: {
+              enabled: true,
+              include: getTestOptimizeDeps(pwd, appImports),
+              rolldownOptions: { plugins: [testDepBundlePlugin(pwd)] },
+            },
+          },
+        },
+        environment: 'jsdom',
+        setupFiles: ['./vitest.setup.js'],
+        globalSetup: ['./vitest.global-setup.js'],
+        coverage: {
+          provider: 'v8',
+          include: ['src/**/*.{js,jsx,ts,tsx}'],
+          thresholds: { branches: 60, functions: 60, lines: 60, statements: 60 },
+        },
+      },
+    };
+
+    if (command === 'serve') {
+      return {
+        ...config,
+        define: {
+          // webpack's node.global shim made `global` the real global object; `{}` would hand
+          // every `global.x` read a fresh empty object and make `global.x = …` a syntax error
+          global: 'globalThis',
+          // Webpack's EnvironmentPlugin exposed the whole environment, so apps read
+          // their own REACT_APP_* vars straight off process.env.
+          'process.env': {
+            ...process.env,
+            DEV_CENTER_APP_PATH: '',
+            NODE_ENV: 'development',
+            REACT_APP_ENVIRONMENT: process.env.REACT_APP_ENVIRONMENT || 'development',
+            ...getCorvaApiEnvVariables(),
+          },
+        },
+        plugins: [
+          ...config.plugins,
+          ...(packageJson.dependencies?.['mapbox-gl'] ? [mapboxDevSetupPlugin()] : []),
+          runtimeErrorsPlugin(),
+          corvaUiVersionPlugin(),
+          reloadOnNonComponentEditPlugin(pwd),
+          // webpack's dev config copied @corva/ui's and @corva/dc-platform-shared's assets
+          // into static/media, where both packages request them by hash name (the loader gif
+          // of every DevCenter screen is one). stripBase drops the node_modules path the
+          // plugin would otherwise keep, which put them out of the platform's reach.
+          viteStaticCopy({
+            watch: { reloadPageOnChange: false },
+            targets: [
+              {
+                src: `${PLATFORM_SHARED_DIR}/assets/*`,
+                dest: 'static/media',
+                rename: { stripBase: true },
+              },
+              {
+                src: `${join(PLATFORM_SHARED_DIR, '../ui/assets')}/*`,
+                dest: 'static/media',
+                rename: { stripBase: true },
+              },
+            ],
+          }),
+        ],
+      };
+    }
+
+    return {
+      ...config,
+      define: {
+        // webpack's prod config ran `EnvironmentPlugin(process.env)`: one textual replacement
+        // per key, so only the keys the source actually reads reach the bundle. Without it an
+        // app reading e.g. process.env.CORVA_API_ENV silently compiles to undefined.
+        ...Object.fromEntries(
+          Object.entries(process.env)
+            .filter(([key]) => /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(key))
+            .map(([key, value]) => [`process.env.${key}`, JSON.stringify(value)]),
+        ),
+        'process.env': { NODE_ENV: 'production' },
+        'process.env.NODE_ENV': '"production"',
+        global: 'globalThis',
+      },
+      plugins: [
+        ...config.plugins,
+        emitAssetsAsFilesPlugin(),
+        viteStaticCopy({ targets: [{ src: 'manifest.json', dest: '.' }] }),
+        {
+          name: 'corva-single-file-bundle',
+          writeBundle(_options, bundle) {
+            finalizeJsBundle({
+              outDir: resolve(pwd, 'dist'),
+              cssFileNames: Object.keys(bundle).filter(fileName => fileName.endsWith('.css')),
+              appIdentifier,
+              emittedGlobalName: appIifeName,
+            });
+          },
+        },
+      ],
+      // an asset URL has to be resolved at runtime, from the bundle's own location: the same
+      // app.js is served from a different package directory for every version
+      experimental: {
+        renderBuiltUrl: (filename, { hostType }) =>
+          (hostType === 'css'
+            ? `${ASSET_MARKER}${filename}`
+            : { runtime: `__CORVA_ASSET_BASE__+${JSON.stringify(filename)}` }),
+      },
+      build: {
+        outDir: 'dist',
+        emptyOutDir: true,
+        copyPublicDir: false,
+        sourcemap: false,
+        cssCodeSplit: false,
+        minify: 'terser',
+        terserOptions: {
+          format: { comments: false },
+        },
+        // lib mode plus named exports keeps the IIFE compatible with the platform
+        // loader, which reads `this["appKey-version"].default.component`.
+        lib: {
+          entry: resolve(pwd, 'src/index.js'),
+          name: appIifeName,
+          fileName: () => 'app.js',
+          formats: ['iife'],
+        },
+        rolldownOptions: {
+          external: isExternal,
+          moduleTypes: { '.cjs': 'js' },
+          output: {
+            format: 'iife',
+            name: appIifeName,
+            entryFileNames: 'app.js',
+            // flat next to app.js, the way webpack's default assetModuleFilename emitted them
+            assetFileNames: '[hash][extname]',
+            globals: toGlobal,
+            exports: 'named',
+            // Rolldown doesn't rewrite `require()` inside bundled CJS modules (e.g.
+            // react-is) to their external global references. This shim resolves them
+            // to the globals the IIFE receives as params.
+            intro:
+              `var require=function(id){var g=globalThis[id];return g&&g.default||g;};` +
+              `var __CORVA_ASSET_BASE__=${ASSET_BASE_EXPR};`,
+          },
+          plugins: [
+            {
+              // Rolldown rejects `typeof require` as a define key (not an identifier),
+              // so the CJS-detection branches are stripped by transform instead.
+              name: 'replace-typeof-require',
+              transform(code) {
+                if (!code.includes('typeof require')) return null;
+
+                return { code: code.replaceAll('typeof require', '"undefined"'), map: null };
+              },
+            },
+            license({
+              thirdParty: { output: resolve(pwd, 'dist/app.js.LICENSE.txt') },
+            }),
+          ],
+        },
+      },
+    };
+  };
+
+  return defineConfig(env => mergeConfig(resolveConfig(env), overrides));
+};