@px-lsp/server 0.1.0

package/src/gui/layoutService.ts

@@ -0,0 +1,221 @@
+/**
+ * paradox/guiLayout request backend: lazily builds the cross-file template/type
+ * store from the vanilla + mod gui trees (FIOS: path-sorted, first definition
+ * wins; a mod file replaces the vanilla file at the same relative path), then
+ * runs the measured layout engine over the requested document.
+ *
+ * The store build costs ~200ms over the full vanilla tree and is cached per
+ * (gamePath, modPath) pair; mod .gui edits re-collect only the mod side.
+ */
+import * as fs from "fs";
+import * as path from "path";
+import type { GuiLayoutNode, GuiLayoutResult, GuiVisibilityOptions } from "@px-lsp/protocol/protocol";
+import { collectGuiDefs, emptyGuiDefs, mergeGuiDefs, type GuiDefs } from "./guiDefs";
+import {
+  calibratedMeasurer,
+  computeGuiLayout,
+  measurerFromMetrics,
+  type LayoutEnv,
+  type LayoutNode,
+  type LayoutTiming,
+  type VisibilityCheck,
+} from "./layoutEngine";
+import { collectScriptedGuiCalls, emptyGuiScriptLinks, type GuiScriptLinks } from "./guiLinks";
+import { activeProfile } from "../games/active";
+
+/**
+ * The active game's measured layout environment, when its profile carries
+ * probe results (GameProfile.guiTextMetrics / guiLayoutQuirks); undefined
+ * falls back to the engine's calibrated defaults.
+ */
+export function profileMeasurer(): LayoutEnv | undefined {
+  const { guiTextMetrics, guiLayoutQuirks } = activeProfile();
+  if (!guiTextMetrics && !guiLayoutQuirks) return undefined;
+  const base = guiTextMetrics ? measurerFromMetrics(guiTextMetrics) : calibratedMeasurer;
+  return { ...base, ...guiLayoutQuirks };
+}
+
+/** Matches the game's UI reference resolution at 100% scaling. */
+export const VIEWPORT = { w: 1920, h: 1080 };
+
+let cache: { key: string; defs: GuiDefs; files: number; links: GuiScriptLinks } | null = null;
+
+/**
+ * Per-file parse results, keyed by absolute path and kept across store
+ * rebuilds. A store rebuild used to re-read and re-parse every .gui of the
+ * game (about a thousand files) whenever ONE mod .gui was saved, which is
+ * exactly what autosave does after every editor gesture; now a rebuild
+ * re-parses only the files whose mtime moved and re-merges the rest.
+ */
+const fileCache = new Map<string, { mtimeMs: number; defs: GuiDefs; text: string }>();
+
+/**
+ * Observer of a cold store build, so the server can report the phase without
+ * this module knowing about the connection. Absent = nobody is watching.
+ */
+let onBuild: ((state: "start" | "done") => void) | null = null;
+
+export function observeGuiStoreBuild(fn: ((state: "start" | "done") => void) | null): void {
+  onBuild = fn;
+}
+
+function listGuiFiles(root: string): Map<string, string> {
+  // relative path (lowercased, forward slashes) -> absolute path
+  const out = new Map<string, string>();
+  const walk = (dir: string): void => {
+    let entries: fs.Dirent[];
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const e of entries) {
+      const p = path.join(dir, e.name);
+      if (e.isDirectory()) walk(p);
+      else if (e.name.toLowerCase().endsWith(".gui")) {
+        out.set(path.relative(root, p).toLowerCase().replace(/\\/g, "/"), p);
+      }
+    }
+  };
+  walk(root);
+  return out;
+}
+
+function buildStore(
+  gamePath: string | null,
+  modPath: string | null,
+  parentPaths: string[],
+  engineRoots: string[]
+): { defs: GuiDefs; files: number; links: GuiScriptLinks } {
+  // The stage prefix is part of the key: switching game changes which folder of
+  // the same roots the store was built from.
+  const stage = activeProfile().stageRoots?.[0] ?? "";
+  const key = `${stage}|${engineRoots.join(";")}|${gamePath ?? ""}|${parentPaths.join(";")}|${modPath ?? ""}`;
+  if (cache) {
+    if (cache.key === key) return cache;
+    cache = null;
+  }
+
+  // Effective file set: later roots win the same relative path (whole-file
+  // replacement) — engine (jomini), vanilla, parent mods in load order, then the
+  // mod — and FIOS applies across the sorted result.
+  const effective = new Map<string, string>();
+  // Content roots of a game with load-stage folders carry the stage prefix
+  // (`in_game/gui/`); the engine layer next to the install never does, since it
+  // is shared by every stage.
+  const stagePrefix = stage ? [stage] : [];
+  for (const root of engineRoots) {
+    for (const [rel, abs] of listGuiFiles(path.join(root, "gui"))) effective.set(rel, abs);
+  }
+  for (const root of [gamePath, ...parentPaths, modPath]) {
+    if (!root) continue;
+    for (const [rel, abs] of listGuiFiles(path.join(root, ...stagePrefix, "gui"))) effective.set(rel, abs);
+  }
+  onBuild?.("start");
+  const defs = emptyGuiDefs();
+  const links = emptyGuiScriptLinks();
+  let files = 0;
+  const seen = new Set<string>();
+  for (const rel of [...effective.keys()].sort()) {
+    const abs = effective.get(rel)!;
+    try {
+      const mtimeMs = fs.statSync(abs).mtimeMs;
+      let entry = fileCache.get(abs);
+      if (!entry || entry.mtimeMs !== mtimeMs) {
+        const text = fs.readFileSync(abs, "utf8");
+        entry = { mtimeMs, defs: collectGuiDefs(text, undefined, abs), text };
+        fileCache.set(abs, entry);
+      }
+      seen.add(abs);
+      mergeGuiDefs(defs, entry.defs);
+      // Piggybacked on the one pass that already reads every .gui file: the
+      // scripted_gui call scan is a substring test on all but the few files
+      // that hold one, so the link index is effectively free here and a
+      // second walk of the tree would not be.
+      collectScriptedGuiCalls(entry.text, abs, links);
+      files++;
+    } catch {
+      /* unreadable file: skip */
+    }
+  }
+  // A file that left the effective set (deleted, or shadowed by another root) drops out.
+  for (const abs of fileCache.keys()) if (!seen.has(abs)) fileCache.delete(abs);
+  cache = { key, defs, files, links };
+  onBuild?.("done");
+  return cache;
+}
+
+/** The cross-file template/type store (cached), for navigation and hover. */
+export function getGuiDefs(
+  gamePath: string | null,
+  modPath: string | null,
+  parentPaths: string[] = [],
+  engineRoots: string[] = []
+): GuiDefs {
+  return buildStore(gamePath, modPath, parentPaths, engineRoots).defs;
+}
+
+/** The cross-file `GetScriptedGui(...)` call index (cached with the store). */
+export function getGuiScriptLinks(
+  gamePath: string | null,
+  modPath: string | null,
+  parentPaths: string[] = [],
+  engineRoots: string[] = []
+): GuiScriptLinks {
+  return buildStore(gamePath, modPath, parentPaths, engineRoots).links;
+}
+
+/** Drop the cached store (mod .gui saved, settings changed). */
+export function invalidateGuiDefsCache(): void {
+  cache = null;
+}
+
+export function computeGuiLayoutResult(
+  text: string,
+  gamePath: string | null,
+  modPath: string | null,
+  parentPaths: string[] = [],
+  engineRoots: string[] = [],
+  visibility?: GuiVisibilityOptions,
+  /** Loc/datafunction resolution for textboxes; absent = raw `text =` values. */
+  resolveText?: LayoutEnv["resolveText"]
+): GuiLayoutResult {
+  const t0 = performance.now();
+  const { defs, files } = buildStore(gamePath, modPath, parentPaths, engineRoots);
+  const defsMs = performance.now() - t0;
+  const checks = new Map<string, VisibilityCheck>();
+  const timing: LayoutTiming = { parseMs: 0, layoutMs: 0 };
+  const nodes = computeGuiLayout(text, {
+    defs,
+    viewport: VIEWPORT,
+    visibility,
+    checks,
+    timing,
+    measurer: resolveText ? { ...(profileMeasurer() ?? calibratedMeasurer), resolveText } : profileMeasurer(),
+  });
+  const textures = new Set<string>();
+  let nodeCount = 0;
+  const visit = (n: LayoutNode): void => {
+    nodeCount++;
+    if (n.bg?.texture) textures.add(n.bg.texture);
+    if (n.fill?.texture) textures.add(n.fill.texture);
+    if (n.bg?.mask) textures.add(n.bg.mask);
+    if (n.fill?.mask) textures.add(n.fill.mask);
+    for (const c of n.children) visit(c);
+  };
+  for (const n of nodes) visit(n);
+  return {
+    // LayoutNode is structurally identical to the wire type.
+    nodes: nodes as unknown as GuiLayoutNode[],
+    textures: [...textures].sort(),
+    nodeCount,
+    defsFiles: files,
+    visibilityChecks: [...checks.values()].sort((a, b) => a.key.localeCompare(b.key)),
+    timings: {
+      parseMs: timing.parseMs,
+      defsMs,
+      layoutMs: timing.layoutMs,
+      totalMs: performance.now() - t0,
+    },
+  };
+}

package/src/gui/measuredMetrics.ts

@@ -0,0 +1,21 @@
+/**
+ * Text metrics measured in-game for Gitan-Regular (StandardGameFont) at
+ * fontsize 15, probe batches 01-03 (docs/gui-designer/calibration/probes/).
+ *
+ * They serve twice: as the measured table of the profile whose font this is,
+ * and as the layout engine's assumption for a game whose own probe has not run
+ * yet. That is why they sit in their own module: a game's meta reads them, and
+ * the engine may not import a game profile (the games/ -> gui/ direction only).
+ */
+import type { GuiTextMetrics } from "./layoutEngine";
+
+export const GITAN_MEASURED_METRICS: GuiTextMetrics = {
+  baseFontsize: 15,
+  lineHeight: 21, // B1-G
+  glyphs: {
+    M: { adv: 14, ink: 13 }, // B1-G, B2-L
+    i: { adv: 4, ink: 4 }, // B1-G, B2-L
+    " ": { adv: 4, ink: 0 }, // B3-S2
+  },
+  defaultGlyph: { adv: 9, ink: 8 }, // unmeasured average guess
+};

package/src/gui/previewService.ts

@@ -0,0 +1,89 @@
+/**
+ * `paradox/guiPreview`: one laid-out instance per palette entry, for a
+ * library tile. The synthetic document keeps the requested document's own
+ * declarations (template / local_template / types / type) and adds a single
+ * root instance:
+ *
+ *   type or builtin  ->  `<name> = { }`
+ *   template         ->  `widget = { using = <name> }`
+ *   raw              ->  the fragment verbatim (a saved component)
+ *
+ * Layout goes through computeGuiLayout with the same store the canvas uses,
+ * so a tile shows what inserting the entry would show. No vscode, no fs.
+ */
+import type { GuiLayoutNode, GuiPreview, GuiPreviewEntry } from "@px-lsp/protocol/protocol";
+import { parseScript } from "../parser";
+import { computeGuiLayout, type LayoutEnv, type LayoutNode } from "./layoutEngine";
+import type { GuiDefs } from "./guiDefs";
+import { DECL_MARKERS } from "./declMarkers";
+import { VIEWPORT } from "./layoutService";
+
+/** The document's declarations, verbatim, so local templates and types resolve in the synthetic doc. */
+export function declarationsOf(text: string): string {
+  const { root } = parseScript(text);
+  const parts: string[] = [];
+  // `template name { }` parses as a bare `template` word followed by the
+  // `name { }` assignment; keep both, verbatim, the way the engine reads them.
+  let marker: { start: number } | null = null;
+  for (const s of root.statements) {
+    if (s.kind === "value") {
+      marker =
+        s.value.kind === "scalar" && DECL_MARKERS.has(s.value.text.toLowerCase())
+          ? { start: s.range.start }
+          : null;
+      continue;
+    }
+    if (marker) parts.push(text.slice(marker.start, s.range.end));
+    marker = null;
+  }
+  return parts.join("\n");
+}
+
+function instanceFor(entry: GuiPreviewEntry): string | null {
+  switch (entry.kind) {
+    case "type":
+    case "builtin":
+      return /^[A-Za-z_][\w.]*$/.test(entry.name) ? `${entry.name} = {\n}` : null;
+    case "template":
+      return /^[A-Za-z_][\w.]*$/.test(entry.name) ? `widget = {\n\tusing = ${entry.name}\n}` : null;
+    case "raw":
+      return entry.fragment?.trim() ? entry.fragment : null;
+  }
+}
+
+export function previewEntries(
+  text: string,
+  entries: GuiPreviewEntry[],
+  defs: GuiDefs,
+  measurer: LayoutEnv | undefined
+): GuiPreview[] {
+  const decls = declarationsOf(text);
+  return entries.map((entry) => {
+    const instance = instanceFor(entry);
+    if (!instance) return { name: entry.name, node: null, textures: [], reason: "nothing to lay out" };
+    let nodes: LayoutNode[];
+    try {
+      nodes = computeGuiLayout(`${decls}\n${instance}\n`, { defs, viewport: VIEWPORT, measurer });
+    } catch (err) {
+      return {
+        name: entry.name,
+        node: null,
+        textures: [],
+        reason: err instanceof Error ? err.message : String(err),
+      };
+    }
+    const node = nodes[0];
+    if (!node) return { name: entry.name, node: null, textures: [], reason: "the store has no such widget" };
+    if (node.rect.w <= 0 || node.rect.h <= 0) {
+      return { name: entry.name, node: null, textures: [], reason: "zero size without a parent" };
+    }
+    const textures = new Set<string>();
+    const visit = (n: LayoutNode): void => {
+      if (n.bg?.texture) textures.add(n.bg.texture);
+      if (n.fill?.texture) textures.add(n.fill.texture);
+      for (const c of n.children) visit(c);
+    };
+    visit(node);
+    return { name: entry.name, node: node as unknown as GuiLayoutNode, textures: [...textures].sort() };
+  });
+}

package/src/gui/saveSchema.ts

@@ -0,0 +1,220 @@
+/**
+ * The shape of a save game, as data: which meta keys name the campaign and its
+ * date, where the entities a preview needs sit, and which datafunction chain
+ * shows which field. A game profile carries one (`GameProfile.saveSchema`,
+ * built in games/<id>/saveSchema.ts); the reader (saveValues.ts) stays generic
+ * over it and names no game.
+ *
+ * The small readers a mapping table needs live here too, so a profile's table
+ * can be plain data sitting next to that game's other tables.
+ *
+ * Pure: parsed blocks in, display text out. No fs, no vscode.
+ */
+import type { BlockNode, Statement } from "../parser";
+
+/** The blocks a preview reads, cut out of the save. */
+export interface SaveEntities {
+  /** The save's meta block. */
+  meta?: BlockNode;
+  /** The played country's entry, for a game whose player runs one. */
+  country?: BlockNode;
+  /** The played country's ruler. */
+  ruler?: BlockNode;
+  /** The played country's heir. */
+  heir?: BlockNode;
+  /** The played country's capital. */
+  capital?: BlockNode;
+  /** The played character's own record, for a game whose player IS a character. */
+  character?: BlockNode;
+}
+
+/** Everything the readers may look at. An absent field means the save had none. */
+export interface SaveContext extends SaveEntities {
+  /** The country's tag (`GBR`), when the save names its entries by one. */
+  tag?: string;
+  /** The save's date, formatted. */
+  date?: string;
+  loc: (key: string) => string | undefined;
+}
+
+export interface ValueMapping {
+  /** Every chain (bracket-free) that shows this value. */
+  chains: string[];
+  read: (ctx: SaveContext) => string | undefined;
+}
+
+/** The entity slots a country entry points at, filled from its own registry. */
+export type SaveSlot = "ruler" | "heir" | "capital";
+
+/** One id a country entry holds, and the registry that id is looked up in. */
+export interface SaveLink {
+  slot: SaveSlot;
+  /** Key on the country entry holding the id. */
+  key: string;
+  /** Top-level registry block the entry lives in. */
+  block: string;
+}
+
+/**
+ * A save that keeps its entities in top-level registries, each an id-keyed
+ * table under one sub-block (`<block>.<entries>.<id>`). The played country is
+ * the entry whose tag localizes to the campaign name the meta states, and its
+ * own fields say which ids the later registries are searched for — which is why
+ * one pass in file order answers everything.
+ */
+export interface SaveRegistry {
+  /** Sub-block each registry keeps its entries under (`database`). */
+  entries: string;
+  /** Registry holding the country entries, one of which is the player's. */
+  countryBlock: string;
+  /** Country-entry key naming it; matched, through loc, against the meta name. */
+  tagKey: string;
+  /** Country-entry key marking a playable country, used when no name matched. */
+  mainKey: string;
+  links: SaveLink[];
+}
+
+/**
+ * A save whose player is a character named at the very END of the file, long
+ * after the record a preview wants. Finding the id costs a cheap chunk scan for
+ * the marker before the streaming pass that cuts the record out.
+ */
+export interface SavePlayerRecord {
+  /** Line-start marker opening the block that names the played record. */
+  marker: string;
+  /** Key inside that block holding the record's id. */
+  idKey: string;
+  /** Top-level block whose `<id>` entry is the played record. */
+  block: string;
+}
+
+/** How one game's saves are read. */
+export interface SaveSchema {
+  /** Meta key holding the save's date. Absent = `game_date`. */
+  dateKey?: string;
+  /** Meta key holding the campaign or player name. Absent = `name`. */
+  nameKey?: string;
+  /** The curated chain -> value table. */
+  mappings: ValueMapping[];
+  /**
+   * Chains the save's own contents name rather than the table (a character's
+   * stored variables), read per save. Absent = the table is all there is.
+   */
+  expand?: (ctx: SaveContext) => Record<string, string>;
+  /** Set when the save keeps its entities in id-keyed registries. */
+  registry?: SaveRegistry;
+  /** Set when the played character is named at the end of the save. */
+  record?: SavePlayerRecord;
+}
+
+// ---------------------------------------------------------------------------
+// The readers a mapping table is written with
+// ---------------------------------------------------------------------------
+
+export function statements(node: BlockNode | undefined): Statement[] {
+  return node?.statements ?? [];
+}
+
+/** The scalar value of `key` in a block. */
+export function scalar(node: BlockNode | undefined, key: string): string | undefined {
+  for (const s of statements(node)) {
+    if (s.kind === "assignment" && s.key.text === key && s.value?.kind === "scalar") {
+      return s.value.text;
+    }
+  }
+  return undefined;
+}
+
+/** The block value of `key` in a block. */
+export function block(node: BlockNode | undefined, key: string): BlockNode | undefined {
+  for (const s of statements(node)) {
+    if (s.kind === "assignment" && s.key.text === key && s.value?.kind === "block") {
+      return s.value;
+    }
+  }
+  return undefined;
+}
+
+/** A name is either literal text or a loc key; a key that resolves wins. */
+export function named(ctx: SaveContext, raw: string | undefined): string | undefined {
+  if (!raw) return undefined;
+  return /^[A-Za-z0-9_.]+$/.test(raw) ? (ctx.loc(raw) ?? raw) : raw;
+}
+
+/** `1247181.89015` -> `1,247,182`: money shows whole and grouped. */
+export function thousands(raw: string | undefined): string | undefined {
+  const n = raw === undefined ? NaN : Number(raw);
+  if (!Number.isFinite(n)) return undefined;
+  return Math.round(n)
+    .toString()
+    .replace(/\B(?=(\d{3})+(?!\d))/g, ",");
+}
+
+const MONTHS = [
+  "January",
+  "February",
+  "March",
+  "April",
+  "May",
+  "June",
+  "July",
+  "August",
+  "September",
+  "October",
+  "November",
+  "December",
+];
+
+/** `1836.1.21` -> `[1836, 1, 21]`; anything else is not a date. */
+function parseDate(raw: string | undefined): [number, number, number] | undefined {
+  const m = raw === undefined ? null : /^(\d+)\.(\d+)\.(\d+)/.exec(raw);
+  return m ? [Number(m[1]), Number(m[2]), Number(m[3])] : undefined;
+}
+
+/** `1836.1.21` -> `21 January 1836`; anything else comes back verbatim. */
+export function formatDate(raw: string | undefined): string {
+  if (!raw) return "";
+  const d = parseDate(raw);
+  const month = d ? MONTHS[d[1] - 1] : undefined;
+  return d && month ? `${d[2]} ${month} ${d[0]}` : raw;
+}
+
+/** Whole years between a birth date and the save's date. */
+export function age(birth: string | undefined, today: string | undefined): string | undefined {
+  const b = parseDate(birth);
+  const t = parseDate(today);
+  if (!b || !t) return undefined;
+  const beforeBirthday = t[1] < b[1] || (t[1] === b[1] && t[2] < b[2]);
+  const years = t[0] - b[0] - (beforeBirthday ? 1 : 0);
+  return years >= 0 ? String(years) : undefined;
+}
+
+// ---------------------------------------------------------------------------
+// The default schema
+// ---------------------------------------------------------------------------
+
+/**
+ * What any Jomini save answers out of its meta block alone. Every reader
+ * tolerates absence, so a game whose profile carries no schema of its own still
+ * gets exactly these rows.
+ */
+export const META_MAPPINGS: ValueMapping[] = [
+  {
+    chains: ["GetPlayer.GetName", "GetPlayer.GetCountry.GetName"],
+    read: (ctx) => scalar(ctx.meta, "name"),
+  },
+  {
+    chains: ["GetPlayer.GetRank", "GetPlayer.GetCountryRank.GetName"],
+    read: (ctx) => {
+      const rank = scalar(ctx.meta, "rank");
+      return rank ? (ctx.loc(rank) ?? rank) : undefined;
+    },
+  },
+  {
+    chains: ["GetCurrentDate", "GetGameDate"],
+    read: (ctx) => ctx.date,
+  },
+];
+
+/** The schema a profile that carries none of its own is read with. */
+export const DEFAULT_SAVE_SCHEMA: SaveSchema = { mappings: META_MAPPINGS };