@px-lsp/protocol 0.1.0

package/dist/protocol.d.ts

@@ -0,0 +1,1462 @@
+/** Resolved extension settings, computed client-side (path validation, Steam
+ * detection fallbacks, workspace-folder default) and pushed to the server. */
+export interface ParadoxSettings {
+    /** Game profile id; absent/unknown ids fall back to the server's default
+     * game. Detected client-side per workspace (descriptor file, else setting). */
+    gameId?: string;
+    gamePath: string | null;
+    logsPath: string | null;
+    modPath: string | null;
+    /** Parent/dependency mod roots (load order, base first) indexed as source "parent"
+     *, the submod / compatibility-patch workflow. */
+    parentPaths: string[];
+    /** Workspace mod roots (subset of parentPaths): mods the user is EDITING in
+     * this workspace, so they get the mod treatment, reference indexing and
+     * reference diagnostics, on top of the parent definition scan. */
+    workspaceMods?: string[];
+    locLanguage: string;
+    /** Show inferred scope after scope-changing block openers (off by default). */
+    scopeInlayHints: boolean;
+    /** Our diagnostic codes to suppress everywhere. */
+    diagnosticsIgnore: string[];
+    /** Glob patterns (workspace-relative paths) whose diagnostics are suppressed. */
+    diagnosticsIgnorePatterns: string[];
+    /** When false (default) mod-only: never diagnose files under the game path. */
+    diagnosticsVanilla: boolean;
+    /** `px.trace.perf`: wall clock for every request, rescan, index change and
+     * scan phase into the output channel. Off by default (perf campaign §A2). */
+    tracePerf?: boolean;
+}
+/**
+ * What the connected client can do beyond plain LSP. Every capability is
+ * independent and off by default, so a bare client gets the degraded shape
+ * without declaring anything and a rich client opts in to exactly the parts
+ * it implements.
+ */
+export interface ParadoxClientCapabilities {
+    /**
+     * The client renders the sanitized `<span style="color:var(--vscode-*)">`
+     * markup in hover markdown (VSCode theme variables). Default false: hover
+     * cards are plain markdown, with the same content.
+     */
+    hoverHtml?: boolean;
+    /**
+     * The command ids the client registers, from {@link clientCommands}. The
+     * server emits `command:` links and command-carrying code actions ONLY for
+     * ids listed here; for the rest it falls back to plain text or a real
+     * WorkspaceEdit. Default: none.
+     */
+    commands?: string[];
+    /**
+     * The client watches the mod tree itself and pushes
+     * {@link modFileChangedNotification}. The server then does NOT register its
+     * own `workspace/didChangeWatchedFiles` watcher. Default false: the server
+     * registers one whenever the client supports dynamic registration.
+     */
+    ownFileWatcher?: boolean;
+}
+/** initializationOptions passed at LanguageClient start. All fields optional:
+ * the server has fail-soft fallbacks for bare clients. */
+export interface ParadoxInitOptions {
+    /** Server-side cache directory (the extension's global storage path). */
+    storageDir?: string;
+    /** What this client can do; see {@link ParadoxClientCapabilities}. Absent
+     * fields default to off (the plain-LSP-client shape). */
+    client?: ParadoxClientCapabilities;
+    /**
+     * @deprecated Send {@link ParadoxInitOptions.client} instead. `true` is an
+     * alias for `{ hoverHtml: true, commands: <every id in clientCommands>,
+     * ownFileWatcher: true }` (what the VSCode extension declared before the
+     * capabilities object existed); false/absent means all-off. Ignored when
+     * `client` is present.
+     */
+    clientCommands?: boolean;
+    /**
+     * Root holding the bundled per-game data directories: the server reads
+     * `<dataDir>/<gameId>/wikidocs/` and `<dataDir>/<gameId>/freqs.json`.
+     * Normally omitted: the server uses `data/` next to its own bundle. Set it
+     * when the data ships apart from the server bundle (an embedder unpacking
+     * both separately). Re-resolved against the new `gameId` whenever the game
+     * changes, so it stays profile-correct.
+     */
+    dataDir?: string;
+    /**
+     * @deprecated Send {@link ParadoxInitOptions.dataDir} instead. Overrides the
+     * wikidocs/ folder ALONE, freqs.json still comes from `dataDir`/the bundle,
+     * and, being one fixed folder, it does NOT follow a `gameId` change.
+     */
+    wikidocsDir?: string;
+    settings?: ParadoxSettings;
+}
+/**
+ * Client commands the server references in code actions and hover links (part
+ * of the wire contract: a client that implements one must register exactly
+ * this id and list it in {@link ParadoxClientCapabilities.commands}). They
+ * carry the "px." prefix: these are public extension command ids with shipped
+ * default keybindings. The prefix was renamed in the Paradox Toolkit rebrand
+ * and no fallback to the old ids is registered.
+ */
+export declare const clientCommands: {
+    readonly editLocalization: "px.editLocalization";
+    readonly openLocalizationSideBySide: "px.openLocalizationSideBySide";
+    readonly showReferences: "px.showReferences";
+};
+/** Every id in {@link clientCommands}: what a fully capable client registers. */
+export declare const allClientCommandIds: string[];
+/** Notification: settings changed; payload {@link ParadoxSettings}. */
+export declare const configChangedNotification = "paradox/configChanged";
+/** Notification: a mod file changed on disk; payload {@link ModFileChangeParams}. */
+export declare const modFileChangedNotification = "paradox/modFileChanged";
+export interface ModFileChangeParams {
+    /** Absolute filesystem path (not a URI). */
+    fsPath: string;
+}
+/** Request: re-parse script_docs logs; payload {@link ReloadDocsParams} -> {@link ReloadDocsResult}. */
+export declare const reloadDocsRequest = "paradox/reloadDocs";
+export interface ReloadDocsParams {
+    force: boolean;
+}
+export interface ReloadDocsResult {
+    tokens: number;
+}
+/** Request: index statistics; no payload -> {@link IndexStats}. */
+export declare const 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). */
+export declare const lookupLocRequest = "paradox/lookupLoc";
+export interface LookupLocParams {
+    key: string;
+}
+export interface LocEntryInfo {
+    file: string;
+    /** 0-based. */
+    line: number;
+    source: "vanilla" | "parent" | "mod";
+    value?: string;
+}
+/** Notification: data health for the status bar; payload {@link StatusPayload}. */
+export declare const statusNotification = "paradox/status";
+export interface StatusPayload {
+    tokens: number;
+    tokensFromScriptDocs: boolean;
+    /** True when the script_docs tokens came from the BUNDLED dump snapshot
+     * (data/<gameId>/script_docs) rather than the user's own dump. */
+    tokensFromBundledDumps?: boolean;
+    definitions: number;
+    /** True while a (re)scan is running. */
+    indexing: boolean;
+}
+/** Notification: the definition index changed (debounced server-side); no payload.
+ * Overview views re-query on this signal. */
+export declare const indexChangedNotification = "paradox/indexChanged";
+/** Notification: a long-running server phase started or finished; payload
+ * {@link ProgressPayload}. The status bar lists what is still loading, so a
+ * cold workspace says which step it is on instead of looking idle. No
+ * percentages: the phases are coarse and the client only shows their state. */
+export declare const progressNotification = "paradox/progress";
+export interface ProgressPayload {
+    /** Stable phase id, so a "done" can find the "start" it belongs to. */
+    phase: string;
+    state: "start" | "done";
+    /** Human-readable label for the phase, sent with "start". */
+    detail?: string;
+}
+/** Shared param for the mod-scoped overview requests: restrict the result to
+ * one workspace mod (absolute root path). Absent/null = all workspace mods. */
+export interface ModScopedParams {
+    modRoot?: string | null;
+}
+/** Request: mod content inventory; {@link ModScopedParams} -> {@link ModOverview}. */
+export declare const modOverviewRequest = "paradox/modOverview";
+export interface OverviewDef {
+    name: string;
+    file: string;
+    line: number;
+}
+export interface OverviewKind {
+    kind: string;
+    count: number;
+    /** Capped list (first N alphabetically); `count` is the real total. */
+    defs: OverviewDef[];
+}
+export interface ModOverview {
+    kinds: OverviewKind[];
+    totalDefs: number;
+    totalRefs: number;
+}
+/** Request: localization coverage; {@link ModScopedParams} -> {@link LocCoverage}[]. */
+export declare const locCoverageRequest = "paradox/locCoverage";
+export interface LocIssue {
+    key: string;
+    file?: string;
+    /** 0-based. */
+    line?: number;
+    /** For untranslated: the source-language text. */
+    value?: string;
+}
+export interface LocCoverage {
+    language: string;
+    defined: number;
+    /** Referenced by mod script / required by schema but not defined anywhere. */
+    missing: LocIssue[];
+    /** Defined in the mod but never referenced and not overriding vanilla. */
+    orphaned: LocIssue[];
+    /** Value identical to the source language (only for non-source languages). */
+    untranslated: LocIssue[];
+}
+/** Request: override/conflict map; {@link ModScopedParams} -> {@link OverrideInfo}[]. */
+export declare const overridesRequest = "paradox/overrides";
+export interface OverrideSite {
+    source: "vanilla" | "parent" | "mod";
+    /** Display label: the owning mod's descriptor name when known, else `source`. */
+    label?: string;
+    file: string;
+    line: number;
+}
+export interface OverrideInfo {
+    name: string;
+    kind: string;
+    mod: OverrideSite;
+    shadowed: OverrideSite[];
+    /** Folder rule: script is last-in-wins, GUI is first-in-wins. */
+    rule: "LIOS" | "FIOS";
+    winner: "mod" | "other";
+    note?: string;
+}
+/** Request: full event detail for the graph inspector; {@link EventDetailParams} -> {@link EventDetail} | null. */
+export declare const eventDetailRequest = "paradox/eventDetail";
+export interface EventDetailParams {
+    id: string;
+}
+/** A localizable field: key, resolved text, and (for mod entries) the editable site. */
+export interface EventLocField {
+    key: string;
+    text?: string;
+    /** Present only when the entry lives in the mod (in-place editable). */
+    file?: string;
+    line?: number;
+    /** The value comes from a dynamic block (first_valid / triggered_desc), not a plain key. */
+    dynamic?: boolean;
+}
+/**
+ * One flattened line of a rendered block: enough to print an event's logic
+ * back as readable pseudo-script without the client re-parsing anything.
+ */
+export interface EventScriptLine {
+    /** Nesting depth inside the rendered block (0 = a direct child). */
+    depth: number;
+    /** The statement without indentation: `key = value`, `key = {`, `}`, or a bare scalar. */
+    text: string;
+    /** 0-based source line. */
+    line: number;
+}
+/**
+ * A reference inside a block that hands control to another event or on_action:
+ * the step-into edge of an event walkthrough. Collected from the schema's
+ * event/on_action reference fields (`trigger_event`, `on_action`, `events`,
+ * `random_events`, …), so a game profile that names them differently is
+ * covered without a hard-coded key list.
+ */
+export interface EventStepTarget {
+    /** The key that produced the reference (`trigger_event`, `on_action`, …). */
+    via: string;
+    /** Referenced event id / on_action name, exactly as written. */
+    name: string;
+    /** What the index says `name` is. "unknown" = not indexed; say so, do not guess. */
+    kind: "event" | "on_action" | "unknown";
+    /** 0-based line of the reference, in the file that contains it (for a
+     * {@link EventStepTarget.fires} entry that is the on_action's own file). */
+    line: number;
+    /** Definition site, when the name is indexed. */
+    file?: string;
+    defLine?: number;
+    /** Definition sites of that kind, when more than one. on_actions merge
+     * across files (a mod extending a vanilla on_action), so `fires` reflects
+     * only the site at {@link EventStepTarget.file}. */
+    defCount?: number;
+    /**
+     * on_action targets only: what that on_action itself fires, read from its own
+     * definition. Empty when the definition names nothing. Absent when there was
+     * nothing to read: the name is not an indexed on_action, its file could not
+     * be parsed, or this target already IS one level deep (resolution stops
+     * there, so a self-chaining pair cannot recurse).
+     */
+    fires?: EventStepTarget[];
+    /** Real target count before `fires` was capped. */
+    firesTotal?: number;
+}
+/**
+ * A scalar `key = value` written directly in an event body or an option body,
+ * with the line it sits on, so an editor can rewrite it in place instead of
+ * re-parsing the file. Blocks are not fields: they are `sections` / `options`.
+ */
+export interface EventFieldInfo {
+    key: string;
+    value: string;
+    /** 0-based source line. */
+    line: number;
+    /** The value was written in quotes and must be rewritten that way. */
+    quoted?: boolean;
+}
+export interface EventSectionInfo {
+    name: string;
+    /** 0-based line of the section key. */
+    line: number;
+    /** Top-level keys inside the section (capped). */
+    keys: string[];
+    /** The section rendered as pseudo-script, capped (`totalLines` is the truth). */
+    lines: EventScriptLine[];
+    totalLines: number;
+    /** Events / on_actions this section hands control to, capped. */
+    targets: EventStepTarget[];
+    /** Real target count before `targets` was capped. */
+    targetsTotal: number;
+}
+/** A gate block (trigger / ai_chance) rendered for in-place editing. */
+export interface EventGateInfo {
+    /** 0-based line of the block's key. */
+    line: number;
+    lines: EventScriptLine[];
+    totalLines: number;
+}
+export interface EventOptionInfo {
+    line: number;
+    /** Line the option's first statement may be inserted before (0-based). */
+    bodyLine: number;
+    /** Scalar keys written in the option body, editable in place. */
+    fields: EventFieldInfo[];
+    name?: EventLocField;
+    effectKeys: string[];
+    hasTrigger: boolean;
+    hasAiChance: boolean;
+    /** The option's own trigger block, rendered, when it has one. */
+    trigger?: EventGateInfo;
+    /** The option's ai_chance block, rendered, when it has one. */
+    aiChance?: EventGateInfo;
+    /** The option's effects rendered as pseudo-script (name/trigger/ai_chance/
+     * ai_value dropped: they gate the option, they are not its effect), capped. */
+    lines: EventScriptLine[];
+    totalLines: number;
+    /** Events / on_actions this option hands control to, capped. */
+    targets: EventStepTarget[];
+    /** Real target count before `targets` was capped. */
+    targetsTotal: number;
+}
+export interface EventRefInfo {
+    name: string;
+    kind: "saved_scope" | "variable" | "scripted_effect" | "scripted_trigger" | "script_value" | "event";
+    /** First use inside the event, 0-based. */
+    line: number;
+    defFile?: string;
+    defLine?: number;
+    /** Number of definition/save sites. */
+    defCount?: number;
+}
+export interface EventDetail {
+    id: string;
+    file: string;
+    line: number;
+    /** Line of the event's closing brace (option-scaffold insertion point). */
+    endLine: number;
+    /** Line a new top-level statement may be inserted before (0-based). */
+    bodyLine: number;
+    /** Scalar keys written at the event's top level, editable in place. */
+    fields: EventFieldInfo[];
+    type?: string;
+    hidden?: boolean;
+    theme?: string;
+    title?: EventLocField;
+    desc?: EventLocField;
+    /** The event's third displayed string in the games whose events have one
+     *  (top-level `flavor`); absent everywhere else. */
+    flavor?: EventLocField;
+    sections: EventSectionInfo[];
+    options: EventOptionInfo[];
+    refs: EventRefInfo[];
+}
+/** Request: GUI widget tree for a .gui document; {@link GuiTreeParams} -> {@link GuiTree}. */
+export declare const guiTreeRequest = "paradox/guiTree";
+export interface GuiTreeParams {
+    /** For display only; the text is authoritative. */
+    uri: string;
+    text: string;
+}
+export interface GuiTreeNode {
+    /** Widget type or declaration header (window, flowcontainer, "template NAME"…). */
+    key: string;
+    /** name = "..." when present. */
+    name?: string;
+    /** For `type x = base { }` / tagged blocks: the base widget type. */
+    base?: string;
+    /** using = template references. */
+    using?: string[];
+    /** decl = template/types/type/blockoverride/block headers; state = animation states. */
+    kind: "widget" | "state" | "decl";
+    /** 0-based line of the key. */
+    line: number;
+    children: GuiTreeNode[];
+}
+export interface GuiTree {
+    nodes: GuiTreeNode[];
+    /** Total node count across all depths. */
+    count: number;
+}
+/**
+ * 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
+ * templates/types resolved against the vanilla + mod gui tree.
+ */
+export declare const guiLayoutRequest = "paradox/guiLayout";
+export interface GuiLayoutParams {
+    /** For display only; the text is authoritative. */
+    uri: string;
+    text: string;
+    /** Conditional-visibility preview mode; absent = `showAll`. */
+    visibility?: GuiVisibilityOptions;
+    /**
+     * `resolve` (default): textbox keys show their localized value and
+     * `[datafunctions]` their knowable text, and sizes follow. `raw`: the
+     * `text =` value verbatim, as the file has it.
+     */
+    loc?: "resolve" | "raw";
+    /** Modder-supplied preview text per `[...]` expression (the `.<game>modding/gui-preview-values.json` table). */
+    previewValues?: Record<string, string>;
+}
+/**
+ * How the layout treats a CONDITIONALLY visible widget, one whose `visible`
+ * holds an expression a static preview cannot evaluate (`visible =
+ * "[GetPlayer.IsAI]"`). A literal `visible = no` is deterministic and always
+ * collapses; `visible = yes` always shows. Neither is a check.
+ */
+export type GuiVisibilityMode = "showAll" | "hideAll" | "evaluate";
+export interface GuiVisibilityOptions {
+    mode: GuiVisibilityMode;
+    /**
+     * `evaluate` only: per-check assignments. The KEY is the `visible` value
+     * exactly as authored, minus its quotes (`[GetPlayer.IsAI]`). The source
+     * string is the only identity a static preview has, so two widgets written
+     * with the same condition share one toggle, and a key stays stable across
+     * edits that do not touch the condition. A check with no assignment behaves
+     * as `showAll` (shown).
+     */
+    checks?: Record<string, boolean>;
+}
+/** A conditional `visible` the layout met, for building a toggle UI. */
+export interface GuiVisibilityCheck {
+    /** The condition source string, the key {@link GuiVisibilityOptions.checks} takes. */
+    key: string;
+    /** Widgets carrying this condition in this document. */
+    count: number;
+    /** True when THIS run resolved the check to hidden. */
+    hidden: boolean;
+}
+/** Server-side wall clock of one `paradox/guiLayout`, for a stats line. */
+export interface GuiLayoutTimings {
+    /** Parsing the document and collecting its own template/type declarations. */
+    parseMs: number;
+    /** Building the cross-file template/type store; 0 on a cache hit. */
+    defsMs: number;
+    /** Building the widget tree and arranging every rect. */
+    layoutMs: number;
+    /** The whole request, server side. */
+    totalMs: number;
+}
+export interface GuiLayoutFill {
+    texture?: string;
+    /** rgba 0..1, straight sRGB multiply (rendered = round(v*255)). */
+    color?: [number, number, number, number];
+    /**
+     * Nine-slice border widths [left, top, right, bottom] in texture pixels
+     * (from `spriteborder`/`spriteborder_<side>`). The values as authored;
+     * `mode` says whether they apply.
+     */
+    border?: [number, number, number, number];
+    /**
+     * How to draw the texture. Nine-slicing needs BOTH a `Cornered*` spriteType
+     * AND a non-zero border; a border alone is ignored and the whole texture
+     * stretches. `nineslice-*` = corners unscaled, edges and centre tiled or
+     * stretched per the suffix; `tile` = repeat the whole texture.
+     */
+    mode?: "stretch" | "tile" | "nineslice-stretch" | "nineslice-tile";
+    /** `framesize = { w h }` cell size when the texture is a frame sheet. */
+    framesize?: [number, number];
+    /** `alpha = x`: the fill's opacity, 0..1 (absent = 1). */
+    alpha?: number;
+    /**
+     * `modify_texture` with `blend_mode = alphamultiply`: a texture whose alpha
+     * multiplies the fill's, stretched over the rect. Listed in `textures` like
+     * any other path. Other blend modes are not carried.
+     */
+    mask?: string;
+    /** `fittype = centercrop`: cover the rect and crop to the centre instead of stretching. */
+    fit?: "centercrop";
+    /**
+     * 1-based frame index into that sheet, row-major over the cols x rows grid
+     * (cols = texW/w). Out-of-range values clamp to the first or last cell.
+     */
+    frame?: number;
+}
+/**
+ * One piece of what a textbox shows. `loc`: a localization key the index
+ * resolved (or not: `resolved` false shows the key itself). `datafn`: a
+ * `[...]` expression; resolved through `Localize`/`Concept` or the modder's
+ * preview values, else shown as its last chain segment with `resolved` false.
+ * `source` is the key or the expression without brackets.
+ */
+export interface GuiTextSegment {
+    text: string;
+    kind: "literal" | "loc" | "datafn";
+    source: string;
+    resolved: boolean;
+}
+export interface GuiLayoutText {
+    /** What is measured and drawn (resolved when the request asked for it). */
+    text: string;
+    /** The raw `text =` value; differs from `text` when something resolved. */
+    raw?: string;
+    segments?: GuiTextSegment[];
+    fontsize: number;
+    offsetX: number;
+    offsetY: number;
+    lines: string[];
+    color?: [number, number, number, number];
+}
+export interface GuiLayoutNode {
+    key: string;
+    name?: string;
+    rect: {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    };
+    /** Scrollarea viewport: children are clipped to the rect. */
+    clip: boolean;
+    bg?: GuiLayoutFill;
+    fill?: GuiLayoutFill;
+    text?: GuiLayoutText;
+    /** 0-based line of the instance statement in the requested document. */
+    line?: number;
+    /** Placed via anchor+position rules (position honored -> draggable). */
+    positioned: boolean;
+    /**
+     * `line` is the widget's own statement in this document (safe to edit);
+     * false for children spliced from type definitions.
+     */
+    editable: boolean;
+    /** Raw `position = { x y }` source values, when present. */
+    srcPosition?: [number, number];
+    /** Raw `size = { w h }` source values, when present. */
+    srcSize?: [number, number];
+    /**
+     * The widget's index among its parent body's REORDER SIBLINGS: exactly the
+     * index a `reorder`, `insert` or `delete` op counts (see {@link GuiSourceOp}).
+     * Those are the body's DECLARATIONS, which include the `blockoverride` /
+     * `block` / `template` entries a preview never shows, so a client that ranks
+     * the widgets it can see is off by one per intervening declaration.
+     *
+     * Absent whenever no index names the node: a template- or type-spliced child,
+     * a datamodel ghost, the contents of a named slot, and a scrollarea's
+     * pass-through children, whose ranks count a body their drawn parent does not
+     * own. Absent means "not addressable by index"; do not fall back to counting.
+     */
+    srcIndex?: number;
+    /**
+     * Placeholder copy of a datamodel item template (the list has no runtime
+     * rows in a static preview). The renderer draws it at reduced opacity; it is
+     * never editable. Presentation only, not a measured layout rule.
+     */
+    ghost?: boolean;
+    /**
+     * The widget's `onclick` value as authored, minus its quotes, when it has
+     * one. A static preview cannot run it; a client's interact mode reads the
+     * `GetVariableSystem.*` calls out of it to drive the visibility checks, and
+     * names the rest as what the game would run.
+     */
+    onclick?: string;
+    /** The widget's `tooltip` value as authored (a loc key or a [datafunction]), when it has one. */
+    tooltip?: string;
+    /**
+     * A root that is a `type name = base { }` DECLARATION laid out as one
+     * instance of itself. Set only on roots, and only for a document that
+     * instantiates nothing at top level, the shape whole panels are written in
+     * by the games whose engine instantiates a window by name from code. The
+     * declaration header is not editable; the children under it are ordinary
+     * statements of the document and are.
+     */
+    declared?: boolean;
+    children: GuiLayoutNode[];
+}
+export interface GuiLayoutResult {
+    nodes: GuiLayoutNode[];
+    /** Distinct texture paths referenced anywhere in the tree (mod-relative). */
+    textures: string[];
+    /** Total node count across all depths. */
+    nodeCount: number;
+    /** How many .gui files fed the template/type store (0 = no game path). */
+    defsFiles: number;
+    /**
+     * Every conditional `visible` the layout met, key-sorted. Reported in ALL
+     * modes, `showAll` included, so a client can build the toggle UI before the
+     * user has switched mode.
+     */
+    visibilityChecks: GuiVisibilityCheck[];
+    /** Per-stage wall clock of this request. */
+    timings: GuiLayoutTimings;
+}
+/**
+ * Request: the properties of ONE widget, as the layout engine resolved them;
+ * {@link GuiWidgetInfoParams} -> {@link GuiWidgetInfo}, null when the line
+ * carries no widget of its own (a node spliced in from a template or a type has
+ * no source here, the same answer `guiSourceEdit` refuses with).
+ *
+ * This is the designer inspector's READ side. It is a separate request rather
+ * than a field on {@link GuiLayoutNode} because it is per-SELECTION data: a
+ * vanilla window lays out 500+ widgets and carrying every widget's expanded
+ * property list on every layout push would multiply the payload for rows one
+ * widget at a time is ever shown.
+ */
+export declare const guiWidgetInfoRequest = "paradox/guiWidgetInfo";
+export interface GuiWidgetInfoParams {
+    /** For display only; the text is authoritative. */
+    uri: string;
+    text: string;
+    /** 0-based line of the widget's own statement (`GuiLayoutNode.line`). */
+    line: number;
+    /**
+     * Also answer "why is it here": run the layout with an explanation trace on
+     * and return {@link GuiWidgetInfo.placement}. Off by default because it costs
+     * a full layout of the document; the trace itself is what the flag gates, so
+     * an ordinary `paradox/guiLayout` never pays for it.
+     */
+    placement?: boolean;
+}
+/** One step of the chain a property was spliced through. */
+export interface GuiWidgetOrigin {
+    kind: "type" | "template";
+    /** The type or template name, as `expandWidget` resolved it. */
+    name: string;
+}
+export interface GuiWidgetProperty {
+    key: string;
+    /**
+     * The value as authored, rendered from the tokens: a quoted scalar keeps its
+     * quotes, a block reads `{ a b }`. Blocks come from other files whose text
+     * the store does not keep, so this is a rendering, not a byte copy.
+     */
+    value: string;
+    /**
+     * Definitions the entry was spliced through, INNERMOST first (`[template
+     * PxDeco, type px_card]` = a template used inside a type). Empty means the
+     * property is authored in the widget's own body, which is the only case
+     * `setProperties` rewrites in place.
+     */
+    origin: GuiWidgetOrigin[];
+    /**
+     * The values this key SHADOWED, in expansion order (base-most first), so the
+     * last entry is the one this row directly overrides. Present only when the
+     * key was assigned more than once, which is exactly when the inspector can
+     * say "this overrides `{ 100 50 }` from type px_card". Absent otherwise.
+     */
+    overrides?: GuiWidgetOverride[];
+}
+/** A value a later assignment of the same key replaced. */
+export interface GuiWidgetOverride {
+    /** Rendered the same way {@link GuiWidgetProperty.value} is. */
+    value: string;
+    /** Where the replaced value came from; empty = the widget's own body. */
+    origin: GuiWidgetOrigin[];
+}
+/**
+ * One contribution to a widget's final origin, in engine order. The `dx`/`dy`
+ * of the terms sum to the rect's `x`/`y` exactly (see spec.md B1-B/C/D:
+ * `x = parent.x + parentanchor.fx*parent.w - widgetanchor.fx*w + position.x`).
+ */
+export interface GuiPlacementTerm {
+    kind: "parentOrigin" | "parentanchor" | "widgetanchor" | "position";
+    /**
+     * The authored spec behind the term (`bottom|right`, `{ -30 -30 }`). Absent
+     * on `parentOrigin`, which is the parent's rect rather than a property, and
+     * on a `widgetanchor` that was never written (it mirrors `parentanchor`,
+     * B1-B/C), there `source` names the anchor it mirrored.
+     */
+    source?: string;
+    dx: number;
+    dy: number;
+}
+/**
+ * The layout container that assigned a rect outright. The engine DROPS an
+ * authored `position` on such a child and logs "Widget cannot have a position
+ * in a layout" (probe 2026-08-02, parity-checklist L23), which is the single
+ * most common "why is my widget not where I put it".
+ */
+export interface GuiPlacedBy {
+    /** The parent's widget key (`hbox`, `flowcontainer`, `fixedgridbox`, …). */
+    key: string;
+    name?: string;
+    layout: "box" | "flow" | "grid";
+    /** The `position` the engine dropped, when the widget authored one. */
+    droppedPosition?: [number, number];
+}
+/** Why a widget's rect is where it is. */
+export interface GuiPlacement {
+    /** The final rect, the same one `GuiLayoutNode.rect` carries. */
+    rect: {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    };
+    /** What the terms are measured against: the parent's content rect, or the
+     * viewport for a root widget. */
+    parentRect: {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    };
+    /**
+     * The anchor terms, summing to the rect origin. EMPTY when `placedBy` is
+     * set: a layout container computes the slot, so there is no anchor sum to
+     * show.
+     */
+    terms: GuiPlacementTerm[];
+    placedBy?: GuiPlacedBy;
+    /**
+     * The innermost clipping ancestor (a scrollarea viewport, or any widget with
+     * `scissor = yes`), when one clips this widget. The rect is the clip rect,
+     * NOT the intersection: the geometry is true and the renderer clips.
+     */
+    clippedBy?: {
+        key: string;
+        name?: string;
+        rect: {
+            x: number;
+            y: number;
+            w: number;
+            h: number;
+        };
+    };
+}
+/**
+ * A texture the widget draws, with its frame-sheet grid when it is one. The
+ * sheet's pixel size comes from the DDS header alone (128 bytes read, no
+ * decode); `columns`/`rows`/`cell` need it, so they are absent when the file
+ * does not resolve under the configured roots.
+ *
+ * The grid is driven by `framesize`, the property the vanilla gui trees
+ * actually carry (both harvested titles ship it; neither ships `noofframes`).
+ */
+export interface GuiTextureInfo {
+    /** The path as authored, mod-relative, the way the engine reads it. */
+    path: string;
+    /** Which fill it belongs to. */
+    source: "fill" | "background";
+    /** Absolute file it resolved to: mod, then parent mods (last first), then the game. */
+    file?: string;
+    /** Sheet pixel size from the DDS header. */
+    width?: number;
+    height?: number;
+    /** `framesize = { w h }`: the grid's cell size. */
+    framesize?: [number, number];
+    /** Grid shape, row-major: floor(width/cellW) x floor(height/cellH). */
+    columns?: number;
+    rows?: number;
+    /** The 1-based frame the widget shows (`frame`, default 1), clamped to the grid. */
+    frame?: number;
+    /** That frame's cell in texture pixels. */
+    cell?: {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    };
+}
+export interface GuiWidgetInfo {
+    key: string;
+    name?: string;
+    /** The base-type chain the key resolves through, derived-most first. */
+    typeChain: string[];
+    /**
+     * Effective properties in expansion order, last-in-wins per key: exactly the
+     * values the engine laid the widget out with, so the inspector cannot show a
+     * row the canvas did not use.
+     */
+    properties: GuiWidgetProperty[];
+    /**
+     * Textures the widget draws (its own fill first, then its background), with
+     * frame-sheet geometry. `[]` when it draws none; absent only from a server
+     * that predates the field.
+     */
+    textures?: GuiTextureInfo[];
+    /**
+     * Why the widget's rect is where it is. Present only when the request asked
+     * for it (`placement: true`) AND the layout actually reached the widget: a
+     * declaration inside a `tooltipwidget` or a subtree the engine skips has a
+     * source line but no rect.
+     */
+    placement?: GuiPlacement;
+}
+/**
+ * Request: what a `.gui` document reaches on the SCRIPT side;
+ * {@link GuiDependenciesParams} -> {@link GuiDependenciesResult}. The forward
+ * half of the dependency surface; the reverse (script definition -> the .gui
+ * paths using it) is `paradox/dependencies` with `guiUses: true`, so both
+ * directions come out of the same scripted_gui link.
+ */
+export declare const guiDependenciesRequest = "paradox/guiDependencies";
+export interface GuiDependenciesParams {
+    /** For display only; the text is authoritative. */
+    uri: string;
+    text: string;
+    /**
+     * Restrict the answer to one widget's SOURCE subtree, addressed by the
+     * 0-based line of its own statement (`GuiLayoutNode.line`). Absent = the
+     * whole document. A line carrying no widget answers with empty lists.
+     */
+    line?: number;
+}
+/** A scripted_gui the document calls, and what it hands control to. */
+export interface GuiScriptedGuiRow {
+    name: string;
+    /** Definition site; absent when the index has no scripted_gui by that name. */
+    file?: string;
+    line?: number;
+    /** 0-based lines in the REQUESTED document that call it. */
+    callLines: number[];
+    /** Call sites across every `.gui` file the layout store scanned. */
+    uses: number;
+    /** Events / on_actions the scripted_gui's own blocks hand control to. */
+    chains: GuiEventChain[];
+}
+/** An event or on_action a scripted_gui reaches, and how. */
+export interface GuiEventChain {
+    name: string;
+    kind: "event" | "on_action";
+    file?: string;
+    line?: number;
+    /**
+     * The scripted effects traversed to get there, outermost first. Empty =
+     * "directly"; `["effect_a", "effect_b"]` renders as "via effect_a -> effect_b".
+     */
+    via: string[];
+}
+/** A localization key the document names, checked against the loc index. */
+export interface GuiLocRow {
+    key: string;
+    /** The gui property that named it (`text`, `tooltip`). */
+    prop: string;
+    /** 0-based line in the requested document. */
+    line: number;
+    /** No `loc_key` definition anywhere in the index. */
+    missing: boolean;
+    /** The resolved text, when the index has one. */
+    value?: string;
+}
+export interface GuiDependenciesResult {
+    /** The widget the answer is scoped to; absent for a whole-document answer. */
+    widget?: {
+        key: string;
+        name?: string;
+        line: number;
+    };
+    scriptedGuis: GuiScriptedGuiRow[];
+    locKeys: GuiLocRow[];
+}
+/**
+ * Request: the widget names a designer palette may offer for THIS document;
+ * {@link GuiVocabularyParams} -> {@link GuiVocabularyResult}.
+ *
+ * Every name is harvested, never listed by hand: the bundled per-game widget
+ * schema (`data/<game>/guiSchema.json`, built from the vanilla `gui/` tree)
+ * plus the requested document's own `template` and `type` declarations. A
+ * palette entry is therefore always a widget the game knows.
+ */
+export declare const guiVocabularyRequest = "paradox/guiVocabulary";
+export interface GuiVocabularyParams {
+    /** For display only; the text is authoritative. */
+    uri: string;
+    text: string;
+}
+export interface GuiVocabularyEntry {
+    name: string;
+    /** `builtin` = the vanilla harvest; `type`/`template` = this document declares it. */
+    kind: "builtin" | "type" | "template";
+    /** How many times the vanilla gui tree writes it (`builtin` only). */
+    count?: number;
+    /** The base widget key a `type` derives from. */
+    base?: string;
+    /** Declared in the requested document itself. */
+    local?: boolean;
+    /**
+     * The vanilla tree writes widgets inside it, so it can hold children: what a
+     * "wrap in a container" menu offers. Derived from the harvest's own child
+     * counts, not from a list of container names.
+     */
+    container?: boolean;
+}
+export interface GuiVocabularyResult {
+    /**
+     * The document's own declarations first, then the harvested types by vanilla
+     * usage. Capped; `total` gives the real count, so a UI states what it hid.
+     */
+    entries: GuiVocabularyEntry[];
+    total: number;
+    /**
+     * Widget type -> the property names the harvest saw on it, most used first
+     * and capped: what an inspector's add-property row completes from. Only the
+     * types THIS DOCUMENT names are here (the keys it writes blocks under, plus
+     * the bases of its own `type X = base` declarations), because the harvest
+     * holds hundreds of types and this answer is re-asked after every layout.
+     * The server always sends it (empty for a game with no harvest); it is
+     * optional only so older recorded responses stay type-valid.
+     */
+    properties?: Record<string, string[]>;
+    /**
+     * The vanilla tree's most-used property names overall, most used first and
+     * capped: the fallback ranking for a widget whose type the harvest has never
+     * seen, so completion still offers something real rather than nothing.
+     */
+    commonProperties?: string[];
+}
+/**
+ * Render-ready previews of palette entries: one instance of each entry laid
+ * out in a synthetic document that keeps the requested document's own
+ * declarations (so a local template previews with its real base). The
+ * result is an ordinary node tree the client draws with the same painter as
+ * the canvas. Entries a synthetic document cannot stand up (nothing to show,
+ * zero size, a type the store lacks) come back with `node: null` and a
+ * `reason`. Capped per request (GUI_PREVIEW_MAX); ask for the visible page.
+ */
+export declare const guiPreviewRequest = "paradox/guiPreview";
+export declare const GUI_PREVIEW_MAX = 48;
+export interface GuiPreviewEntry {
+    name: string;
+    /** `raw`: `fragment` is `.gui` text (a saved component) laid out as is. */
+    kind: "builtin" | "type" | "template" | "raw";
+    fragment?: string;
+}
+export interface GuiPreviewParams {
+    /** For display only; the text is authoritative. */
+    uri: string;
+    text: string;
+    entries: GuiPreviewEntry[];
+}
+export interface GuiPreview {
+    name: string;
+    node: GuiLayoutNode | null;
+    /** Texture paths the node tree references (mod-relative). */
+    textures: string[];
+    reason?: string;
+}
+export interface GuiPreviewResult {
+    previews: GuiPreview[];
+}
+/**
+ * Preview values read out of a save game, so a designer draws
+ * `[GetPlayer.GetName]` as "Great Britain" instead of a placeholder chip.
+ *
+ * `values` is keyed by datafunction chain WITHOUT brackets, exactly the shape
+ * {@link GuiLayoutParams.previewValues} takes, so a client hands the answer
+ * straight back to the next layout request. A chain the save has no field for
+ * is absent: a preview shows what is knowable and never invents a value.
+ *
+ * The server streams the file and parses only the few blocks it needs (a big
+ * campaign runs ~115 MB), and caches the answer per file and mtime.
+ * Ironman and binary saves are refused with `error` set; melting them is a
+ * different tool.
+ */
+export declare const guiSaveValuesRequest = "paradox/guiSaveValues";
+export interface GuiSaveValuesParams {
+    /** Absolute path to the save file. */
+    path: string;
+}
+export interface GuiSaveValuesResult {
+    /** Datafunction chain without brackets -> display text. */
+    values: Record<string, string>;
+    /** What the values came from, for a UI to name the save it is showing. */
+    source: {
+        /** The campaign's name as the save's meta data states it. */
+        name: string;
+        /** The in-game date, already formatted ("21 January 1836"). */
+        date: string;
+        /** The game the values were read for. */
+        game: string;
+    };
+    /** Set when the save cannot be read (ironman, binary, unreadable). */
+    error?: string;
+}
+/**
+ * Request: source edits for a `.gui` designer gesture;
+ * {@link GuiSourceEditParams} -> {@link GuiSourceEditResult}, null when the
+ * request itself makes no sense (an unknown op). The server never writes: it
+ * returns offsets into the text it was handed and the host applies them, which
+ * keeps undo, dirty state and the live preview in the editor (EMBEDDING.md,
+ * host-owns-text).
+ *
+ * Every edit is surgical, over the exact span the source model recorded, so
+ * untouched bytes stay byte-identical: comments, CRLF, tabs-vs-spaces and
+ * single-line bodies all survive a write.
+ */
+export declare const guiSourceEditRequest = "paradox/guiSourceEdit";
+export interface GuiSourceEditParams {
+    /** For display only; the text is authoritative. */
+    uri: string;
+    /** Authoritative document text every offset refers to. */
+    text: string;
+    /** One op. Mutually exclusive with {@link ops}; sending both answers null. */
+    op?: GuiSourceOp;
+    /**
+     * A BATCH: several ops computed against this one text and answered as one
+     * edit set, which is what makes a multi-widget gesture one document change
+     * and one undo step. Every op gets a verdict of its own in
+     * {@link GuiSourceEditResult.results}, so a refusal is per op and the rest
+     * still apply. Order matters: the ops are computed in the order given, and a
+     * later one whose bytes a earlier one already changes is refused rather than
+     * silently dropped.
+     */
+    ops?: GuiSourceOp[];
+}
+/** One surgical replacement: replace `[start, end)` with `newText`. */
+export interface GuiTextEdit {
+    /** UTF-16 offsets into the request text. */
+    start: number;
+    end: number;
+    newText: string;
+}
+/**
+ * What to do. `line` is the 0-based line of the target widget's own statement,
+ * the same `line` {@link GuiLayoutNode} reports; a node with no line of its own
+ * (spliced in from a template or a type) has no source to edit and is refused.
+ * `index` counts SOURCE children, not the template-expanded ones a preview
+ * shows; out of range appends.
+ */
+export type GuiSourceOp = 
+/** Set or (with a null value) remove properties on one widget. */
+{
+    kind: "setProperties";
+    line: number;
+    properties: {
+        key: string;
+        value: string | null;
+    }[];
+}
+/** Move a source child of the widget on `line` from one index to another. */
+ | {
+    kind: "reorder";
+    line: number;
+    from: number;
+    to: number;
+} | {
+    kind: "insert";
+    line: number;
+    widget: GuiNewWidget;
+    index?: number;
+}
+/** Paste `.gui` text as a child, re-indented for the destination. */
+ | {
+    kind: "insertRaw";
+    line: number;
+    fragment: string;
+    index?: number;
+} | {
+    kind: "delete";
+    line: number;
+}
+/** Copy the widget in as its own next sibling, optionally renamed. */
+ | {
+    kind: "duplicate";
+    line: number;
+    name?: string;
+}
+/** Wrap the widgets on `lines` (siblings) in a fresh container. */
+ | {
+    kind: "wrap";
+    lines: number[];
+    container: GuiNewWidget;
+}
+/** Read-only: the widget's block, verbatim, for a clipboard. */
+ | {
+    kind: "blockText";
+    line: number;
+};
+/** A declaration to write: `type = { properties }`, properties in order. */
+export interface GuiNewWidget {
+    type: string;
+    properties?: [string, string][];
+}
+/**
+ * For a single `op`, exactly one of `edits` and `refused` is present. A refusal
+ * is an ANSWER, not an error: it names why the gesture would not do what it
+ * looks like it does (a box owns its children's slots, a content-sized type
+ * ignores an explicit size, a type definition other files use). `warning` rides
+ * along with a write that went ahead but is only half honoured.
+ *
+ * For a BATCH (`ops`), `results` is present with one entry per op in the same
+ * order, `edits` is every applied op's edits together (apply them as ONE
+ * change), and `warning` joins the warnings. Top-level `refused` then names
+ * only a whole-request failure (a document that does not parse, an empty
+ * batch): a per-op refusal lives in its own entry and does not stop the others.
+ */
+export interface GuiSourceEditResult {
+    edits?: GuiTextEdit[];
+    refused?: string;
+    warning?: string;
+    /** `blockText` only: the copied block. */
+    blockText?: string;
+    /** Batch only: one verdict per requested op, in request order. */
+    results?: GuiSourceOpResult[];
+}
+/** One op's own answer inside a batch. */
+export interface GuiSourceOpResult {
+    /** Why this op wrote nothing. The others in the batch still applied. */
+    refused?: string;
+    /** This op wrote, and is only half honoured. */
+    warning?: string;
+    /** This op's contribution to the combined `edits`; empty when it wrote nothing. */
+    edits: GuiTextEdit[];
+    /** `blockText` only: the copied block. */
+    blockText?: string;
+}
+/**
+ * Request: text edit for a preview interaction (drag / property change);
+ * {@link GuiWidgetEditParams} -> {@link GuiWidgetEditResult} (null when the
+ * widget or property cannot be edited). The client applies the offsets via
+ * WorkspaceEdit so undo and the live preview loop stay in the editor.
+ *
+ * @deprecated Use {@link guiSourceEditRequest} with a `setProperties` op. This
+ * is a thin alias over the same core, kept for hosts already wired to it: it
+ * can only write the `position`/`size` pair and returns one edit or null, so a
+ * refusal reaches the caller as a bare null with no reason attached.
+ */
+export declare const guiWidgetEditRequest = "paradox/guiWidgetEdit";
+export interface GuiWidgetEditParams {
+    uri: string;
+    /** Authoritative document text the offsets refer to. */
+    text: string;
+    /** 0-based line of the widget's instance statement (GuiLayoutNode.line). */
+    line: number;
+    /** Pair property to set. */
+    property: "position" | "size";
+    values: [number, number];
+}
+export interface GuiWidgetEditResult {
+    /** UTF-16 offsets into the request text. */
+    start: number;
+    end: number;
+    newText: string;
+}
+/** Request: event graph; {@link EventGraphParams} -> {@link EventGraph}. */
+export declare const eventGraphRequest = "paradox/eventGraph";
+export interface EventGraphParams {
+    /** Focus definition (event id / on_action name); with namespace, either works. */
+    root?: string;
+    /** Restrict to an event namespace. */
+    namespace?: string;
+    /** Restrict to one workspace mod (absolute root path). */
+    modRoot?: string | null;
+    maxNodes?: number;
+    /** Also read each mod event's `theme`. Off by default: it costs one parse per
+     *  event file, and only a client that draws the theme's art needs it. */
+    themes?: boolean;
+}
+/**
+ * One row of a mod event's card, in EXECUTION order (immediate, then the
+ * options, then after) rather than file order. `line` is the join key an edge
+ * uses to anchor at the row that fires it ({@link EventGraphEdge.fromLine}).
+ */
+export interface EventGraphStep {
+    phase: "immediate" | "option" | "after";
+    /** Option ordinal within the event, 0-based. */
+    index?: number;
+    /** The option's localized text, when resolvable. */
+    text?: string;
+    /** 0-based line of the step's key in the event's file. */
+    line: number;
+}
+export interface EventGraphNode {
+    id: string;
+    kind: string;
+    source: "vanilla" | "parent" | "mod";
+    file?: string;
+    line?: number;
+    /** Localized title (best-effort: <id>.t / <id>_t / <id>.title lookups). */
+    title?: string;
+    /** The event's declared `theme`, when the request asked for themes. */
+    theme?: string;
+    /** How many `option` blocks this definition has (mod-side definitions only). */
+    options?: number;
+    /** The first keys of its `trigger` block, e.g. `is_adult, has_trait…`; absent = no trigger. */
+    triggerSummary?: string;
+    /** How many other nodes of this graph it fires; absent when it fires none. */
+    fires?: number;
+    /** The card's rows (mod events only), capped; {@link EventGraphNode.options} is the true count. */
+    steps?: EventGraphStep[];
+}
+export interface EventGraphEdge {
+    from: string;
+    to: string;
+    /** The referencing field (trigger_event, events, on_actions...). */
+    via: string;
+    /** Where in the source event the reference sits: an option's text, or immediate/after/… */
+    label?: string;
+    /** The block the reference sits in, normalized (option/immediate/after/effect/…). */
+    phase?: string;
+    /** 0-based line of that block's key: matches a step's `line` on the source node. */
+    fromLine?: number;
+    /** The trigger_event delay at this site, pre-rendered short: "30d", "7–14d", "2mo", "1y". */
+    delay?: string;
+    /** random_events weight at this site (raw script number). */
+    weight?: number;
+}
+/**
+ * What a query box may offer: the whole mod-side vocabulary of the graph, NOT
+ * the ids this particular query selected. It is the same pass that collects the
+ * mod's graph definitions, so a client gets it without a second request.
+ */
+export interface EventGraphSuggestions {
+    /** Mod-side event / on_action / decision ids, sorted, capped at 2000. */
+    ids: string[];
+    /** The event namespaces those ids belong to, sorted. */
+    namespaces: string[];
+}
+export interface EventGraph {
+    nodes: EventGraphNode[];
+    edges: EventGraphEdge[];
+    truncated: boolean;
+    /** Absent from servers that predate it; a client must tolerate that. */
+    suggestions?: EventGraphSuggestions;
+    /**
+     * Set only when the graph is empty AND the server knows why: the queried
+     * namespace/root exists, but outside what the graph shows (another workspace
+     * mod when a focus filter is on, a dependency mod, or vanilla). One
+     * user-readable sentence; absent = the generic "nothing found" story.
+     */
+    emptyReason?: string;
+}
+/**
+ * Request: the value sets an event editor may offer; {@link EventVocabularyParams}
+ * to {@link EventVocabularyResult}.
+ *
+ * Everything in the answer is DERIVED: the key lists come from the active
+ * profile's structure table, the field value sets from the schema's reference
+ * fields resolved through the definition index, and the effect/trigger lists
+ * from the user's script_docs (or the bundled wiki fallback). Nothing here is a
+ * hand-written name list, so a game patch that adds a theme or an effect shows
+ * up without a release.
+ */
+/**
+ * Request: the illustration an event theme puts behind its window;
+ * {@link EventBannerParams} to {@link EventBannerResult}.
+ *
+ * Resolved through the game's own two hops (event_themes -> event_backgrounds),
+ * taking the last `background` block that carries no `trigger`, which is the
+ * file's own unconditional fallback. `texture` is the engine's mod-relative
+ * path, exactly as a `.gui` file would spell it, so a client resolves it with
+ * the same mod-then-game lookup it uses for any other texture. A theme that
+ * resolves to nothing answers `reason` instead: the caller is expected to say
+ * so rather than draw a picture that is not the event's.
+ */
+export declare const eventBannerRequest = "paradox/eventBanner";
+export interface EventBannerParams {
+    /** Theme name as the event writes it (`theme = intrigue`). */
+    theme: string;
+}
+export interface EventBannerResult {
+    theme: string;
+    /** Mod-relative texture path, absent when nothing resolved. */
+    texture?: string;
+    /** Why nothing resolved. Present exactly when `texture` is absent. */
+    reason?: string;
+}
+export declare const eventVocabularyRequest = "paradox/eventVocabulary";
+export interface EventVocabularyParams {
+    /** Restrict definition-backed value sets to one workspace mod (plus vanilla). */
+    modRoot?: string | null;
+}
+/** One offerable value with the one-line docs an editor shows beside it. */
+export interface EventVocabularyItem {
+    value: string;
+    /** Documentation, capped. Empty when the source has none; never invented. */
+    doc?: string;
+    /** Dimmer right-hand label: where the value comes from (mod / vanilla / a kind). */
+    hint?: string;
+}
+/** Caps: an editor lists a page at a time, and these ride on every open. */
+export declare const EVENT_VOCABULARY_MAX_TOKENS = 600;
+export declare const EVENT_VOCABULARY_MAX_VALUES = 400;
+/**
+ * Request: the value set a VALUE belongs to, resolved through the definition
+ * index; {@link EventValueOptionsParams} -> {@link EventValueOptionsResult} |
+ * null. The static vocabulary maps a KEY to its values, which only works where
+ * the schema knows the key's context (an event's or option's own fields). Deep
+ * inside an effect tree the same key name means something else (`type` in
+ * `random_secret` is a secret, not an event type), so there the editor asks
+ * about the value it already has: `secret_cultivator` is an indexed `secret`,
+ * and the answer is every secret the index knows. Null = the value resolves to
+ * nothing enumerable; the editor falls back to a free input.
+ */
+export declare const eventValueOptionsRequest = "paradox/eventValueOptions";
+export interface EventValueOptionsParams {
+    value: string;
+    /** Restrict mod-side entries to one workspace mod (plus vanilla/parents). */
+    modRoot?: string | null;
+}
+export interface EventValueOptionsResult {
+    /** The definition kind the value resolved to (trait, secret, faith…). */
+    kind: string;
+    /** Every indexed definition of that kind, mod entries first, capped. */
+    items: EventVocabularyItem[];
+}
+export interface EventVocabularyResult {
+    /** Keys valid at an event's top level, most used first. */
+    eventKeys: EventVocabularyItem[];
+    /** Keys valid inside an `option` block, most used first. */
+    optionKeys: EventVocabularyItem[];
+    /**
+     * Key to the values that key accepts, for the keys whose value set is known:
+     * a declared enumeration, or a reference field resolved through the index
+     * (`theme` gives every indexed event_theme). Keys with a free value are absent.
+     */
+    values: Record<string, EventVocabularyItem[]>;
+    /** Effect tokens, most used first, capped at EVENT_VOCABULARY_MAX_TOKENS. */
+    effects: EventVocabularyItem[];
+    /** Trigger tokens, same ordering and cap. */
+    triggers: EventVocabularyItem[];
+    /** Saved scopes the mod writes (`save_scope_as`), sorted. */
+    savedScopes: EventVocabularyItem[];
+}
+/**
+ * Request: dependency explorer for any indexed definition;
+ * {@link DependenciesParams} -> {@link DependenciesResult}. Cursor-driven
+ * (uri + position) or by name (optionally disambiguated by kind).
+ */
+export declare const dependenciesRequest = "paradox/dependencies";
+export interface DependenciesParams {
+    /** Resolve the definition under this cursor position. */
+    uri?: string;
+    position?: {
+        line: number;
+        character: number;
+    };
+    /** Fallback: look the definition up by name (optionally by kind). */
+    name?: string;
+    kind?: string;
+    /**
+     * Also resolve {@link DependenciesResult.guiUses}: the `.gui` call sites that
+     * reach this definition through a scripted_gui. Off by default, it walks the
+     * scripted_gui definitions that any .gui file calls, which the plain
+     * dependency answer does not need.
+     */
+    guiUses?: boolean;
+}
+export interface DependencyDef {
+    name: string;
+    kind: string;
+    file: string;
+    /** 0-based. */
+    line: number;
+}
+export interface DependencyItem {
+    name: string;
+    file: string;
+    /** 0-based. */
+    line: number;
+}
+export interface DependencyGroup {
+    kind: string;
+    items: DependencyItem[];
+}
+export interface DependenciesResult {
+    /** The resolved definition, or null when nothing matches the cursor/name. */
+    def: DependencyDef | null;
+    /** Mod definitions/sites that reference `def` (mod files only; vanilla
+     * references aren't indexed, AD-4). Grouped by the containing definition's
+     * kind, else by file. */
+    dependents: DependencyGroup[];
+    /** Named definitions referenced inside `def`'s block, grouped by target kind. */
+    dependencies: DependencyGroup[];
+    /**
+     * The GUI side of the same question, present only when `guiUses` was asked
+     * for: which `.gui` files reach `def`, and through which scripted_gui. `[]`
+     * is the honest "none found"; the field is absent when it was not requested.
+     */
+    guiUses?: GuiUseSite[];
+}
+/**
+ * One `.gui` call site that reaches a script definition. The link is always a
+ * scripted_gui: `.gui` invokes script through `GetScriptedGui('name')` and
+ * nothing else, so the path is `file:line -> scripted_gui -> [effects] -> def`.
+ */
+export interface GuiUseSite {
+    /** Absolute path of the `.gui` file holding the call. */
+    file: string;
+    /** 0-based line of the `GetScriptedGui(...)` call. */
+    line: number;
+    /** The scripted_gui the call names. */
+    scriptedGui: string;
+    /**
+     * The scripted effects between that scripted_gui and the definition,
+     * outermost first. Empty means the scripted_gui's own blocks name it
+     * ("directly"); `["effect_a", "effect_b"]` renders as
+     * "via effect_a -> effect_b".
+     */
+    via: string[];
+}
+/**
+ * Request: the inferred scope chain at a cursor position;
+ * {@link ScopeAtParams} -> {@link ScopeAtResult} | null. Answers for OPEN
+ * script documents only (the server reads the client's text, not the disk);
+ * null means "not open / not a script document", which a status bar renders as
+ * nothing rather than as an error.
+ *
+ * This is a read-out of the same inference completion, hover and inlay hints
+ * run at a position: it ranks and annotates, never diagnoses, and never
+ * asserts more than the derived link tables actually say.
+ */
+export declare const scopeAtRequest = "paradox/scopeAt";
+export interface ScopeAtParams {
+    uri: string;
+    /** 0-based, as in LSP. */
+    position: {
+        line: number;
+        character: number;
+    };
+}
+/** One resolved step of the walk from the root scope down to the cursor. */
+export interface ScopeChainStep {
+    /**
+     * The key that produced the step: a link (`liege`), an iterator
+     * (`every_vassal`), `root`/`prev`, a `scope:x` / `var:x` anchor, or a data
+     * link abbreviated as `culture:…`. Absent on the FIRST step only, which is
+     * the enclosing definition's root scope and comes from no key.
+     */
+    entryKeyword?: string;
+    /** Scopes after this step; empty = unknown. */
+    scopes: string[];
+}
+/** A saved scope visible in the document, with the type it resolves to. */
+export interface SavedScopeInfo {
+    name: string;
+    /** Scopes the name resolves to; empty = unknown. */
+    scopes: string[];
+}
+export interface ScopeAtResult {
+    /**
+     * Scopes at the position. A SET, not one name: a link or iterator with
+     * several documented output scopes stays ambiguous instead of guessing, and
+     * an EMPTY array means unknown, which is a first-class answer here. Render
+     * several as `a|b` and none as "unknown".
+     */
+    scopes: string[];
+    /** The walk, outermost (root) first, one entry per scope-changing step. */
+    chain: ScopeChainStep[];
+    /**
+     * Saved scopes visible in the document, name-sorted: every `save_scope_as` /
+     * `save_scope_value_as` site in the file plus the engine-provided ambient
+     * scopes of its definition kind. NOT flow-sensitive, a save further down
+     * the file is listed too, matching what completion and hover already offer.
+     */
+    savedScopes: SavedScopeInfo[];
+}