@px-lsp/protocol 0.1.0 → 0.2.1

package/dist/protocol.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.scopeAtRequest = exports.dependenciesRequest = exports.eventValueOptionsRequest = exports.EVENT_VOCABULARY_MAX_VALUES = exports.EVENT_VOCABULARY_MAX_TOKENS = exports.eventVocabularyRequest = exports.eventBannerRequest = exports.eventGraphRequest = exports.guiWidgetEditRequest = exports.guiSourceEditRequest = exports.guiSaveValuesRequest = exports.GUI_PREVIEW_MAX = exports.guiPreviewRequest = exports.guiVocabularyRequest = exports.guiDependenciesRequest = exports.guiWidgetInfoRequest = exports.guiLayoutRequest = exports.guiTreeRequest = exports.eventDetailRequest = exports.overridesRequest = exports.locCoverageRequest = exports.modOverviewRequest = exports.progressNotification = exports.indexChangedNotification = exports.statusNotification = exports.lookupLocRequest = exports.indexStatsRequest = exports.reloadDocsRequest = exports.modFileChangedNotification = exports.configChangedNotification = exports.allClientCommandIds = exports.clientCommands = void 0;
+exports.DYNASTY_SKILLS = exports.dynastyTreeRequest = exports.modifierFormatsRequest = exports.definitionEditRequest = exports.definitionFormRequest = exports.scopeAtRequest = exports.snippetsRequest = exports.dependenciesRequest = exports.eventValueOptionsRequest = exports.DEFINITION_FORM_MAX_EXAMPLE = exports.DEFINITION_FORM_MAX_SAMPLED = exports.EVENT_VOCABULARY_MAX_VALUES = exports.EVENT_VOCABULARY_MAX_TOKENS = exports.eventVocabularyRequest = exports.eventBannerRequest = exports.eventGraphRequest = exports.guiWidgetEditRequest = exports.guiSourceEditRequest = exports.guiSaveValuesRequest = exports.GUI_PREVIEW_MAX = exports.guiPreviewRequest = exports.guiVocabularyRequest = exports.guiDependenciesRequest = exports.guiWidgetInfoRequest = exports.guiLayoutRequest = exports.guiTreeRequest = exports.exampleWikiEntryRequest = exports.exampleWikiVocabularyKinds = exports.exampleWikiVariableKinds = exports.exampleWikiRequest = exports.eventDetailRequest = exports.overridesRequest = exports.locCoverageRequest = exports.modOverviewRequest = exports.progressNotification = exports.indexChangedNotification = exports.statusNotification = exports.locTextRequest = exports.lookupLocRequest = exports.indexStatsRequest = exports.reloadDocsRequest = exports.modFileChangedNotification = exports.configChangedNotification = exports.allClientCommandIds = exports.clientCommands = void 0;
 // ---- client command ids ----------------------------------------------------
 /**
  * Client commands the server references in code actions and hover links (part
@@ -14,6 +14,7 @@ exports.clientCommands = {
     editLocalization: "px.editLocalization",
     openLocalizationSideBySide: "px.openLocalizationSideBySide",
     showReferences: "px.showReferences",
+    showExamplesWiki: "px.showExamplesWiki",
 };
 /** Every id in {@link clientCommands}: what a fully capable client registers. */
 exports.allClientCommandIds = Object.values(exports.clientCommands);
@@ -29,6 +30,24 @@ exports.indexStatsRequest = "paradox/indexStats";
 /** Request: look up localization entries for a key; {@link LookupLocParams} -> {@link LocEntryInfo}[].
  * Mod entries shadow vanilla ones (the full list is returned, mod first). */
 exports.lookupLocRequest = "paradox/lookupLoc";
+/**
+ * Request: a localization value as the PLAYER reads it;
+ * {@link LocTextParams} -> {@link LocTextResult}.
+ *
+ * {@link lookupLocRequest} answers the value verbatim, which is what an editor
+ * needs. A panel that SHOWS the value needs the sentence: the games write a
+ * culture parameter as `"The [GetTrait('rough_terrain_expert').GetName(
+ * GetNullCharacter )] Commander Trait is more common"` (145 of the 280
+ * parameter values with a real call take that one shape), and a modder reading
+ * a form must not be shown the brackets.
+ *
+ * Everything the renderer knows is DERIVED: the words come from the loc index
+ * (mod entries shadow the game's), the kind a `Get<Something>('name')` chain
+ * names comes from the definition index, and the loc key that kind's names take
+ * comes from the active profile's schema. No table of function names, so a
+ * workspace of any of the games gets the same behavior from its own schema.
+ */
+exports.locTextRequest = "paradox/locText";
 // ---- server -> client ------------------------------------------------------
 /** Notification: data health for the status bar; payload {@link StatusPayload}. */
 exports.statusNotification = "paradox/status";
@@ -48,12 +67,46 @@ exports.locCoverageRequest = "paradox/locCoverage";
 exports.overridesRequest = "paradox/overrides";
 /** Request: full event detail for the graph inspector; {@link EventDetailParams} -> {@link EventDetail} | null. */
 exports.eventDetailRequest = "paradox/eventDetail";
+/**
+ * Request: the searchable catalog behind the Examples Wiki;
+ * `null` -> {@link ExampleWikiIndex}.
+ *
+ * One compact row per name the server knows about, so a client can filter and
+ * rank the whole vocabulary without asking again. Everything expensive (the
+ * full documentation, the usage block, the vanilla sites) is left to
+ * {@link exampleWikiEntryRequest}.
+ */
+exports.exampleWikiRequest = "paradox/exampleWiki";
+/** The {@link ExampleWikiKind}s whose rows come from the definition index. */
+exports.exampleWikiVariableKinds = [
+    "variable",
+    "local_variable",
+    "global_variable",
+    "variable_list",
+    "local_variable_list",
+    "global_variable_list",
+    "list",
+];
+/**
+ * The {@link ExampleWikiKind}s whose rows are script grammar rather than a
+ * name from a dump or an index. One filter chip covers both.
+ */
+exports.exampleWikiVocabularyKinds = ["keyword", "scope_word"];
+/**
+ * Request: everything the toolkit knows about ONE Examples Wiki row;
+ * {@link ExampleWikiEntryParams} -> {@link ExampleWikiDetail} | null.
+ *
+ * `null` means the name is not in the catalog. Vanilla example sites are
+ * searched on demand and come back as absolute paths, so a client can open
+ * the file at the line without resolving anything itself.
+ */
+exports.exampleWikiEntryRequest = "paradox/exampleWikiEntry";
 /** Request: GUI widget tree for a .gui document; {@link GuiTreeParams} -> {@link GuiTree}. */
 exports.guiTreeRequest = "paradox/guiTree";
 /**
  * Request: rendered GUI layout for a .gui document;
  * {@link GuiLayoutParams} -> {@link GuiLayoutResult}. Rectangles come from
- * the measured layout engine (docs/gui-designer/calibration/spec.md), with
+ * the measured layout engine (docs/gui-designer/spec.md), with
  * templates/types resolved against the vanilla + mod gui tree.
  */
 exports.guiLayoutRequest = "paradox/guiLayout";
@@ -169,6 +222,20 @@ exports.eventVocabularyRequest = "paradox/eventVocabulary";
 /** Caps: an editor lists a page at a time, and these ride on every open. */
 exports.EVENT_VOCABULARY_MAX_TOKENS = 600;
 exports.EVENT_VOCABULARY_MAX_VALUES = 400;
+/**
+ * Most values {@link DefinitionFormKey.sampled} carries, and the point past
+ * which a key is taken to have no value SET at all (a key whose value differs
+ * per definition is a free field, not a list to offer).
+ */
+exports.DEFINITION_FORM_MAX_SAMPLED = 80;
+/**
+ * How long a block body {@link DefinitionFormKey.example} may be. A placeholder
+ * is read at a glance, and the shortest bodies a game writes for a block key
+ * (a trait's `triggered_opinion`, a culture's `parameters`) fit well inside
+ * this; a longer one is cut with an ellipsis rather than dropped, because half
+ * a real body still says what the key wants.
+ */
+exports.DEFINITION_FORM_MAX_EXAMPLE = 120;
 /**
  * Request: the value set a VALUE belongs to, resolved through the definition
  * index; {@link EventValueOptionsParams} -> {@link EventValueOptionsResult} |
@@ -187,6 +254,23 @@ exports.eventValueOptionsRequest = "paradox/eventValueOptions";
  * (uri + position) or by name (optionally disambiguated by kind).
  */
 exports.dependenciesRequest = "paradox/dependencies";
+/**
+ * Request: the code snippets a host can offer for one open script document;
+ * {@link SnippetsParams} -> {@link SnippetsResult}. Answers for OPEN script
+ * documents only (the server reads the client's text, not the disk); a document
+ * it does not know answers with an EMPTY list, never an error.
+ *
+ * Two sources, neither hand-written. The definition and child-block skeletons
+ * are the measured shape of the document folder's own definition kind (at least
+ * half of the game's definitions of that kind carry each key, in the median
+ * order they hold there). The token entries are the block form of the `usage:`
+ * example the game's own script_docs dump ships for an engine trigger or effect,
+ * filtered to the block the cursor sits in.
+ *
+ * Every entry carries BOTH insert forms, exactly like completion does: `snippet`
+ * for a host that expands `${1:…}` tabstops, `plain` for one that does not.
+ */
+exports.snippetsRequest = "paradox/snippets";
 /**
  * Request: the inferred scope chain at a cursor position;
  * {@link ScopeAtParams} -> {@link ScopeAtResult} | null. Answers for OPEN
@@ -199,3 +283,76 @@ exports.dependenciesRequest = "paradox/dependencies";
  * asserts more than the derived link tables actually say.
  */
 exports.scopeAtRequest = "paradox/scopeAt";
+// ---- content creators --------------------------------------------------------
+/**
+ * Request: everything a visual creator needs to draw a form for one definition
+ * kind; {@link DefinitionFormParams} -> {@link DefinitionForm} | null (null =
+ * the active game's schema has no such kind, which is the honest answer for a
+ * client asking about content this game does not have).
+ *
+ * Nothing in the answer is hand-written for the creator: the folder, the loc
+ * key patterns and the icon folder come from the schema table, the keys from
+ * the harvested `_*.info` structures, the option lists from the definition
+ * index (the same resolver {@link eventValueOptionsRequest} answers with) and
+ * `existing` from the same index walk {@link modOverviewRequest} does. A game
+ * patch that adds a key or a value changes the form without a release.
+ */
+exports.definitionFormRequest = "paradox/definitionForm";
+/**
+ * Request: text edits that write a definition into a script file;
+ * {@link DefinitionEditParams} -> {@link DefinitionEditResult}. The script
+ * sibling of {@link guiSourceEditRequest}, over the same span model, and with
+ * the same division of labour: the server never writes, it returns offsets
+ * into the text it was handed and the host applies them as ONE
+ * `WorkspaceEdit`, which keeps undo and dirty state in the editor.
+ *
+ * Offsets are UTF-16 into `params.text` (the document text, with no BOM, the
+ * way an editor delivers it), computed against that one text and applied
+ * end-first. Every edit is surgical, so a file's other definitions, its
+ * comments, its CRLF and its indentation stay byte-identical.
+ */
+exports.definitionEditRequest = "paradox/definitionEdit";
+/**
+ * Request: how the GAME prints each modifier; {@link ModifierFormatsParams} ->
+ * {@link ModifierFormatsResult} | null (null = the active profile names no
+ * formats source, or the game folder is not configured).
+ *
+ * A creator that lets a modder add `monthly_income = 0.5` has to show what the
+ * player will see, and the player sees "[gold_i] +0.50 Monthly Income" in
+ * green. None of that is written here: the flags come from the game's own
+ * `common/modifier_definition_formats/` (documented by `_definitions.info`
+ * there), every word comes from the loc index, and every icon comes from the
+ * `texticon` blocks of the game's `gui/texticons.gui`. A modifier no format
+ * block names gets the file's documented defaults, so the answer covers every
+ * modifier token the server knows rather than only the formatted ones.
+ */
+exports.modifierFormatsRequest = "paradox/modifierFormats";
+/**
+ * Request: a dynasty as a family tree; {@link DynastyTreeParams} ->
+ * {@link DynastyTreeResult}.
+ *
+ * Two answers behind one method. Without `dynasty` the result is the picker
+ * list: every dynasty the index knows, mod entries first. With `dynasty` it is
+ * that dynasty's houses and members, read out of the game's own
+ * `history/characters` files.
+ *
+ * Everything is DERIVED: the folders come from the active profile's schema
+ * (`dynasty`, `dynasty_house`, `character` kinds), the members from the
+ * character blocks themselves, the display names from the loc index. A profile
+ * whose schema has no `dynasty` kind answers `supported: false` and empty
+ * lists, which is what a client shows instead of an empty tree.
+ */
+exports.dynastyTreeRequest = "paradox/dynastyTree";
+/**
+ * The character-level skill keys, in the order a client shows them. MEASURED
+ * over the vanilla `history/characters` corpus (2026-09-03): stewardship 8 964,
+ * martial 8 940, diplomacy 8 908, intrigue 8 892, learning 495, prowess 150.
+ */
+exports.DYNASTY_SKILLS = [
+    "diplomacy",
+    "martial",
+    "stewardship",
+    "intrigue",
+    "learning",
+    "prowess",
+];

package/dist/workshopMeta.d.ts

@@ -0,0 +1,40 @@
+/** Title/description pair of one Workshop language. Absent field = not translated. */
+export interface WorkshopTranslation {
+    title?: string;
+    description?: string;
+}
+/** The fields of `workshop.json` this toolkit reads or writes. */
+export interface WorkshopMeta {
+    /** Workshop item id (decimal string), for the games whose descriptor has no field for it. */
+    publishedFileId?: string;
+    /** The item's description in the default language, BBCode as Steam renders it. */
+    description?: string;
+    /** Keyed by Steam API language code (`german`, `schinese`, ...), never the default language. */
+    translations?: Record<string, WorkshopTranslation>;
+}
+/** The parsed `<configDir>/workshop.json`, or null when absent/unreadable. */
+export declare function readWorkshopMeta(configDir: string): WorkshopMeta | null;
+/**
+ * Merge `patch` into the record and write it back. Unknown keys of the file
+ * survive; a patch key set to `undefined` is left as it was. `translations`
+ * replaces as a whole (the caller edits the full map).
+ */
+export declare function upsertWorkshopMeta(configDir: string, patch: WorkshopMeta): void;
+/**
+ * The languages the Workshop accepts item text in: Steam's API language codes
+ * with their English names, in Steam's documented order.
+ * https://partner.steamgames.com/doc/store/localization/languages
+ */
+export declare const STEAM_LANGUAGES: readonly {
+    api: string;
+    label: string;
+}[];
+/** English name of a Steam API language code; the code itself when unknown. */
+export declare function steamLanguageLabel(api: string): string;
+/**
+ * Steam API language code for a Paradox localization folder language
+ * (`translationCore.ts` LOC_LANGUAGES), or null when Steam has no counterpart.
+ * The two vocabularies differ where Steam's codes predate its own store pages
+ * (`koreana`, `schinese`).
+ */
+export declare function steamLanguageForLoc(locLanguage: string): string | null;

package/dist/workshopMeta.js

@@ -0,0 +1,146 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.STEAM_LANGUAGES = void 0;
+exports.readWorkshopMeta = readWorkshopMeta;
+exports.upsertWorkshopMeta = upsertWorkshopMeta;
+exports.steamLanguageLabel = steamLanguageLabel;
+exports.steamLanguageForLoc = steamLanguageForLoc;
+/**
+ * The mod's local Workshop record: `<mod>/<configDir>/workshop.json`. It holds
+ * what the game's own descriptor has no field for - the item's description and
+ * its per-language translations (title + description shown to Workshop
+ * visitors browsing Steam in that language), plus the published id for the
+ * `.metadata` games (launcher-`.mod` games keep the id in `remote_file_id`).
+ *
+ * The local file is the canonical copy once the user manages the item from the
+ * toolkit: uploads read from here, and "fetch" pulls the live values down into
+ * it. Reads and writes are merge-preserving: keys this version does not know
+ * survive a round trip.
+ *
+ * No `vscode` imports here: this module is unit-tested in plain Node.
+ */
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+/** The parsed `<configDir>/workshop.json`, or null when absent/unreadable. */
+function readWorkshopMeta(configDir) {
+    try {
+        const raw = JSON.parse(fs.readFileSync(path.join(configDir, "workshop.json"), "utf8"));
+        if (typeof raw !== "object" || raw === null)
+            return null;
+        return raw;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Merge `patch` into the record and write it back. Unknown keys of the file
+ * survive; a patch key set to `undefined` is left as it was. `translations`
+ * replaces as a whole (the caller edits the full map).
+ */
+function upsertWorkshopMeta(configDir, patch) {
+    const file = path.join(configDir, "workshop.json");
+    const current = (readWorkshopMeta(configDir) ?? {});
+    for (const [key, value] of Object.entries(patch)) {
+        if (value !== undefined)
+            current[key] = value;
+    }
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, JSON.stringify(current, null, 2) + "\n", "utf8");
+}
+/**
+ * The languages the Workshop accepts item text in: Steam's API language codes
+ * with their English names, in Steam's documented order.
+ * https://partner.steamgames.com/doc/store/localization/languages
+ */
+exports.STEAM_LANGUAGES = [
+    { api: "arabic", label: "Arabic" },
+    { api: "bulgarian", label: "Bulgarian" },
+    { api: "schinese", label: "Chinese (Simplified)" },
+    { api: "tchinese", label: "Chinese (Traditional)" },
+    { api: "czech", label: "Czech" },
+    { api: "danish", label: "Danish" },
+    { api: "dutch", label: "Dutch" },
+    { api: "english", label: "English" },
+    { api: "finnish", label: "Finnish" },
+    { api: "french", label: "French" },
+    { api: "german", label: "German" },
+    { api: "greek", label: "Greek" },
+    { api: "hungarian", label: "Hungarian" },
+    { api: "indonesian", label: "Indonesian" },
+    { api: "italian", label: "Italian" },
+    { api: "japanese", label: "Japanese" },
+    { api: "koreana", label: "Korean" },
+    { api: "norwegian", label: "Norwegian" },
+    { api: "polish", label: "Polish" },
+    { api: "portuguese", label: "Portuguese" },
+    { api: "brazilian", label: "Portuguese (Brazil)" },
+    { api: "romanian", label: "Romanian" },
+    { api: "russian", label: "Russian" },
+    { api: "spanish", label: "Spanish (Spain)" },
+    { api: "latam", label: "Spanish (Latin America)" },
+    { api: "swedish", label: "Swedish" },
+    { api: "thai", label: "Thai" },
+    { api: "turkish", label: "Turkish" },
+    { api: "ukrainian", label: "Ukrainian" },
+    { api: "vietnamese", label: "Vietnamese" },
+];
+/** English name of a Steam API language code; the code itself when unknown. */
+function steamLanguageLabel(api) {
+    return exports.STEAM_LANGUAGES.find((l) => l.api === api)?.label ?? api;
+}
+/**
+ * Steam API language code for a Paradox localization folder language
+ * (`translationCore.ts` LOC_LANGUAGES), or null when Steam has no counterpart.
+ * The two vocabularies differ where Steam's codes predate its own store pages
+ * (`koreana`, `schinese`).
+ */
+function steamLanguageForLoc(locLanguage) {
+    const map = {
+        english: "english",
+        french: "french",
+        german: "german",
+        spanish: "spanish",
+        russian: "russian",
+        korean: "koreana",
+        simp_chinese: "schinese",
+        japanese: "japanese",
+        polish: "polish",
+        braz_por: "brazilian",
+        turkish: "turkish",
+    };
+    return map[locLanguage] ?? null;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@px-lsp/protocol",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "license": "GPL-3.0-or-later",
   "description": "Wire contract (custom LSP requests/notifications, settings types) and shared helpers for the px-lsp language server and its clients.",
   "keywords": [

package/src/arrays.ts

@@ -1,16 +1,16 @@
-/** Array helpers shared by the server and the client. */
-
-/**
- * Append every element of `source` to `target`.
- *
- * `target.push(...source)` passes one argument per element and throws
- * `RangeError: Maximum call stack size exceeded` past ~125k elements (measured,
- * node 24, default stack). On the index paths that is a size-triggered crash:
- * one engine/vanilla root already carries ~460k definitions and one generated
- * mod file can carry six figures on its own. The loop has no ceiling and
- * measures the same as the spread (2M elements appended in 10k pieces: 23 ms
- * loop vs 22 ms spread; as one 500k piece: 5.5 ms loop vs 9.6 ms spread).
- */
-export function pushAll<T>(target: T[], source: readonly T[]): void {
-  for (let i = 0; i < source.length; i++) target.push(source[i]);
-}
+/** Array helpers shared by the server and the client. */
+
+/**
+ * Append every element of `source` to `target`.
+ *
+ * `target.push(...source)` passes one argument per element and throws
+ * `RangeError: Maximum call stack size exceeded` past ~125k elements (measured,
+ * node 24, default stack). On the index paths that is a size-triggered crash:
+ * one engine/vanilla root already carries ~460k definitions and one generated
+ * mod file can carry six figures on its own. The loop has no ceiling and
+ * measures the same as the spread (2M elements appended in 10k pieces: 23 ms
+ * loop vs 22 ms spread; as one 500k piece: 5.5 ms loop vs 9.6 ms spread).
+ */
+export function pushAll<T>(target: T[], source: readonly T[]): void {
+  for (let i = 0; i < source.length; i++) target.push(source[i]);
+}

package/src/calendar.ts

@@ -0,0 +1,183 @@
+/**
+ * Custom calendar display: total-conversion mods (AGoT, LotR, Hegemonia...)
+ * keep script dates on the engine's single increasing year axis but *display*
+ * them on their own era system, e.g. epoch 4000 means script year 3000 shows
+ * as "1000 BC" and 4000 as "1 AD". The mapping cannot be detected from mod
+ * files, so the mod declares it once in `px.calendar` (workspace settings,
+ * committed with the mod).
+ *
+ * Pure logic, no `vscode` imports: shared by the language server (inlay hints,
+ * hover) and the extension (the Insert Date command), unit-tested in plain
+ * Node.
+ */
+
+export interface CalendarSetting {
+  /** Script year displayed as year 1 of the `after` era (no year zero). */
+  epoch: number;
+  /** Era label for script years >= epoch ("AD", "TA"...). */
+  after: string;
+  /** Era label for script years < epoch ("BC"). Omitted = single-era
+   * calendar: years before the epoch get no display form. */
+  before?: string;
+  /**
+   * The engine's twelve months under the mod's own names, first month first.
+   * Omitted = January to December. Only the NAMES are the mod's: the game has
+   * twelve months of fixed length (31 28 31 30 31 30 31 31 30 31 30 31, no
+   * leap years) and no script can change that, so a date's month and day are
+   * always the engine's and only read differently.
+   */
+  months?: string[];
+}
+
+/** Days per engine month; what a script date's day is bounded by. */
+export const ENGINE_MONTH_DAYS = [31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];
+
+export const GREGORIAN_MONTHS: string[] = [
+  "January",
+  "February",
+  "March",
+  "April",
+  "May",
+  "June",
+  "July",
+  "August",
+  "September",
+  "October",
+  "November",
+  "December",
+];
+
+/** The month names a date reads with: the mod's twelve, or the engine's. */
+export function monthNames(cal: CalendarSetting): string[] {
+  return cal.months ?? GREGORIAN_MONTHS;
+}
+
+/**
+ * Validate a calendar straight out of JSON settings (any client, any hand-
+ * edited settings file). Returns a clean copy, or undefined when the value is
+ * not a usable calendar - features then behave as if none was configured.
+ */
+export function sanitizeCalendar(raw: unknown): CalendarSetting | undefined {
+  if (typeof raw !== "object" || raw === null) return undefined;
+  const o = raw as Record<string, unknown>;
+  const epoch = o.epoch;
+  const after = o.after;
+  if (typeof epoch !== "number" || !Number.isInteger(epoch) || epoch < 1) return undefined;
+  if (typeof after !== "string" || after.trim() === "") return undefined;
+  const cal: CalendarSetting = { epoch, after: after.trim() };
+  if (typeof o.before === "string" && o.before.trim() !== "") cal.before = o.before.trim();
+  // Typed input picks the era by its label and the month by its name, so a
+  // collision would resolve silently to the wrong one: not a usable calendar.
+  if (cal.before && cal.before.toLowerCase() === cal.after.toLowerCase()) return undefined;
+  if (Array.isArray(o.months) && o.months.length > 0) {
+    // Exactly the engine's twelve. A name may still arrive as the older
+    // `{ name, days }` object; its day count never meant anything to the
+    // game and is dropped.
+    if (o.months.length !== GREGORIAN_MONTHS.length) return undefined;
+    const months: string[] = [];
+    const seen = new Set<string>();
+    for (const m of o.months) {
+      const name = typeof m === "string" ? m : ((m as Record<string, unknown> | null)?.name ?? null);
+      if (typeof name !== "string" || name.trim() === "") return undefined;
+      const key = name.trim().toLowerCase();
+      if (seen.has(key)) return undefined;
+      seen.add(key);
+      months.push(name.trim());
+    }
+    cal.months = months;
+  }
+  return cal;
+}
+
+/** A script-file date token (`3000.1.1`), or null when the text is not one. */
+export function parseScriptDate(text: string): { y: number; m: number; d: number } | null {
+  const match = /^(\d{1,5})\.(\d{1,2})\.(\d{1,2})$/.exec(text);
+  if (!match) return null;
+  return { y: Number(match[1]), m: Number(match[2]), d: Number(match[3]) };
+}
+
+/** A date the engine reads: a positive year, one of its twelve months, a day that month has. */
+export function isValidScriptDate(y: number, m: number, d: number): boolean {
+  return y >= 1 && m >= 1 && m <= ENGINE_MONTH_DAYS.length && d >= 1 && d <= ENGINE_MONTH_DAYS[m - 1];
+}
+
+/** Era-mapped year: "1000 BC". Null for pre-epoch years of a single-era calendar. */
+export function displayYear(cal: CalendarSetting, y: number): string | null {
+  if (y >= cal.epoch) return `${y - cal.epoch + 1} ${cal.after}`;
+  return cal.before ? `${cal.epoch - y} ${cal.before}` : null;
+}
+
+/**
+ * Full display form of a script date: "1000 BC" for the year's first day
+ * (how start dates read in game), "15 March 1000 BC" otherwise. Null when the
+ * date does not fit the calendar.
+ */
+export function displayDate(cal: CalendarSetting, y: number, m: number, d: number): string | null {
+  if (!isValidScriptDate(y, m, d)) return null;
+  const year = displayYear(cal, y);
+  if (!year) return null;
+  if (m === 1 && d === 1) return year;
+  return `${d} ${monthNames(cal)[m - 1]} ${year}`;
+}
+
+export type ConvertResult = { ok: true; script: string; display: string } | { ok: false; error: string };
+
+/** Case-insensitive month lookup: exact name, else unique prefix. */
+function monthByName(cal: CalendarSetting, text: string): number | null {
+  const needle = text.toLowerCase();
+  const months = monthNames(cal);
+  const exact = months.findIndex((m) => m.toLowerCase() === needle);
+  if (exact >= 0) return exact + 1;
+  const prefixed = months.map((m, i) => ({ m, i })).filter(({ m }) => m.toLowerCase().startsWith(needle));
+  return prefixed.length === 1 ? prefixed[0].i + 1 : null;
+}
+
+/**
+ * A display-calendar date typed by the user -> the script date the file needs.
+ * Grammar: `YEAR [ERA] [MONTH [DAY]]`, e.g. "1000 BC", "1000 BC March 15",
+ * "1000 BC 3 15", "1 AD", "500" (era defaults to `after`). MONTH is a number
+ * or a month name (unique prefix is enough).
+ */
+export function convertDisplayInput(cal: CalendarSetting, input: string): ConvertResult {
+  const words = input.trim().split(/\s+/).filter(Boolean);
+  if (words.length === 0) return { ok: false, error: "type a year, e.g. 1000 " + (cal.before ?? cal.after) };
+  if (!/^\d{1,5}$/.test(words[0])) return { ok: false, error: `"${words[0]}" is not a year` };
+  const year = Number(words[0]);
+  let rest = words.slice(1);
+
+  let era = cal.after;
+  if (rest.length > 0) {
+    const w = rest[0].toLowerCase();
+    if (w === cal.after.toLowerCase()) {
+      rest = rest.slice(1);
+    } else if (cal.before && w === cal.before.toLowerCase()) {
+      era = cal.before;
+      rest = rest.slice(1);
+    }
+  }
+
+  let m = 1;
+  let d = 1;
+  if (rest.length > 0) {
+    const month = /^\d{1,2}$/.test(rest[0]) ? Number(rest[0]) : monthByName(cal, rest[0]);
+    if (month === null) return { ok: false, error: `"${rest[0]}" is not a month of this calendar` };
+    m = month;
+    rest = rest.slice(1);
+  }
+  if (rest.length > 0) {
+    if (!/^\d{1,3}$/.test(rest[0])) return { ok: false, error: `"${rest[0]}" is not a day` };
+    d = Number(rest[0]);
+    rest = rest.slice(1);
+  }
+  if (rest.length > 0) return { ok: false, error: `unexpected "${rest.join(" ")}"` };
+
+  if (year < 1) return { ok: false, error: "years start at 1 (no year zero)" };
+  const y = era === cal.after ? year + cal.epoch - 1 : cal.epoch - year;
+  if (y < 1) return { ok: false, error: `${year} ${era} is before script year 1 (epoch ${cal.epoch})` };
+  if (!isValidScriptDate(y, m, d)) {
+    return m >= 1 && m <= ENGINE_MONTH_DAYS.length
+      ? { ok: false, error: `${monthNames(cal)[m - 1]} has ${ENGINE_MONTH_DAYS[m - 1]} days` }
+      : { ok: false, error: `the game has ${ENGINE_MONTH_DAYS.length} months` };
+  }
+  return { ok: true, script: `${y}.${m}.${d}`, display: displayDate(cal, y, m, d)! };
+}