@checkstack/ui 1.11.0 → 1.13.0

package/src/components/CodeEditor/TypefoxEditor.tsx

@@ -19,16 +19,21 @@
 // (Monarch grammars for ~80 languages) without pulling in the extension host
 // (no SharedArrayBuffer / COOP / COEP needed).
 import "@codingame/monaco-vscode-standalone-languages";
-// The named imports below ALSO trigger this package's side-effect registration
-// of the standalone TypeScript language features (defaults + ts.worker). We use
-// them to configure the TS/JS language services + inject ambient context types.
+// TS/JS language-service setup (compiler options, ambient stdlib types, worker
+// factory) lives in the shared `monacoTsService` module so the headless
+// `validateScripts` validator can reuse the exact same configured singletons.
 import {
   typescriptDefaults,
   javascriptDefaults,
-  ScriptTarget,
-  ModuleKind,
-  ModuleResolutionKind,
-} from "@codingame/monaco-vscode-standalone-typescript-language-features";
+  ensureStandaloneWorkerFactory,
+} from "./monacoTsService";
+import {
+  areVscodeServicesReady,
+  claimColdInit,
+  markVscodeServicesReady,
+  onVscodeServicesReady,
+  releaseColdInit,
+} from "./vscodeServicesSignal";
 // Named import also triggers the side-effect registration of the REAL VS Code
 // JSON language service (proper highlighting + completion + folding), replacing
 // the hand-rolled `json-template` Monarch grammar. We turn its built-in
@@ -41,21 +46,25 @@ import { jsonDefaults } from "@codingame/monaco-vscode-standalone-json-language-
 // `languageStatusServiceOverride` below).
 import getLanguagesServiceOverride from "@codingame/monaco-vscode-languages-service-override";
 
-// Worker entry URLs, bundled and resolved by Vite via the `?worker&url`
-// suffix. We import them as URL STRINGS (not Worker constructors) because
-// monaco-languageclient's worker factory consumes `loader().url.toString()`.
-// Vite's STATIC `?worker&url` resolution is required here: a runtime
-// `new URL(specifier, import.meta.url)` would resolve the bare specifier
-// relative to THIS source file (e.g. core/ui/src/components/CodeEditor/...)
-// and 404. The editor worker comes from the monaco-editor drop-in
-// (@codingame/monaco-vscode-editor-api); the TypeScript worker (which also
-// serves JavaScript) from the standalone language-features package.
-import editorWorkerUrl from "@codingame/monaco-vscode-editor-api/esm/vs/editor/editor.worker.js?worker&url";
-import tsWorkerUrl from "@codingame/monaco-vscode-standalone-typescript-language-features/worker?worker&url";
-import jsonWorkerUrl from "@codingame/monaco-vscode-standalone-json-language-features/worker?worker&url";
-
-import { useEffect, useId, useRef, useState } from "react";
-import * as monaco from "@codingame/monaco-vscode-editor-api";
+
+import {
+  type CSSProperties,
+  useEffect,
+  useId,
+  useLayoutEffect,
+  useRef,
+  useState,
+} from "react";
+// Types come from the package directly (type-only, so it pulls no runtime code
+// and the lint rule allows it). RUNTIME monaco access goes through the guarded
+// accessor (`monacoRuntime`, see monacoGuard.ts): in dev it throws if a
+// `monaco.editor.*` / `monaco.languages.*` function runs before the services
+// are initialized, preventing the "Services are already initialized" regression
+// class. `no-restricted-imports` forbids importing the raw editor-api value.
+import type * as monaco from "@codingame/monaco-vscode-editor-api";
+import { monaco as monacoRuntime } from "./monacoGuard";
+import { useTheme } from "../ThemeProvider";
+import { MONACO_THEME_MAP, VARIABLE_TOKEN_COLOR } from "./editorTheme";
 import { MonacoEditorReactComp } from "@typefox/monaco-editor-react";
 import { extractBracketKeyGroups } from "./bracketKeyGroups";
 import { validateJsonTemplate } from "./validateJsonTemplate";
@@ -68,131 +77,152 @@ import {
   matchShellEnvVarTrigger,
 } from "./shellEnvVarMatcher";
 import type {
+  AcquireTypes,
   CodeEditorLanguage,
   EditorMarker,
   ShellEnvVar,
   TemplateProperty,
 } from "./types";
+import {
+  importSpecifierCompletionContext,
+  mergeImportCompletionEntries,
+  parseBareImportSpecifiers,
+  planAcquisitions,
+} from "./importSpecifiers";
+// Authoritative, build-time-derived list of importable runtime built-in
+// specifiers (`node:fs`, bare `fs`, `bun`, `bun:test`, ...). Generated from the
+// SAME bundled `@types/node` + `bun-types` declarations the editor injects (see
+// scripts/generate-stdlib-types.ts -> extractBuiltinModuleSpecifiers), so the
+// import-name completions never drift from the runtime stdlib. Imported as a
+// plain JSON module (tiny: ~115 names); the bulky type bodies stay in the
+// separately code-split stdlib-types.json.
+import builtinModulesJson from "./generated/builtin-modules.json";
 import {
   type EditorAppConfig,
   type TextContents,
 } from "monaco-languageclient/editorApp";
 import { type MonacoVscodeApiConfig } from "monaco-languageclient/vscodeApiWrapper";
-import {
-  // `useWorkerFactory` is a plain library registration function, not a React
-  // hook. We alias away the `use` prefix so the `react-hooks/rules-of-hooks`
-  // lint rule (which keys purely off the identifier name) does not misfire.
-  useWorkerFactory as registerWorkerFactory,
-  Worker,
-  type WorkerFactoryConfig,
-  type WorkerLoader,
-} from "monaco-languageclient/workerFactory";
-
-// The logger type originates from `@codingame/monaco-vscode-log-service-override`,
-// which is not a direct dependency of this package. We derive it from the
-// `WorkerFactoryConfig` we already import so we never reach for a transitive
-// specifier (and never need an `any`).
-type WorkerFactoryLogger = WorkerFactoryConfig["logger"];
-
-const editorWorkerLoader: WorkerLoader = () =>
-  new Worker(editorWorkerUrl, { type: "module" });
-
-const tsWorkerLoader: WorkerLoader = () =>
-  new Worker(tsWorkerUrl, { type: "module" });
-
-const jsonWorkerLoader: WorkerLoader = () =>
-  new Worker(jsonWorkerUrl, { type: "module" });
+// ─── Lazy Automatic Type Acquisition (ATA) registry ─────────────────────────
+//
+// The TS/JS language services are singletons, so acquired package types are
+// registered ONCE and shared across every editor instance (a package imported
+// in one script editor is then typed in all of them — harmless, since the
+// declarations are the same install). State is module-scoped:
+//
+//  - `acquiredFilePaths`: virtual paths already passed to addExtraLib (dedupe
+//    so two editors importing the same package don't double-register a file).
+//  - `acquiredSpecifiers`: package names already acquired (skip the fetch).
+//  - `acquireResetKey`: the install identity (lockfile hash) the current
+//    acquired-set belongs to; when it changes, the set is reset so types
+//    refresh against the new install.
+const acquiredFilePaths = new Set<string>();
+const acquiredSpecifiers = new Set<string>();
+let currentAcquireResetKey: string | undefined;
 
 /**
- * Registers the worker loaders required for the standalone (classic) Monaco
- * setup. We only need the generic editor worker plus the TypeScript worker
- * (which also serves JavaScript). Mirrors the upstream `defineClassicWorkers`
- * helper referenced above. The underlying `useWorkerFactory` export is a
- * plain library registration function (not a React hook) despite its name;
- * it is called from module scope here, never from a component render.
+ * Reset the acquired-set when the install identity changes. The already-
+ * registered extra-libs are left in place (disposing them is unnecessary —
+ * the new install re-registers the same virtual paths, and addExtraLib
+ * overwrites by path), but the specifier set clears so each package is
+ * re-fetched against the new hash.
  */
-const configureStandaloneWorkerFactory = (
-  logger?: WorkerFactoryLogger,
-): void => {
-  registerWorkerFactory({
-    workerLoaders: {
-      editorWorkerService: editorWorkerLoader,
-      // Both must be defined or the worker factory errors (see upstream
-      // helper-classic.ts).
-      javascript: tsWorkerLoader,
-      typescript: tsWorkerLoader,
-      json: jsonWorkerLoader,
-    },
-    logger,
-  });
-};
-
-// Base compiler options for the standalone TS + JS services. `types` (node +
-// bun-types) is added only once the stdlib bundle has loaded (see
-// ensureStandaloneStdlib), so the service doesn't transiently error on a
-// missing `node` type while the ~3 MB bundle is still fetching.
-const BASE_COMPILER_OPTIONS = {
-  target: ScriptTarget.ESNext,
-  module: ModuleKind.ESNext,
-  moduleResolution: ModuleResolutionKind.NodeJs,
-  lib: ["esnext"],
-  allowNonTsExtensions: false,
-  noEmit: true,
-  strict: true,
-  esModuleInterop: true,
+const syncAcquireResetKey = (resetKey: string | undefined): void => {
+  if (resetKey === currentAcquireResetKey) return;
+  currentAcquireResetKey = resetKey;
+  acquiredSpecifiers.clear();
+  acquiredFilePaths.clear();
 };
 
 /**
- * Configure the standalone TS + JS language services ONCE at module load.
- * `typescriptDefaults` / `javascriptDefaults` are singletons, so doing this at
- * module scope (not per-mount) guarantees the first editor to mount cannot
- * start the service with stale defaults - the timing race the legacy monaco
- * editor hit.
+ * Register one acquired package's declaration files with both the TS and JS
+ * services, deduped by virtual path. Paths are `node_modules/...`-relative;
+ * we mount each at `file:///<path>` so NodeJs + `@types` resolution finds it.
  */
-const configureTypeScriptDefaults = (): void => {
-  for (const defaults of [typescriptDefaults, javascriptDefaults]) {
-    defaults.setCompilerOptions({ ...BASE_COMPILER_OPTIONS });
-    // 1108: a top-level `return` is valid because the runtime wraps scripts in
-    // an async IIFE (same suppression as the legacy editor).
-    defaults.setDiagnosticsOptions({ diagnosticCodesToIgnore: [1108] });
-    // Push models to the worker eagerly so diagnostics/completions are ready on
-    // the first keystroke.
-    defaults.setEagerModelSync(true);
+const registerAcquiredFiles = (
+  files: ReadonlyArray<{ path: string; content: string }>,
+): void => {
+  for (const file of files) {
+    const uri = `file:///${file.path}`;
+    if (acquiredFilePaths.has(uri)) continue;
+    acquiredFilePaths.add(uri);
+    for (const defaults of [typescriptDefaults, javascriptDefaults]) {
+      defaults.addExtraLib(file.content, uri);
+    }
   }
 };
 
-configureTypeScriptDefaults();
+// ─── @checkstack/sdk editor-type injection ──────────────────────────────────
+//
+// The running release's SDK editor bundle (ambient `.d.ts` for the script
+// helpers + typed client) is mounted ONCE into the shared TS/JS services,
+// keyed by release version. A deployment upgrade changes the key, so the libs
+// reset and the editor never serves stale SDK types (plan §6.2).
+const sdkMountedPaths = new Set<string>();
+let currentSdkResetKey: string | undefined;
 
 /**
- * Lazy-load the bundled `@types/node` + `bun-types` declarations into the
- * standalone TS service so script editors have `console`, `fetch`, `process`,
- * `Bun`, etc. typed (parity with the legacy editor). The ~3 MB bundle is
- * code-split into its own chunk and fetched once. Ported from the legacy
- * `monacoStdlib.ts` (without its `@monaco-editor/react` dependency). Runs at
- * module load; this file is browser-only so the dynamic import is safe here.
+ * Mount the SDK bundle files, resetting on a release-version change. addExtraLib
+ * overwrites by path, so a version bump re-mounts the same virtual paths with
+ * fresh content; the mounted-path set just dedupes within a version so two
+ * editors don't double-register.
  */
-let stdlibLoadStarted = false;
-const ensureStandaloneStdlib = async (): Promise<void> => {
-  if (stdlibLoadStarted) {
-    return;
+const mountSdkTypes = ({
+  files,
+  resetKey,
+}: {
+  files: ReadonlyArray<{ path: string; content: string }>;
+  resetKey: string | undefined;
+}): void => {
+  if (resetKey !== currentSdkResetKey) {
+    currentSdkResetKey = resetKey;
+    sdkMountedPaths.clear();
   }
-  stdlibLoadStarted = true;
-  const stdlibModule = await import("./generated/stdlib-types.json");
-  const bundle = stdlibModule.default;
-  for (const defaults of [typescriptDefaults, javascriptDefaults]) {
-    for (const [path, content] of Object.entries(bundle)) {
-      defaults.addExtraLib(content, `file:///${path}`);
+  for (const file of files) {
+    const uri = `file:///${file.path}`;
+    // On a fresh version we re-mount (overwrite) even if the path was seen
+    // under a prior key; within a version, skip an already-mounted path.
+    if (sdkMountedPaths.has(uri)) continue;
+    sdkMountedPaths.add(uri);
+    for (const defaults of [typescriptDefaults, javascriptDefaults]) {
+      defaults.addExtraLib(file.content, uri);
     }
-    // The @types/node + bun-types declarations now exist at their node_modules
-    // virtual paths, so include them ambiently.
-    defaults.setCompilerOptions({
-      ...BASE_COMPILER_OPTIONS,
-      types: ["node", "bun-types"],
-    });
   }
 };
 
-void ensureStandaloneStdlib();
+/**
+ * Acquire types for every NEW bare specifier in `source`, against the given
+ * resolver. Pure planning (`parseBareImportSpecifiers` / `planAcquisitions`)
+ * is unit-tested; this thin async glue is intentionally untested (no DOM /
+ * network in unit tests). A specifier is marked acquired even when it returns
+ * no files, so a typeless package isn't re-fetched on every keystroke.
+ */
+const runTypeAcquisition = async ({
+  source,
+  acquireTypes,
+  resetKey,
+}: {
+  source: string;
+  acquireTypes: AcquireTypes;
+  resetKey: string | undefined;
+}): Promise<void> => {
+  syncAcquireResetKey(resetKey);
+  const specifiers = parseBareImportSpecifiers(source);
+  const toAcquire = planAcquisitions({
+    specifiers,
+    acquired: acquiredSpecifiers,
+  });
+  for (const specifier of toAcquire) {
+    // Mark first so concurrent/keystroke re-runs don't double-fetch.
+    acquiredSpecifiers.add(specifier);
+    try {
+      const files = await acquireTypes(specifier);
+      registerAcquiredFiles(files);
+    } catch {
+      // A failed fetch un-marks so a later edit can retry.
+      acquiredSpecifiers.delete(specifier);
+    }
+  }
+};
 
 // Turn OFF the JSON service's built-in validation. The editor content is a
 // template that renders to JSON, so we validate the template-substituted form
@@ -242,20 +272,31 @@ const TEMPLATE_VALIDATORS: Partial<
 // Variable-like tokens (`{{ template }}` expressions, shell `$env` refs) are
 // highlighted via inline decorations rather than per-language grammars: this
 // works for any language (yaml / xml / markdown have no template grammar; shell
-// doesn't color `$VAR` inside strings) and keeps the color consistent. #9cdcfe
-// is the vs-dark `variable` token color, matching json-template's grammar. The
-// CSS class is injected once.
+// doesn't color `$VAR` inside strings) and keeps the color consistent.
+// The style element is injected once and updated whenever the resolved theme
+// changes so the decoration tracks the editor theme.
 const VARIABLE_TOKEN_CLASS = "checkstack-editor-variable";
-let variableTokenStyleInjected = false;
-const ensureVariableTokenStyle = (): void => {
-  if (variableTokenStyleInjected) {
+const VARIABLE_TOKEN_STYLE_ID = "checkstack-editor-variable-style";
+
+const ensureVariableTokenStyle = ({
+  resolvedTheme,
+}: {
+  resolvedTheme: "light" | "dark";
+}): void => {
+  const color = VARIABLE_TOKEN_COLOR[resolvedTheme];
+  const existing = document.querySelector<HTMLStyleElement>(
+    `#${VARIABLE_TOKEN_STYLE_ID}`,
+  );
+  if (existing !== null) {
+    // Update in place so a theme toggle refreshes the color.
+    existing.textContent = `.${VARIABLE_TOKEN_CLASS}{color:${color} !important;}`;
     return;
   }
-  variableTokenStyleInjected = true;
   const style = document.createElement("style");
+  style.id = VARIABLE_TOKEN_STYLE_ID;
   // `!important` so the decoration color always wins over the underlying token
   // color (.mtkN), making `{{ }}` look identical inside and outside strings.
-  style.textContent = `.${VARIABLE_TOKEN_CLASS}{color:#9cdcfe !important;}`;
+  style.textContent = `.${VARIABLE_TOKEN_CLASS}{color:${color} !important;}`;
   document.head.append(style);
 };
 
@@ -271,7 +312,6 @@ const installRegexDecorations = ({
   pattern: RegExp;
   className: string;
 }): monaco.IDisposable => {
-  ensureVariableTokenStyle();
   const compute = (): monaco.editor.IModelDeltaDecoration[] => {
     const text = model.getValue();
     const decorations: monaco.editor.IModelDeltaDecoration[] = [];
@@ -281,7 +321,7 @@ const installRegexDecorations = ({
       const start = model.getPositionAt(match.index);
       const end = model.getPositionAt(match.index + match[0].length);
       decorations.push({
-        range: new monaco.Range(
+        range: new monacoRuntime.Range(
           start.lineNumber,
           start.column,
           end.lineNumber,
@@ -312,7 +352,7 @@ const installRegexDecorations = ({
 const findModelById = (
   modelId: string,
 ): monaco.editor.ITextModel | undefined =>
-  monaco.editor
+  monacoRuntime.editor
     .getModels()
     .find((candidate) => candidate.uri.toString().includes(modelId));
 
@@ -327,6 +367,13 @@ export type TypefoxEditorProps = {
   language?: CodeEditorLanguage;
   /** Minimum editor height in pixels. Defaults to 240. */
   minHeight?: number;
+  /**
+   * When true, the editor container fills its flex parent (`height: 100%`)
+   * instead of using a fixed `minHeight` px height, so it grows to fit a tall
+   * flex column (e.g. the popout dialog body). `minHeight` is still applied as
+   * a floor. Defaults to false, preserving the inline fixed-height behaviour.
+   */
+  fillHeight?: boolean;
   /**
    * Generated ambient type definitions (the `context.d.ts`) injected as a TS
    * extra-lib so `context.*` resolves with real fields. Wired up once per
@@ -356,11 +403,56 @@ export type TypefoxEditorProps = {
   readOnly?: boolean;
   /** Accessible label / hint for the editor (surfaced via aria-label). */
   placeholder?: string;
+  /**
+   * Lazy Automatic Type Acquisition resolver. When provided (TS/JS editors),
+   * bare `import`/`require` specifiers in the buffer are parsed (debounced)
+   * and each NEW package's `.d.ts` closure is fetched + registered so e.g.
+   * `import { debounce } from "lodash"` autocompletes. Injected by the
+   * consumer so this component stays plugin-agnostic.
+   */
+  acquireTypes?: AcquireTypes;
+  /**
+   * Install identity (lockfile hash). When it changes, the shared acquired-set
+   * resets so types refresh against the new install.
+   */
+  acquireResetKey?: string;
+  /**
+   * The running release's `@checkstack/sdk` editor bundle, as virtual `.d.ts`
+   * files to mount (TS/JS editors). Makes `import { defineHealthCheck } from
+   * "@checkstack/sdk/healthcheck"` resolve with real, version-matched types.
+   * Each file mounts at `file:///<path>` via `addExtraLib`. Fetched live by the
+   * consumer (so this component stays network-agnostic + DOM-test-free).
+   */
+  sdkTypes?: ReadonlyArray<{ path: string; content: string }>;
+  /**
+   * Release-version reset key for `sdkTypes`. When it changes, the previously
+   * mounted SDK libs are reset so the editor never serves stale SDK types after
+   * a deployment upgrade.
+   */
+  sdkTypesResetKey?: string;
+  /**
+   * Importable installed package NAMES (TS/JS editors). When provided, the
+   * editor suggests these as completions while the cursor is inside an import
+   * specifier string (`import {} from "lod"` -> `lodash`) - solving the
+   * lazy-ATA catch-22 where no module is registered yet. Must already exclude
+   * `@types/*` companions (you import `lodash`, never `@types/lodash`).
+   * Injected by the consumer so this component stays plugin-agnostic.
+   */
+  importablePackages?: string[];
+  /**
+   * When `true`, this editor never CLAIMS the one-time global cold init - it
+   * always waits for another (visible) editor to bring the monaco-vscode
+   * services up, then mounts. Set this for OFFSCREEN/hidden editors (the
+   * automation `ScriptServicesBooter`): a hidden editor's init may never
+   * complete, so it must not be the sole initializer. Defaults to `false`.
+   */
+  deferInit?: boolean;
 };
 
 /**
  * Isolated editor used to validate the Typefox/monaco-vscode stack in the
- * browser. Dark theme, no minimap, automatic layout, word-based suggestions
+ * browser. Theme follows `useTheme().resolvedTheme` (`vs` in light mode,
+ * `vs-dark` in dark mode), no minimap, automatic layout, word-based suggestions
  * disabled. For `typescript`/`javascript` it injects the `context` types +
  * bracket completions; for markup/text languages it offers `{{ }}` template
  * completions.
@@ -382,19 +474,81 @@ const languageStatusServiceOverride: monaco.editor.IEditorOverrideServices =
       : {};
   })();
 
+// The monaco-vscode global API config. Hoisted to module scope (it has no
+// per-editor state) so it can drive a single, app-lifetime global init below.
+const vscodeApiConfig: MonacoVscodeApiConfig = {
+  // 'classic' is the standalone axis (no extension host); 'extended' is the
+  // extension-host axis we deliberately avoid in this migration.
+  $type: "classic",
+  // Register the missing ILanguageStatusService (see the override above) so
+  // focusing a JSON editor doesn't throw "addStatus is not supported".
+  serviceOverrides: { ...languageStatusServiceOverride },
+  // Plain editor, no workbench views.
+  viewsConfig: { $type: "EditorService" },
+  monacoWorkerFactory: ensureStandaloneWorkerFactory,
+};
+
+// ─── How the global monaco-vscode init is serialized ────────────────────────
+//
+// `@codingame/monaco-vscode-api`'s global `initialize()` is ONE-SHOT and can
+// never be torn down or re-run. `@typefox/monaco-editor-react` performs that
+// init itself when a `MonacoEditorReactComp` is given a `vscodeApiConfig`, and
+// that is StrictMode-safe FOR A SINGLE EDITOR (upstream tests cover exactly
+// that). The breakage is two editors on one page (e.g. an open script-action
+// editor PLUS the hidden `ScriptServicesBooter`): both wrappers race the init
+// guard (only set inside an async `start()`), both call `initialize()`, the
+// second throws "Services are already initialized", and the global state is
+// corrupted so NO editor starts. StrictMode (dev only) makes the race
+// deterministic via mount -> unmount -> remount; production works because
+// StrictMode is a no-op there.
+//
+// Fix (per the maintainers' single-editor-init guidance): exactly ONE editor
+// claims the cold init and mounts WITH `vscodeApiConfig` (the proven path);
+// every other editor waits for `areVscodeServicesReady()` and only then mounts
+// (it still passes `vscodeApiConfig`, but @typefox no-ops since the services
+// are already initialized). The hidden booter sets `deferInit` so it never
+// claims - the claimer must be a real, visible editor whose init can complete.
+
+// Always-available runtime built-in import specifiers (Node + Bun), derived at
+// build time from the bundled stdlib types. These are importable in the script
+// sandbox regardless of the installed-package allowlist (the sandbox is a Bun
+// subprocess; Bun provides Node's builtins + its own `bun:` modules), and their
+// types are already loaded ambiently via the stdlib bundle - so completing one
+// needs no lazy acquisition. The JSON is a plain `string[]`.
+const BUILTIN_MODULE_SPECIFIERS: readonly string[] = builtinModulesJson;
+
+// Passed as the wrapper's `onError` so a wrapper failure is surfaced here
+// instead of becoming an uncaught promise rejection (and so @typefox doesn't
+// reset its internal run-queue lock + re-throw).
+const handleEditorError = (error: Error): void => {
+  console.error("[CodeEditor] monaco editor error:", error);
+};
+
 export const TypefoxEditor = ({
   id,
   value,
   onChange,
   language = "typescript",
   minHeight = 240,
+  fillHeight = false,
   typeDefinitions,
   templateProperties,
   shellEnvVars,
   markers,
   readOnly = false,
   placeholder,
+  acquireTypes,
+  acquireResetKey,
+  sdkTypes,
+  sdkTypesResetKey,
+  importablePackages,
+  deferInit = false,
 }: TypefoxEditorProps) => {
+  // Follow the app's resolved theme so the editor uses `vs` (light) or
+  // `vs-dark` (dark) and updates live when the user toggles the theme.
+  const { resolvedTheme } = useTheme();
+  const monacoTheme = MONACO_THEME_MAP[resolvedTheme];
+
   // `MonacoEditorReactComp` captures `onTextChanged` once at editor-start, so
   // the handler it calls would otherwise close over a stale `onChange` (bound
   // to the value/sibling-config at mount time). Routing through a ref that we
@@ -419,8 +573,62 @@ export const TypefoxEditor = ({
   // completion providers below register against a ready languages registry.
   const [apiReady, setApiReady] = useState(false);
 
+  // Cold-init serialization (see the block comment above). Tracks whether the
+  // global services are up yet, and whether THIS editor is the designated
+  // initializer (the one that mounts first, with `vscodeApiConfig`).
+  const [servicesReady, setServicesReady] = useState(() =>
+    areVscodeServicesReady(),
+  );
+  const [isInitializer, setIsInitializer] = useState(false);
   useEffect(() => {
-    if (!isTsLike || typeDefinitions === undefined) {
+    if (servicesReady) return;
+    return onVscodeServicesReady(() => setServicesReady(true));
+  }, [servicesReady]);
+  // Decide the initializer role in a layout effect (NOT during render) so it is
+  // StrictMode-safe: StrictMode runs setup -> cleanup -> setup, and the cleanup
+  // releases the claim, so exactly one editor ends up the stable holder. A
+  // `deferInit` editor (the hidden booter) never claims - the initializer must
+  // be a real, visible editor whose @typefox init can actually complete.
+  useLayoutEffect(() => {
+    if (areVscodeServicesReady() || deferInit) return;
+    const claimed = claimColdInit();
+    setIsInitializer(claimed);
+    return () => {
+      if (claimed) releaseColdInit();
+    };
+  }, [deferInit]);
+
+  // Mount the wrapper when the services are ready (we attach to them) OR when we
+  // are the initializer (we bring them up, passing `vscodeApiConfig`). Until
+  // then, a sized, non-animated placeholder so the layout doesn't jump.
+  const canMountWrapper = servicesReady || isInitializer;
+
+  // Keep the Monaco global theme and the variable-token decoration color in
+  // sync whenever the resolved app theme changes. Monaco's theme is a global
+  // imperative setting (not per-editor), so re-deriving `editorAppConfig`
+  // alone is not enough after the editor has started - this effect is what
+  // makes live toggling work.
+  //
+  // GATED on `apiReady`: `monaco.editor.setTheme()` resolves a service via
+  // `StandaloneServices.get()`, which AUTO-INITIALIZES the monaco-vscode
+  // services if they aren't up yet (CodinGame standaloneServices.js:963). If
+  // this ran before the wrapper's own init (e.g. on the deferred booter, which
+  // mounts but never gets `apiReady`), it would trip CodinGame's
+  // `servicesInitialized` flag and make the wrapper's later `initialize()` throw
+  // "Services are already initialized". The initial theme is already applied via
+  // `editorAppConfig.editorOptions.theme`; this effect only handles live
+  // toggling, which is always after the editor (and thus the API) has started.
+  useEffect(() => {
+    if (!apiReady) return;
+    monacoRuntime.editor.setTheme(monacoTheme);
+    ensureVariableTokenStyle({ resolvedTheme });
+  }, [apiReady, resolvedTheme, monacoTheme]);
+
+  useEffect(() => {
+    // GATED on `apiReady` for the same reason as the theme effect above:
+    // touching `typescriptDefaults` before the wrapper init can auto-initialize
+    // the services and collide with the wrapper's `initialize()`.
+    if (!apiReady || !isTsLike || typeDefinitions === undefined) {
       return;
     }
     // Inject this editor's ambient `context` types. addExtraLib keys by path
@@ -436,7 +644,150 @@ export const TypefoxEditor = ({
     return () => {
       lib.dispose();
     };
-  }, [isTsLike, typeDefinitions, modelId]);
+  }, [apiReady, isTsLike, typeDefinitions, modelId]);
+
+  // Mount the @checkstack/sdk editor bundle (script helpers + typed client) so
+  // `import ... from "@checkstack/sdk/healthcheck"` resolves with real types.
+  // Shared/module-scoped + reset-on-version (mountSdkTypes); the fetch lives in
+  // the consumer so this component is network-agnostic + DOM-test-free.
+  useEffect(() => {
+    if (!apiReady || !isTsLike || sdkTypes === undefined) {
+      return;
+    }
+    mountSdkTypes({ files: sdkTypes, resetKey: sdkTypesResetKey });
+  }, [apiReady, isTsLike, sdkTypes, sdkTypesResetKey]);
+
+  // Lazy Automatic Type Acquisition (ATA). For TS/JS editors with an injected
+  // `acquireTypes` resolver, parse the buffer's bare import/require specifiers
+  // (debounced) and fetch + register each NEW package's `.d.ts` closure, so
+  // `import { x } from "pkg"` autocompletes. The acquired-set is module-scoped
+  // and shared across editors (the declarations are install-global); the pure
+  // parse/plan steps are unit-tested in importSpecifiers.test.ts. Re-running
+  // on a new `acquireTypes`/`acquireResetKey` identity is cheap and safe — the
+  // module-scoped acquired-set dedupes, so it never double-fetches.
+  useEffect(() => {
+    if (!apiReady || !isTsLike || acquireTypes === undefined) {
+      return;
+    }
+    const model = findModelById(modelId);
+    if (!model) {
+      return;
+    }
+
+    const acquire = (source: string): void => {
+      void runTypeAcquisition({
+        source,
+        acquireTypes,
+        resetKey: acquireResetKey,
+      });
+    };
+
+    // Run once for the initial content so existing imports resolve on open.
+    acquire(model.getValue());
+
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    const subscription = model.onDidChangeContent(() => {
+      if (timer !== undefined) clearTimeout(timer);
+      timer = setTimeout(() => {
+        acquire(model.getValue());
+      }, 400);
+    });
+    return () => {
+      if (timer !== undefined) clearTimeout(timer);
+      subscription.dispose();
+    };
+  }, [apiReady, isTsLike, acquireTypes, acquireResetKey, modelId]);
+
+  // Controlled-value sync. `value` is only seeded into the model at mount
+  // (codeResources), so the editor is otherwise uncontrolled. Apply external
+  // `value` changes — a sibling editor's edits (the inline ↔ popout pair share
+  // one controlled `value`), a YAML→Visual reset, a loaded definition — to this
+  // model. Guarded by an equality check: the user's own edit round-trips
+  // `value === model.getValue()`, so the actively-edited editor is a no-op and
+  // there is no feedback loop; only a background editor whose `value` prop
+  // diverged gets updated.
+  useEffect(() => {
+    if (!apiReady) return;
+    const model = findModelById(modelId);
+    if (!model || model.getValue() === value) return;
+    model.setValue(value);
+  }, [apiReady, modelId, value]);
+
+  // Import-specifier name completions. Lazy ATA only registers a package's
+  // types AFTER its name is in the buffer, so while the user is still TYPING
+  // the specifier (`import {} from "lod"`) no module exists yet and the TS
+  // worker offers nothing. This provider fills that gap: when the cursor is
+  // inside an import/require string (detected by the unit-tested
+  // `importSpecifierCompletionContext`), it suggests:
+  //   - the always-available runtime built-ins (`node:fs`, `bun`, ...), so
+  //     they appear even with an empty allowlist; AND
+  //   - the injected installed-package names (already `@types/*`-free).
+  // Selecting a built-in inserts an already-typed module; selecting an
+  // installed package triggers the ATA loop to load its closure. The list is
+  // merged + deduped + sorted by `mergeImportCompletionEntries` (a unit-tested
+  // pure helper). Built-ins read as "Node.js" / "Bun built-in" via `detail`.
+  // Scoped to THIS model; only the import-string position triggers it, so it
+  // never pollutes normal completions. Always registered (built-ins are
+  // always available), independent of the allowlist.
+  useEffect(() => {
+    if (!apiReady || !isTsLike) {
+      return;
+    }
+    const entries = mergeImportCompletionEntries({
+      builtins: BUILTIN_MODULE_SPECIFIERS,
+      installedPackages: importablePackages ?? [],
+    });
+
+    const provideCompletionItems = (
+      model: monaco.editor.ITextModel,
+      position: monaco.Position,
+    ): monaco.languages.CompletionList => {
+      if (!model.uri.toString().includes(modelId)) {
+        return { suggestions: [] };
+      }
+      const lineUpToCursor = model
+        .getLineContent(position.lineNumber)
+        .slice(0, position.column - 1);
+      const ctx = importSpecifierCompletionContext(lineUpToCursor);
+      if (!ctx) {
+        return { suggestions: [] };
+      }
+      // Replace the whole partial specifier (between the quotes) without
+      // touching the quotes themselves.
+      const range = {
+        startLineNumber: position.lineNumber,
+        startColumn: ctx.replaceFromColumn,
+        endLineNumber: position.lineNumber,
+        endColumn: position.column,
+      };
+      return {
+        suggestions: entries.map((entry) => ({
+          label: entry.name,
+          kind: monacoRuntime.languages.CompletionItemKind.Module,
+          detail: entry.detail,
+          insertText: entry.name,
+          filterText: entry.name,
+          range,
+        })),
+        // The list is the full known set; let monaco filter by `partial`.
+        incomplete: false,
+      };
+    };
+
+    const disposables = (["typescript", "javascript"] as const).map((lang) =>
+      monacoRuntime.languages.registerCompletionItemProvider(lang, {
+        // Opening quotes start a specifier; `:` advances into a `node:`/`bun:`
+        // builtin; `/` advances into a scoped name or subpath.
+        triggerCharacters: ['"', "'", "/", ":"],
+        provideCompletionItems,
+      }),
+    );
+    return () => {
+      for (const disposable of disposables) {
+        disposable.dispose();
+      }
+    };
+  }, [apiReady, isTsLike, importablePackages, modelId]);
 
   // Type-driven bracket-notation completions. The standalone TS worker omits
   // object members whose keys aren't valid identifiers (artifact ids like
@@ -485,7 +836,7 @@ export const TypefoxEditor = ({
         return {
           suggestions: keys.map((key) => ({
             label: `["${key}"]`,
-            kind: monaco.languages.CompletionItemKind.Property,
+            kind: monacoRuntime.languages.CompletionItemKind.Property,
             detail: objectExpression,
             insertText: `["${key}"]`,
             filterText: key,
@@ -514,7 +865,7 @@ export const TypefoxEditor = ({
     };
 
     const disposables = (["typescript", "javascript"] as const).map((lang) =>
-      monaco.languages.registerCompletionItemProvider(lang, {
+      monacoRuntime.languages.registerCompletionItemProvider(lang, {
         triggerCharacters: ["."],
         provideCompletionItems,
       }),
@@ -565,7 +916,7 @@ export const TypefoxEditor = ({
         )
         .map((prop, index) => ({
           label: `{{${prop.path}}}`,
-          kind: monaco.languages.CompletionItemKind.Variable,
+          kind: monacoRuntime.languages.CompletionItemKind.Variable,
           detail: prop.type,
           documentation: prop.description,
           insertText: `{{${prop.path}}}`,
@@ -584,7 +935,7 @@ export const TypefoxEditor = ({
       return { suggestions, incomplete: false };
     };
 
-    const provider = monaco.languages.registerCompletionItemProvider(
+    const provider = monacoRuntime.languages.registerCompletionItemProvider(
       languageId,
       { triggerCharacters: ["{"], provideCompletionItems },
     );
@@ -686,7 +1037,7 @@ export const TypefoxEditor = ({
         )
         .map((v, index) => ({
           label: `$${v.name}`,
-          kind: monaco.languages.CompletionItemKind.Variable,
+          kind: monacoRuntime.languages.CompletionItemKind.Variable,
           detail: v.example ? `e.g. ${v.example}` : "shell env var",
           // Full name in the (wrapping) docs panel so long CHECKSTACK_* names
           // stay legible even when the suggest-list label truncates.
@@ -707,7 +1058,7 @@ export const TypefoxEditor = ({
       return { suggestions, incomplete: false };
     };
 
-    const provider = monaco.languages.registerCompletionItemProvider("shell", {
+    const provider = monacoRuntime.languages.registerCompletionItemProvider("shell", {
       triggerCharacters: ["$", "{"],
       provideCompletionItems,
     });
@@ -723,7 +1074,7 @@ export const TypefoxEditor = ({
     if (!apiReady) {
       return;
     }
-    const model = monaco.editor
+    const model = monacoRuntime.editor
       .getModels()
       .find((candidate) => candidate.uri.toString().includes(modelId));
     if (!model) {
@@ -733,14 +1084,14 @@ export const TypefoxEditor = ({
       severity: EditorMarker["severity"],
     ): monaco.MarkerSeverity => {
       if (severity === "warning") {
-        return monaco.MarkerSeverity.Warning;
+        return monacoRuntime.MarkerSeverity.Warning;
       }
       if (severity === "info") {
-        return monaco.MarkerSeverity.Info;
+        return monacoRuntime.MarkerSeverity.Info;
       }
-      return monaco.MarkerSeverity.Error;
+      return monacoRuntime.MarkerSeverity.Error;
     };
-    monaco.editor.setModelMarkers(
+    monacoRuntime.editor.setModelMarkers(
       model,
       "external-validation",
       (markers ?? []).map((marker) => ({
@@ -753,7 +1104,7 @@ export const TypefoxEditor = ({
       })),
     );
     return () => {
-      monaco.editor.setModelMarkers(model, "external-validation", []);
+      monacoRuntime.editor.setModelMarkers(model, "external-validation", []);
     };
   }, [apiReady, markers, modelId]);
 
@@ -775,7 +1126,7 @@ export const TypefoxEditor = ({
     const owner = "template-validation";
     const runValidation = (): void => {
       const diagnostics = validate(model.getValue());
-      monaco.editor.setModelMarkers(
+      monacoRuntime.editor.setModelMarkers(
         model,
         owner,
         diagnostics.map((diagnostic) => {
@@ -789,7 +1140,7 @@ export const TypefoxEditor = ({
             endLineNumber: end.lineNumber,
             endColumn: end.column,
             message: diagnostic.message,
-            severity: monaco.MarkerSeverity.Error,
+            severity: monacoRuntime.MarkerSeverity.Error,
           };
         }),
       );
@@ -800,25 +1151,10 @@ export const TypefoxEditor = ({
     });
     return () => {
       subscription.dispose();
-      monaco.editor.setModelMarkers(model, owner, []);
+      monacoRuntime.editor.setModelMarkers(model, owner, []);
     };
   }, [apiReady, language, modelId]);
 
-  const vscodeApiConfig: MonacoVscodeApiConfig = {
-    // 'classic' is the standalone axis (no extension host); 'extended' is the
-    // extension-host axis we deliberately avoid in this migration.
-    $type: "classic",
-    // Register the missing ILanguageStatusService (see the override comment
-    // above) so focusing a JSON editor doesn't throw "addStatus is not
-    // supported".
-    serviceOverrides: { ...languageStatusServiceOverride },
-    viewsConfig: {
-      // Plain editor, no workbench views.
-      $type: "EditorService",
-    },
-    monacoWorkerFactory: configureStandaloneWorkerFactory,
-  };
-
   const editorAppConfig: EditorAppConfig = {
     // Unique per instance (modelId includes a useId suffix) so multiple editors
     // sharing the same `id` prop don't collide in the wrapper's app registry.
@@ -831,10 +1167,12 @@ export const TypefoxEditor = ({
       },
     },
     editorOptions: {
-      // 'vs-dark' is the builtin classic dark theme. (The VS Code
-      // 'Default Dark Modern' theme would require the extension-host
-      // theme-defaults extension, which the standalone setup omits.)
-      theme: "vs-dark",
+      // Derived from useTheme().resolvedTheme: "vs" for light, "vs-dark" for
+      // dark. These are the two built-in classic themes available in the
+      // standalone setup (the VS Code 'Default Dark Modern' theme requires the
+      // extension-host theme-defaults extension, which the standalone setup
+      // omits).
+      theme: monacoTheme,
       minimap: { enabled: false },
       automaticLayout: true,
       // Force completions to come from the TS language service rather than
@@ -850,18 +1188,49 @@ export const TypefoxEditor = ({
     onChangeRef.current?.(textChanges.modified ?? "");
   };
 
+  // In `fillHeight` mode the container takes its parent's height so Monaco's
+  // `automaticLayout` resizes to fill a tall flex column (the popout body);
+  // `minHeight` stays as a floor. Otherwise the inline fixed-px behaviour is
+  // preserved exactly.
+  const containerStyle: CSSProperties = fillHeight
+    ? { minHeight: `${minHeight}px`, height: "100%" }
+    : { minHeight: `${minHeight}px`, height: `${minHeight}px` };
+
+  // Non-initializer editors wait for the services to be up before mounting (a
+  // sized, non-animated placeholder until then, so the layout doesn't jump).
+  // The initializer mounts immediately and brings the services up.
+  if (!canMountWrapper) {
+    return (
+      <div
+        style={containerStyle}
+        className="w-full rounded-md bg-muted"
+        aria-busy="true"
+        aria-label={placeholder ?? "Loading editor"}
+      />
+    );
+  }
+
   return (
     <MonacoEditorReactComp
-      style={{ minHeight: `${minHeight}px`, height: `${minHeight}px` }}
+      style={containerStyle}
       vscodeApiConfig={vscodeApiConfig}
       editorAppConfig={editorAppConfig}
       onTextChanged={handleTextChanged}
+      // Route wrapper errors to our handler rather than letting @typefox reset
+      // its run-queue lock and re-throw as an uncaught rejection (recommended by
+      // the monaco-languageclient maintainers).
+      onError={handleEditorError}
       onEditorStartDone={() => {
         // Per-editor ready signal for the completion providers. We use this
         // (not onVscodeApiInitDone) because the vscode API initialises globally
         // once, so a second editor never gets its own onVscodeApiInitDone - but
         // onEditorStartDone fires for each editor instance.
         setApiReady(true);
+        // The monaco-vscode services are now up. Let the headless script
+        // validator know it may safely use the worker (it must never init the
+        // services itself - that would collide with this wrapper's one-time
+        // init and throw "Services are already initialized").
+        markVscodeServicesReady();
       }}
     />
   );