@px-lsp/server 0.1.0

package/src/gui/textResolve.ts

@@ -0,0 +1,145 @@
+/**
+ * What a textbox SHOWS, as far as a static preview can know it.
+ *
+ * A `text = "..."` value is one of: a localization key, a literal, or a mix of
+ * literal text and `[datafunction]` expressions the running game evaluates.
+ * The preview resolves what is knowable (a key through the loc index,
+ * `Localize('key')`, `Concept('key', 'text')`, a value the modder typed into
+ * the per-mod preview table) and shows the rest honestly: the last segment of
+ * the chain (`GetName`) marked as unresolved, never an invented value. The
+ * result is segmented so a client can style and explain each part.
+ *
+ * Pure: the loc index is an injected lookup. No vscode, no fs.
+ */
+import type { GuiTextSegment } from "@px-lsp/protocol/protocol";
+
+export interface TextResolvers {
+  /** The configured language's value for a loc key, or undefined. */
+  loc: (key: string) => string | undefined;
+  /** Modder-supplied preview text per exact `[...]` source (without brackets). */
+  previewValues?: Record<string, string>;
+}
+
+export interface ResolvedText {
+  /** What is measured and drawn. */
+  text: string;
+  /** Absent when the text is a plain literal with nothing to explain. */
+  segments?: GuiTextSegment[];
+}
+
+/** A loc key: one word of key characters, nothing a literal sentence would have. */
+const LOC_KEY = /^[A-Za-z0-9_][A-Za-z0-9_.\-']*$/;
+
+/**
+ * Loc formatting the game does not draw: `#bold text#!`, `#R text#!`, `§Ytext§!`,
+ * `@icon!` icon references. Removed for measurement; the preview has no glyphs for them.
+ */
+function stripFormatting(s: string): string {
+  return s
+    .replace(/#!/g, "")
+    .replace(/#[A-Za-z_][A-Za-z0-9_;:]*\s?/g, "")
+    .replace(/§!/g, "")
+    .replace(/§[A-Za-z0-9]/g, "")
+    .replace(/@[A-Za-z0-9_]+!/g, "")
+    .replace(/\\n/g, "\n");
+}
+
+/** Split `a [Fn] b [[literal]` into literal and datafunction pieces. */
+function tokenize(s: string): { literal?: string; fn?: string }[] {
+  const out: { literal?: string; fn?: string }[] = [];
+  let lit = "";
+  for (let i = 0; i < s.length; i++) {
+    const c = s[i];
+    if (c === "[" && s[i + 1] === "[") {
+      lit += "[";
+      i++;
+      continue;
+    }
+    if (c === "[") {
+      let depth = 1;
+      let j = i + 1;
+      for (; j < s.length && depth > 0; j++) {
+        if (s[j] === "[") depth++;
+        else if (s[j] === "]") depth--;
+      }
+      if (depth !== 0) {
+        lit += s.slice(i);
+        break;
+      }
+      if (lit) out.push({ literal: lit });
+      lit = "";
+      out.push({ fn: s.slice(i + 1, j - 1) });
+      i = j - 1;
+      continue;
+    }
+    lit += c;
+  }
+  if (lit) out.push({ literal: lit });
+  return out;
+}
+
+/** `Localize('key')` / `Concept('key','shown')` / `Concept('key')`: the loc the chain stands for. */
+function locOfCall(fn: string, loc: TextResolvers["loc"]): string | undefined {
+  const m = /^(Localize|Concept)\s*\(\s*'([^']*)'(?:\s*,\s*'([^']*)')?\s*\)$/.exec(fn.trim());
+  if (!m) return undefined;
+  if (m[1] === "Concept" && m[3] !== undefined) return loc(m[3]) ?? m[3];
+  return loc(m[2]);
+}
+
+/** `GetPlayer.GetName` -> `GetName`; `Concept('x','y')` -> `Concept`; strips a `Get` prefix and arguments. */
+function chipFor(fn: string): string {
+  // `|0`, `|%`: format specifiers after the chain, not part of the name.
+  const chain = fn.split("|")[0];
+  const last = chain.split(".").pop() ?? chain;
+  const name = last.replace(/\(.*$/, "").trim() || fn;
+  return name.replace(/^Get(?=[A-Z])/, "") || name;
+}
+
+function resolveFn(fn: string, r: TextResolvers): GuiTextSegment {
+  const override = r.previewValues?.[fn] ?? r.previewValues?.[`[${fn}]`];
+  if (override !== undefined) return { text: override, kind: "datafn", source: fn, resolved: true };
+  const viaLoc = locOfCall(fn, r.loc);
+  if (viaLoc !== undefined)
+    return { text: stripFormatting(viaLoc), kind: "datafn", source: fn, resolved: true };
+  return { text: chipFor(fn), kind: "datafn", source: fn, resolved: false };
+}
+
+/** Resolve one string's datafunctions into segments (no loc-key lookup of the whole). */
+function resolveMixed(s: string, r: TextResolvers): GuiTextSegment[] {
+  return tokenize(s).map((t) =>
+    t.fn !== undefined
+      ? resolveFn(t.fn, r)
+      : {
+          text: stripFormatting(t.literal ?? ""),
+          kind: "literal" as const,
+          source: t.literal ?? "",
+          resolved: true,
+        }
+  );
+}
+
+export function resolveGuiText(raw: string, r: TextResolvers): ResolvedText {
+  const trimmed = raw.trim();
+  if (!trimmed) return { text: "" };
+  if (LOC_KEY.test(trimmed)) {
+    const value = r.loc(trimmed);
+    if (value !== undefined) {
+      // The value itself may hold datafunctions; those resolve one level deep.
+      const inner = resolveMixed(value, r);
+      const text = inner.map((s) => s.text).join("");
+      const segments: GuiTextSegment[] =
+        inner.length === 1 && inner[0].kind === "literal"
+          ? [{ text, kind: "loc", source: trimmed, resolved: true }]
+          : inner.map((s) => (s.kind === "literal" ? { ...s, kind: "loc", source: trimmed } : s));
+      return { text, segments };
+    }
+    // Not in the index: a key nobody localized yet, or a literal word. Shown as is, flagged.
+    if (trimmed.includes("_") || trimmed.includes(".")) {
+      return { text: trimmed, segments: [{ text: trimmed, kind: "loc", source: trimmed, resolved: false }] };
+    }
+    return { text: trimmed };
+  }
+  const segments = resolveMixed(trimmed, r);
+  const text = segments.map((s) => s.text).join("");
+  return segments.every((s) => s.kind === "literal") ? { text } : { text, segments };
+}

package/src/gui/textureInfo.ts

@@ -0,0 +1,106 @@
+/**
+ * Frame-sheet facts for the inspector: where a widget's texture file is, how
+ * big the sheet is, and which cell of it the widget draws.
+ *
+ * The sheet's pixel size is the only thing that needs the file, and a DDS
+ * carries it in its 128-byte header, so this reads exactly that prefix and
+ * never decodes: an inspector row must not cost a 4096x4096 BC7 decode.
+ *
+ * The grid comes from `framesize = { w h }` plus `frame` (Studio §L, L22),
+ * which is what the vanilla trees carry: the default profile's gui tree has
+ * 111 files with a `framesize` and neither harvested vanilla tree (nor either
+ * harvested guiSchema.json) contains a `noofframes`, so no second spelling is
+ * invented here. The cell math itself is computeFrameCell's, shared with the renderer.
+ *
+ * No `vscode` imports: unit-tested in plain Node.
+ */
+import * as fs from "fs";
+import * as path from "path";
+import type { GuiTextureInfo } from "@px-lsp/protocol/protocol";
+import { ddsFormatInfo } from "../dds/decoder";
+import { computeFrameCell } from "./fillGeometry";
+
+/** Roots a mod-relative texture path is resolved against. */
+export interface TextureRoots {
+  gamePath: string | null;
+  modPath: string | null;
+  /** Parent/dependency mods in load order, base first. */
+  parentPaths?: string[];
+  /** Engine (jomini) roots, below the game. */
+  engineRoots?: string[];
+}
+
+/**
+ * A DDS header is 128 bytes, 148 with the DX10 extension. Read a round 256 so
+ * a header read is one syscall and never depends on the file's total size.
+ */
+const HEADER_BYTES = 256;
+
+/**
+ * First root that has the file. Load order for a plain asset is last-in-wins,
+ * so the mod is tried first, then parent mods from the last loaded back, then
+ * the game, then the engine folder.
+ */
+export function resolveTextureFile(rel: string, roots: TextureRoots): string | null {
+  const parents = [...(roots.parentPaths ?? [])].reverse();
+  const order = [roots.modPath, ...parents, roots.gamePath, ...(roots.engineRoots ?? [])];
+  for (const root of order) {
+    if (!root) continue;
+    const abs = path.join(root, rel);
+    try {
+      if (fs.statSync(abs).isFile()) return abs;
+    } catch {
+      /* not under this root */
+    }
+  }
+  return null;
+}
+
+/** Width/height from the file's header alone; null when it is not a readable DDS. */
+export function readTextureSize(file: string): { width: number; height: number } | null {
+  let fd: number;
+  try {
+    fd = fs.openSync(file, "r");
+  } catch {
+    return null;
+  }
+  try {
+    const buf = Buffer.alloc(HEADER_BYTES);
+    const read = fs.readSync(fd, buf, 0, HEADER_BYTES, 0);
+    const info = ddsFormatInfo(new Uint8Array(buf.subarray(0, read)));
+    if (!info || info.width <= 0 || info.height <= 0) return null;
+    return { width: info.width, height: info.height };
+  } catch {
+    return null;
+  } finally {
+    fs.closeSync(fd);
+  }
+}
+
+/** What the inspector shows for one fill: the path, the sheet, the current cell. */
+export function describeTexture(
+  fill: { texture: string; framesize?: [number, number]; frame?: number },
+  source: "fill" | "background",
+  roots?: TextureRoots
+): GuiTextureInfo {
+  const info: GuiTextureInfo = { path: fill.texture, source };
+  if (fill.framesize) {
+    info.framesize = fill.framesize;
+    info.frame = fill.frame ?? 1;
+  }
+  const file = roots ? resolveTextureFile(fill.texture, roots) : null;
+  if (!file) return info;
+  info.file = file;
+  const size = readTextureSize(file);
+  if (!size) return info;
+  info.width = size.width;
+  info.height = size.height;
+  if (!fill.framesize) return info;
+  const [fw, fh] = fill.framesize;
+  if (fw <= 0 || fh <= 0) return info;
+  info.columns = Math.max(1, Math.floor(size.width / fw));
+  info.rows = Math.max(1, Math.floor(size.height / fh));
+  const cell = computeFrameCell(fill.framesize, info.frame ?? 1, size.width, size.height);
+  info.cell = { x: cell.sx, y: cell.sy, w: cell.sw, h: cell.sh };
+  return info;
+}

package/src/gui/vocabulary.ts

@@ -0,0 +1,149 @@
+/**
+ * paradox/guiVocabulary backend: which widgets a designer palette may offer.
+ *
+ * Every name comes from something the project already harvested, never from a
+ * list typed here: the bundled `data/<game>/guiSchema.json` (600+ widget types
+ * with their vanilla usage counts, built by `scripts/build-gui-schema.ts`) plus
+ * the requested document's own `template` / `type` declarations. A palette that
+ * offered a name from memory would write a widget the game does not know, which
+ * is exactly the failure AGENTS.md's one design idea exists to prevent.
+ *
+ * The same harvest answers the other half of a designer's vocabulary: which
+ * PROPERTIES a widget type carries, for an inspector that offers to add one.
+ * Ranked by vanilla usage, scoped to the types this document names, with the
+ * tree-wide ranking as the fallback for a type the harvest does not know.
+ *
+ * `container` is derived the same way: a type is one when the vanilla tree ever
+ * wrote a WIDGET block inside it (the harvest counts child keys among a type's
+ * props), with the engine's own attribute-block set excluded so `size` and
+ * `background` do not make everything a container.
+ *
+ * No `vscode` imports: unit-tested in plain Node.
+ */
+import type { GuiVocabularyEntry, GuiVocabularyResult } from "@px-lsp/protocol/protocol";
+import { parseScript, type Statement } from "../parser";
+import { collectGuiDefsParsed } from "./guiDefs";
+import { PROPERTY_BLOCKS } from "./layoutEngine";
+
+/** The slice of `guiSchema.json` a palette needs. */
+interface GuiSchemaTypes {
+  types?: Record<string, { count: number; props?: Record<string, number> }>;
+  globalProps?: Record<string, number>;
+}
+
+/**
+ * How many harvested types a palette gets. The tail is single-use vanilla
+ * types; `total` reports what was left out rather than pretending the list is
+ * everything. A UI budget, not a measurement.
+ */
+export const VOCABULARY_LIMIT = 300;
+
+/**
+ * How many property names one type offers, and how long the tree-wide fallback
+ * ranking is. Both are UI budgets: the harvest keeps up to 100 properties per
+ * type and 200 overall, and a completion list nobody scrolls past the twentieth
+ * row of does not need to carry the tail across the wire on every layout.
+ */
+export const TYPE_PROPERTY_LIMIT = 60;
+export const COMMON_PROPERTY_LIMIT = 80;
+
+export function computeGuiVocabulary(text: string, schema: unknown): GuiVocabularyResult {
+  const types = (schema as GuiSchemaTypes | undefined)?.types ?? {};
+  const known = new Set(Object.keys(types));
+  const entries: GuiVocabularyEntry[] = [];
+
+  // The document's own declarations first, and never capped: they are the ones
+  // its author reaches for, and no harvest can know them.
+  const statements = parseScript(text).root.statements;
+  const own = collectGuiDefsParsed(statements);
+  for (const [name, def] of own.types) {
+    entries.push({ name, kind: "type", local: true, base: def.base, container: true });
+  }
+  for (const [name] of own.templates) {
+    entries.push({ name, kind: "template", local: true });
+  }
+  const declared = new Set(entries.map((e) => e.name));
+
+  const harvested = [...known]
+    .filter((name) => !declared.has(name))
+    .sort((a, b) => types[b].count - types[a].count || a.localeCompare(b));
+  for (const name of harvested.slice(0, VOCABULARY_LIMIT)) {
+    entries.push({
+      name,
+      kind: "builtin",
+      count: types[name].count,
+      container: holdsWidgets(types[name].props, known),
+    });
+  }
+  return {
+    entries,
+    total: declared.size + harvested.length,
+    properties: propertiesFor(statements, own.types, types),
+    commonProperties: rank((schema as GuiSchemaTypes | undefined)?.globalProps, COMMON_PROPERTY_LIMIT),
+  };
+}
+
+/**
+ * The property names the harvest saw on the widget types THIS DOCUMENT names,
+ * which is what an inspector's add-property row completes from. Scoped to the
+ * document rather than sent whole because the harvest holds 556 types and an
+ * open panel re-asks after every layout; the types a file actually writes are a
+ * couple of dozen, and `commonProperties` covers the rest.
+ *
+ * "Names" is the union of the keys it writes blocks under and the bases of its
+ * own `type X = base` declarations: a derived type's properties live under its
+ * base in the harvest, which is also where the widget's type chain ends.
+ */
+function propertiesFor(
+  statements: readonly Statement[],
+  localTypes: ReadonlyMap<string, { base: string }>,
+  types: Record<string, { count: number; props?: Record<string, number> }>
+): Record<string, string[]> {
+  const named = new Set<string>();
+  collectBlockKeys(statements, named);
+  for (const def of localTypes.values()) named.add(def.base.toLowerCase());
+
+  const out: Record<string, string[]> = {};
+  for (const name of named) {
+    const props = types[name]?.props;
+    if (props) out[name] = rank(props, TYPE_PROPERTY_LIMIT);
+  }
+  return out;
+}
+
+/** Every key the document writes a block under, lowercased, at any depth. */
+function collectBlockKeys(statements: readonly Statement[], into: Set<string>): void {
+  for (const stmt of statements) {
+    if (stmt.kind === "value") {
+      if (stmt.value.kind === "block") collectBlockKeys(stmt.value.statements, into);
+      continue;
+    }
+    const value = stmt.value;
+    if (!value) continue;
+    const block = value.kind === "block" ? value : value.kind === "tagged-block" ? value.block : null;
+    if (!block) continue;
+    if (!stmt.key.quoted) into.add(stmt.key.text.toLowerCase());
+    collectBlockKeys(block.statements, into);
+  }
+}
+
+/** Usage counts to names, most used first, capped. */
+function rank(counts: Record<string, number> | undefined, limit: number): string[] {
+  return Object.entries(counts ?? {})
+    .sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))
+    .slice(0, limit)
+    .map(([name]) => name);
+}
+
+/**
+ * A type the vanilla tree ever wrote another widget inside. The harvest counts
+ * child widget keys among a type's props, so the test is "does any prop name a
+ * known widget type", with the engine's attribute blocks (`size`, `background`,
+ * `state`, …) taken out — those are data, not children.
+ */
+function holdsWidgets(props: Record<string, number> | undefined, known: ReadonlySet<string>): boolean {
+  for (const prop of Object.keys(props ?? {})) {
+    if (!PROPERTY_BLOCKS.has(prop) && known.has(prop)) return true;
+  }
+  return false;
+}

package/src/gui/widgetEdit.ts

@@ -0,0 +1,52 @@
+/**
+ * paradox/guiWidgetEdit backend: DEPRECATED, kept for hosts already wired to
+ * it. It is a thin alias over the `paradox/guiSourceEdit` core
+ * (`sourceEditService.ts`): the same span model, the same refusal guards, the
+ * same edits, narrowed to the one gesture this request can express (set
+ * `position` or `size` on the widget whose statement starts on a given line).
+ *
+ * What the narrow shape costs the caller: it returns ONE edit or null, so a
+ * refusal arrives as a bare null with its reason dropped, and a batch has to be
+ * several round trips. New hosts should send `paradox/guiSourceEdit` with a
+ * `setProperties` op instead.
+ */
+import type { GuiDefs } from "./guiDefs";
+import { emptyGuiDefs } from "./guiDefs";
+import { computeGuiSourceEdit } from "./sourceEditService";
+
+export interface WidgetTextEdit {
+  /** UTF-16 offsets into the request's text. */
+  start: number;
+  end: number;
+  newText: string;
+}
+
+const PAIR_PROPERTIES = new Set(["position", "size"]);
+
+export function computeGuiWidgetEdit(
+  text: string,
+  line: number,
+  property: string,
+  values: [number, number],
+  defs: GuiDefs = emptyGuiDefs()
+): WidgetTextEdit | null {
+  if (!PAIR_PROPERTIES.has(property)) return null;
+  const result = computeGuiSourceEdit(
+    text,
+    {
+      kind: "setProperties",
+      line,
+      properties: [{ key: property, value: `{ ${fmt(values[0])} ${fmt(values[1])} }` }],
+    },
+    defs
+  );
+  // One edit is all this shape can carry, and a batch of one is what it asks
+  // for; a refusal (and its reason) collapses to null.
+  const edits = result?.edits;
+  return edits?.length === 1 ? edits[0] : null;
+}
+
+function fmt(v: number): string {
+  const rounded = Math.round(v);
+  return Math.abs(v - rounded) < 0.005 ? String(rounded) : v.toFixed(1);
+}