@checkstack/ui 1.9.0 → 1.11.0

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

@@ -0,0 +1,120 @@
+import { describe, it, expect } from "bun:test";
+import { extractBracketKeyGroups } from "./bracketKeyGroups";
+
+describe("extractBracketKeyGroups", () => {
+  it("returns [] when there is no `declare const context`", () => {
+    expect(
+      extractBracketKeyGroups({ typeDefinitions: "interface Foo { x: string }" }),
+    ).toEqual([]);
+  });
+
+  it("returns [] when no property keys are non-identifiers", () => {
+    const typeDefinitions = `declare const context: {
+      event: { payload: { repository: string; count: number } };
+    };`;
+    expect(extractBracketKeyGroups({ typeDefinitions })).toEqual([]);
+  });
+
+  it("extracts a non-identifier key and its dotted parent path", () => {
+    const typeDefinitions = `declare const context: {
+      artifacts: {
+        "integration-jira.issue": { key: string; summary: string };
+      };
+    };`;
+    expect(extractBracketKeyGroups({ typeDefinitions })).toEqual([
+      { objectExpression: "context.artifacts", keys: ["integration-jira.issue"] },
+    ]);
+  });
+
+  it("groups multiple non-identifier keys under the same parent", () => {
+    const typeDefinitions = `declare const context: {
+      artifacts: {
+        "integration-jira.issue": { key: string };
+        "integration-github.pr": { number: number };
+        valid: { ok: boolean };
+      };
+    };`;
+    expect(extractBracketKeyGroups({ typeDefinitions })).toEqual([
+      {
+        objectExpression: "context.artifacts",
+        keys: ["integration-jira.issue", "integration-github.pr"],
+      },
+    ]);
+  });
+
+  it("does NOT treat string-literal union *values* as keys", () => {
+    const typeDefinitions = `declare const context: {
+      artifacts: {
+        "a-b": { status: "open" | "closed"; url: "https://x" };
+      };
+    };`;
+    expect(extractBracketKeyGroups({ typeDefinitions })).toEqual([
+      { objectExpression: "context.artifacts", keys: ["a-b"] },
+    ]);
+  });
+
+  it("ignores JSDoc and line comments (including braces inside them)", () => {
+    const typeDefinitions = `declare const context: {
+      /** an object like { not: a real brace } */
+      artifacts: {
+        // "comment-key": should be ignored
+        "real-key": { x: string };
+      };
+    };`;
+    expect(extractBracketKeyGroups({ typeDefinitions })).toEqual([
+      { objectExpression: "context.artifacts", keys: ["real-key"] },
+    ]);
+  });
+
+  it("handles `readonly` and optional `?` modifiers and deeper paths", () => {
+    const typeDefinitions = `declare const context: {
+      readonly event: {
+        readonly meta?: {
+          "x-trace.id": { v: string };
+        };
+      };
+    };`;
+    expect(extractBracketKeyGroups({ typeDefinitions })).toEqual([
+      { objectExpression: "context.event.meta", keys: ["x-trace.id"] },
+    ]);
+  });
+
+  it("skips non-identifier keys nested under a non-identifier parent", () => {
+    // `context["a-b"]` is not a dotted objectExpression, so the inner key has
+    // no addressable parent and must be skipped.
+    const typeDefinitions = `declare const context: {
+      "a-b": {
+        "c-d": { x: string };
+      };
+    };`;
+    expect(extractBracketKeyGroups({ typeDefinitions })).toEqual([
+      { objectExpression: "context", keys: ["a-b"] },
+    ]);
+  });
+
+  it("extracts OPTIONAL quoted keys (`\"key\"?:`) - the real generated shape", () => {
+    // Mirrors generateAutomationContextTypes output for upstream artifacts:
+    // `readonly artifacts: { readonly "integration-jira.issue"?: {...}; }`.
+    const typeDefinitions = `declare const context: {
+      readonly artifacts: {
+        readonly "integration-jira.issue"?: { key: string; url?: string };
+        readonly "integration-github.pr"?: { number: number };
+      };
+    };`;
+    expect(extractBracketKeyGroups({ typeDefinitions })).toEqual([
+      {
+        objectExpression: "context.artifacts",
+        keys: ["integration-jira.issue", "integration-github.pr"],
+      },
+    ]);
+  });
+
+  it("respects a custom root name", () => {
+    const typeDefinitions = `declare const scope: {
+      vars: { "weird key": { x: string } };
+    };`;
+    expect(
+      extractBracketKeyGroups({ typeDefinitions, rootName: "scope" }),
+    ).toEqual([{ objectExpression: "scope.vars", keys: ["weird key"] }]);
+  });
+});

package/src/components/CodeEditor/bracketKeyGroups.ts

@@ -0,0 +1,205 @@
+// Stage 2b (monaco-editor -> @typefox/monaco-editor-react migration).
+//
+// The standalone TS worker calls `getCompletionsAtPosition` with no options
+// (tsWorker.js: `getCompletionsAtPosition(fileName, position, void 0)`), so it
+// never surfaces object members whose keys are not valid JS identifiers (e.g.
+// artifact ids like `integration-jira.issue`). The built-in SuggestAdapter also
+// hardcodes `insertText: entry.name` and can't be overridden, so a custom TS
+// worker is not viable. Instead we register our own completion provider that
+// offers those keys as `["key"]` bracket completions.
+//
+// To stay TYPE-DRIVEN (and avoid threading a separate `dottedKeyCompletions`
+// prop), this module derives the groups straight from the injected
+// `context.d.ts`: it finds object members whose property name is a quoted,
+// non-identifier string and reports the dotted access path to their parent
+// object plus the list of such keys.
+
+/** A parent object plus the non-identifier keys reachable under it. */
+export interface BracketKeyGroup {
+  /** Member-access expression preceding the dot, e.g. `context.artifacts`. */
+  objectExpression: string;
+  /** Keys to offer; each is inserted as `["<key>"]`. */
+  keys: string[];
+}
+
+const IDENTIFIER_RE = /^[A-Za-z_$][\w$]*$/;
+
+const isIdentifier = (name: string): boolean => IDENTIFIER_RE.test(name);
+
+const isWhitespace = (ch: string): boolean =>
+  ch === " " || ch === "\t" || ch === "\n" || ch === "\r";
+
+/**
+ * Extract bracket-notation completion groups from generated TS type
+ * definitions. Walks the `declare const <rootName>: { ... }` object literal,
+ * tracking the dotted path as it descends, and records every property whose
+ * name is a quoted non-identifier string.
+ *
+ * The walk is a small purpose-built scanner (not a full TS parser): it is only
+ * ever fed our own generated `context.d.ts`, whose shape is a plain nested
+ * object type. It correctly ignores string-literal type *values* (e.g.
+ * `status: "open" | "closed"`), JSDoc/line comments, and the `readonly` /
+ * optional (`?`) modifiers. Keys nested under a non-identifier parent are
+ * skipped because no dotted `objectExpression` can address them.
+ */
+export const extractBracketKeyGroups = ({
+  typeDefinitions,
+  rootName = "context",
+}: {
+  typeDefinitions: string;
+  rootName?: string;
+}): BracketKeyGroup[] => {
+  const src = typeDefinitions;
+  // Locate `declare const <rootName>` then the opening `{` of its type.
+  const declMatch = new RegExp(
+    String.raw`declare\s+const\s+${rootName}\b`,
+  ).exec(src);
+  if (!declMatch) {
+    return [];
+  }
+  let i = src.indexOf("{", declMatch.index + declMatch[0].length);
+  if (i === -1) {
+    return [];
+  }
+
+  // Insertion-ordered accumulation so output is stable for tests/snapshots.
+  const groups = new Map<string, string[]>();
+  const addKey = (objectExpression: string, key: string): void => {
+    const existing = groups.get(objectExpression);
+    if (existing) {
+      if (!existing.includes(key)) {
+        existing.push(key);
+      }
+    } else {
+      groups.set(objectExpression, [key]);
+    }
+  };
+
+  // path[k] / dottable[k] describe the object open at brace depth k+1.
+  const path: string[] = [rootName];
+  const dottable: boolean[] = [true];
+  let depth = 1; // we consume the root `{` below
+  i += 1; // step past the root object's opening brace
+
+  // The property name most recently parsed, awaiting its value. Used to label
+  // the object we descend into on the next `{`.
+  let pendingName: { value: string; identifier: boolean } | null = null;
+
+  const peekNonWs = (from: number): number => {
+    let j = from;
+    while (j < src.length && isWhitespace(src[j] ?? "")) {
+      j += 1;
+    }
+    return j;
+  };
+
+  while (i < src.length && depth > 0) {
+    const ch = src[i] ?? "";
+
+    // Comments.
+    if (ch === "/" && src[i + 1] === "*") {
+      const end = src.indexOf("*/", i + 2);
+      i = end === -1 ? src.length : end + 2;
+      continue;
+    }
+    if (ch === "/" && src[i + 1] === "/") {
+      const nl = src.indexOf("\n", i + 2);
+      i = nl === -1 ? src.length : nl + 1;
+      continue;
+    }
+
+    if (isWhitespace(ch)) {
+      i += 1;
+      continue;
+    }
+
+    // String token: either a property name (if followed by `:`) or a
+    // type-position literal (e.g. a union member) which we ignore.
+    if (ch === '"' || ch === "'") {
+      const quote = ch;
+      let j = i + 1;
+      let str = "";
+      while (j < src.length && src[j] !== quote) {
+        if (src[j] === "\\") {
+          str += src[j + 1] ?? "";
+          j += 2;
+          continue;
+        }
+        str += src[j];
+        j += 1;
+      }
+      const afterStr = j + 1; // past closing quote
+      // A quoted property name may be optional: `"key"?: ...` (this is exactly
+      // how generated artifact keys look, e.g. `"integration-jira.issue"?:`).
+      let colon = peekNonWs(afterStr);
+      if (src[colon] === "?") {
+        colon = peekNonWs(colon + 1);
+      }
+      if (src[colon] === ":") {
+        // Quoted property name. Record under the current object when every
+        // ancestor segment is dot-addressable.
+        if (dottable.every(Boolean) && !isIdentifier(str)) {
+          addKey(path.join("."), str);
+        }
+        pendingName = { value: str, identifier: isIdentifier(str) };
+        i = colon + 1;
+      } else {
+        // Type-position string literal - not a key.
+        i = afterStr;
+      }
+      continue;
+    }
+
+    // Identifier: a property name (if followed by `:`, allowing an optional
+    // `?`) or a type keyword / modifier we skip.
+    if (/[A-Za-z_$]/.test(ch)) {
+      let j = i;
+      while (j < src.length && /[\w$]/.test(src[j] ?? "")) {
+        j += 1;
+      }
+      const word = src.slice(i, j);
+      let after = peekNonWs(j);
+      if (src[after] === "?") {
+        after = peekNonWs(after + 1);
+      }
+      if (src[after] === ":") {
+        pendingName = { value: word, identifier: true };
+        i = after + 1;
+      } else {
+        // `readonly`, `string`, `interface`, etc. - not a key for us.
+        i = j;
+      }
+      continue;
+    }
+
+    if (ch === "{") {
+      depth += 1;
+      path.push(pendingName?.value ?? "");
+      dottable.push(pendingName?.identifier ?? false);
+      pendingName = null;
+      i += 1;
+      continue;
+    }
+
+    if (ch === "}") {
+      depth -= 1;
+      path.pop();
+      dottable.pop();
+      pendingName = null;
+      i += 1;
+      continue;
+    }
+
+    // End of a property's value (e.g. `: string;`) - the pending name had a
+    // non-object type, so it never labels a descent.
+    if (ch === ";" || ch === ",") {
+      pendingName = null;
+    }
+    i += 1;
+  }
+
+  return [...groups].map(([objectExpression, keys]) => ({
+    objectExpression,
+    keys,
+  }));
+};

package/src/components/CodeEditor/generateTypeDefinitions.ts

@@ -89,10 +89,10 @@ declare const context: {
     `);
   }
 
-  // We deliberately don't redeclare `console`, `fetch`, the Node stdlib,
-  // or the Bun globals here — MonacoEditor mounts the bundled upstream
-  // `@types/node` + `bun-types` declarations into Monaco's virtual
-  // filesystem via `ensureMonacoStdlib`, so all of that is already in scope.
+  // We deliberately don't redeclare `console`, `fetch`, the Node stdlib, or
+  // the Bun globals here: the editor mounts the bundled upstream `@types/node`
+  // + `bun-types` declarations into the TypeScript service, so all of that is
+  // already in scope.
   return lines.join("\n");
 }
 

package/src/components/CodeEditor/index.ts

@@ -4,6 +4,7 @@ export {
   type CodeEditorLanguage,
   type TemplateProperty,
   type ShellEnvVar,
+  type EditorMarker,
 } from "./CodeEditor";
 
 export {
@@ -12,6 +13,7 @@ export {
 } from "./generateTypeDefinitions";
 
 export {
+  customShellEnvVars,
   healthcheckScriptContext,
   integrationScriptContext,
   type ScriptEditorContext,

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

@@ -52,6 +52,15 @@ describe("healthcheckScriptContext", () => {
     expect(ctx.typeDefinitions).toContain("HealthCheckScriptContext");
   });
 
+  it("exposes `context.check` and `context.system` run-context metadata", () => {
+    // The runner injects check/system metadata alongside config, so the
+    // editor must type them or `context.system.name` would error.
+    const ctx = healthcheckScriptContext({});
+    expect(ctx.typeDefinitions).toContain("readonly check: {");
+    expect(ctx.typeDefinitions).toContain("readonly system: {");
+    expect(ctx.typeDefinitions).toContain("readonly intervalSeconds: number");
+  });
+
   it("types the `defineHealthCheck` callback parameter from the schema (not `unknown`)", () => {
     // Regression guard: the previous version had `(ctx: unknown) => …`,
     // so `ctx.config.host` produced "'ctx' is of type 'unknown'". The
@@ -95,10 +104,42 @@ describe("healthcheckScriptContext", () => {
     expect(names).toContain("PATH");
     expect(names).toContain("HOME");
     expect(names).toContain("TZ");
+    // Run-context vars the shell collector injects are suggested too.
+    expect(names).toContain("CHECKSTACK_CHECK_NAME");
+    expect(names).toContain("CHECKSTACK_SYSTEM_NAME");
+    expect(names).toContain("CHECKSTACK_CHECK_INTERVAL_SECONDS");
     // Integration-only vars must NOT leak into the healthcheck context.
     expect(names).not.toContain("EVENT_ID");
     expect(names).not.toContain("PAYLOAD_TITLE");
   });
+
+  it("surfaces the user's custom Env (JSON) keys as shell completions", () => {
+    const ctx = healthcheckScriptContext({
+      customEnv: { API_TOKEN: "secret", "not-an-ident": "x" },
+    });
+    const names = ctx.shellEnvVars.map((v) => v.name);
+    // Valid shell identifier from the user's env is suggested...
+    expect(names).toContain("API_TOKEN");
+    // ...alongside the whitelist + reserved run-context vars.
+    expect(names).toContain("PATH");
+    expect(names).toContain("CHECKSTACK_SYSTEM_NAME");
+    // Keys that aren't valid `$NAME` identifiers are dropped.
+    expect(names).not.toContain("not-an-ident");
+    // The user's own var must be ordered ahead of the whitelist + run-context
+    // vars so it's not buried at the bottom of the suggest list.
+    expect(names.indexOf("API_TOKEN")).toBeLessThan(names.indexOf("PATH"));
+    expect(names.indexOf("API_TOKEN")).toBeLessThan(
+      names.indexOf("CHECKSTACK_SYSTEM_NAME"),
+    );
+  });
+
+  it("ignores a non-object customEnv without throwing", () => {
+    const names = healthcheckScriptContext({
+      customEnv: "not an object",
+    }).shellEnvVars.map((v) => v.name);
+    expect(names).toContain("PATH");
+    expect(names).toContain("CHECKSTACK_CHECK_ID");
+  });
 });
 
 describe("integrationScriptContext", () => {

package/src/components/CodeEditor/scriptContext.ts

@@ -89,6 +89,22 @@ interface HealthCheckScriptResult {
 interface HealthCheckScriptContext {
   /** Strongly-typed collector configuration. */
   readonly config: ${configType};
+  /** Metadata about the health check this run is for. */
+  readonly check: {
+    /** The health check configuration id. */
+    readonly id: string;
+    /** The health check's display name (falls back to the id). */
+    readonly name: string;
+    /** The configured run interval, in seconds. */
+    readonly intervalSeconds: number;
+  };
+  /** Metadata about the system this check runs for. */
+  readonly system: {
+    /** The system id. */
+    readonly id: string;
+    /** The system's display name (falls back to the id). */
+    readonly name: string;
+  };
 }
 
 /**
@@ -328,6 +344,51 @@ const SAFE_SHELL_VARS: ShellEnvVar[] = [
   { name: "SHELL", description: "User's login shell." },
 ];
 
+/**
+ * Run-context vars the satellite injects into every shell health-check
+ * run, describing the check + system it's for. Mirrors the reserved
+ * `CHECKSTACK_*` keys set by `healthcheck-script-backend`'s shell
+ * collector. User-supplied `env` values override these.
+ */
+const HEALTHCHECK_RUN_CONTEXT_VARS: ShellEnvVar[] = [
+  { name: "CHECKSTACK_CHECK_ID", description: "This health check's configuration id." },
+  {
+    name: "CHECKSTACK_CHECK_NAME",
+    description: "This health check's display name (falls back to the id).",
+  },
+  {
+    name: "CHECKSTACK_CHECK_INTERVAL_SECONDS",
+    description: "The configured run interval, in seconds.",
+  },
+  { name: "CHECKSTACK_SYSTEM_ID", description: "The id of the system being checked." },
+  {
+    name: "CHECKSTACK_SYSTEM_NAME",
+    description: "The system's display name (falls back to the id).",
+  },
+];
+
+/** A valid POSIX shell identifier — only these can be referenced as `$NAME`. */
+const SHELL_IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+/**
+ * Turn a user's custom `env` object (e.g. a script action's or health
+ * check's "Env (JSON)" field) into `$`-completion hints. Defensive about
+ * the loosely-typed form value: non-objects yield nothing, and only keys
+ * that are valid shell identifiers are surfaced (a `$my-var` completion
+ * wouldn't be usable). Exported so editors that build their shell env
+ * suggestions outside the `*ScriptContext` helpers (e.g. the automation
+ * action editor) can merge custom env keys the same way.
+ */
+export function customShellEnvVars(env: unknown): ShellEnvVar[] {
+  if (typeof env !== "object" || env === null || Array.isArray(env)) return [];
+  return Object.keys(env)
+    .filter((name) => SHELL_IDENTIFIER.test(name))
+    .map((name) => ({
+      name,
+      description: "Custom variable from this check's Env (JSON) field.",
+    }));
+}
+
 /**
  * Vars injected by the integration platform on every delivery. Per-
  * payload-field `PAYLOAD_*` vars are appended at call time based on the
@@ -406,6 +467,13 @@ function flattenSchemaToEnvVars(
  */
 export function healthcheckScriptContext(input: {
   collectorConfigSchema?: JsonSchemaProperty;
+  /**
+   * The collector's current `env` value (the "Env (JSON)" field). Its
+   * keys are surfaced as `$`-completions so a user's own declared vars
+   * autocomplete alongside the whitelist + reserved run-context vars.
+   * Typed `unknown` because it comes from the loosely-typed form value.
+   */
+  customEnv?: unknown;
 }): ScriptEditorContext {
   const configType = input.collectorConfigSchema
     ? jsonSchemaToTypeScript(input.collectorConfigSchema)
@@ -418,7 +486,14 @@ export function healthcheckScriptContext(input: {
       javascript: HEALTHCHECK_INLINE_TS_STARTER,
       shell: HEALTHCHECK_SHELL_STARTER,
     },
-    shellEnvVars: SAFE_SHELL_VARS,
+    // Most-relevant-first: the user's own declared env, then this check's
+    // run-context metadata, then the generic OS whitelist (the suggest list
+    // is ordered by insertion index, so order here is what the user sees).
+    shellEnvVars: [
+      ...customShellEnvVars(input.customEnv),
+      ...HEALTHCHECK_RUN_CONTEXT_VARS,
+      ...SAFE_SHELL_VARS,
+    ],
   };
 }
 

package/src/components/CodeEditor/templateValidation.ts

@@ -0,0 +1,51 @@
+// Shared bits for template-aware language validation (monaco -> @typefox
+// migration). Markup editors (json / yaml / xml) hold a TEMPLATE that renders
+// to the target language, not the language itself: a value can be templated in
+// any position, including unquoted ones (e.g. a number `timeout: {{x}}`). So we
+// validate "is this valid once the templates are filled in?" - substitute each
+// `{{ ... }}` with a same-length neutral value, then parse with a real parser.
+//
+// Per-language validators live in validate{Json,Yaml,Xml}Template.ts and all
+// return TemplateDiagnostic[]; the editor maps offsets to monaco markers.
+
+export interface TemplateDiagnostic {
+  /** 0-based character offset into the ORIGINAL text. */
+  offset: number;
+  /** Length of the offending span (>= 1). */
+  length: number;
+  /** Human-readable message. */
+  message: string;
+}
+
+// `[^{}]*` (not `[^}]*`) so an unclosed `{{` can't swallow up to a later `}}`.
+const TEMPLATE_PATTERN = /\{\{[^{}]*\}\}/g;
+
+/**
+ * Replace each `{{ ... }}` with `0` padded to the same length with spaces - a
+ * neutral value token, valid in value positions (a number followed by
+ * whitespace) and harmless inside strings/text. Same length keeps byte offsets
+ * identical, so parser offsets map 1:1 onto the original text.
+ */
+export const substituteTemplates = (text: string): string =>
+  text.replaceAll(
+    TEMPLATE_PATTERN,
+    (match) => `0${" ".repeat(match.length - 1)}`,
+  );
+
+/** Convert a 1-based line/column (some parsers report this) to a 0-based offset. */
+export const lineColumnToOffset = ({
+  text,
+  line,
+  column,
+}: {
+  text: string;
+  line: number;
+  column: number;
+}): number => {
+  const lines = text.split("\n");
+  let offset = 0;
+  for (let index = 0; index < line - 1 && index < lines.length; index += 1) {
+    offset += (lines[index]?.length ?? 0) + 1; // +1 for the newline
+  }
+  return offset + Math.max(column - 1, 0);
+};

package/src/components/CodeEditor/types.ts

@@ -0,0 +1,109 @@
+// Shared, pure type definitions for the CodeEditor public API.
+//
+// NOTE: this file MUST stay free of monaco / @codingame / vite imports so that
+// SSR/test/node paths can reference these types (and the package barrel can
+// re-export them) without pulling in the browser-only editor stack.
+
+export type CodeEditorLanguage =
+  | "json"
+  | "yaml"
+  | "xml"
+  | "markdown"
+  | "javascript"
+  | "typescript"
+  | "shell";
+
+/**
+ * A single payload property available for templating. Used by both the
+ * Monaco-backed `CodeEditor` and the lightweight single-line
+ * `TemplateValueInput` for the simple "insert a `{{ path }}` reference" flow.
+ */
+export interface TemplateProperty {
+  /** Full canonical path to the property, e.g., "trigger.payload.title". */
+  path: string;
+  /**
+   * Runtime-parseable `{{ }}` insertion text, e.g.
+   * `artifacts["integration-jira.issue"].issueKey`. When present this is
+   * what gets inserted; consumers fall back to `path` when it's absent.
+   */
+  templateRef?: string;
+  /** Type label rendered on the right, e.g. "string", "number". */
+  type: string;
+  /** Optional description of the property. */
+  description?: string;
+  /**
+   * Known discrete values for this field, when the schema declares an `enum`.
+   * Consumed by the template-completion provider to suggest concrete values
+   * after a comparator (e.g. `"low"` / `"high"` for a severity field).
+   */
+  enumValues?: Array<string | number | boolean>;
+}
+
+/**
+ * A single environment variable available to shell scripts. Surfaced as a
+ * completion item after the user types `$` or `${` in shell mode.
+ */
+export interface ShellEnvVar {
+  /** Variable name without the leading `$`, e.g. `EVENT_ID`. */
+  name: string;
+  /** Optional description shown in the completion popup. */
+  description?: string;
+  /** Optional example value shown in the completion item detail. */
+  example?: string;
+}
+
+/**
+ * An externally-supplied diagnostic to render as an inline squiggle. Positions
+ * are 1-based line/column (the editor's convention). Callers compute these from
+ * their own validation (e.g. mapping a definition issue path back to a YAML
+ * node range) and pass them via `markers`.
+ */
+export interface EditorMarker {
+  startLineNumber: number;
+  startColumn: number;
+  endLineNumber: number;
+  endColumn: number;
+  message: string;
+  severity?: "error" | "warning" | "info";
+}
+
+export interface CodeEditorProps {
+  /** Unique identifier for the editor. */
+  id?: string;
+  /** Current value of the editor. */
+  value: string;
+  /** Callback when the value changes. */
+  onChange: (value: string) => void;
+  /** Language for syntax highlighting. */
+  language?: CodeEditorLanguage;
+  /** Minimum height of the editor, as a CSS length (e.g. "240px"). */
+  minHeight?: string;
+  /** Whether the editor is read-only. */
+  readOnly?: boolean;
+  /** Placeholder text when empty. */
+  placeholder?: string;
+  /**
+   * TypeScript type definitions to inject for IntelliSense (the `context.d.ts`).
+   * Generated from JSON schemas for context-aware autocomplete. For
+   * `typescript` / `javascript` editors, non-identifier object keys in these
+   * definitions (e.g. artifact ids) are offered as `["key"]` bracket
+   * completions automatically.
+   */
+  typeDefinitions?: string;
+  /**
+   * Optional template properties for autocomplete. When provided, typing "{{"
+   * triggers autocomplete with the available template variables.
+   */
+  templateProperties?: TemplateProperty[];
+  /**
+   * Optional environment-variable hints for shell mode. When provided and
+   * `language === "shell"`, they autocomplete after `$` and `${`.
+   */
+  shellEnvVars?: ShellEnvVar[];
+  /**
+   * Externally-computed diagnostics rendered as inline squiggles (under a
+   * dedicated marker owner, so they coexist with the editor's own language
+   * diagnostics).
+   */
+  markers?: EditorMarker[];
+}