@checkstack/ui 1.11.0 → 1.12.0

package/src/components/CodeEditor/monacoTsService.ts

@@ -0,0 +1,217 @@
+// Shared standalone TypeScript / JavaScript language-service setup.
+//
+// Extracted from `TypefoxEditor` so it can be imported by BOTH the editor and
+// the headless `validateScripts` validator. Both need the same singletons
+// configured (compiler options, ambient stdlib types, the TS worker), and the
+// validator must work even when NO editor is mounted (every script action card
+// collapsed) - so the setup cannot live inside the editor component module's
+// render path.
+//
+// The TS/JS language-service `defaults` are singletons, so the configuration
+// here runs ONCE at module load. The worker factory is registered lazily (and
+// idempotently) via `ensureStandaloneWorkerFactory()` because the editor also
+// registers it during its own init - the guard makes a double-call a no-op.
+
+// Side-effect import: registers the standalone language grammars. Imported here
+// too (not only in TypefoxEditor) so the validator gets a fully-registered TS
+// language environment regardless of import order.
+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).
+import {
+  typescriptDefaults,
+  javascriptDefaults,
+  ScriptTarget,
+  ModuleKind,
+  ModuleResolutionKind,
+} from "@codingame/monaco-vscode-standalone-typescript-language-features";
+// Worker entry URLs, bundled and resolved by Vite via the `?worker&url` suffix.
+// Imported as URL STRINGS (not Worker constructors) because
+// monaco-languageclient's worker factory consumes `loader().url.toString()`.
+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 {
+  // `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";
+
+// Re-exported so consumers keep a single import surface for the TS services.
+export {
+  typescriptDefaults,
+  javascriptDefaults,
+  ScriptTarget,
+  ModuleKind,
+  ModuleResolutionKind,
+} from "@codingame/monaco-vscode-standalone-typescript-language-features";
+
+// 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" });
+
+// The monaco-vscode API initializes globally exactly ONCE, and that init is
+// owned by the editor wrapper (`MonacoEditorReactComp`) - it throws "Services
+// are already initialized" if anything else inits first. So the headless
+// validator must NOT touch the worker / models until an editor has brought the
+// services up. The editor flips this flag from its `onEditorStartDone`; the
+// validator checks it and otherwise no-ops. Net effect: scripts validate once
+// any script editor has been opened this session (covering collapsed cards
+// from then on); a never-opened, all-collapsed automation is left to the
+// deferred backend typecheck.
+let vscodeServicesReady = false;
+const servicesReadyListeners = new Set<() => void>();
+
+/** Called by the editor once the monaco-vscode services have initialized. */
+export const markVscodeServicesReady = (): void => {
+  if (vscodeServicesReady) return;
+  vscodeServicesReady = true;
+  for (const listener of servicesReadyListeners) listener();
+  servicesReadyListeners.clear();
+};
+
+/** True once an editor has initialized the monaco-vscode services. */
+export const areVscodeServicesReady = (): boolean => vscodeServicesReady;
+
+/**
+ * Subscribe to the one-time "services ready" transition. Fires immediately if
+ * already ready. Returns an unsubscribe. Lets the headless validator re-run the
+ * moment the first editor brings the services up (otherwise a never-edited
+ * definition would not re-validate just because a card was opened).
+ */
+export const onVscodeServicesReady = (listener: () => void): (() => void) => {
+  if (vscodeServicesReady) {
+    listener();
+    return () => {};
+  }
+  servicesReadyListeners.add(listener);
+  return () => servicesReadyListeners.delete(listener);
+};
+
+let workerFactoryRegistered = false;
+
+/**
+ * Register the worker loaders for the standalone (classic) Monaco setup. We
+ * only need the generic editor worker plus the TypeScript worker (which also
+ * serves JavaScript) and the JSON worker. Mirrors the upstream
+ * `defineClassicWorkers` helper.
+ *
+ * Idempotent: the first caller registers, subsequent calls no-op. Both the
+ * editor (via its `monacoWorkerFactory` app-config hook) AND the headless
+ * validator call this, so the guard prevents a double registration. The
+ * editor's call may pass a `logger`; the first registration wins, so when the
+ * validator registers first the editor simply reuses it (logging is optional).
+ */
+export const ensureStandaloneWorkerFactory = (
+  logger?: WorkerFactoryLogger,
+): void => {
+  if (workerFactoryRegistered) {
+    return;
+  }
+  workerFactoryRegistered = true;
+  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.
+//
+// `baseUrl: "file:///"` anchors NodeJs bare-import resolution at the virtual
+// root so an `import "lodash"` walks `file:///node_modules/...` - the same
+// virtual layout the stdlib bundle AND the lazy-ATA extra-libs are registered
+// under. `typeRoots` lists BOTH the `@types` root (so a package with no own
+// types, e.g. lodash, falls back to `@types/lodash`) and the bare
+// `node_modules` root (so the bundled `bun-types`, which is NOT under
+// `@types`, still resolves as an ambient `types` entry).
+export const BASE_COMPILER_OPTIONS = {
+  target: ScriptTarget.ESNext,
+  module: ModuleKind.ESNext,
+  moduleResolution: ModuleResolutionKind.NodeJs,
+  lib: ["esnext"],
+  allowNonTsExtensions: false,
+  noEmit: true,
+  strict: true,
+  esModuleInterop: true,
+  baseUrl: "file:///",
+  typeRoots: ["file:///node_modules/@types", "file:///node_modules"],
+};
+
+/**
+ * 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.
+ */
+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);
+  }
+};
+
+configureTypeScriptDefaults();
+
+/**
+ * Lazy-load the bundled `@types/node` + `bun-types` declarations into the
+ * standalone TS service so script editors have `console`, `fetch`, `process`,
+ * `Bun`, etc. typed. The ~3 MB bundle is code-split into its own chunk and
+ * fetched once. Runs at module load; this file is browser-only so the dynamic
+ * import is safe here. Returns the in-flight promise so callers (the headless
+ * validator) can await stdlib readiness before requesting diagnostics.
+ */
+let stdlibLoad: Promise<void> | undefined;
+export const ensureStandaloneStdlib = (): Promise<void> => {
+  if (stdlibLoad) {
+    return stdlibLoad;
+  }
+  stdlibLoad = (async () => {
+    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}`);
+      }
+      // 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"],
+      });
+    }
+  })();
+  return stdlibLoad;
+};
+
+void ensureStandaloneStdlib();

package/src/components/CodeEditor/popoutTitle.test.ts

@@ -0,0 +1,37 @@
+import { describe, expect, it } from "bun:test";
+import { popoutTitle } from "./popoutTitle";
+import type { CodeEditorLanguage } from "./types";
+
+describe("popoutTitle", () => {
+  it("derives a script title for TypeScript", () => {
+    expect(popoutTitle({ language: "typescript" })).toBe(
+      "Edit script - TypeScript",
+    );
+  });
+
+  it("derives a script title for JavaScript", () => {
+    expect(popoutTitle({ language: "javascript" })).toBe(
+      "Edit script - JavaScript",
+    );
+  });
+
+  it("derives a script title for Shell", () => {
+    expect(popoutTitle({ language: "shell" })).toBe("Edit script - Shell");
+  });
+
+  it("falls back to a generic title for markup/text languages", () => {
+    const markupLanguages: CodeEditorLanguage[] = [
+      "json",
+      "yaml",
+      "xml",
+      "markdown",
+    ];
+    for (const language of markupLanguages) {
+      expect(popoutTitle({ language })).toBe("Edit");
+    }
+  });
+
+  it("uses a normal hyphen, never an em-dash", () => {
+    expect(popoutTitle({ language: "typescript" })).not.toContain("—");
+  });
+});

package/src/components/CodeEditor/popoutTitle.ts

@@ -0,0 +1,31 @@
+// Pure helper deriving the popout-dialog title from the editor language.
+// Kept separate (and unit-tested) so the title logic isn't buried in UI glue.
+import type { CodeEditorLanguage } from "./types";
+
+// Human-readable display name for the languages that get a script-flavoured
+// title. Markup/text languages fall through to the generic "Edit" title since
+// "script" wouldn't read correctly for them.
+const SCRIPT_LANGUAGE_LABELS: Partial<Record<CodeEditorLanguage, string>> = {
+  typescript: "TypeScript",
+  javascript: "JavaScript",
+  shell: "Shell",
+};
+
+/**
+ * Derive the overlay dialog title from the editor language.
+ *
+ * - Script languages (`typescript` / `javascript` / `shell`) read as
+ *   `Edit script - <Language>`.
+ * - Everything else (markup/text: json / yaml / xml / markdown) falls back to
+ *   the generic `Edit`.
+ *
+ * Uses a normal hyphen (not an em-dash) per the project content style.
+ */
+export const popoutTitle = ({
+  language,
+}: {
+  language: CodeEditorLanguage;
+}): string => {
+  const scriptLabel = SCRIPT_LANGUAGE_LABELS[language];
+  return scriptLabel ? `Edit script - ${scriptLabel}` : "Edit";
+};

package/src/components/CodeEditor/scriptDiagnostics.test.ts

@@ -0,0 +1,135 @@
+import { describe, expect, it } from "bun:test";
+import {
+  buildValidationSource,
+  flattenDiagnosticMessage,
+  mapWorkerDiagnostics,
+  offsetToPosition,
+  type RawTsDiagnostic,
+} from "./scriptDiagnostics";
+
+describe("offsetToPosition", () => {
+  it("returns 1-based line/column", () => {
+    const text = "ab\ncde\nf";
+    expect(offsetToPosition(text, 0)).toEqual({ line: 1, column: 1 });
+    expect(offsetToPosition(text, 1)).toEqual({ line: 1, column: 2 });
+    // offset 3 is the 'c' (first char after the first newline)
+    expect(offsetToPosition(text, 3)).toEqual({ line: 2, column: 1 });
+    expect(offsetToPosition(text, 7)).toEqual({ line: 3, column: 1 });
+  });
+
+  it("clamps an out-of-range offset to the text length", () => {
+    expect(offsetToPosition("ab", 999)).toEqual({ line: 1, column: 3 });
+  });
+});
+
+describe("flattenDiagnosticMessage", () => {
+  it("passes through a plain string", () => {
+    expect(flattenDiagnosticMessage("boom")).toBe("boom");
+  });
+
+  it("flattens a nested chain depth-first", () => {
+    expect(
+      flattenDiagnosticMessage({
+        messageText: "top",
+        next: [
+          { messageText: "child-a" },
+          { messageText: "child-b", next: [{ messageText: "grandchild" }] },
+        ],
+      }),
+    ).toBe("top child-a child-b grandchild");
+  });
+});
+
+describe("buildValidationSource", () => {
+  it("prepends the type defs and reports the prefix line count", () => {
+    const { text, prependedLineCount } = buildValidationSource({
+      typeDefinitions: "declare const context: { x: number };", // 1 line
+      source: "context.x;",
+    });
+    expect(prependedLineCount).toBe(1);
+    expect(text).toBe("declare const context: { x: number };\ncontext.x;");
+  });
+
+  it("counts multi-line type defs", () => {
+    const { prependedLineCount } = buildValidationSource({
+      typeDefinitions: "line1\nline2\nline3",
+      source: "x",
+    });
+    expect(prependedLineCount).toBe(3);
+  });
+});
+
+describe("mapWorkerDiagnostics", () => {
+  // 2 lines of type defs prepended; user source starts at combined line 3.
+  const { text, prependedLineCount } = buildValidationSource({
+    typeDefinitions: "declare const context: {\n  readonly a: number;\n};",
+    source: "const z = context.b;\n", // `b` doesn't exist -> error on user line 1
+  });
+
+  const errorOffset = text.indexOf("context.b") + "context.".length; // points at `b`
+
+  it("shifts a real type error back onto the user's source line", () => {
+    const diagnostics: RawTsDiagnostic[] = [
+      {
+        start: errorOffset,
+        length: 1,
+        category: 1, // Error
+        code: 2339,
+        messageText: "Property 'b' does not exist on type",
+      },
+    ];
+    const mapped = mapWorkerDiagnostics({
+      diagnostics,
+      validationText: text,
+      prependedLineCount,
+    });
+    expect(mapped).toHaveLength(1);
+    expect(mapped[0]).toMatchObject({
+      severity: "error",
+      line: 1,
+      message: "Property 'b' does not exist on type",
+    });
+  });
+
+  it("drops ignored codes (lazy-ATA module resolution, top-level return)", () => {
+    const diagnostics: RawTsDiagnostic[] = [
+      { start: errorOffset, category: 1, code: 2307, messageText: "Cannot find module 'lodash'" },
+      { start: errorOffset, category: 1, code: 1108, messageText: "A 'return' statement" },
+    ];
+    expect(
+      mapWorkerDiagnostics({ diagnostics, validationText: text, prependedLineCount }),
+    ).toEqual([]);
+  });
+
+  it("drops diagnostics that land inside the prepended type-def prefix", () => {
+    const diagnostics: RawTsDiagnostic[] = [
+      { start: 0, category: 1, code: 2300, messageText: "noise in generated types" },
+    ];
+    expect(
+      mapWorkerDiagnostics({ diagnostics, validationText: text, prependedLineCount }),
+    ).toEqual([]);
+  });
+
+  it("drops non-error/-warning categories and unpositioned diagnostics", () => {
+    const diagnostics: RawTsDiagnostic[] = [
+      { start: errorOffset, category: 2, code: 9999, messageText: "suggestion" },
+      { category: 1, code: 2339, messageText: "global, no position" },
+    ];
+    expect(
+      mapWorkerDiagnostics({ diagnostics, validationText: text, prependedLineCount }),
+    ).toEqual([]);
+  });
+
+  it("keeps warnings", () => {
+    const diagnostics: RawTsDiagnostic[] = [
+      { start: errorOffset, category: 0, code: 6133, messageText: "'z' is declared but never read" },
+    ];
+    const mapped = mapWorkerDiagnostics({
+      diagnostics,
+      validationText: text,
+      prependedLineCount,
+    });
+    expect(mapped).toHaveLength(1);
+    expect(mapped[0]?.severity).toBe("warning");
+  });
+});

package/src/components/CodeEditor/scriptDiagnostics.ts

@@ -0,0 +1,172 @@
+// Pure helpers for the headless script validator (`validateScripts.ts`).
+//
+// Kept free of any `monaco` / browser import so this logic is unit-testable
+// under bun. The browser-only worker glue lives in `validateScripts.ts` and
+// composes these helpers.
+//
+// Strategy: to type-check a user script against its generated `context.d.ts`
+// WITHOUT polluting the shared TS service's global scope (which would collide
+// with any mounted editor's own `declare const context`), we PREPEND the
+// generated type declarations onto the user's source and validate that single
+// combined file. Inside one module/script file the prepended `declare const
+// context` is in scope for the user's code below it, but it never leaks to
+// other files. Diagnostics that land in the prepended region are dropped, and
+// the rest are shifted back by the number of prepended lines so positions map
+// onto the user's original source.
+
+/** A type error/warning located in the user's original (un-prepended) source. */
+export interface ScriptDiagnostic {
+  severity: "error" | "warning";
+  /** Flattened, human-readable message. */
+  message: string;
+  /** 1-based line in the user's source. */
+  line: number;
+  /** 1-based column. */
+  column: number;
+}
+
+/**
+ * Diagnostic codes ignored during headless validation because they reflect the
+ * sandbox/loading model rather than a real mistake in the user's logic:
+ *
+ *  - 1108: a top-level `return` is legal (the runtime wraps scripts in an async
+ *    IIFE) - same suppression the editor applies.
+ *  - 2307 / 2792: "cannot find module 'x'". Type acquisition (ATA) is lazy and
+ *    only runs for the editor that is open, so a collapsed-card script's
+ *    imports have no fetched types yet. Flagging these would be a false
+ *    positive, so module-resolution failures are not surfaced here (the
+ *    backend typecheck - deferred - is the place to enforce imports).
+ *  - 7016: "could not find a declaration file for module 'x'" - same reason.
+ */
+export const IGNORED_DIAGNOSTIC_CODES: ReadonlySet<number> = new Set([
+  1108, 2307, 2792, 7016,
+]);
+
+// `ts.DiagnosticCategory`: Warning = 0, Error = 1, Suggestion = 2, Message = 3.
+const CATEGORY_ERROR = 1;
+const CATEGORY_WARNING = 0;
+
+/**
+ * Minimal shape of a TypeScript worker diagnostic (subset of monaco's
+ * `Diagnostic`). `messageText` is either a string or a nested chain.
+ */
+export interface RawTsDiagnostic {
+  start?: number;
+  length?: number;
+  messageText: string | DiagnosticMessageChain;
+  category: number;
+  code: number;
+}
+
+interface DiagnosticMessageChain {
+  messageText: string;
+  next?: DiagnosticMessageChain[];
+}
+
+/** Flatten a (possibly nested) diagnostic message chain to a single string. */
+export function flattenDiagnosticMessage(
+  messageText: string | DiagnosticMessageChain,
+): string {
+  if (typeof messageText === "string") {
+    return messageText;
+  }
+  const parts: string[] = [];
+  const walk = (chain: DiagnosticMessageChain): void => {
+    parts.push(chain.messageText);
+    for (const child of chain.next ?? []) {
+      walk(child);
+    }
+  };
+  walk(messageText);
+  return parts.join(" ");
+}
+
+/** Convert a 0-based character offset into a 1-based {line, column}. */
+export function offsetToPosition(
+  text: string,
+  offset: number,
+): { line: number; column: number } {
+  let line = 1;
+  let column = 1;
+  const end = Math.min(offset, text.length);
+  for (let i = 0; i < end; i++) {
+    if (text[i] === "\n") {
+      line += 1;
+      column = 1;
+    } else {
+      column += 1;
+    }
+  }
+  return { line, column };
+}
+
+/**
+ * Build the combined source to validate: the generated `typeDefinitions`
+ * (the `declare const context` + any ambient augmentations) prepended to the
+ * user's source. Returns the combined text plus the number of lines the prefix
+ * occupies, so diagnostics can be shifted back onto the user's source.
+ */
+export function buildValidationSource({
+  typeDefinitions,
+  source,
+}: {
+  typeDefinitions: string;
+  source: string;
+}): { text: string; prependedLineCount: number } {
+  // The prefix occupies one line per line of `typeDefinitions`; the trailing
+  // "\n" we add then places the user's source on the next line. So the user's
+  // line N maps to combined line N + prependedLineCount.
+  const prependedLineCount = typeDefinitions.split("\n").length;
+  return {
+    text: `${typeDefinitions}\n${source}`,
+    prependedLineCount,
+  };
+}
+
+/**
+ * Map raw worker diagnostics onto the user's source: drop ignored codes,
+ * non-error/-warning categories, unpositioned (global) diagnostics, and any
+ * that fall inside the prepended type-definition prefix; shift the rest back.
+ */
+export function mapWorkerDiagnostics({
+  diagnostics,
+  validationText,
+  prependedLineCount,
+}: {
+  diagnostics: RawTsDiagnostic[];
+  validationText: string;
+  prependedLineCount: number;
+}): ScriptDiagnostic[] {
+  const result: ScriptDiagnostic[] = [];
+  for (const diagnostic of diagnostics) {
+    if (IGNORED_DIAGNOSTIC_CODES.has(diagnostic.code)) {
+      continue;
+    }
+    const severity =
+      diagnostic.category === CATEGORY_ERROR
+        ? "error"
+        : diagnostic.category === CATEGORY_WARNING
+          ? "warning"
+          : undefined;
+    if (severity === undefined) {
+      continue;
+    }
+    if (diagnostic.start === undefined) {
+      // No position - a whole-file diagnostic. Not attributable to a user line,
+      // and the inline strategy shouldn't produce these; skip.
+      continue;
+    }
+    const position = offsetToPosition(validationText, diagnostic.start);
+    if (position.line <= prependedLineCount) {
+      // Lands in the generated prefix, not the user's code.
+      continue;
+    }
+    result.push({
+      severity,
+      message: flattenDiagnosticMessage(diagnostic.messageText),
+      line: position.line - prependedLineCount,
+      column: position.column,
+    });
+  }
+  return result;
+}

package/src/components/CodeEditor/types.ts

@@ -52,6 +52,30 @@ export interface ShellEnvVar {
   example?: string;
 }
 
+/** One declaration file returned by an `AcquireTypes` resolver. */
+export interface AcquiredTypeFile {
+  /**
+   * Real `node_modules/...`-relative path (e.g.
+   * `node_modules/@types/lodash/index.d.ts`). Registered at `file:///<path>`
+   * so TypeScript's NodeJs + `@types` resolution can find it.
+   */
+  path: string;
+  /** Verbatim declaration content (UNWRAPPED — no `declare module` envelope). */
+  content: string;
+}
+
+/**
+ * Resolver for lazy Automatic Type Acquisition (ATA). Given a bare package
+ * specifier (e.g. `lodash`), returns the declaration-file closure to register
+ * with the TypeScript service (own types and/or the `@types/*` companion).
+ * Returns an empty array when the package has no acquirable types. Plugin-
+ * agnostic: the concrete fetch (route URL + lockfile hash + auth) is injected
+ * by the consumer (see `@checkstack/script-packages-frontend`).
+ */
+export type AcquireTypes = (
+  specifier: string,
+) => Promise<AcquiredTypeFile[]>;
+
 /**
  * An externally-supplied diagnostic to render as an inline squiggle. Positions
  * are 1-based line/column (the editor's convention). Callers compute these from
@@ -106,4 +130,39 @@ export interface CodeEditorProps {
    * diagnostics).
    */
   markers?: EditorMarker[];
+  /**
+   * Lazy Automatic Type Acquisition resolver. When provided (TS/JS editors),
+   * the editor parses bare `import`/`require` specifiers from the buffer and
+   * calls this for each NEW package, registering the returned declaration
+   * files so `import { x } from "pkg"` autocompletes. Injected by the
+   * consumer so `@checkstack/ui` stays plugin-agnostic.
+   */
+  acquireTypes?: AcquireTypes;
+  /**
+   * Identity of the current package install (the lockfile hash). When it
+   * changes (a new install), the editor resets its acquired-set so types
+   * refresh against the new install.
+   */
+  acquireResetKey?: string;
+  /**
+   * Importable installed package NAMES (TS/JS editors). When provided, the
+   * editor suggests these while the cursor is inside an import specifier
+   * string (`import {} from "lod"` -> `lodash`), solving the lazy-ATA
+   * catch-22 where no module is registered until its name is typed. Must
+   * already exclude `@types/*` companions. Injected by the consumer.
+   */
+  importablePackages?: string[];
+  /**
+   * Whether to show the "expand editor" affordance that opens the editor in a
+   * large full-screen overlay for comfortably editing big scripts. Defaults to
+   * `true`. Set `false` to suppress it (e.g. for tiny single-line snippets).
+   */
+  allowPopout?: boolean;
+  /**
+   * Optional override for the overlay dialog title. When omitted, the title is
+   * derived from `language` (e.g. "Edit script - TypeScript"). Lets a consumer
+   * surface a field-specific label (e.g. a DynamicForm field name) while
+   * keeping `@checkstack/ui` plugin-agnostic.
+   */
+  title?: string;
 }