@px-lsp/server 0.1.0

package/media/px-lsp.svg

@@ -0,0 +1,12 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 128 128" width="128" height="128">
+  <rect width="128" height="128" rx="26" fill="#17161A" />
+  <g transform="translate(29.559 60.595) scale(0.023192 -0.023192)" fill="#F2EDE3" fill-rule="evenodd">
+    <path transform="translate(0 0)" d="M0 0L0 1466L700 1466Q1010 1466 1140 1362Q1270 1258 1270 1040Q1270 822 1140 719Q1010 616 700 616L453 616L453 0ZM453 946L690 946Q900 946 900 1040Q900 1136 690 1136L453 1136Z" />
+    <path transform="translate(1470 0)" d="M0 1466L560 1466L750 1169.7L940 1466L1500 1466L1030 733L1500 0L940 0L750 296.3L560 0L0 0L470 733Z" />
+  </g>
+  <g transform="translate(19.007 100.595) scale(0.023192 -0.023192)" fill="#C8952F" fill-rule="evenodd">
+    <path transform="translate(0 0)" d="M0 0L0 1466L453 1466L453 362L1080 362L1080 0Z" />
+    <path transform="translate(1280 0)" d="M1077.1 1220.2L1053.8 1257.2L1026.6 1292.4L995.8 1325.4L961.6 1356.0L924.2 1384.0L884.0 1409.1L841.3 1431.1L796.3 1449.9L749.5 1465.3L701.3 1477.2L652.0 1485.4L602.0 1490.0L551.6 1490.9L501.4 1488.0L451.8 1481.5L403.0 1471.3L355.4 1457.5L309.6 1440.3L265.8 1419.8L224.3 1396.1L185.6 1369.5L149.8 1340.1L117.4 1308.2L88.5 1274.0L63.4 1237.8L42.2 1199.9L25.2 1160.6L12.5 1120.2L4.2 1079.0L0.3 1037.3L0.9 995.6L6.0 954.0L15.5 913.0L29.3 872.9L47.4 833.9L69.6 796.4L95.8 760.7L125.7 727.1L159.0 695.8L195.6 667.1L235.1 641.3L277.2 618.4L321.6 598.8L367.9 582.5L415.8 569.6L464.9 560.4L514.7 554.9L565.0 553.0L565.0 903.0L545.9 903.5L526.9 904.9L508.2 907.2L490.0 910.5L472.4 914.6L455.5 919.6L439.4 925.4L424.4 932.0L410.5 939.2L397.8 947.2L386.5 955.7L376.5 964.8L368.1 974.3L361.2 984.2L355.9 994.3L352.3 1004.8L350.3 1015.3L350.1 1025.9L351.6 1036.5L354.8 1046.9L359.6 1057.2L366.1 1067.1L374.1 1076.8L383.7 1085.9L394.7 1094.6L407.0 1102.7L420.6 1110.2L435.4 1116.9L451.1 1122.9L467.8 1128.1L485.3 1132.5L503.3 1136.0L521.9 1138.6L540.8 1140.2L559.9 1141.0L579.1 1140.7L598.1 1139.6L616.9 1137.5L635.2 1134.5L653.0 1130.6L670.1 1125.8L686.4 1120.2L701.7 1113.9L715.9 1106.8L728.9 1099.0L740.7 1090.6L751.0 1081.7L759.9 1072.3ZM565.0 903.0L615.3 901.1L665.1 895.6L714.2 886.4L762.1 873.5L808.4 857.2L852.8 837.6L894.9 814.7L934.4 788.9L971.0 760.2L1004.3 728.9L1034.2 695.3L1060.4 659.6L1082.6 622.1L1100.7 583.1L1114.5 543.0L1124.0 502.0L1129.1 460.4L1129.7 418.7L1125.8 377.0L1117.5 335.8L1104.8 295.4L1087.8 256.1L1066.6 218.2L1041.5 182.0L1012.6 147.8L980.2 115.9L944.4 86.5L905.7 59.9L864.2 36.2L820.4 15.7L774.6 -1.5L727.0 -15.3L678.2 -25.5L628.6 -32.0L578.4 -34.9L528.0 -34.0L478.0 -29.4L428.7 -21.2L380.5 -9.3L333.7 6.1L288.7 24.9L246.0 46.9L205.8 72.0L168.4 100.0L134.2 130.6L103.4 163.6L76.2 198.8L52.9 235.8L370.1 383.7L379.0 374.3L389.3 365.4L401.1 357.0L414.1 349.2L428.3 342.1L443.6 335.8L459.9 330.2L477.0 325.4L494.8 321.5L513.1 318.5L531.9 316.4L550.9 315.3L570.1 315.0L589.2 315.8L608.1 317.4L626.7 320.0L644.7 323.5L662.2 327.9L678.9 333.1L694.6 339.1L709.4 345.8L723.0 353.3L735.3 361.4L746.3 370.1L755.9 379.2L763.9 388.9L770.4 398.8L775.2 409.1L778.4 419.5L779.9 430.1L779.7 440.7L777.7 451.2L774.1 461.7L768.8 471.8L761.9 481.7L753.5 491.2L743.5 500.3L732.2 508.8L719.5 516.8L705.6 524.0L690.6 530.6L674.5 536.4L657.6 541.4L640.0 545.5L621.8 548.8L603.1 551.1L584.1 552.5L565.0 553.0Z" />
+    <path transform="translate(2610 0)" d="M0 0L0 1466L700 1466Q1010 1466 1140 1362Q1270 1258 1270 1040Q1270 822 1140 719Q1010 616 700 616L453 616L453 0ZM453 946L690 946Q900 946 900 1040Q900 1136 690 1136L453 1136Z" />
+  </g>
+</svg>

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@px-lsp/server",
+  "version": "0.1.0",
+  "license": "GPL-3.0-or-later",
+  "description": "Language server for Paradox script (Crusader Kings III first), usable over node-ipc or stdio from any LSP client.",
+  "keywords": [
+    "lsp",
+    "language-server",
+    "paradox",
+    "crusader-kings-3",
+    "ck3",
+    "modding"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/JDeffner/paradox-modding-toolkit.git",
+    "directory": "packages/server"
+  },
+  "bin": {
+    "px-lsp": "./dist/server.js"
+  },
+  "files": [
+    "dist",
+    "data",
+    "media",
+    "src",
+    "README.md",
+    "LICENSE",
+    "THIRD-PARTY-NOTICES.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    "./package.json": "./package.json",
+    "./dds": "./src/dds/index.ts",
+    "./parser": "./src/parser/index.ts",
+    "./*": "./src/*.ts"
+  },
+  "dependencies": {
+    "vscode-languageserver": "^10.1.0",
+    "vscode-languageserver-textdocument": "^1.0.12",
+    "vscode-uri": "^3.1.0",
+    "@px-lsp/protocol": "0.1.0"
+  },
+  "scripts": {
+    "compile": "esbuild src/server.ts --bundle --outfile=dist/server.js --format=cjs --platform=node --target=node18 --banner:js=\"#!/usr/bin/env node\"",
+    "watch": "esbuild src/server.ts --bundle --outfile=dist/server.js --format=cjs --platform=node --target=node18 --watch"
+  }
+}

package/src/clientMode.ts

@@ -0,0 +1,60 @@
+/**
+ * Resolved client capabilities (docs/PROTOCOL.md §Initialization). A client
+ * declares what it implements in `initializationOptions.client`; every gate
+ * site here asks a semantic question (`hoverHtml()`, `canRunCommand(id)`)
+ * instead of "is this the VSCode client", so a client can take the rich hover
+ * markup without the commands, or one command without the others.
+ *
+ * Defaults to fully capable so the pure-render unit tests exercise the rich
+ * output; server.ts installs the resolved value at initialize.
+ */
+import { allClientCommandIds, type ParadoxInitOptions } from "@px-lsp/protocol/protocol";
+
+export interface ClientCapabilities {
+  /** Client renders the sanitized `<span style="color:var(--*)">` hover markup. */
+  hoverHtml: boolean;
+  /** Command ids the client registers; anything else must not be emitted. */
+  commands: ReadonlySet<string>;
+  /** Client watches the mod tree itself and pushes paradox/modFileChanged. */
+  ownFileWatcher: boolean;
+}
+
+/**
+ * Read the capabilities off initializationOptions. The deprecated
+ * `clientCommands: true` boolean is an alias for "everything on" (what the
+ * VSCode extension sent before the object existed); the object wins when both
+ * are present.
+ */
+export function resolveClientCapabilities(init: Partial<ParadoxInitOptions>): ClientCapabilities {
+  if (init.client) {
+    return {
+      hoverHtml: init.client.hoverHtml === true,
+      commands: new Set(init.client.commands ?? []),
+      ownFileWatcher: init.client.ownFileWatcher === true,
+    };
+  }
+  if (init.clientCommands === true) {
+    return { hoverHtml: true, commands: new Set(allClientCommandIds), ownFileWatcher: true };
+  }
+  return { hoverHtml: false, commands: new Set(), ownFileWatcher: false };
+}
+
+let caps: ClientCapabilities = resolveClientCapabilities({ clientCommands: true });
+
+export function setClientCapabilities(value: ClientCapabilities): void {
+  caps = value;
+}
+
+export function clientCapabilities(): ClientCapabilities {
+  return caps;
+}
+
+/** Whether hover markdown may carry the sanitized colored spans. */
+export function hoverHtml(): boolean {
+  return caps.hoverHtml;
+}
+
+/** Whether the client registers `id`, so a `command:` link or command action reaches it. */
+export function canRunCommand(id: string): boolean {
+  return caps.commands.has(id);
+}

package/src/coa/coa.ts

@@ -0,0 +1,184 @@
+/**
+ * Coat-of-arms model for the flag builder (every game whose profile opts in
+ * shares the format): the types, color resolution and the writer. Parsing lives in
+ * coaParse.ts so this module (which the webview app bundles) pulls in no
+ * parser and no game profile.
+ *
+ * The model mirrors what the game reads, no more:
+ *
+ *   NAME = {
+ *     pattern = "pattern_solid.tga"
+ *     color1 = "red"                 # named | color3 (reference) | rgb { } | hsv { } | hsv360 { }
+ *     colored_emblem = {             # | textured_emblem | sub
+ *       texture = "ce_circle.dds"    # sub: parent = "NAME"
+ *       mask = { 1 }                 # colored_emblem only: pattern color slot 1..3
+ *       color1 = color2
+ *       instance = { rotation = 0 scale = { 1 1 } position = { 0.5 0.5 } }
+ *     }                              # sub instances: offset = { } scale = { }
+ *   }
+ *
+ * No vscode imports; runs in the extension host, the webview app and tests.
+ */
+export type Rgb = [number, number, number];
+
+export type CoaColor =
+  | { name: string; kind: "named"; value: string }
+  | { name: string; kind: "ref"; value: string }
+  | { name: string; kind: "rgb"; value: Rgb }
+  | { name: string; kind: "hsv360"; value: [number, number, number] };
+
+export interface CoaInstance {
+  rotation: number;
+  scale: [number, number];
+  position: [number, number];
+}
+
+export interface CoaSubInstance {
+  offset: [number, number];
+  scale: [number, number];
+}
+
+export type CoaLayer =
+  | { kind: "colored_emblem"; texture: string; mask: number; colors: CoaColor[]; instances: CoaInstance[] }
+  | { kind: "textured_emblem"; texture: string; instances: CoaInstance[] }
+  | { kind: "sub"; parent: string; instances: CoaSubInstance[] };
+
+export interface CoaFlag {
+  name: string;
+  pattern: string;
+  colors: CoaColor[];
+  layers: CoaLayer[];
+}
+
+/** The slots a flag or a layer may fill, in the order the game names them. */
+export const COLOR_SLOTS = [
+  "color1",
+  "color2",
+  "color3",
+  "color4",
+  "color5",
+  "color6",
+  "color7",
+  "color8",
+  "color9",
+];
+
+/** Placeholder colors a pattern texture is painted with; slot N maps to color N. */
+export const PATTERN_SOURCE_COLORS: Rgb[] = [
+  [255, 0, 0],
+  [255, 255, 0],
+  [255, 255, 255],
+];
+
+/** Placeholder colors of a colored emblem (red/green identify the slot, blue is shading). */
+export const EMBLEM_SOURCE_COLORS: Rgb[] = [
+  [0, 0, 128],
+  [0, 255, 128],
+  [255, 0, 128],
+];
+
+export const DEFAULT_INSTANCE: CoaInstance = { rotation: 0, scale: [1, 1], position: [0.5, 0.5] };
+export const DEFAULT_SUB_INSTANCE: CoaSubInstance = { offset: [0, 0], scale: [1, 1] };
+
+// ---------------------------------------------------------------------------
+// Colors
+// ---------------------------------------------------------------------------
+
+export function hsv360ToRgb(h: number, s: number, v: number): Rgb {
+  const hh = (((h % 360) + 360) % 360) / 60;
+  const ss = Math.min(1, Math.max(0, s / 100));
+  const vv = Math.min(1, Math.max(0, v / 100));
+  const c = vv * ss;
+  const x = c * (1 - Math.abs((hh % 2) - 1));
+  const m = vv - c;
+  const sector = Math.floor(hh);
+  const [r, g, b] =
+    sector === 0
+      ? [c, x, 0]
+      : sector === 1
+        ? [x, c, 0]
+        : sector === 2
+          ? [0, c, x]
+          : sector === 3
+            ? [0, x, c]
+            : sector === 4
+              ? [x, 0, c]
+              : [c, 0, x];
+  return [Math.round((r + m) * 255), Math.round((g + m) * 255), Math.round((b + m) * 255)];
+}
+
+/**
+ * The rgb a color resolves to: a literal, a named color from the game's
+ * tables, or a reference (`color1 = color3`) into the flag's own colors. A
+ * reference to a reference is followed once (the game does not chain them).
+ */
+export function colorToRgb(color: CoaColor, named: Record<string, Rgb>, flagColors: CoaColor[]): Rgb | null {
+  switch (color.kind) {
+    case "rgb":
+      return color.value;
+    case "hsv360":
+      return hsv360ToRgb(color.value[0], color.value[1], color.value[2]);
+    case "named":
+      return named[color.value] ?? null;
+    case "ref": {
+      const base = flagColors.find((c) => c.name === color.value);
+      if (!base || base.kind === "ref") return null;
+      return colorToRgb(base, named, []);
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Writing
+// ---------------------------------------------------------------------------
+
+const fmt = (n: number): string =>
+  Number.isInteger(n) ? String(n) : n.toFixed(3).replace(/0+$/, "").replace(/\.$/, "");
+
+function writeColor(c: CoaColor): string {
+  switch (c.kind) {
+    case "named":
+      return `${c.name} = "${c.value}"`;
+    case "ref":
+      return `${c.name} = ${c.value}`;
+    case "rgb":
+      return `${c.name} = rgb { ${c.value.join(" ")} }`;
+    case "hsv360":
+      return `${c.name} = hsv360 { ${c.value.map((v) => Math.round(v)).join(" ")} }`;
+  }
+}
+
+/** The flag as the game reads it: tabs, one attribute per line, no trailing newline. */
+export function writeFlag(flag: CoaFlag): string {
+  const lines: string[] = [`${flag.name || "NONE"} = {`];
+  if (flag.pattern) lines.push(`\tpattern = "${flag.pattern}"`);
+  for (const c of flag.colors) lines.push(`\t${writeColor(c)}`);
+  for (const layer of flag.layers) {
+    lines.push("");
+    lines.push(`\t${layer.kind} = {`);
+    if (layer.kind === "sub") {
+      lines.push(`\t\tparent = "${layer.parent}"`);
+      for (const i of layer.instances) {
+        lines.push(
+          `\t\tinstance = { offset = { ${fmt(i.offset[0])} ${fmt(i.offset[1])} } scale = { ${fmt(i.scale[0])} ${fmt(i.scale[1])} } }`
+        );
+      }
+    } else {
+      lines.push(`\t\ttexture = "${layer.texture}"`);
+      if (layer.kind === "colored_emblem") {
+        if (layer.mask > 0) lines.push(`\t\tmask = { ${layer.mask} }`);
+        for (const c of layer.colors) lines.push(`\t\t${writeColor(c)}`);
+      }
+      for (const i of layer.instances) {
+        const parts = [];
+        if (i.rotation !== 0) parts.push(`rotation = ${fmt(i.rotation)}`);
+        parts.push(`scale = { ${fmt(i.scale[0])} ${fmt(i.scale[1])} }`);
+        parts.push(`position = { ${fmt(i.position[0])} ${fmt(i.position[1])} }`);
+        lines.push(`\t\tinstance = { ${parts.join(" ")} }`);
+      }
+    }
+    lines.push("\t}");
+  }
+  lines.push("}");
+  return lines.join("\n");
+}

package/src/coa/coaParse.ts

@@ -0,0 +1,267 @@
+/**
+ * Coat-of-arms parsing: a `common/coat_of_arms/coat_of_arms/*.txt` file into
+ * CoaFlags, `common/named_colors/*.txt` into rgb, and the in-place replace
+ * of one flag in a file. Numbers may be `@vars` defined at the top of the
+ * same file, including `@[ expr ]` arithmetic; both are resolved here so the
+ * renderer only sees numbers. `template = { }` blocks are skipped like the
+ * game's own tool does.
+ *
+ * Host and test side only: the tolerant parser brings the game profiles with
+ * it, which the webview app must not bundle.
+ */
+import { parseScript } from "../parser/parser";
+import type { BlockNode, Statement, ValueNode } from "../parser/cst";
+import {
+  COLOR_SLOTS,
+  colorToRgb,
+  DEFAULT_INSTANCE,
+  DEFAULT_SUB_INSTANCE,
+  type CoaColor,
+  type CoaFlag,
+  type CoaInstance,
+  type CoaLayer,
+  type CoaSubInstance,
+  type Rgb,
+} from "./coa";
+
+// ---------------------------------------------------------------------------
+// @variables
+// ---------------------------------------------------------------------------
+
+type Vars = Map<string, number>;
+
+/**
+ * Evaluate `@[ expr ]` / `@name` / a plain number. Only `+ - * /`, parentheses
+ * and earlier `@vars` are understood, which is all the coa files use; anything
+ * else is NaN and the caller keeps its default.
+ */
+export function resolveNumber(text: string, vars: Vars): number {
+  const t = text.trim();
+  if (t.startsWith("@[") && t.endsWith("]")) return evalExpr(t.slice(2, -1), vars);
+  if (t.startsWith("@")) return vars.get(t) ?? NaN;
+  return Number(t);
+}
+
+function evalExpr(src: string, vars: Vars): number {
+  // Tokens: numbers, @names, operators, parens.
+  const tokens = src.match(/\d+(?:\.\d+)?|@[\w.]+|[-+*/()]/g);
+  if (!tokens || tokens.join("") !== src.replace(/\s+/g, "")) return NaN;
+  let i = 0;
+  const primary = (): number => {
+    const tok = tokens[i++];
+    if (tok === undefined) return NaN;
+    if (tok === "(") {
+      const v = sum();
+      return tokens[i++] === ")" ? v : NaN;
+    }
+    if (tok === "-") return -primary();
+    if (tok.startsWith("@")) return vars.get(tok) ?? NaN;
+    return Number(tok);
+  };
+  const product = (): number => {
+    let v = primary();
+    while (tokens[i] === "*" || tokens[i] === "/") {
+      const op = tokens[i++];
+      const r = primary();
+      v = op === "*" ? v * r : v / r;
+    }
+    return v;
+  };
+  const sum = (): number => {
+    let v = product();
+    while (tokens[i] === "+" || tokens[i] === "-") {
+      const op = tokens[i++];
+      const r = product();
+      v = op === "+" ? v + r : v - r;
+    }
+    return v;
+  };
+  const v = sum();
+  return i === tokens.length ? v : NaN;
+}
+
+// ---------------------------------------------------------------------------
+// Parsing
+// ---------------------------------------------------------------------------
+
+function scalarText(v: ValueNode | null): string | null {
+  return v && v.kind === "scalar" ? v.text : null;
+}
+
+function numbers(block: BlockNode, vars: Vars): number[] {
+  const out: number[] = [];
+  for (const s of block.statements) {
+    if (s.kind === "value" && s.value.kind === "scalar") out.push(resolveNumber(s.value.text, vars));
+  }
+  return out;
+}
+
+function pair(block: BlockNode, vars: Vars, fallback: [number, number]): [number, number] {
+  const n = numbers(block, vars);
+  if (n.length !== 2 || n.some((x) => !Number.isFinite(x))) return fallback;
+  return [n[0], n[1]];
+}
+
+function parseColor(name: string, value: ValueNode, vars: Vars): CoaColor | null {
+  if (value.kind === "scalar") {
+    if (!value.quoted && COLOR_SLOTS.includes(value.text)) return { name, kind: "ref", value: value.text };
+    return { name, kind: "named", value: value.text };
+  }
+  const tag = value.kind === "tagged-block" ? value.tag.text : "";
+  const block = value.kind === "tagged-block" ? value.block : value;
+  const n = numbers(block, vars);
+  if (n.length !== 3 || n.some((x) => !Number.isFinite(x))) return null;
+  if (tag === "hsv") return { name, kind: "hsv360", value: [n[0] * 360, n[1] * 100, n[2] * 100] };
+  if (tag === "hsv360") return { name, kind: "hsv360", value: [n[0], n[1], n[2]] };
+  // rgb, or untyped: floats 0..1 or bytes 0..255
+  const rgb = n.every((x) => x <= 1) ? n.map((x) => Math.round(x * 255)) : n.map((x) => Math.round(x));
+  return { name, kind: "rgb", value: [rgb[0], rgb[1], rgb[2]] };
+}
+
+function parseColors(statements: Statement[], vars: Vars): CoaColor[] {
+  const out: CoaColor[] = [];
+  for (const s of statements) {
+    if (s.kind !== "assignment" || !s.value || !COLOR_SLOTS.includes(s.key.text)) continue;
+    const c = parseColor(s.key.text, s.value, vars);
+    if (c) out.push(c);
+  }
+  return out;
+}
+
+function parseInstances(statements: Statement[], vars: Vars): CoaInstance[] {
+  const out: CoaInstance[] = [];
+  for (const s of statements) {
+    if (s.kind !== "assignment" || s.key.text !== "instance" || s.value?.kind !== "block") continue;
+    const inst: CoaInstance = { ...DEFAULT_INSTANCE };
+    for (const a of s.value.statements) {
+      if (a.kind !== "assignment" || !a.value) continue;
+      if (a.key.text === "rotation" && a.value.kind === "scalar") {
+        const r = resolveNumber(a.value.text, vars);
+        if (Number.isFinite(r)) inst.rotation = r;
+      } else if (a.key.text === "scale" && a.value.kind === "block") inst.scale = pair(a.value, vars, [1, 1]);
+      else if (a.key.text === "position" && a.value.kind === "block")
+        inst.position = pair(a.value, vars, [0.5, 0.5]);
+    }
+    out.push(inst);
+  }
+  return out;
+}
+
+function parseSubInstances(statements: Statement[], vars: Vars): CoaSubInstance[] {
+  const out: CoaSubInstance[] = [];
+  for (const s of statements) {
+    if (s.kind !== "assignment" || s.key.text !== "instance" || s.value?.kind !== "block") continue;
+    const inst: CoaSubInstance = { ...DEFAULT_SUB_INSTANCE };
+    for (const a of s.value.statements) {
+      if (a.kind !== "assignment" || a.value?.kind !== "block") continue;
+      if (a.key.text === "scale") inst.scale = pair(a.value, vars, [1, 1]);
+      else if (a.key.text === "offset") inst.offset = pair(a.value, vars, [0, 0]);
+    }
+    out.push(inst);
+  }
+  return out;
+}
+
+function parseLayer(kind: string, block: BlockNode, vars: Vars): CoaLayer | null {
+  let texture = "";
+  let parent = "";
+  let mask = 0;
+  for (const s of block.statements) {
+    if (s.kind !== "assignment" || !s.value) continue;
+    const text = scalarText(s.value);
+    if (s.key.text === "texture" && text !== null) texture = text;
+    else if (s.key.text === "parent" && text !== null) parent = text;
+    else if (s.key.text === "mask" && s.value.kind === "block") {
+      const n = numbers(s.value, vars);
+      if (n.length === 1 && Number.isFinite(n[0])) mask = n[0];
+    }
+  }
+  switch (kind) {
+    case "colored_emblem":
+      return {
+        kind,
+        texture,
+        mask,
+        colors: parseColors(block.statements, vars),
+        instances: parseInstances(block.statements, vars),
+      };
+    case "textured_emblem":
+      return { kind, texture, instances: parseInstances(block.statements, vars) };
+    case "sub":
+      return { kind, parent, instances: parseSubInstances(block.statements, vars) };
+  }
+  return null;
+}
+
+export function parseFlag(name: string, block: BlockNode, vars: Vars = new Map()): CoaFlag {
+  const flag: CoaFlag = { name, pattern: "", colors: parseColors(block.statements, vars), layers: [] };
+  for (const s of block.statements) {
+    if (s.kind !== "assignment" || !s.value) continue;
+    if (s.key.text === "pattern") flag.pattern = scalarText(s.value) ?? "";
+    else if (s.value.kind === "block") {
+      const layer = parseLayer(s.key.text, s.value, vars);
+      if (layer) flag.layers.push(layer);
+    }
+  }
+  return flag;
+}
+
+/**
+ * Every flag in one coa file. `template` blocks are skipped (they are not
+ * flags) and so is anything that is not `name = { }`.
+ */
+export function parseCoaFile(text: string): CoaFlag[] {
+  const { root } = parseScript(text);
+  const vars: Vars = new Map();
+  const flags: CoaFlag[] = [];
+  for (const s of root.statements) {
+    if (s.kind !== "assignment" || !s.value) continue;
+    if (s.key.text.startsWith("@")) {
+      const text = scalarText(s.value);
+      if (text !== null) {
+        const n = resolveNumber(text, vars);
+        if (Number.isFinite(n)) vars.set(s.key.text, n);
+      }
+      continue;
+    }
+    if (s.key.text === "template" || s.value.kind !== "block") continue;
+    flags.push(parseFlag(s.key.text, s.value, vars));
+  }
+  return flags;
+}
+
+/** `colors = { name = hsv360 { } ... }` entries of a named_colors file, as rgb bytes. */
+export function parseNamedColors(text: string): Record<string, Rgb> {
+  const { root } = parseScript(text);
+  const out: Record<string, Rgb> = {};
+  for (const s of root.statements) {
+    if (s.kind !== "assignment" || s.key.text !== "colors" || s.value?.kind !== "block") continue;
+    for (const c of s.value.statements) {
+      if (c.kind !== "assignment" || !c.value || c.value.kind === "scalar") continue;
+      const color = parseColor(c.key.text, c.value, new Map());
+      if (color) {
+        const rgb = colorToRgb(color, {}, []);
+        if (rgb) out[c.key.text] = rgb;
+      }
+    }
+  }
+  return out;
+}
+
+/**
+ * Replace the top-level `name = { }` block in a coa file with `script`, or
+ * append the script when the file has no such block. The rest of the file is
+ * untouched (line endings, comments, other flags).
+ */
+export function upsertFlagInFile(text: string, name: string, script: string): string {
+  const { root } = parseScript(text);
+  const eol = text.includes("\r\n") ? "\r\n" : "\n";
+  const body = script.replace(/\n/g, eol);
+  for (const s of root.statements) {
+    if (s.kind === "assignment" && s.key.text === name && s.value?.kind === "block") {
+      return text.slice(0, s.range.start) + body + text.slice(s.range.end);
+    }
+  }
+  const sep = text.length === 0 || text.endsWith("\n") ? "" : eol;
+  return text + sep + eol + body + eol;
+}

package/src/context.ts

@@ -0,0 +1,78 @@
+/**
+ * Block-context detection: from a cursor offset, walk the CST path upward to
+ * the nearest block keyword that decides trigger vs effect grammar.
+ *
+ * This is deliberately not scope-chain inference (that is the scope engine's
+ * job, Phase 3); it only answers "am I inside a trigger block, an effect
+ * block, or don't know". Built on the tolerant parser — the v0.3 regex walker
+ * this replaces re-scanned the whole document per keystroke.
+ *
+ * No `vscode` imports here: this module is unit-tested in plain Node.
+ */
+import { classifyKeyword } from "./contextKeywords";
+import { nodeAtOffset, parseScript, type BlockNode, type ParseResult, type Statement } from "./parser";
+
+export type BlockContext = "trigger" | "effect" | "value" | "unknown";
+
+export interface ContextResult {
+  context: BlockContext;
+  /** The block keyword that decided the context, or null at top level. */
+  keyword: string | null;
+}
+
+function childBlock(stmt: Statement): BlockNode | null {
+  const v = stmt.value;
+  if (!v) return null;
+  if (v.kind === "block") return v;
+  if (v.kind === "tagged-block") return v.block;
+  return null;
+}
+
+/** The stack of enclosing block keywords at `offset` (outermost first, "<anon>" for bare blocks). */
+export function blockStackFromParse(parse: ParseResult, offset: number): string[] {
+  return blockPathFromParse(parse, offset).map((stmt) =>
+    stmt && stmt.kind === "assignment" ? stmt.key.text : "<anon>"
+  );
+}
+
+/** As blockStackFromParse, but the enclosing statements themselves (null for bare blocks). */
+export function blockPathFromParse(parse: ParseResult, offset: number): Array<Statement | null> {
+  const hit = nodeAtOffset(parse.root, offset);
+  if (!hit) return [];
+  const path: Array<Statement | null> = [];
+  for (const stmt of hit.path) {
+    const block = childBlock(stmt);
+    // Only statements whose *block* encloses the offset contribute to the stack;
+    // the leaf statement under the cursor (a half-typed word) does not.
+    if (!block) continue;
+    if (offset <= block.openBrace) continue;
+    if (block.closeBrace !== null && offset > block.closeBrace) continue;
+    path.push(stmt.kind === "assignment" ? stmt : null);
+  }
+  return path;
+}
+
+/**
+ * Detect the completion context at `offset` from a cached parse. Walks the
+ * block stack from the innermost block outward: the first keyword classified
+ * as trigger or effect wins; transparent keywords (if/else/AND/OR/scope
+ * changes) are skipped; an unrecognized keyword yields "unknown" (never hide
+ * results when unsure).
+ */
+export function detectContextFromParse(parse: ParseResult, offset: number): ContextResult {
+  const stack = blockStackFromParse(parse, offset);
+  for (let i = stack.length - 1; i >= 0; i--) {
+    const keyword = stack[i];
+    if (keyword === "<anon>") continue;
+    const cls = classifyKeyword(keyword);
+    if (cls === "trigger" || cls === "effect" || cls === "value") return { context: cls, keyword };
+    if (cls === "transparent") continue;
+    return { context: "unknown", keyword };
+  }
+  return { context: "unknown", keyword: null };
+}
+
+/** Convenience for tests and one-off callers: parse + detect in one step. */
+export function detectContext(text: string, offset: number): ContextResult {
+  return detectContextFromParse(parseScript(text), offset);
+}