@px-lsp/server 0.3.0 → 0.3.1

package/src/data/docsParser.ts

@@ -41,6 +41,8 @@ const SCOPE_LINE = /^(Supported [Ss]copes|Input [Ss]copes|Output [Ss]copes):\s*(
 const META_LINE =
   /^(Supported [Tt]argets|Targets?|Traits|Categories|Use [Aa]reas|Requires [Dd]ata|Wild[ _]?[Cc]ard|Global [Ll]ink):\s*(.*)$/;
 
+const braceDelta = (s: string): number => (s.match(/\{/g) ?? []).length - (s.match(/\}/g) ?? []).length;
+
 export function parseLog(content: string, kind: TokenKind): TokenData[] {
   const tokens: TokenData[] = [];
   const seen = new Set<string>();
@@ -50,6 +52,9 @@ export function parseLog(content: string, kind: TokenKind): TokenData[] {
   // True once a `usage:` header was seen for the current entry: subsequent
   // non-metadata lines are captured (with indentation) as the usage example.
   let inUsage = false;
+  // >0 while an inline (header-less) example is still open. Measured on the
+  // 1.19 dumps: 378 effects.log examples run over several lines.
+  let openBraces = 0;
   const flush = () => {
     if (current && current.name && !seen.has(current.name)) {
       current.doc = current.doc.trim();
@@ -61,6 +66,7 @@ export function parseLog(content: string, kind: TokenKind): TokenData[] {
     }
     current = null;
     inUsage = false;
+    openBraces = 0;
   };
 
   for (const rawLine of lines) {
@@ -71,8 +77,8 @@ export function parseLog(content: string, kind: TokenKind): TokenData[] {
     }
     const trimmed = line.trim();
     if (trimmed === "") {
-      // Blank lines inside a `usage:` block are structural; keep them.
-      if (current && inUsage && current.usage) current.usage += "\n";
+      // Blank lines inside a captured example are structural; keep them.
+      if (current && (inUsage || openBraces > 0) && current.usage) current.usage += "\n";
       continue;
     }
 
@@ -108,6 +114,18 @@ export function parseLog(content: string, kind: TokenKind): TokenData[] {
       continue;
     }
 
+    // An inline example that opened a block keeps capturing until the braces
+    // balance. A metadata line always ends the entry's body, so it wins over an
+    // example that never closes (the extractor's balance guard drops those).
+    if (openBraces > 0) {
+      if (applyMetaLine(current, trimmed)) {
+        openBraces = 0;
+        continue;
+      }
+      current.usage += "\n" + line;
+      openBraces += braceDelta(line);
+      continue;
+    }
     // A metadata line ends any open usage capture and is recorded structurally.
     if (applyMetaLine(current, trimmed)) {
       inUsage = false;
@@ -126,6 +144,7 @@ export function parseLog(content: string, kind: TokenKind): TokenData[] {
     // the usage example; anything after it stays prose.
     if (current.usage === undefined && SYNTAX_LINE.test(trimmed)) {
       current.usage = trimmed;
+      openBraces = Math.max(0, braceDelta(trimmed));
       continue;
     }
     // Otherwise: continuation of the description prose.
@@ -172,8 +191,6 @@ const MASKED_FIELD = /^(Mask|Name|Description):\s*(.*)$/;
 // `--- Static modifier types ---` and friends: section banners, not entries.
 const SECTION_BANNER = /^-{3,}/;
 
-const braceDelta = (s: string): number => (s.match(/\{/g) ?? []).length - (s.match(/\}/g) ?? []).length;
-
 /**
  * Markdown dump dialect (effects.log, triggers.log, event_targets.log of newer
  * titles): entries open at a `##`/`###` heading and run until the next one.

package/src/features/blockSnippets.ts

@@ -10,18 +10,25 @@
  *
  *  - the example's leading identifier must be the token's own name (dumps
  *    routinely paste a sibling's example: `add_title_law_effects` shows
- *    `add_title_law = …`);
+ *    `add_title_law = …`). A `<scope> = { name = { … } }` wrapper around a
+ *    single such block is peeled off first; any other placeholder key rejects;
  *  - the example must open a block and its braces must balance (truncated
  *    dumps that never close are dropped);
  *  - every key must be a plain lowercase identifier, or a `a/b/c` alternation
  *    of them (this drops pseudo-key weight lists, `X1 = { … } X2 = { … } …`);
- *  - a `#` comment means the example enumerates alternatives ("# or:") that
- *    cannot be collapsed into one template;
+ *  - a `#` comment is read ONLY when it says the field is optional
+ *    (`#Optional`, `# optional way to …`); every other comment means the
+ *    example enumerates alternatives ("# or:") or explains something we cannot
+ *    turn into script, and rejects the example;
  *  - `(optional)` and `...` truncate the body at that point;
  *  - `<name>` placeholders become tabstops, concrete example values become
  *    pre-filled tabstops.
  *
- * Both forms are produced at once: `snippet` for clients that declared
+ * An example that marks fields optional yields TWO templates rather than none:
+ * `snippet`/`plain` carry the required fields only, `full` carries every field
+ * the example shows.
+ *
+ * Both text forms are produced at once: `snippet` for clients that declared
  * snippetSupport, `plain` (no `${`, insertable as literal text) for the rest.
  */
 import type { TokenData } from "@px-lsp/protocol/types";
@@ -31,6 +38,12 @@ export interface BlockTemplate {
   snippet: string;
   /** Plain-text skeleton, free of `${`. */
   plain: string;
+  /**
+   * The same block with the fields the example marked `# optional` put back.
+   * Present only when the example marked at least one, so `full` never repeats
+   * what `snippet`/`plain` already say. Tabstops are numbered per form.
+   */
+  full?: { snippet: string; plain: string };
 }
 
 /** Keyed on the token object, so a reload or a game switch cannot serve a stale
@@ -54,6 +67,14 @@ const KEY = /^[a-z_][a-z0-9_]*$/;
 /** Everything from here on is optional or elided; the body stops. */
 const TRUNCATE = ["(optional)", "..."];
 
+/** A comment the dumps use to mark a field as not required: `#Optional`,
+ * `# optional way to get a reference`, `# Optional; if set, …`. Anything else
+ * after a `#` is prose or an alternation and rejects the example. */
+const OPTIONAL_COMMENT = /^#[ \t]*optional/i;
+
+/** A `<placeholder> = {` scope wrapper around the example. */
+const WRAPPER_HEAD = /^\s*<[^>]+>\s*=\s*\{/;
+
 interface Leaf {
   /** Raw text as written in the example. */
   text: string;
@@ -63,7 +84,10 @@ interface Leaf {
   alts: string[] | null;
 }
 
-type Item = { key: Leaf; value: Leaf | Body } | { key: null; value: Leaf };
+type Item = ({ key: Leaf; value: Leaf | Body } | { key: null; value: Leaf }) & {
+  /** The example's own `# optional` comment ended this item's line. */
+  optional: boolean;
+};
 
 interface Body {
   items: Item[];
@@ -74,11 +98,23 @@ interface Body {
 /** Pure extractor (exported for the accept/reject table in the tests). */
 export function extractBlockTemplate(name: string, usage: string | undefined): BlockTemplate | null {
   if (!usage) return null;
-  const text = usage.replace(/\r/g, "");
-  // "# or:" style comments enumerate mutually exclusive forms: not one template.
-  if (text.includes("#")) return null;
+  const stripped = stripOptionalComments(usage.replace(/\r/g, ""));
+  if (!stripped) return null;
+  let { text } = stripped;
+  const { optionalLines } = stripped;
+
+  // Some `usage:` blocks wrap the effect in the scope it has to run in
+  // (`<founding character> = { create_cadet_branch = { … } }`; 5 effects in the
+  // 1.19 dumps). The template is the inner block: the modder types it inside the
+  // scope they already mean. Blanking rather than slicing keeps line numbers,
+  // which the `# optional` marks are keyed on. The guards below then do the
+  // rest of the work: the wrapper is unwrapped only when its ONE item is a
+  // block named after the token.
+  const wrapper = WRAPPER_HEAD.test(text) ? unwrap(text) : text;
+  if (wrapper === null) return null;
+  text = wrapper;
 
-  const head = /^([A-Za-z_][A-Za-z0-9_]*)\s*=\s*\{/.exec(text);
+  const head = /^\s*([A-Za-z_][A-Za-z0-9_]*)\s*=\s*\{/.exec(text);
   if (!head || head[1] !== name) return null;
 
   const open = text.indexOf("{");
@@ -86,10 +122,75 @@ export function extractBlockTemplate(name: string, usage: string | undefined): B
   // Unbalanced, or something follows the block: not a template we can trust.
   if (close < 0 || text.slice(close + 1).trim() !== "") return null;
 
-  const body = new BodyParser(text, open + 1).parseBody();
+  const parser = new BodyParser(text, open + 1, optionalLines);
+  const body = parser.parseBody();
   if (body === null) return null;
+  // Every accepted "optional" comment must have landed on an item. One that did
+  // not (a lone `# optional effects…` line, or a comment on the line that only
+  // OPENS a nested block) says something about the example we cannot express.
+  for (const line of optionalLines) if (!parser.markedLines.has(line)) return null;
+
+  const minimal = { snippet: render(name, body, true, false), plain: render(name, body, false, false) };
+  if (!hasOptional(body)) return minimal;
+  return {
+    ...minimal,
+    full: { snippet: render(name, body, true, true), plain: render(name, body, false, true) },
+  };
+}
+
+/**
+ * Drops the `# optional` comments and reports which lines carried one; returns
+ * null when any OTHER `#` comment appears, which still rejects the example.
+ *
+ * A comment runs to the end of its line, and a following line whose first
+ * non-space character is `#` wraps the same comment (the dumps wrap long
+ * `# Optional, …` notes over three lines) and is dropped with it. Dropped
+ * lines are kept as empty lines so line numbers still address the example.
+ */
+function stripOptionalComments(text: string): { text: string; optionalLines: Set<number> } | null {
+  const lines = text.split("\n");
+  const out: string[] = [];
+  const optionalLines = new Set<number>();
+  let wrapping = false;
+  for (let i = 0; i < lines.length; i++) {
+    const hash = lines[i].indexOf("#");
+    if (hash < 0) {
+      out.push(lines[i]);
+      wrapping = false;
+      continue;
+    }
+    const before = lines[i].slice(0, hash);
+    // A continuation of the optional comment above.
+    if (wrapping && before.trim() === "") {
+      out.push("");
+      continue;
+    }
+    if (!OPTIONAL_COMMENT.test(lines[i].slice(hash))) return null;
+    // A comment on its own line marks no item.
+    if (before.trim() === "") return null;
+    out.push(before.trimEnd());
+    optionalLines.add(i);
+    wrapping = true;
+  }
+  return { text: out.join("\n"), optionalLines };
+}
 
-  return { snippet: render(name, body, true), plain: render(name, body, false) };
+/** True when the block, at any depth, has a field the example marked optional. */
+function hasOptional(body: Body): boolean {
+  return body.items.some((item) => item.optional || ("items" in item.value && hasOptional(item.value)));
+}
+
+/**
+ * Blanks everything outside the wrapper's braces (newlines kept, so line
+ * numbers still address the example). Null when the wrapper never closes or
+ * something follows it.
+ */
+function unwrap(text: string): string | null {
+  const open = text.indexOf("{");
+  const close = matchingBrace(text, open);
+  if (close < 0 || text.slice(close + 1).trim() !== "") return null;
+  const blank = (s: string) => s.replace(/[^\n]/g, " ");
+  return blank(text.slice(0, open + 1)) + text.slice(open + 1, close) + blank(text.slice(close));
 }
 
 /** Index of the `}` closing the `{` at `open`, or -1 when it never closes. */
@@ -103,14 +204,35 @@ function matchingBrace(text: string, open: number): number {
 }
 
 class BodyParser {
+  /** Lines of `optionalLines` an item actually ended on. */
+  readonly markedLines = new Set<number>();
+  /** Line number per character offset, so an item can be tied to its comment. */
+  private readonly lineAt: number[];
+
   constructor(
     private readonly text: string,
-    private i: number
-  ) {}
+    private i: number,
+    private readonly optionalLines: Set<number> = new Set()
+  ) {
+    this.lineAt = new Array<number>(text.length);
+    let line = 0;
+    for (let n = 0; n < text.length; n++) {
+      this.lineAt[n] = line;
+      if (text[n] === "\n") line++;
+    }
+  }
 
   /** Items of the block whose `{` was just consumed; null rejects the example. */
   parseBody(): Body | null {
     const items: Item[] = [];
+    const push = (item: Omit<Item, "optional">, end = this.i): void => {
+      // A comment (already stripped) on the line the item ENDS on marked it
+      // optional, so measure the end before any trailing whitespace is skipped.
+      const line = this.lineAt[end - 1] ?? 0;
+      const optional = this.optionalLines.has(line);
+      if (optional) this.markedLines.add(line);
+      items.push({ ...item, optional } as Item);
+    };
     for (;;) {
       this.skipSpace();
       if (this.i >= this.text.length) return null;
@@ -126,11 +248,12 @@ class BodyParser {
       }
       const first = this.readLeaf();
       if (!first) return null;
+      const firstEnd = this.i;
       this.skipSpace();
       if (this.text[this.i] !== "=") {
         // A bare word only makes sense as a `<effects>`-style placeholder.
         if (!first.placeholder) return null;
-        items.push({ key: null, value: first });
+        push({ key: null, value: first }, firstEnd);
         continue;
       }
       if (first.placeholder) return null; // a key we cannot name is not a key
@@ -141,12 +264,12 @@ class BodyParser {
         this.i++;
         const nested = this.parseBody();
         if (nested === null) return null;
-        items.push({ key: first, value: nested });
+        push({ key: first, value: nested });
         continue;
       }
       const value = this.readLeaf();
       if (!value) return null;
-      items.push({ key: first, value });
+      push({ key: first, value });
     }
   }
 
@@ -183,13 +306,21 @@ class BodyParser {
 
 // ---- rendering -------------------------------------------------------------
 
-function render(name: string, body: Body, snippet: boolean): string {
-  return `${name} = {\n${renderBody(body, "\t", snippet, { n: 0 }).join("")}}`;
+/** `all` = the "all fields" form; false drops what the example called optional. */
+function render(name: string, body: Body, snippet: boolean, all: boolean): string {
+  return `${name} = {\n${renderBody(body, "\t", snippet, { n: 0 }, all).join("")}}`;
 }
 
-function renderBody(body: Body, indent: string, snippet: boolean, counter: { n: number }): string[] {
+function renderBody(
+  body: Body,
+  indent: string,
+  snippet: boolean,
+  counter: { n: number },
+  all: boolean
+): string[] {
   const lines: string[] = [];
   for (const item of body.items) {
+    if (item.optional && !all) continue;
     if (item.key === null) {
       lines.push(`${indent}${leaf(item.value, snippet, counter)}\n`);
       continue;
@@ -198,7 +329,7 @@ function renderBody(body: Body, indent: string, snippet: boolean, counter: { n:
     const key = item.key.alts ? leaf(item.key, snippet, counter) : item.key.text;
     if ("items" in item.value) {
       lines.push(`${indent}${key} = {\n`);
-      lines.push(...renderBody(item.value, indent + "\t", snippet, counter));
+      lines.push(...renderBody(item.value, indent + "\t", snippet, counter, all));
       lines.push(`${indent}}\n`);
       continue;
     }

package/src/features/calendarDates.ts

@@ -12,7 +12,7 @@ import {
   type Range,
 } from "vscode-languageserver/node";
 import type { TextDocument } from "vscode-languageserver-textdocument";
-import { displayDate, isValidScriptDate, monthsOf, type CalendarSetting } from "@px-lsp/protocol/calendar";
+import { displayDate, isValidScriptDate, type CalendarSetting } from "@px-lsp/protocol/calendar";
 import { getLineText, isScriptLanguage } from "../documents";
 
 interface DateToken {
@@ -47,7 +47,7 @@ export function dateTokensOnLine(cal: CalendarSetting, lineText: string): DateTo
     const quotesBefore = (code.slice(0, match.index).match(/"/g) ?? []).length;
     if (quotesBefore % 2 === 1) continue;
     const [y, m, d] = [Number(match[1]), Number(match[2]), Number(match[3])];
-    if (!isValidScriptDate(cal, y, m, d)) continue;
+    if (!isValidScriptDate(y, m, d)) continue;
     tokens.push({ start: match.index, end: match.index + match[0].length, y, m, d });
   }
   return tokens;
@@ -72,11 +72,14 @@ export function calendarHints(cal: CalendarSetting, document: TextDocument, rang
   return hints;
 }
 
-/** Hover on a date token: the display form plus the calendar rule in force. */
+/** Hover on a date token: the display form plus the calendar rule in force,
+ * labelled with where the rule came from (`.px-toolkit/calendar.json` or the
+ * `px.calendar` setting). */
 export function provideDateHover(
   cal: CalendarSetting | undefined,
   document: TextDocument,
-  position: Position
+  position: Position,
+  source = "px.calendar"
 ): Hover | null {
   if (!cal || !isScriptLanguage(document.languageId)) return null;
   const lineText = getLineText(document, position.line);
@@ -90,7 +93,7 @@ export function provideDateHover(
   const eras = cal.before ? `${cal.before} / ${cal.after}` : cal.after;
   const value =
     `\`${script}\` → **${display}**\n\n` +
-    `*px.calendar: epoch ${cal.epoch} (${eras}), ${monthsOf(cal).length} months*`;
+    `*${source}: epoch ${cal.epoch} (${eras})${cal.months ? ", the mod's month names" : ""}*`;
   return {
     contents: { kind: MarkupKind.Markdown, value },
     range: {

package/src/features/completion.ts

@@ -72,6 +72,7 @@ import type { ParadoxSettings } from "@px-lsp/protocol/protocol";
 import { assetDirContext, provideAssetDirCompletion, provideBareNameCompletion } from "./assetPaths";
 import { snippetSupport } from "../clientMode";
 import { blockTemplateFor } from "./blockSnippets";
+import { skeletonsAt } from "./definitionSkeletons";
 
 /** Cap on items per response; the client re-queries per keystroke (isIncomplete). */
 export const MAX_ITEMS = 1000;
@@ -477,13 +478,46 @@ export class CompletionFeature {
       }
       ranked.push(out);
     }
-    const structured =
-      structureItems.length > 0
-        ? [...structureItems.filter((s) => matchesTypedWord(wordLow, s.label)), ...ranked]
-        : ranked;
+    const lead = [...structureItems, ...this.skeletonItems(result, offset, entry, lineSuffix)].filter((s) =>
+      matchesTypedWord(wordLow, s.label)
+    );
+    const structured = lead.length > 0 ? [...lead, ...ranked] : ranked;
     return finalize(structured, typedWord, limit, /*alreadyFiltered*/ true);
   }
 
+  /**
+   * Definition and child-block skeletons (schema/skeletons.ts) as items of their
+   * own kind, ranked right after the block's structure keys.
+   *
+   * Gated on a BLANK line tail: a multi-line insert must not land inside an
+   * existing statement, and half a definition pasted over `= { … }` is worse
+   * than no offer. That gate also keeps these items out of every rank-eval
+   * sample, which always leaves the `= …` in place when it strips a key, so the
+   * ranking of existing items is unchanged by construction.
+   */
+  private skeletonItems(
+    result: ParseResult,
+    offset: number,
+    entry: SchemaEntry | null,
+    lineSuffix: string
+  ): CompletionItem[] {
+    if (!entry?.kind || lineSuffix.trim() !== "") return [];
+    return skeletonsAt(result, offset, entry.kind, activeProfile().skeletons).map((offer) => {
+      const item: CompletionItem = {
+        label: offer.label,
+        kind: CompletionItemKind.Snippet,
+        detail: offer.detail,
+        // Structure tier, coldest rank: after every structure key of the block
+        // and ahead of the token list. At a file's top level there are no
+        // structure keys, so the skeleton leads a list that otherwise has
+        // nothing to offer outside a definition body.
+        sortText: TIER_STRUCTURE + rankBucket(99) + SRC_MOD + offer.label,
+      };
+      setInsert(item, offer.text.snippet, offer.text.plain);
+      return item;
+    });
+  }
+
   /**
    * Completing a scripted effect/trigger/modifier inserts a ready-to-fill
    * block: one `PARAM = <tabstop>` line per $PARAM$ the definition's body

package/src/features/definitionSkeletons.ts

@@ -0,0 +1,109 @@
+/**
+ * Which definition skeletons (schema/skeletons.ts) apply at a cursor, and how
+ * they read. One resolver, three consumers: key-position completion, the
+ * paradox/snippets request, and the unit tests.
+ *
+ * Placement is the whole trick. A definition skeleton belongs OUTSIDE every
+ * definition body (the file's top level, where completion has nothing useful to
+ * say today); a child-block skeleton belongs directly INSIDE a definition body,
+ * where that block key is valid. Anywhere else the answer is nothing.
+ */
+import { blockStackFromParse } from "../context";
+import type { ParseResult } from "../parser";
+import {
+  renderBlockSkeleton,
+  renderDefinitionSkeleton,
+  type KindSkeleton,
+  type RenderedSkeleton,
+} from "../schema/skeletons";
+
+export interface SkeletonOffer {
+  /** Stable id: `<kind>` for the definition, `<kind>.<block>` for a child block. */
+  id: string;
+  /** What the item reads as: "new event", "option block". */
+  label: string;
+  /** How many of the game's own definitions the shape was measured over. */
+  detail: string;
+  /** A whole definition, or one of its child blocks. */
+  form: "definition" | "block";
+  text: RenderedSkeleton;
+}
+
+/** Depth of the enclosing definition bodies at `offset`; 0 = the file's top level. */
+function definitionDepth(parse: ParseResult, offset: number): number {
+  return blockStackFromParse(parse, offset).filter((s) => s !== "<anon>").length;
+}
+
+/** `3214` → `3,214`, so a detail line reads as a measurement and not as an id. */
+function count(n: number): string {
+  return n.toLocaleString("en-US");
+}
+
+/**
+ * The value the document already declares for the kind's header key
+ * (`namespace = intrigue`), or undefined when it declares none.
+ */
+function headerValue(parse: ParseResult, key: string): string | undefined {
+  for (const stmt of parse.root.statements) {
+    if (stmt.kind !== "assignment" || stmt.key.quoted || stmt.key.text !== key) continue;
+    if (stmt.value?.kind === "scalar") return stmt.value.text;
+  }
+  return undefined;
+}
+
+/**
+ * Skeletons offered at `offset` in a document the schema classifies as `kind`.
+ * Empty when the game has no measured skeleton for the kind, or when the cursor
+ * is deeper than a definition body (an effect block wants effects, not a form).
+ */
+export function skeletonsAt(
+  parse: ParseResult,
+  offset: number,
+  kind: string,
+  skeletons: Record<string, KindSkeleton> | undefined
+): SkeletonOffer[] {
+  const skel = skeletons?.[kind];
+  if (!skel) return [];
+  const depth = definitionDepth(parse, offset);
+  if (depth === 0) return [definitionOffer(parse, kind, skel)];
+  if (depth !== 1) return [];
+  return blockOffers(kind, skel);
+}
+
+/**
+ * Every skeleton the document's kind has, position-independent: what a picker
+ * offers, where the modder chooses the insert point rather than the cursor.
+ */
+export function skeletonsFor(
+  parse: ParseResult,
+  kind: string,
+  skeletons: Record<string, KindSkeleton> | undefined
+): SkeletonOffer[] {
+  const skel = skeletons?.[kind];
+  if (!skel) return [];
+  return [definitionOffer(parse, kind, skel), ...blockOffers(kind, skel)];
+}
+
+function definitionOffer(parse: ParseResult, kind: string, skel: KindSkeleton): SkeletonOffer {
+  const existing = skel.nameFromHeader ? headerValue(parse, skel.nameFromHeader) : undefined;
+  return {
+    id: kind,
+    label: `new ${kind.replace(/_/g, " ")}`,
+    detail: `skeleton measured over ${count(skel.sampled)} vanilla definitions`,
+    form: "definition",
+    text: renderDefinitionSkeleton(kind, skel, {
+      headerValue: existing,
+      withHeader: skel.nameFromHeader !== undefined && existing === undefined,
+    }),
+  };
+}
+
+function blockOffers(kind: string, skel: KindSkeleton): SkeletonOffer[] {
+  return Object.entries(skel.blocks ?? {}).map(([name, block]) => ({
+    id: `${kind}.${name}`,
+    label: `${name} block`,
+    detail: `skeleton measured over ${count(block.sampled)} vanilla ${name} blocks`,
+    form: "block" as const,
+    text: renderBlockSkeleton(name, block),
+  }));
+}

package/src/features/inlayHints.ts

@@ -21,6 +21,7 @@ import type { SchemaEntry } from "../schema/types";
 import type { Scope } from "../scopes/model";
 import { walkStatements } from "../parser";
 import { calendarHints } from "./calendarDates";
+import type { CalendarSetting } from "@px-lsp/protocol/calendar";
 
 const HINT_MAX_LEN = 60;
 
@@ -34,12 +35,14 @@ export function provideInlayHints(
   document: TextDocument,
   range: Range,
   rootScopes: Set<Scope> | null,
-  entry: SchemaEntry | null
+  entry: SchemaEntry | null,
+  /** The mod's own `.px-toolkit/calendar.json` when it has one; defaults to the setting. */
+  calendar: CalendarSetting | undefined = settings.calendar
 ): InlayHint[] {
   if (document.languageId === "paradox-loc") return translationOverlayHints(data, settings, document, range);
   const hints = locPreviewHints(data, document, range);
   if (settings.scopeInlayHints) hints.push(...scopeHints(data, document, range, rootScopes, entry));
-  if (settings.calendar) hints.push(...calendarHints(settings.calendar, document, range));
+  if (calendar) hints.push(...calendarHints(calendar, document, range));
   return hints;
 }