@px-lsp/server 0.1.0

package/src/games/vic3/structures.ts

@@ -0,0 +1,33 @@
+/**
+ * The Victoria 3 block-schema `structure` layer (update plan v1.1 §B2): the
+ * document shape of each definition kind, the structural keys every modder
+ * types most, which come from neither script_docs tokens nor the definition
+ * index. Without this layer, typing at a definition's top level offered only
+ * the flat engine-token soup, which is why Vic3 completion ranked far below
+ * CK3's before 0.3.2.
+ *
+ * SOURCE: fully harvested, no hand curation. scripts/build-structures-json.ts
+ * reads the 91 `*.md` schema docs Victoria 3 ships next to its data
+ * (common/buildings/buildings.md and friends, the same `key = value  # doc`
+ * shape as CK3's `_*.info`) and cross-checks every key against real depth-1
+ * usage in the vanilla corpus, which also supplies the `freq` counts that drive
+ * completion ranking and the vocabulary for the folders that ship no doc at all
+ * (events and decisions among them).
+ *
+ * Static bundled JSON on purpose: users may not have gamePath set, so nothing is
+ * harvested at runtime. Regenerate per game patch with:
+ *   node dist/build-structures-json.cjs --game vic3
+ */
+import type { KeySpec, StructureSpec } from "../../schema/types";
+import HARVESTED_JSON from "../../../data/vic3/structures.json";
+
+interface HarvestedShape {
+  sources: Record<string, string>;
+  kinds: Record<string, { topLevel: KeySpec[]; blocks?: Record<string, KeySpec[]> }>;
+}
+const HARVESTED = HARVESTED_JSON as unknown as HarvestedShape;
+
+/** Provenance shown in hover, keyed by schema kind (the doc folder's name). */
+export const VIC3_STRUCTURE_SOURCES: Record<string, string> = HARVESTED.sources;
+
+export const VIC3_STRUCTURES: Record<string, StructureSpec> = HARVESTED.kinds;

package/src/gui/anchorSpec.ts

@@ -0,0 +1,66 @@
+/**
+ * The `parentanchor` / `widgetanchor` vocabulary, and the fractions the layout
+ * engine turns it into.
+ *
+ * A dependency-free leaf like `fillGeometry.ts`, and for the same reason: the
+ * engine imports it to place widgets and the webview's anchor picker imports it
+ * to OFFER anchors. One table means the picker cannot offer a word the engine
+ * does not parse, which would write a value the game silently ignores.
+ *
+ * The engine reads a spec as `|`-separated words, in either order, and ignores
+ * anything it does not know (B1-B/C). Every word here is one the engine reads.
+ */
+
+/** The horizontal words, left to right: fraction = index / 2. */
+export const ANCHOR_X = ["left", "hcenter", "right"] as const;
+/** The vertical words, top to bottom: fraction = index / 2. */
+export const ANCHOR_Y = ["top", "vcenter", "bottom"] as const;
+/** The one word that sets BOTH axes to the middle. */
+export const ANCHOR_CENTER = "center";
+
+export type AnchorX = (typeof ANCHOR_X)[number];
+export type AnchorY = (typeof ANCHOR_Y)[number];
+
+/**
+ * `parentanchor`/`widgetanchor` -> fractional point (0 = left/top, 1 =
+ * right/bottom). An empty or unknown spec anchors at the origin, which is the
+ * engine's own default.
+ */
+export function anchorFractions(spec: string | undefined): [number, number] {
+  let fx = 0;
+  let fy = 0;
+  if (!spec) return [0, 0];
+  for (const raw of spec.toLowerCase().split("|")) {
+    const part = raw.trim();
+    if (part === ANCHOR_CENTER) {
+      fx = 0.5;
+      fy = 0.5;
+      continue;
+    }
+    const x = ANCHOR_X.indexOf(part as AnchorX);
+    if (x >= 0) {
+      fx = x / 2;
+      continue;
+    }
+    const y = ANCHOR_Y.indexOf(part as AnchorY);
+    if (y >= 0) fy = y / 2;
+  }
+  return [fx, fy];
+}
+
+/**
+ * The spec a 9-point picker writes for one cell. `center` for the middle,
+ * because the engine has that exact word and vanilla writes it; everything else
+ * is `<vertical>|<horizontal>`, the order vanilla uses (`bottom|right`), though
+ * the engine reads either.
+ */
+export function anchorSpec(x: AnchorX, y: AnchorY): string {
+  if (x === "hcenter" && y === "vcenter") return ANCHOR_CENTER;
+  return `${y}|${x}`;
+}
+
+/** The cell a written spec lands on, so a picker can show what the file says. */
+export function anchorCell(spec: string | undefined): { x: AnchorX; y: AnchorY } {
+  const [fx, fy] = anchorFractions(spec);
+  return { x: ANCHOR_X[Math.round(fx * 2)], y: ANCHOR_Y[Math.round(fy * 2)] };
+}

package/src/gui/declMarkers.ts

@@ -0,0 +1,30 @@
+/**
+ * The words that make a `.gui` statement a DECLARATION rather than a widget or
+ * a property, shared by the source model and the layout engine.
+ *
+ * A dependency-free leaf, like `fillGeometry.ts`, and for the same reason: the
+ * writer's reorder/insert/delete sibling list (`GuiBody.children`) and the
+ * engine's `srcIndex` for a laid-out node have to count the SAME entries. Two
+ * copies of this set would drift, and the drift would show up as a reorder
+ * moving the wrong block.
+ *
+ * No `vscode` imports: unit-tested in plain Node.
+ */
+
+/** Marker words that turn the FOLLOWING assignment into a declaration. */
+export const DECL_MARKERS = new Set([
+  "template",
+  "local_template",
+  "types",
+  "type",
+  "block",
+  "blockoverride",
+]);
+
+/**
+ * Named slots, which vanilla spells two ways: `blockoverride "name" { ... }`
+ * (272 uses in the game tree, the marker form) and `blockoverride = "name"
+ * { ... }` (29 uses, one assignment whose value is a tagged block). Both are
+ * declarations, so both count as one sibling.
+ */
+export const SLOT_KEYS = new Set(["block", "blockoverride"]);

package/src/gui/fillGeometry.ts

@@ -0,0 +1,101 @@
+/**
+ * Sprite fill geometry: nine-slice regions and frame-sheet cells. Deterministic
+ * arithmetic over a rect plus the source texture's pixel size, with no engine
+ * state behind it, which is why it lives in its own dependency-free leaf module:
+ * the layout engine re-exports it, and the webview GUI editor bundles it
+ * DIRECTLY into the canvas renderer. One implementation means the drawn pixels
+ * cannot drift from the measured rules (parity-checklist.md L21a-d, L22).
+ */
+
+/** The destination rect a fill covers; structurally LayoutRect. */
+export interface FillRect {
+  x: number;
+  y: number;
+  w: number;
+  h: number;
+}
+
+/**
+ * Nine-slice (corneredtiled/corneredstretched) region layout: corners drawn
+ * 1:1, edges stretched on one axis, center on both. Pure deterministic
+ * geometry — border widths come from the .gui `spriteborder` attributes and
+ * the source texture's own pixel size. Returns 9 src->dst blits in row-major
+ * order (TL, T, TR, L, C, R, BL, B, BR); zero-area slices are dropped.
+ */
+export interface NineSliceRegion {
+  sx: number;
+  sy: number;
+  sw: number;
+  sh: number;
+  dx: number;
+  dy: number;
+  dw: number;
+  dh: number;
+}
+export function computeNineSlice(
+  rect: FillRect,
+  border: [number, number, number, number],
+  texW: number,
+  texH: number
+): NineSliceRegion[] {
+  // Clamp borders so opposite sides never overlap on a small texture or rect.
+  const bl = Math.max(0, Math.min(border[0], texW, rect.w));
+  const bt = Math.max(0, Math.min(border[1], texH, rect.h));
+  const br = Math.max(0, Math.min(border[2], texW - bl, rect.w - bl));
+  const bb = Math.max(0, Math.min(border[3], texH - bt, rect.h - bt));
+  // Source and destination column/row spans: [start, size] triples.
+  const sCols: [number, number][] = [
+    [0, bl],
+    [bl, texW - bl - br],
+    [texW - br, br],
+  ];
+  const sRows: [number, number][] = [
+    [0, bt],
+    [bt, texH - bt - bb],
+    [texH - bb, bb],
+  ];
+  const dCols: [number, number][] = [
+    [rect.x, bl],
+    [rect.x + bl, rect.w - bl - br],
+    [rect.x + rect.w - br, br],
+  ];
+  const dRows: [number, number][] = [
+    [rect.y, bt],
+    [rect.y + bt, rect.h - bt - bb],
+    [rect.y + rect.h - bb, bb],
+  ];
+  const out: NineSliceRegion[] = [];
+  for (let r = 0; r < 3; r++) {
+    for (let c = 0; c < 3; c++) {
+      const [sx, sw] = sCols[c];
+      const [sy, sh] = sRows[r];
+      const [dx, dw] = dCols[c];
+      const [dy, dh] = dRows[r];
+      if (sw <= 0 || sh <= 0 || dw <= 0 || dh <= 0) continue;
+      out.push({ sx, sy, sw, sh, dx, dy, dw, dh });
+    }
+  }
+  return out;
+}
+
+/**
+ * Frame-sheet cell for `framesize = { w h }` + `frame = N`: the texture is a
+ * cols x rows GRID indexed ROW-MAJOR and 1-based, so frame 4 on a 3-wide sheet
+ * is the first cell of the SECOND row, not a fourth column. `frame <= 0`
+ * clamps to the first cell, a frame past the last clamps to the last.
+ * (Studio §L, in-game 2026-07-17; L22.) Deterministic geometry like
+ * computeNineSlice: the texture's pixel size comes from the renderer.
+ */
+export function computeFrameCell(
+  framesize: [number, number],
+  frame: number,
+  texW: number,
+  texH: number
+): { sx: number; sy: number; sw: number; sh: number } {
+  const [fw, fh] = framesize;
+  if (fw <= 0 || fh <= 0) return { sx: 0, sy: 0, sw: texW, sh: texH };
+  const cols = Math.max(1, Math.floor(texW / fw));
+  const rows = Math.max(1, Math.floor(texH / fh));
+  const index = Math.min(Math.max(Math.floor(frame) - 1, 0), cols * rows - 1);
+  return { sx: (index % cols) * fw, sy: Math.floor(index / cols) * fh, sw: fw, sh: fh };
+}

package/src/gui/guiDefs.ts

@@ -0,0 +1,386 @@
+/**
+ * PdxGui reuse-vocabulary store: `template` / `local_template` property
+ * snippets (spliced via `using = Name`) and `types Group { type name = base
+ * {...} }` widget classes, collected across files with the gui/ override
+ * rule: FIOS, the FIRST definition wins (opposite of script's LIOS; see
+ * AGENTS.md).
+ *
+ * The layout engine consumes this store to expand instances; collection is
+ * separate so callers control the file set and order (vanilla + mod).
+ *
+ * No `vscode` imports: unit-tested in plain Node.
+ */
+import { LineIndex, parseScript, type BlockNode, type Statement } from "../parser";
+
+export interface GuiTypeDef {
+  /** The base widget/type key after `=`, e.g. `textbox` in `type text_single = textbox {}`. */
+  base: string;
+  block: BlockNode;
+  /**
+   * Offset of the declared NAME token in the text this def was collected from.
+   * Always present (unlike `line`, which needs a file path), so a caller
+   * holding the same text can turn a declaration back into a position.
+   */
+  keyOffset: number;
+  /** Declaration site, present when the collector was given a file path. */
+  file?: string;
+  line?: number;
+}
+
+export interface GuiTemplateDef {
+  block: BlockNode;
+  /** local_template: valid only inside its defining file; mergeGuiDefs skips it. */
+  local: boolean;
+  /** Declaration site, present when the collector was given a file path. */
+  file?: string;
+  line?: number;
+}
+
+export interface GuiDefs {
+  types: Map<string, GuiTypeDef>;
+  templates: Map<string, GuiTemplateDef>;
+}
+
+export function emptyGuiDefs(): GuiDefs {
+  return { types: new Map(), templates: new Map() };
+}
+
+const DECL_MARKERS = new Set(["template", "local_template", "types", "type"]);
+
+/**
+ * Collect one file's declarations (including its local_templates). Pass `file`
+ * to record each declaration's site (file + line) for navigation features.
+ */
+export function collectGuiDefs(text: string, into?: GuiDefs, file?: string): GuiDefs {
+  const lines = file !== undefined ? new LineIndex(text) : null;
+  return collectGuiDefsParsed(parseScript(text).root.statements, into, file, lines);
+}
+
+/** Same as collectGuiDefs but over an already-parsed tree (parseCache reuse). */
+export function collectGuiDefsParsed(
+  statements: Statement[],
+  into?: GuiDefs,
+  file?: string,
+  lines?: LineIndex | null
+): GuiDefs {
+  const defs = into ?? emptyGuiDefs();
+  collectFrom(statements, defs, false, file, lines);
+  return defs;
+}
+
+function collectFrom(
+  statements: Statement[],
+  defs: GuiDefs,
+  insideTypes: boolean,
+  file?: string,
+  lines?: LineIndex | null
+): void {
+  let pending: string | null = null;
+  const siteOf = (offset: number): { file?: string; line?: number } =>
+    file !== undefined && lines ? { file, line: lines.positionAt(offset).line } : {};
+  for (const stmt of statements) {
+    if (stmt.kind === "value") {
+      if (stmt.value.kind === "scalar" && DECL_MARKERS.has(stmt.value.text.toLowerCase())) {
+        pending = stmt.value.text.toLowerCase();
+      } else {
+        pending = null;
+      }
+      continue;
+    }
+    // assignment
+    const marker = pending;
+    pending = null;
+    if (!marker && !insideTypes) continue;
+    const name = stmt.key.text;
+    if (marker === "template" || marker === "local_template") {
+      if (stmt.value?.kind === "block" && !defs.templates.has(name)) {
+        defs.templates.set(name, {
+          block: stmt.value,
+          local: marker === "local_template",
+          ...siteOf(stmt.key.range.start),
+        });
+      }
+    } else if (marker === "types") {
+      if (stmt.value?.kind === "block") {
+        collectFrom(stmt.value.statements, defs, true, file, lines);
+      }
+    } else if (marker === "type" || insideTypes) {
+      // `type name = base { ... }` parses as name = tagged-block(base).
+      // Type names are stored lowercase (widget keys are matched
+      // case-insensitively); template names stay exact-case like `using` refs.
+      const lower = name.toLowerCase();
+      if (stmt.value?.kind === "tagged-block" && !defs.types.has(lower)) {
+        defs.types.set(lower, {
+          base: stmt.value.tag.text,
+          block: stmt.value.block,
+          keyOffset: stmt.key.range.start,
+          ...siteOf(stmt.key.range.start),
+        });
+      }
+    }
+  }
+}
+
+/**
+ * Merge `source` into `target` under FIOS: existing (earlier-file) entries
+ * win, and local_templates never cross files. Call in game load order
+ * (path-sorted file list).
+ */
+export function mergeGuiDefs(target: GuiDefs, source: GuiDefs): void {
+  for (const [name, def] of source.types) {
+    if (!target.types.has(name)) target.types.set(name, def);
+  }
+  for (const [name, def] of source.templates) {
+    if (!def.local && !target.templates.has(name)) target.templates.set(name, def);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Expansion
+// ---------------------------------------------------------------------------
+
+/** Guards recursive templates/types (a self-referencing type hard-crashes the game). */
+const MAX_DEPTH = 32;
+
+/** One step of the chain a statement was spliced through (innermost first). */
+export interface GuiOriginStep {
+  kind: "type" | "template";
+  name: string;
+}
+
+/** An expanded statement plus where it came from ([] = the instance's own body). */
+export interface OriginedStatement {
+  stmt: Statement;
+  origin: GuiOriginStep[];
+}
+
+/**
+ * Resolve a widget key's type chain and produce the effective statement list:
+ * base-most type first, derived types after, instance statements last (so
+ * later statements override scalar props and draw on top). `using =`
+ * template references are spliced inline at their position.
+ */
+export function expandWidget(
+  key: string,
+  instance: BlockNode,
+  defs: GuiDefs,
+  /** Skip the type chain (recursion guard) but still splice templates. */
+  skipChain = false
+): { baseKey: string; statements: Statement[] } {
+  const expanded = expandWidgetWithOrigins(key, instance, defs, skipChain);
+  return { baseKey: expanded.baseKey, statements: expanded.statements.map((s) => s.stmt) };
+}
+
+/**
+ * {@link expandWidget} with provenance: the same expansion, each statement
+ * labelled with the definitions it was spliced through. The inspector reads
+ * this so a property row can say where its value came from, and it goes through
+ * the one expansion the engine itself uses rather than a second walk that could
+ * disagree with the rendering.
+ */
+export function expandWidgetWithOrigins(
+  key: string,
+  instance: BlockNode,
+  defs: GuiDefs,
+  skipChain = false
+): { baseKey: string; statements: OriginedStatement[] } {
+  const chain: { block: BlockNode; origin: GuiOriginStep[] }[] = [];
+  let base = key.toLowerCase();
+  const seen = new Set<string>();
+  while (!skipChain && defs.types.has(base) && !seen.has(base)) {
+    seen.add(base);
+    const def = defs.types.get(base)!;
+    chain.unshift({ block: def.block, origin: [{ kind: "type", name: base }] });
+    base = def.base.toLowerCase();
+  }
+  const statements: OriginedStatement[] = [];
+  for (const entry of chain) spliceTemplates(entry.block.statements, defs, statements, 0, entry.origin);
+  spliceTemplates(instance.statements, defs, statements, 0, []);
+  return { baseKey: base, statements };
+}
+
+function spliceTemplates(
+  statements: Statement[],
+  defs: GuiDefs,
+  out: OriginedStatement[],
+  depth: number,
+  origin: GuiOriginStep[]
+): void {
+  if (depth > MAX_DEPTH) return;
+  for (const stmt of statements) {
+    if (
+      stmt.kind === "assignment" &&
+      stmt.key.text.toLowerCase() === "using" &&
+      stmt.value?.kind === "scalar"
+    ) {
+      const name = stmt.value.text;
+      const tpl = defs.templates.get(name);
+      if (tpl) {
+        spliceTemplates(tpl.block.statements, defs, out, depth + 1, [{ kind: "template", name }, ...origin]);
+        continue;
+      }
+      // Unknown template: keep the statement (the game logs one error and
+      // renders nothing for it; downstream treats it as an inert property).
+    }
+    out.push({ stmt, origin });
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Navigation helpers (go-to-definition, hover)
+// ---------------------------------------------------------------------------
+
+/** A resolved template/type declaration plus what it is. */
+export interface ResolvedGuiDef {
+  kind: "template" | "type";
+  name: string;
+  def: GuiTypeDef | GuiTemplateDef;
+}
+
+/**
+ * Resolve a name against an ordered list of def stores (current document
+ * first, then the cross-file FIOS store). Templates match exact-case (like
+ * `using =` references); types match lowercased (like widget keys).
+ */
+export function resolveGuiDef(name: string, sources: GuiDefs[]): ResolvedGuiDef | null {
+  for (const defs of sources) {
+    const tpl = defs.templates.get(name);
+    if (tpl) return { kind: "template", name, def: tpl };
+  }
+  const lower = name.toLowerCase();
+  for (const defs of sources) {
+    const type = defs.types.get(lower);
+    if (type) return { kind: "type", name: lower, def: type };
+  }
+  return null;
+}
+
+/** A `block "name"` site inside a template/type body (offset is into `file`'s text). */
+export interface GuiBlockSite {
+  name: string;
+  file?: string;
+  offset: number;
+}
+
+/**
+ * All block names a widget built from `root` can override with
+ * `blockoverride "name"`: `block` declarations in the body itself, in
+ * templates spliced via `using =` (recursively), and, for types, up the
+ * base-type chain. First site found per name wins (derived-most, matching
+ * FIOS spirit); `blockoverride` declarations inside templates re-expose the
+ * same name and count too.
+ */
+export function collectOverridableBlocks(
+  root: ResolvedGuiDef,
+  sources: GuiDefs[]
+): Map<string, GuiBlockSite> {
+  const out = new Map<string, GuiBlockSite>();
+  const seen = new Set<string>();
+  const walk = (statements: Statement[], file: string | undefined, depth: number): void => {
+    if (depth > MAX_DEPTH) return;
+    let pending = false;
+    for (const stmt of statements) {
+      if (stmt.kind === "value") {
+        pending =
+          stmt.value.kind === "scalar" &&
+          (stmt.value.text.toLowerCase() === "block" || stmt.value.text.toLowerCase() === "blockoverride");
+        continue;
+      }
+      const wasBlockDecl = pending;
+      pending = false;
+      if (wasBlockDecl && stmt.value?.kind === "block") {
+        if (!out.has(stmt.key.text)) {
+          out.set(stmt.key.text, { name: stmt.key.text, file, offset: stmt.key.range.start });
+        }
+        // Blocks nest (a block's body can declare further blocks).
+        walk(stmt.value.statements, file, depth + 1);
+        continue;
+      }
+      if (
+        stmt.kind === "assignment" &&
+        stmt.key.text.toLowerCase() === "using" &&
+        stmt.value?.kind === "scalar"
+      ) {
+        const tplName = stmt.value.text;
+        if (!seen.has(`t:${tplName}`)) {
+          seen.add(`t:${tplName}`);
+          for (const defs of sources) {
+            const tpl = defs.templates.get(tplName);
+            if (tpl) {
+              walk(tpl.block.statements, tpl.file, depth + 1);
+              break;
+            }
+          }
+        }
+        continue;
+      }
+      const inner = stmt.value;
+      if (inner?.kind === "block") walk(inner.statements, file, depth + 1);
+      else if (inner?.kind === "tagged-block") walk(inner.block.statements, file, depth + 1);
+    }
+  };
+
+  walk(root.def.block.statements, root.def.file, 0);
+  if (root.kind === "type") {
+    let base = (root.def as GuiTypeDef).base.toLowerCase();
+    let depth = 0;
+    while (depth++ < MAX_DEPTH && !seen.has(`y:${base}`)) {
+      seen.add(`y:${base}`);
+      let next: GuiTypeDef | null = null;
+      for (const defs of sources) {
+        const t = defs.types.get(base);
+        if (t) {
+          next = t;
+          break;
+        }
+      }
+      if (!next) break;
+      walk(next.block.statements, next.file, 0);
+      base = next.base.toLowerCase();
+    }
+  }
+  return out;
+}
+
+/** The base-type chain of a type, derived-first (for hover display). */
+export function typeBaseChain(name: string, sources: GuiDefs[]): string[] {
+  const chain: string[] = [];
+  let base = name.toLowerCase();
+  const seen = new Set<string>();
+  while (!seen.has(base) && chain.length <= MAX_DEPTH) {
+    seen.add(base);
+    let def: GuiTypeDef | null = null;
+    for (const defs of sources) {
+      const t = defs.types.get(base);
+      if (t) {
+        def = t;
+        break;
+      }
+    }
+    if (!def) break;
+    chain.push(def.base);
+    base = def.base.toLowerCase();
+  }
+  return chain;
+}
+
+/**
+ * Scan an expanded statement list for `blockoverride "name" { ... }` pairs.
+ * Later declarations win (instance statements come after type statements in
+ * expandWidget order, so instance overrides beat type-internal ones).
+ */
+export function collectBlockOverrides(statements: Statement[]): Map<string, BlockNode> {
+  const overrides = new Map<string, BlockNode>();
+  let pending = false;
+  for (const stmt of statements) {
+    if (stmt.kind === "value") {
+      pending = stmt.value.kind === "scalar" && stmt.value.text.toLowerCase() === "blockoverride";
+      continue;
+    }
+    if (pending && stmt.value?.kind === "block") {
+      overrides.set(stmt.key.text, stmt.value);
+    }
+    pending = false;
+  }
+  return overrides;
+}