@px-lsp/server 0.1.0

package/src/dds/encode.ts

@@ -0,0 +1,235 @@
+/**
+ * DDS encoder for the image → DDS converter: uncompressed A8R8G8B8 plus BC1
+ * (DXT1) and BC3 (DXT5) via classic range-fit block compression — compact,
+ * dependency-free, and good enough for GUI icons/illustrations. Round-trip
+ * tested against decoder.ts.
+ *
+ * No `vscode` imports: unit-tested in plain Node, used by the client host.
+ */
+
+export type DdsEncodeFormat = "bc1" | "bc3" | "bgra8";
+
+const DDSD_CAPS = 0x1;
+const DDSD_HEIGHT = 0x2;
+const DDSD_WIDTH = 0x4;
+const DDSD_PITCH = 0x8;
+const DDSD_PIXELFORMAT = 0x1000;
+const DDSD_LINEARSIZE = 0x80000;
+const DDPF_ALPHAPIXELS = 0x1;
+const DDPF_FOURCC = 0x4;
+const DDPF_RGB = 0x40;
+const DDSCAPS_TEXTURE = 0x1000;
+
+function fourCC(s: string): number {
+  return (s.charCodeAt(0) | (s.charCodeAt(1) << 8) | (s.charCodeAt(2) << 16) | (s.charCodeAt(3) << 24)) >>> 0;
+}
+
+/** True when any pixel has alpha < 255 — drives the "auto" format choice. */
+export function hasTransparency(rgba: Uint8Array): boolean {
+  for (let i = 3; i < rgba.length; i += 4) if (rgba[i] !== 255) return true;
+  return false;
+}
+
+/** Encode RGBA8 pixels as a DDS file (no mipmaps). */
+export function encodeDds(
+  width: number,
+  height: number,
+  rgba: Uint8Array,
+  format: DdsEncodeFormat
+): Uint8Array {
+  if (rgba.length < width * height * 4) throw new Error("pixel buffer too small");
+  const data =
+    format === "bgra8" ? encodeBgra(width, height, rgba) : encodeBlocks(width, height, rgba, format);
+
+  const header = new Uint8Array(128);
+  const dv = new DataView(header.buffer);
+  dv.setUint32(0, fourCC("DDS "), true);
+  dv.setUint32(4, 124, true); // dwSize
+  const compressed = format !== "bgra8";
+  dv.setUint32(
+    8,
+    DDSD_CAPS | DDSD_HEIGHT | DDSD_WIDTH | DDSD_PIXELFORMAT | (compressed ? DDSD_LINEARSIZE : DDSD_PITCH),
+    true
+  );
+  dv.setUint32(12, height, true);
+  dv.setUint32(16, width, true);
+  dv.setUint32(20, compressed ? data.length : width * 4, true); // linear size / pitch
+  // depth, mipmaps, 11 reserved dwords stay 0
+  const pf = 76; // pixel-format struct offset
+  dv.setUint32(pf, 32, true); // pf size
+  if (format === "bc1") {
+    dv.setUint32(pf + 4, DDPF_FOURCC, true);
+    dv.setUint32(pf + 8, fourCC("DXT1"), true);
+  } else if (format === "bc3") {
+    dv.setUint32(pf + 4, DDPF_FOURCC, true);
+    dv.setUint32(pf + 8, fourCC("DXT5"), true);
+  } else {
+    dv.setUint32(pf + 4, DDPF_RGB | DDPF_ALPHAPIXELS, true);
+    dv.setUint32(pf + 12, 32, true); // bit count
+    dv.setUint32(pf + 16, 0x00ff0000, true); // R
+    dv.setUint32(pf + 20, 0x0000ff00, true); // G
+    dv.setUint32(pf + 24, 0x000000ff, true); // B
+    dv.setUint32(pf + 28, 0xff000000, true); // A
+  }
+  dv.setUint32(108, DDSCAPS_TEXTURE, true);
+
+  const out = new Uint8Array(128 + data.length);
+  out.set(header, 0);
+  out.set(data, 128);
+  return out;
+}
+
+function encodeBgra(width: number, height: number, rgba: Uint8Array): Uint8Array {
+  const out = new Uint8Array(width * height * 4);
+  for (let i = 0; i < width * height; i++) {
+    out[i * 4] = rgba[i * 4 + 2]; // B
+    out[i * 4 + 1] = rgba[i * 4 + 1]; // G
+    out[i * 4 + 2] = rgba[i * 4]; // R
+    out[i * 4 + 3] = rgba[i * 4 + 3]; // A
+  }
+  return out;
+}
+
+function encodeBlocks(width: number, height: number, rgba: Uint8Array, format: "bc1" | "bc3"): Uint8Array {
+  const bw = Math.ceil(width / 4);
+  const bh = Math.ceil(height / 4);
+  const blockSize = format === "bc1" ? 8 : 16;
+  const out = new Uint8Array(bw * bh * blockSize);
+  const px = new Uint8Array(64); // 16 RGBA pixels
+  let offset = 0;
+  for (let by = 0; by < bh; by++) {
+    for (let bx = 0; bx < bw; bx++) {
+      // Gather the 4x4 block, clamping at edges.
+      for (let y = 0; y < 4; y++) {
+        const sy = Math.min(height - 1, by * 4 + y);
+        for (let x = 0; x < 4; x++) {
+          const sx = Math.min(width - 1, bx * 4 + x);
+          const so = (sy * width + sx) * 4;
+          const d = (y * 4 + x) * 4;
+          px[d] = rgba[so];
+          px[d + 1] = rgba[so + 1];
+          px[d + 2] = rgba[so + 2];
+          px[d + 3] = rgba[so + 3];
+        }
+      }
+      if (format === "bc3") {
+        writeAlphaBlock(px, out, offset);
+        offset += 8;
+      }
+      writeColorBlock(px, out, offset);
+      offset += 8;
+    }
+  }
+  return out;
+}
+
+function to565(r: number, g: number, b: number): number {
+  return ((r >> 3) << 11) | ((g >> 2) << 5) | (b >> 3);
+}
+
+function from565(c: number): [number, number, number] {
+  const r = (c >> 11) & 0x1f;
+  const g = (c >> 5) & 0x3f;
+  const b = c & 0x1f;
+  return [(r << 3) | (r >> 2), (g << 2) | (g >> 4), (b << 3) | (b >> 2)];
+}
+
+/**
+ * Range-fit BC1 color block (always 4-color mode: c0 > c1). Endpoints are the
+ * extremes of the block's principal luminance ordering; each pixel snaps to
+ * the nearest of the 4 palette entries.
+ */
+function writeColorBlock(px: Uint8Array, out: Uint8Array, offset: number): void {
+  // Find the two extreme pixels by projecting on the max-variance axis
+  // (approximated by luminance — adequate for icon/illustration content).
+  let minL = Infinity;
+  let maxL = -Infinity;
+  let minI = 0;
+  let maxI = 0;
+  for (let i = 0; i < 16; i++) {
+    const l = px[i * 4] * 3 + px[i * 4 + 1] * 6 + px[i * 4 + 2];
+    if (l < minL) {
+      minL = l;
+      minI = i;
+    }
+    if (l > maxL) {
+      maxL = l;
+      maxI = i;
+    }
+  }
+  let c0 = to565(px[maxI * 4], px[maxI * 4 + 1], px[maxI * 4 + 2]);
+  let c1 = to565(px[minI * 4], px[minI * 4 + 1], px[minI * 4 + 2]);
+  if (c0 < c1) {
+    const t = c0;
+    c0 = c1;
+    c1 = t;
+  } else if (c0 === c1 && c1 > 0) {
+    c1 = c1 - 1; // keep 4-color mode; palette entry 0 still matches exactly
+  }
+  const [r0, g0, b0] = from565(c0);
+  const [r1, g1, b1] = from565(c1);
+  const palette = [
+    [r0, g0, b0],
+    [r1, g1, b1],
+    [(2 * r0 + r1 + 1) / 3, (2 * g0 + g1 + 1) / 3, (2 * b0 + b1 + 1) / 3],
+    [(r0 + 2 * r1 + 1) / 3, (g0 + 2 * g1 + 1) / 3, (b0 + 2 * b1 + 1) / 3],
+  ];
+  let indices = 0;
+  for (let i = 0; i < 16; i++) {
+    let best = 0;
+    let bestD = Infinity;
+    for (let p = 0; p < 4; p++) {
+      const dr = px[i * 4] - palette[p][0];
+      const dg = px[i * 4 + 1] - palette[p][1];
+      const db = px[i * 4 + 2] - palette[p][2];
+      const d = dr * dr + dg * dg + db * db;
+      if (d < bestD) {
+        bestD = d;
+        best = p;
+      }
+    }
+    indices |= best << (i * 2);
+  }
+  const dv = new DataView(out.buffer, out.byteOffset + offset, 8);
+  dv.setUint16(0, c0, true);
+  dv.setUint16(2, c1, true);
+  dv.setUint32(4, indices >>> 0, true);
+}
+
+/** BC3 alpha block: a0 > a1 (8-level) range fit with 3-bit indices. */
+function writeAlphaBlock(px: Uint8Array, out: Uint8Array, offset: number): void {
+  let a0 = 0;
+  let a1 = 255;
+  for (let i = 0; i < 16; i++) {
+    const a = px[i * 4 + 3];
+    if (a > a0) a0 = a;
+    if (a < a1) a1 = a;
+  }
+  if (a0 === a1) {
+    // Uniform alpha: endpoints equal would flip to the 6-level mode; nudge.
+    if (a0 < 255) a0 = a0 + 1;
+    else a1 = a1 - 1;
+  }
+  const palette = [a0, a1];
+  for (let i = 1; i <= 6; i++) palette.push(Math.round(((7 - i) * a0 + i * a1) / 7));
+  const idx: number[] = [];
+  for (let i = 0; i < 16; i++) {
+    const a = px[i * 4 + 3];
+    let best = 0;
+    let bestD = Infinity;
+    for (let p = 0; p < 8; p++) {
+      const d = Math.abs(a - palette[p]);
+      if (d < bestD) {
+        bestD = d;
+        best = p;
+      }
+    }
+    idx.push(best);
+  }
+  out[offset] = a0;
+  out[offset + 1] = a1;
+  // Pack 16 × 3-bit indices little-endian into 6 bytes.
+  let bits = 0n;
+  for (let i = 15; i >= 0; i--) bits = (bits << 3n) | BigInt(idx[i]);
+  for (let i = 0; i < 6; i++) out[offset + 2 + i] = Number((bits >> BigInt(i * 8)) & 0xffn);
+}

package/src/dds/index.ts

@@ -0,0 +1,58 @@
+import { decodeDds, type DecodedImage } from "./decoder";
+import { encodePng } from "./png";
+
+export { decodeDds, ddsFormatInfo } from "./decoder";
+export { encodePng } from "./png";
+export { decodeTga } from "./tga";
+export { encodeDds, hasTransparency, type DdsEncodeFormat } from "./encode";
+export type { DecodedImage } from "./decoder";
+
+/** Nearest-neighbour downscale so max(width, height) <= maxDim. Returns the image unchanged if already small enough. */
+export function downscale(img: DecodedImage, maxDim: number): DecodedImage {
+  const { width, height, pixels } = img;
+  const longest = Math.max(width, height);
+  if (longest <= maxDim || maxDim <= 0) return img;
+
+  const scale = maxDim / longest;
+  const dw = Math.max(1, Math.round(width * scale));
+  const dh = Math.max(1, Math.round(height * scale));
+  const out = new Uint8Array(dw * dh * 4);
+  for (let y = 0; y < dh; y++) {
+    const sy = Math.min(height - 1, Math.floor((y * height) / dh));
+    for (let x = 0; x < dw; x++) {
+      const sx = Math.min(width - 1, Math.floor((x * width) / dw));
+      const so = (sy * width + sx) * 4;
+      const dof = (y * dw + x) * 4;
+      out[dof] = pixels[so];
+      out[dof + 1] = pixels[so + 1];
+      out[dof + 2] = pixels[so + 2];
+      out[dof + 3] = pixels[so + 3];
+    }
+  }
+  return { width: dw, height: dh, pixels: out };
+}
+
+/**
+ * Decode a DDS, downscale so max(w,h) <= maxDim, encode PNG, return a data URI —
+ * or null if even a shrunk preview can't fit the length budget.
+ *
+ * VS Code's hover markdown renderer hard-truncates any hover body longer than
+ * 100_000 chars (`preprocessMarkdownString` in markdownRenderer.ts: `if
+ * (value.length > 100_000) value = value.substr(0, 100_000) + '…'`). That cut
+ * lands mid-base64 inside `![texture](data:...)`, leaving an unterminated image
+ * link that markdown-it then renders as literal text — the raw base64 spilling
+ * into the popup. Smooth vanilla art deflates small (~55-80 KB URIs) and stays
+ * under the limit; noisy/photographic converter output can exceed it (a 1592x848
+ * DXT1 event scene measured ~108 KB). So we cap the URI at `maxUriLength` and
+ * progressively shrink maxDim until it fits, decoding only once.
+ */
+export function ddsToPngDataUri(buf: Uint8Array, maxDim = 256, maxUriLength = 90_000): string | null {
+  const decoded = decodeDds(buf);
+  for (let dim = maxDim; dim >= 32; dim = Math.floor(dim * 0.75)) {
+    const scaled = downscale(decoded, dim);
+    const png = encodePng(scaled.width, scaled.height, scaled.pixels);
+    const uri = `data:image/png;base64,${Buffer.from(png).toString("base64")}`;
+    if (uri.length <= maxUriLength) return uri;
+  }
+  return null;
+}

package/src/dds/png.ts

@@ -0,0 +1,96 @@
+import { deflateSync } from "node:zlib";
+
+// CRC32 table (IEEE polynomial 0xEDB88320)
+const CRC_TABLE: Uint32Array = (() => {
+  const table = new Uint32Array(256);
+  for (let n = 0; n < 256; n++) {
+    let c = n;
+    for (let k = 0; k < 8; k++) {
+      c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+    }
+    table[n] = c >>> 0;
+  }
+  return table;
+})();
+
+function crc32(bytes: Uint8Array): number {
+  let crc = 0xffffffff;
+  for (let i = 0; i < bytes.length; i++) {
+    crc = CRC_TABLE[(crc ^ bytes[i]) & 0xff] ^ (crc >>> 8);
+  }
+  return (crc ^ 0xffffffff) >>> 0;
+}
+
+function u32be(n: number): Uint8Array {
+  const b = new Uint8Array(4);
+  b[0] = (n >>> 24) & 0xff;
+  b[1] = (n >>> 16) & 0xff;
+  b[2] = (n >>> 8) & 0xff;
+  b[3] = n & 0xff;
+  return b;
+}
+
+function chunk(type: string, data: Uint8Array): Uint8Array {
+  const typeBytes = new Uint8Array(4);
+  for (let i = 0; i < 4; i++) typeBytes[i] = type.charCodeAt(i);
+  const body = new Uint8Array(typeBytes.length + data.length);
+  body.set(typeBytes, 0);
+  body.set(data, typeBytes.length);
+  const crc = crc32(body);
+  const out = new Uint8Array(4 + body.length + 4);
+  out.set(u32be(data.length), 0);
+  out.set(body, 4);
+  out.set(u32be(crc), 4 + body.length);
+  return out;
+}
+
+/**
+ * Encode an 8-bit RGBA image to PNG bytes. No external dependencies:
+ * filter type 0 per scanline, zlib deflate via node:zlib, manual CRC32.
+ */
+export function encodePng(width: number, height: number, rgba: Uint8Array): Uint8Array {
+  if (width <= 0 || height <= 0) throw new Error("encodePng: invalid dimensions");
+  if (rgba.length < width * height * 4) throw new Error("encodePng: pixel buffer too small");
+
+  const sig = new Uint8Array([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+
+  // IHDR: width, height, bit depth 8, color type 6 (RGBA), compression 0, filter 0, interlace 0
+  const ihdr = new Uint8Array(13);
+  ihdr.set(u32be(width), 0);
+  ihdr.set(u32be(height), 4);
+  ihdr[8] = 8;
+  ihdr[9] = 6;
+  ihdr[10] = 0;
+  ihdr[11] = 0;
+  ihdr[12] = 0;
+
+  // Raw image data with filter byte (0) prepended to each scanline
+  const stride = width * 4;
+  const raw = new Uint8Array((stride + 1) * height);
+  for (let y = 0; y < height; y++) {
+    const dst = y * (stride + 1);
+    raw[dst] = 0; // filter type none
+    raw.set(rgba.subarray(y * stride, y * stride + stride), dst + 1);
+  }
+
+  const compressed = deflateSync(raw);
+
+  const ihdrChunk = chunk("IHDR", ihdr);
+  const idatChunk = chunk(
+    "IDAT",
+    new Uint8Array(compressed.buffer, compressed.byteOffset, compressed.byteLength)
+  );
+  const iendChunk = chunk("IEND", new Uint8Array(0));
+
+  const total = sig.length + ihdrChunk.length + idatChunk.length + iendChunk.length;
+  const out = new Uint8Array(total);
+  let off = 0;
+  out.set(sig, off);
+  off += sig.length;
+  out.set(ihdrChunk, off);
+  off += ihdrChunk.length;
+  out.set(idatChunk, off);
+  off += idatChunk.length;
+  out.set(iendChunk, off);
+  return out;
+}

package/src/dds/tga.ts

@@ -0,0 +1,62 @@
+/**
+ * Truevision TGA decoder: true-color 24/32-bit, raw (type 2) or RLE (type 10),
+ * either vertical origin. That is every .tga the games ship under gfx/ (the
+ * coat-of-arms patterns are 24-bit, raw or RLE, bottom-left origin). No
+ * color-mapped or grayscale images: nothing in the corpus uses them.
+ */
+import type { DecodedImage } from "./decoder";
+
+export function decodeTga(buf: Uint8Array): DecodedImage {
+  if (buf.length < 18) throw new Error("truncated TGA header");
+  const idLength = buf[0];
+  const colorMapType = buf[1];
+  const imageType = buf[2];
+  const width = buf[12] | (buf[13] << 8);
+  const height = buf[14] | (buf[15] << 8);
+  const depth = buf[16];
+  const descriptor = buf[17];
+  if (colorMapType !== 0 || (imageType !== 2 && imageType !== 10)) {
+    throw new Error(`unsupported TGA image type ${imageType} (color map ${colorMapType})`);
+  }
+  if (depth !== 24 && depth !== 32) throw new Error(`unsupported TGA depth ${depth}`);
+  if (width === 0 || height === 0) throw new Error("empty TGA");
+
+  const bpp = depth / 4 / 2; // bytes per pixel: 3 or 4
+  const topDown = (descriptor & 0x20) !== 0;
+  const pixels = new Uint8Array(width * height * 4);
+  let src = 18 + idLength;
+  const count = width * height;
+
+  const put = (i: number): void => {
+    // Row i / width of the file maps to the bottom row first unless top-down.
+    const row = Math.floor(i / width);
+    const y = topDown ? row : height - 1 - row;
+    const o = (y * width + (i % width)) * 4;
+    pixels[o] = buf[src + 2];
+    pixels[o + 1] = buf[src + 1];
+    pixels[o + 2] = buf[src];
+    pixels[o + 3] = bpp === 4 ? buf[src + 3] : 255;
+  };
+
+  if (imageType === 2) {
+    if (src + count * bpp > buf.length) throw new Error("truncated TGA data");
+    for (let i = 0; i < count; i++, src += bpp) put(i);
+    return { width, height, pixels };
+  }
+
+  let i = 0;
+  while (i < count) {
+    if (src >= buf.length) throw new Error("truncated TGA RLE data");
+    const packet = buf[src++];
+    const n = (packet & 0x7f) + 1;
+    if (packet & 0x80) {
+      if (src + bpp > buf.length) throw new Error("truncated TGA RLE data");
+      for (let k = 0; k < n && i < count; k++, i++) put(i);
+      src += bpp;
+    } else {
+      if (src + n * bpp > buf.length) throw new Error("truncated TGA RLE data");
+      for (let k = 0; k < n && i < count; k++, i++, src += bpp) put(i);
+    }
+  }
+  return { width, height, pixels };
+}

package/src/documents.ts

@@ -0,0 +1,35 @@
+/**
+ * Small helpers over `vscode-languageserver-textdocument` documents: the LSP
+ * TextDocument API has no lineAt(), so line text is sliced via ranges (offsets
+ * clamp to the line end).
+ */
+import type { TextDocument } from "vscode-languageserver-textdocument";
+
+/**
+ * The non-script languages we serve. Everything else whose id starts with
+ * `paradox` is the script language.
+ */
+const NON_SCRIPT_LANGUAGES = new Set(["paradox-loc", "paradox-gui", "paradox-mod", "paradox-info"]);
+
+/**
+ * Whether a document is jomini script, whatever the client called it.
+ *
+ * Clients may append a suffix to get a per-language icon and label per game
+ * (the VS Code extension sends `paradox-<game>`, neovim sends plain
+ * `paradox`). They are one language to the server, and naming the suffixes
+ * here would put game names in engine code, so the test is generic: it is
+ * script unless it is one of the four other Paradox languages.
+ */
+export function isScriptLanguage(languageId: string): boolean {
+  return languageId.startsWith("paradox") && !NON_SCRIPT_LANGUAGES.has(languageId);
+}
+
+export function getLineText(document: TextDocument, line: number): string {
+  if (line < 0 || line >= document.lineCount) return "";
+  const text = document.getText({
+    start: { line, character: 0 },
+    end: { line, character: Number.MAX_SAFE_INTEGER },
+  });
+  // The range clamp keeps the trailing newline out, but guard against CR.
+  return text.replace(/[\r\n]+$/, "");
+}

package/src/features/assetPaths.ts

@@ -0,0 +1,169 @@
+/**
+ * Filesystem-backed asset-path IntelliSense (user-reported gap): completion for
+ * quoted/unquoted asset paths (`texture = "gfx/interface/icons/..."`) drilled
+ * one directory segment at a time across the content roots, plus bare-filename
+ * `.dds` fields whose base directory the engine fixes per context
+ * (`icon = cultivation_realm_2.dds` in a trait → gfx/interface/icons/traits/).
+ *
+ * Roots are listed in the same shadowing order as textureHover.ts: modPath,
+ * then parentPaths, then gamePath. Listing is lazy — one fs.readdirSync per root
+ * per request, no upfront recursive scan.
+ */
+import { CompletionItemKind, type CompletionItem } from "vscode-languageserver/node";
+import * as fs from "fs";
+import * as path from "path";
+import type { ParadoxSettings } from "@px-lsp/protocol/protocol";
+import type { CompletionResult } from "./completion";
+
+/** Top-level folders under a content root that hold referenceable assets. */
+const ASSET_ROOTS = new Set(["gfx", "gui", "fonts", "sound", "music", "dlc"]);
+
+/**
+ * Bare-filename `.dds` fields and the base directory the engine resolves them
+ * against, keyed by definition kind (the file's schema folder) then by key.
+ * Every entry was verified against vanilla: a real file uses the bare name AND
+ * the asset lives at the mapped directory (defines in
+ * common/defines/graphic/00_graphics.txt, cross-checked with the assets):
+ *   - trait.icon          → TRAIT_ICON_PATH        (also documented in _traits.info)
+ *   - death_reason.icon   → DEATH_REASON_ICON_PATH
+ *   - building.type_icon  → BUILDING_TYPE_ICON_PATH
+ */
+const BARE_NAME_BASE_DIRS: Record<string, Record<string, string[]>> = {
+  trait: { icon: ["gfx/interface/icons/traits"] },
+  death_reason: { icon: ["gfx/interface/icons/death_reason"] },
+  building: { type_icon: ["gfx/interface/icons/building_types"] },
+};
+
+interface Root {
+  root: string;
+  label: string;
+}
+
+/** Content roots in shadowing order (mod → parents → vanilla), non-null only. */
+export function assetRoots(settings: ParadoxSettings): Root[] {
+  const roots: Root[] = [];
+  if (settings.modPath) roots.push({ root: settings.modPath, label: "mod" });
+  for (const p of settings.parentPaths ?? []) roots.push({ root: p, label: "parent" });
+  if (settings.gamePath) roots.push({ root: settings.gamePath, label: "vanilla" });
+  return roots;
+}
+
+/** Base dirs a bare `.dds` field resolves against, or null when the key is not mapped. */
+export function bareNameBaseDirs(kind: string | null | undefined, key: string): string[] | null {
+  if (!kind) return null;
+  return BARE_NAME_BASE_DIRS[kind]?.[key] ?? null;
+}
+
+/**
+ * The asset-path prefix being typed inside a value, or null when the value is
+ * not a directory-style asset path. Matches `key = "gfx/interface/ico`
+ * (quote optional — script paths are often unquoted). A path qualifies when its
+ * first segment is a known asset root; a slash-free partial qualifies when it is
+ * still a prefix of one (so `"g` can suggest gfx/gui), which keeps arbitrary
+ * quoted strings (`name = "PdxWidget"`) out.
+ */
+export function assetDirContext(linePrefix: string): string | null {
+  const m = /([A-Za-z_][A-Za-z0-9_]*)\s*=\s*"?([A-Za-z0-9_.\-/]*)$/.exec(linePrefix);
+  if (!m) return null;
+  const value = m[2];
+  // An empty value is ambiguous (could be a bare-name field): let the value-position
+  // handler decide, kick in only once a segment is being typed.
+  if (value === "") return null;
+  const first = value.split("/")[0].toLowerCase();
+  if (value.includes("/")) {
+    return ASSET_ROOTS.has(first) ? value : null;
+  }
+  // No slash yet: only offer when the partial can still grow into a root.
+  const low = value.toLowerCase();
+  for (const r of ASSET_ROOTS) if (r.startsWith(low)) return value;
+  return null;
+}
+
+function startsWithFold(name: string, prefix: string): boolean {
+  return name.toLowerCase().startsWith(prefix.toLowerCase());
+}
+
+/**
+ * Directory-segment completion for `pathPrefix` (e.g. `gfx/interface/ico`):
+ * children of the parent directory across roots, deduped by relative path in
+ * shadowing order. Directories get a trailing `/` and a retrigger command so the
+ * user drills down; files complete as-is. isIncomplete so the client re-queries
+ * per keystroke.
+ */
+export function provideAssetDirCompletion(settings: ParadoxSettings, pathPrefix: string): CompletionResult {
+  const slash = pathPrefix.lastIndexOf("/");
+  const parentRel = slash >= 0 ? pathPrefix.slice(0, slash) : "";
+  const partial = slash >= 0 ? pathPrefix.slice(slash + 1) : pathPrefix;
+
+  const seen = new Set<string>();
+  const items: CompletionItem[] = [];
+  for (const { root, label } of assetRoots(settings)) {
+    const dir = parentRel ? path.join(root, ...parentRel.split("/")) : root;
+    let entries: fs.Dirent[];
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const d of entries) {
+      const name = d.name;
+      if (partial && !startsWithFold(name, partial)) continue;
+      const isDir = d.isDirectory();
+      const relLow = `${parentRel}/${name}`.toLowerCase();
+      if (seen.has(relLow)) continue;
+      seen.add(relLow);
+      const item: CompletionItem = {
+        label: name,
+        kind: isDir ? CompletionItemKind.Folder : CompletionItemKind.File,
+        detail: label,
+        // Directories first, then files; alphabetical within each group.
+        sortText: `${isDir ? "0" : "1"}${name.toLowerCase()}`,
+      };
+      if (isDir) {
+        item.insertText = `${name}/`;
+        item.command = { command: "editor.action.triggerSuggest", title: "Suggest next segment" };
+      }
+      items.push(item);
+    }
+  }
+  return { isIncomplete: true, items };
+}
+
+/**
+ * `*.dds` completion for a bare-filename field: files from the mapped base dirs
+ * across roots (mod-first), deduped by filename. Returns null when the key is
+ * not a mapped bare-name field.
+ */
+export function provideBareNameCompletion(
+  settings: ParadoxSettings,
+  kind: string | null | undefined,
+  key: string
+): CompletionItem[] | null {
+  const dirs = bareNameBaseDirs(kind, key);
+  if (!dirs) return null;
+  const seen = new Set<string>();
+  const items: CompletionItem[] = [];
+  for (const { root, label } of assetRoots(settings)) {
+    for (const rel of dirs) {
+      let entries: string[];
+      try {
+        entries = fs.readdirSync(path.join(root, ...rel.split("/")));
+      } catch {
+        continue;
+      }
+      for (const name of entries) {
+        if (!name.toLowerCase().endsWith(".dds")) continue;
+        const low = name.toLowerCase();
+        if (seen.has(low)) continue;
+        seen.add(low);
+        items.push({
+          label: name,
+          kind: CompletionItemKind.File,
+          detail: `${rel} (${label})`,
+          sortText: name.toLowerCase(),
+        });
+      }
+    }
+  }
+  return items;
+}