perf(cli): code-split lowlight to cut startup V8 parse cost

esbuild.config.js

@@ -74,9 +74,12 @@ const external = [
 
 esbuild
   .build({
-    entryPoints: ['packages/cli/index.ts'],
+    entryPoints: { cli: 'packages/cli/index.ts' },
     bundle: true,
-    outfile: 'dist/cli.js',
+    outdir: 'dist',
+    entryNames: '[name]',
+    chunkNames: 'chunks/[name]-[hash]',
+    splitting: true,
     platform: 'node',
     format: 'esm',
     target: 'node22',
@@ -103,6 +106,11 @@ esbuild
       'process.env.CLI_VERSION': JSON.stringify(pkg.version),
       // Make global available for compatibility
       global: 'globalThis',
+      // Redirect free __dirname/__filename references to the shim so that
+      // vendored libraries that emit their own `var __dirname` locals don't
+      // collide with our injected bindings when code-splitting is enabled.
+      __dirname: '__qwen_dirname',
+      __filename: '__qwen_filename',
     },
     loader: { '.node': 'file' },
     plugins: [wasmBinaryPlugin, wasmLoader({ mode: 'embedded' })],

packages/cli/src/commands/extensions/new.ts

@@ -5,9 +5,9 @@
  */
 
 import { access, cp, mkdir, readdir, writeFile } from 'node:fs/promises';
-import { join, dirname, basename } from 'node:path';
+import { join, basename } from 'node:path';
 import type { CommandModule } from 'yargs';
-import { fileURLToPath } from 'node:url';
+import { resolveBundleDir } from '@qwen-code/qwen-code-core';
 import { getErrorMessage } from '../../utils/errors.js';
 import { writeStdoutLine, writeStderrLine } from '../../utils/stdioHelpers.js';
 
@@ -16,10 +16,13 @@ interface NewArgs {
   template?: string;
 }
 
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = dirname(__filename);
-
-const EXAMPLES_PATH = join(__dirname, 'examples');
+// Anchor the bundled extension-examples directory at the on-disk sibling of
+// `cli.js` (i.e. `dist/examples/`, populated by `prepare-package.js`). Today
+// this module is bundled into `cli.js` itself, so the `chunks/` strip in
+// `resolveBundleDir` is a no-op — but using the same helper as the other
+// asset-anchor sites means this code stays correct if esbuild later hoists
+// this module into a shared chunk.
+const EXAMPLES_PATH = join(resolveBundleDir(import.meta.url), 'examples');
 
 async function pathExists(path: string) {
   try {

packages/cli/src/i18n/index.ts

@@ -6,9 +6,9 @@
 
 import * as fs from 'node:fs';
 import * as path from 'node:path';
-import { fileURLToPath, pathToFileURL } from 'node:url';
+import { pathToFileURL } from 'node:url';
 import { writeStderrLine } from '../utils/stdioHelpers.js';
-import { Storage } from '@qwen-code/qwen-code-core';
+import { Storage, resolveBundleDir } from '@qwen-code/qwen-code-core';
 import {
   type SupportedLanguage,
   SUPPORTED_LANGUAGES,
@@ -42,10 +42,14 @@ type TranslationLoadResult =
   | { translations?: undefined; error: Error };
 
 // Path helpers
-const getBuiltinLocalesDir = (): string => {
-  const __filename = fileURLToPath(import.meta.url);
-  return path.join(path.dirname(__filename), 'locales');
-};
+//
+// Anchor the bundled locales directory at the on-disk sibling of `cli.js`
+// (i.e. `dist/locales/`, populated by `prepare-package.js`). See
+// `resolveBundleDir` for the rationale behind stripping a trailing
+// `chunks/` segment when this module is hoisted into a shared esbuild
+// chunk.
+const getBuiltinLocalesDir = (): string =>
+  path.join(resolveBundleDir(import.meta.url), 'locales');
 
 const getUserLocalesDir = (): string =>
   path.join(Storage.getGlobalQwenDir(), 'locales');

packages/cli/src/ui/AppContainer.tsx

@@ -61,6 +61,7 @@ import {
   ToolNames,
 } from '@qwen-code/qwen-code-core';
 import { buildResumedHistoryItems } from './utils/resumeHistoryUtils.js';
+import { loadLowlight } from './utils/lowlightLoader.js';
 import {
   getStickyTodos,
   getStickyTodoMaxVisibleItems,
@@ -406,6 +407,31 @@ export const AppContainer = (props: AppContainerProps) => {
   const lastTitleRef = useRef<string | null>(null);
   const staticExtraHeight = 3;
 
+  // Prefetch the lowlight chunk on mount so the dynamic import is already
+  // in flight before the first code block needs colorizing. Without this
+  // kick-off, code blocks committed to ink's append-only <Static> region
+  // before the import resolves stay plain text for the rest of the session
+  // — Static can only be re-rendered via `refreshStatic`, which is not
+  // wired to lowlight load completion. Common reachable paths: short
+  // `--prompt -p` runs that finalize quickly, Ctrl+C-cancelled first turns,
+  // and the first-paint history replay on `--resume`. Firing the load
+  // from mount keeps the startup parse-cost win (V8 still parses off the
+  // critical path) while restoring the "first paint sees a loaded
+  // instance" guarantee. Errors are silently swallowed; CodeColorizer
+  // already falls back to plain text on miss.
+  useEffect(() => {
+    void loadLowlight().catch((err) => {
+      // The loader latches its failure permanently (see `lowlightFailed` in
+      // `lowlightLoader.ts`), so this catch only fires once per session. Log
+      // to the debug channel so a degraded syntax-highlight state (corrupted
+      // install, missing chunk) leaves a breadcrumb without spamming the
+      // user's TTY — `CodeColorizer` already falls back to plain text.
+      debugLogger.warn(
+        `Failed to load lowlight chunk; code blocks will render as plain text: ${err instanceof Error ? err.message : String(err)}`,
+      );
+    });
+  }, []);
+
   // Initialize config (runs once on mount)
   useEffect(() => {
     (async () => {

packages/cli/src/ui/utils/CodeColorizer.tsx

@@ -6,7 +6,6 @@
 
 import React from 'react';
 import { Text, Box } from 'ink';
-import { common, createLowlight } from 'lowlight';
 import type {
   Root,
   Element,
@@ -22,11 +21,20 @@ import {
 } from '../components/shared/MaxSizedBox.js';
 import type { LoadedSettings } from '../../config/settings.js';
 import { createDebugLogger } from '@qwen-code/qwen-code-core';
+import { getLowlightInstance, loadLowlight } from './lowlightLoader.js';
 
-// Configure theming and parsing utilities.
-const lowlight = createLowlight(common);
 const debugLogger = createDebugLogger('CODE_COLORIZER');
 
+// Lowlight is heavy (~1.5 MB bundled, ~36–60 ms V8 parse). It's loaded lazily
+// from `./lowlightLoader.js` via dynamic import so it lives in a separate
+// esbuild chunk that's only parsed once a code block actually needs
+// highlighting. To avoid leaving code blocks committed to ink's append-only
+// <Static> region as plain text for the rest of the session, AppContainer
+// fires `loadLowlight()` from a mount effect — in steady state the import
+// is already resolved by the time any colorize call lands. The fallback
+// below still handles the brief window before resolution and any
+// permanent-failure path (latched inside lowlightLoader).
+
 function renderHastNode(
   node: Root | Element | HastText | RootContent,
   theme: Theme,
@@ -97,11 +105,21 @@ function highlightAndRenderLine(
   language: string | null,
   theme: Theme,
 ): React.ReactNode {
+  // Trigger the lazy load on first use; until it resolves, fall back to a
+  // plain-text rendering of the line. The next React render of the
+  // surrounding subtree will pick up the highlighted version.
+  const ll = getLowlightInstance();
+  if (!ll) {
+    void loadLowlight().catch((err) => {
+      debugLogger.error('[CodeColorizer] failed to load lowlight:', err);
+    });
+    return line;
+  }
   try {
     const getHighlightedLine = () =>
-      !language || !lowlight.registered(language)
-        ? lowlight.highlightAuto(line)
-        : lowlight.highlight(language, line);
+      !language || !ll.registered(language)
+        ? ll.highlightAuto(line)
+        : ll.highlight(language, line);
 
     const renderedNode = renderHastNode(getHighlightedLine(), theme, undefined);
 

packages/cli/src/ui/utils/lowlightLoader.ts

@@ -0,0 +1,72 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Standalone loader for the lowlight syntax-highlight engine.
+ *
+ * Kept in its own module — with zero imports beyond `lowlight` itself — so
+ * that priming the cache from `test-setup.ts` does not transitively pull
+ * `themeManager`, settings, or `@qwen-code/qwen-code-core` into every test
+ * file's module graph. That cascade was observed to alter theme/config test
+ * outcomes (e.g. theme-manager auto-detection and QWEN_HOME env tests).
+ */
+
+import type { Root } from 'hast';
+
+export type Lowlight = {
+  registered(language: string): boolean;
+  highlight(language: string, value: string): Root;
+  highlightAuto(value: string): Root;
+};
+
+let lowlightInstance: Lowlight | null = null;
+let lowlightLoad: Promise<Lowlight> | null = null;
+// Latches once the dynamic import has failed permanently. Without this,
+// every React render of a code block would re-call `loadLowlight()` and
+// re-attempt `import('lowlight')` — wasting CPU and spamming debug logs on
+// every keystroke if the chunk file is permanently missing (corrupted
+// install). A single permanent latch is acceptable because the colorizer
+// already falls back to plain text on miss; recovery requires a fresh
+// process anyway.
+let lowlightFailed = false;
+let lowlightError: Error | null = null;
+
+export function getLowlightInstance(): Lowlight | null {
+  return lowlightInstance;
+}
+
+/**
+ * Kicks off (or returns the in-flight) load of the lowlight chunk. Exported
+ * for two callers:
+ *   1. `CodeColorizer.tsx` — fires the load on first colorize call so the
+ *      next React commit picks up the highlighted output.
+ *   2. `test-setup.ts` — awaits this once to keep snapshot tests
+ *      deterministic without dragging more modules into the test graph.
+ *
+ * Once an import attempt fails the failure is latched (see `lowlightFailed`)
+ * and subsequent calls return the same rejection without retrying.
+ */
+export function loadLowlight(): Promise<Lowlight> {
+  if (lowlightInstance) return Promise.resolve(lowlightInstance);
+  if (lowlightFailed) {
+    return Promise.reject(
+      lowlightError ?? new Error('lowlight import previously failed'),
+    );
+  }
+  if (lowlightLoad) return lowlightLoad;
+  lowlightLoad = import('lowlight')
+    .then((mod) => {
+      lowlightInstance = mod.createLowlight(mod.common) as Lowlight;
+      return lowlightInstance;
+    })
+    .catch((err) => {
+      lowlightFailed = true;
+      lowlightError = err instanceof Error ? err : new Error(String(err));
+      lowlightLoad = null;
+      throw err;
+    });
+  return lowlightLoad;
+}

packages/cli/test-setup.ts

@@ -16,3 +16,23 @@ if (process.env['QWEN_DEBUG_LOG_FILE'] === undefined) {
 }
 
 import './src/test-utils/customMatchers.js';
+
+// Lowlight is loaded asynchronously in production to keep it out of the
+// startup-critical bundle chunk. Snapshot tests render synchronously via
+// `lastFrame()` and would otherwise capture the plain-text fallback before
+// the dynamic import resolves. Prime the cache once here so every test sees
+// the fully-highlighted output. The loader is intentionally a tiny standalone
+// module (no transitive imports of themeManager / settings / core) so this
+// prime does not perturb any other test's module graph.
+import { loadLowlight } from './src/ui/utils/lowlightLoader.js';
+try {
+  await loadLowlight();
+} catch (err) {
+  // Don't crash the entire test run if lowlight fails to import; snapshot
+  // tests that hit a code block will then render the plain-text fallback.
+  console.warn(
+    '[test-setup] Failed to prime lowlight cache, snapshot tests may ' +
+      'show plain-text fallback:',
+    String(err),
+  );
+}

packages/core/src/index.ts

@@ -269,6 +269,7 @@ export * from './followup/index.js';
 // ============================================================================
 
 export * from './utils/browser.js';
+export * from './utils/bundlePaths.js';
 export * from './utils/configResolver.js';
 export * from './utils/debugLogger.js';
 export * from './utils/editor.js';

packages/core/src/skills/skill-manager.ts

@@ -8,8 +8,8 @@ import * as fs from 'fs/promises';
 import * as fsSync from 'fs';
 import * as path from 'path';
 import * as os from 'os';
-import { fileURLToPath } from 'url';
 import { watch as watchFs, type FSWatcher } from 'chokidar';
+import { resolveBundleDir } from '../utils/bundlePaths.js';
 import { parse as parseYaml } from '../utils/yaml-parser.js';
 import * as yaml from 'yaml';
 import type {
@@ -86,8 +86,13 @@ export class SkillManager {
   private activationRegistry: SkillActivationRegistry | null = null;
 
   constructor(private readonly config: Config) {
+    // Anchor the bundled skills directory at the on-disk sibling of
+    // `cli.js` (i.e. `dist/bundled/`, populated by `copy_bundle_assets.js`).
+    // See `resolveBundleDir` for the rationale behind stripping a trailing
+    // `chunks/` segment when this module is hoisted into a shared esbuild
+    // chunk.
     this.bundledSkillsDir = path.join(
-      path.dirname(fileURLToPath(import.meta.url)),
+      resolveBundleDir(import.meta.url),
       'bundled',
     );
   }

packages/core/src/utils/bundlePaths.ts

@@ -0,0 +1,42 @@
+/**
+ * @license
+ * Copyright 2025 Qwen team
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+/**
+ * Resolves the on-disk directory a module should treat as a sibling of the
+ * bundled `cli.js` entry, given the caller's `import.meta.url`.
+ *
+ * Why this exists: `esbuild.config.js` ships with `splitting: true` and
+ * `chunkNames: 'chunks/[name]-[hash]'`, so modules that are hoisted into a
+ * shared chunk live at `dist/chunks/<chunk>.js`. Any code that derives a path
+ * from `import.meta.url` and joins a sibling asset (e.g. `bundled/`,
+ * `vendor/`, `locales/`, `examples/`) would otherwise land in
+ * `dist/chunks/<asset>` and miss the actual `dist/<asset>` location.
+ *
+ * The fix is intentionally narrow: only strip the trailing path segment when
+ * its basename is exactly `chunks`. In source / transpiled / non-split
+ * builds the trailing segment is the source directory's own name, never
+ * `chunks`, so this is a no-op there.
+ *
+ * Centralising the check keeps the coupling to `esbuild.config.js`'s
+ * `chunkNames` setting in one place — if that ever changes, only this helper
+ * needs to be updated (rather than each call site).
+ *
+ * @param importMetaUrl Pass `import.meta.url` from the caller. It must be
+ *   evaluated at the caller's chunk so the resolution matches that chunk's
+ *   on-disk location; centralising the `fileURLToPath`/`dirname` work here
+ *   does not change that.
+ * @returns The directory that should be used as the anchor for sibling
+ *   asset lookups (`path.join(result, 'bundled')`, etc.).
+ */
+export function resolveBundleDir(importMetaUrl: string): string {
+  const moduleDir = path.dirname(fileURLToPath(importMetaUrl));
+  return path.basename(moduleDir) === 'chunks'
+    ? path.dirname(moduleDir)
+    : moduleDir;
+}

packages/core/src/utils/ripgrepUtils.ts

@@ -5,8 +5,8 @@
  */
 
 import path from 'node:path';
-import { fileURLToPath } from 'node:url';
 import { execFile } from 'node:child_process';
+import { resolveBundleDir } from './bundlePaths.js';
 import { fileExists } from './fileUtils.js';
 import { execCommand, isCommandAvailable } from './shell-utils.js';
 import { createDebugLogger } from './debugLogger.js';
@@ -57,9 +57,11 @@ function wslTimeout(): number {
     : RIPGREP_RUN_TIMEOUT_MS;
 }
 
-// Get the directory of the current module
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = path.dirname(__filename);
+// Resolved at module load to the directory that should anchor sibling-asset
+// lookups (here: the vendored ripgrep binary copied to `dist/vendor/`). See
+// `resolveBundleDir` for the rationale behind stripping a trailing `chunks/`
+// segment when this module is hoisted into a shared esbuild chunk.
+const __dirname = resolveBundleDir(import.meta.url);
 
 type Platform = 'darwin' | 'linux' | 'win32';
 type Architecture = 'x64' | 'arm64';

scripts/create-standalone-package.js

@@ -36,9 +36,15 @@ const TARGETS = new Map([
   ['win-x64', { outputExtension: 'zip', nodeExecutable: ['node.exe'] }],
 ]);
 
-const DIST_REQUIRED_PATHS = ['cli.js', 'vendor', 'bundled/qc-helper/docs'];
+const DIST_REQUIRED_PATHS = [
+  'cli.js',
+  'chunks',
+  'vendor',
+  'bundled/qc-helper/docs',
+];
 const DIST_ALLOWED_ENTRIES = new Set([
   'cli.js',
+  'chunks',
   'vendor',
   'bundled',
   'package.json',