@px-lsp/server 0.3.0 → 0.3.1

package/dist/types/packages/server/src/features/blockSnippets.d.ts

@@ -10,18 +10,25 @@
  *
  *  - the example's leading identifier must be the token's own name (dumps
  *    routinely paste a sibling's example: `add_title_law_effects` shows
- *    `add_title_law = …`);
+ *    `add_title_law = …`). A `<scope> = { name = { … } }` wrapper around a
+ *    single such block is peeled off first; any other placeholder key rejects;
  *  - the example must open a block and its braces must balance (truncated
  *    dumps that never close are dropped);
  *  - every key must be a plain lowercase identifier, or a `a/b/c` alternation
  *    of them (this drops pseudo-key weight lists, `X1 = { … } X2 = { … } …`);
- *  - a `#` comment means the example enumerates alternatives ("# or:") that
- *    cannot be collapsed into one template;
+ *  - a `#` comment is read ONLY when it says the field is optional
+ *    (`#Optional`, `# optional way to …`); every other comment means the
+ *    example enumerates alternatives ("# or:") or explains something we cannot
+ *    turn into script, and rejects the example;
  *  - `(optional)` and `...` truncate the body at that point;
  *  - `<name>` placeholders become tabstops, concrete example values become
  *    pre-filled tabstops.
  *
- * Both forms are produced at once: `snippet` for clients that declared
+ * An example that marks fields optional yields TWO templates rather than none:
+ * `snippet`/`plain` carry the required fields only, `full` carries every field
+ * the example shows.
+ *
+ * Both text forms are produced at once: `snippet` for clients that declared
  * snippetSupport, `plain` (no `${`, insertable as literal text) for the rest.
  */
 import type { TokenData } from "@px-lsp/protocol/types";
@@ -30,6 +37,15 @@ export interface BlockTemplate {
     snippet: string;
     /** Plain-text skeleton, free of `${`. */
     plain: string;
+    /**
+     * The same block with the fields the example marked `# optional` put back.
+     * Present only when the example marked at least one, so `full` never repeats
+     * what `snippet`/`plain` already say. Tabstops are numbered per form.
+     */
+    full?: {
+        snippet: string;
+        plain: string;
+    };
 }
 /** The block template for a token, or null when its example does not qualify. */
 export declare function blockTemplateFor(token: TokenData): BlockTemplate | null;

package/dist/types/packages/server/src/features/completion.d.ts

@@ -60,6 +60,17 @@ export declare class CompletionFeature {
      */
     private mergedCount;
     provide(document: TextDocument, offset: number, rootScopes: Set<Scope> | null, entry?: SchemaEntry | null, limit?: number): CompletionResult;
+    /**
+     * Definition and child-block skeletons (schema/skeletons.ts) as items of their
+     * own kind, ranked right after the block's structure keys.
+     *
+     * Gated on a BLANK line tail: a multi-line insert must not land inside an
+     * existing statement, and half a definition pasted over `= { … }` is worse
+     * than no offer. That gate also keeps these items out of every rank-eval
+     * sample, which always leaves the `= …` in place when it strips a key, so the
+     * ranking of existing items is unchanged by construction.
+     */
+    private skeletonItems;
     /**
      * Completing a scripted effect/trigger/modifier inserts a ready-to-fill
      * block: one `PARAM = <tabstop>` line per $PARAM$ the definition's body

package/dist/types/packages/server/src/features/definitionSkeletons.d.ts

@@ -0,0 +1,24 @@
+import type { ParseResult } from "../parser";
+import { type KindSkeleton, type RenderedSkeleton } from "../schema/skeletons";
+export interface SkeletonOffer {
+    /** Stable id: `<kind>` for the definition, `<kind>.<block>` for a child block. */
+    id: string;
+    /** What the item reads as: "new event", "option block". */
+    label: string;
+    /** How many of the game's own definitions the shape was measured over. */
+    detail: string;
+    /** A whole definition, or one of its child blocks. */
+    form: "definition" | "block";
+    text: RenderedSkeleton;
+}
+/**
+ * Skeletons offered at `offset` in a document the schema classifies as `kind`.
+ * Empty when the game has no measured skeleton for the kind, or when the cursor
+ * is deeper than a definition body (an effect block wants effects, not a form).
+ */
+export declare function skeletonsAt(parse: ParseResult, offset: number, kind: string, skeletons: Record<string, KindSkeleton> | undefined): SkeletonOffer[];
+/**
+ * Every skeleton the document's kind has, position-independent: what a picker
+ * offers, where the modder chooses the insert point rather than the cursor.
+ */
+export declare function skeletonsFor(parse: ParseResult, kind: string, skeletons: Record<string, KindSkeleton> | undefined): SkeletonOffer[];

package/dist/types/packages/server/src/games/ck3/schema.d.ts

@@ -1,7 +1,7 @@
 /**
  * The bundled CK3 schema table (rework plan AD-3). One entry per game folder
  * we understand; community-editable in-repo, extendable per-workspace via
- * .ck3modding/schema.json.
+ * .px-toolkit/schema.json.
  *
  * Every entry was verified against a real CK3 install (game version with
  * common/ ~150 subfolders): the folder was listed, a file opened, and the

package/dist/types/packages/server/src/games/eu5/index.d.ts

@@ -8,7 +8,7 @@
  * upstream, commit and license) and has NOT been checked against a live EU5
  * install. Folder→kind mappings are only as right as those rules are; report
  * gaps with the "Schema gap" issue form, and work around them locally with the
- * `<mod>/.eu5modding/schema.json` overlay.
+ * `<mod>/.px-toolkit/schema.json` overlay.
  */
 import type { GameProfile } from "../profile";
 export declare const eu5Profile: GameProfile;

package/dist/types/packages/server/src/games/profile.d.ts

@@ -10,6 +10,7 @@
  */
 import type { CalendarLocSpec } from "@px-lsp/protocol/calendarLoc";
 import type { DefRootKey, RefField, SchemaEntry, StructureSpec } from "../schema/types";
+import type { KindSkeleton } from "../schema/skeletons";
 import type { PlaceholderSpec } from "../data/modifierTemplates";
 import type { GuiLayoutQuirks, GuiTextMetrics } from "../gui/layoutEngine";
 import type { SaveSchema } from "../gui/saveSchema";
@@ -68,8 +69,10 @@ export interface GameMeta {
     engine: "jomini" | "clausewitz-classic";
     /** Mod descriptor convention: Paradox-launcher `.mod` file vs `.metadata/metadata.json`. */
     descriptor: "mod" | "metadata";
-    /** Per-workspace config dir holding schema.json / playset.json overlays. */
+    /** Per-mod config dir holding schema.json / playset.json overlays, workshop.json, the listing folder. */
     configDirName: string;
+    /** The pre-0.4.0 per-game name of that dir, still read as a fallback and renamed on first write. */
+    legacyConfigDirName?: string;
     /** Game folder under `Documents/Paradox Interactive/` (script_docs logs live in its logs/). */
     docsFolderName: string;
     /**
@@ -85,6 +88,12 @@ export interface GameMeta {
      */
     dataTypesCommand?: string;
     steamAppId: number;
+    /**
+     * Folder under the game data dir holding one icon per DLC, named after the
+     * DLC folder's number (`dlc_003.dds` or `dlc003.dds`). Absent = the install
+     * ships no such folder and the DLC's own `thumbnail.png` is used instead.
+     */
+    dlcIconDir?: string;
     /** Whether event files declare `namespace = x` and use `ns.N` event ids. */
     eventNamespaces: boolean;
     /**
@@ -126,6 +135,42 @@ export interface GameMeta {
      * not open for this game.
      */
     flagBuilder?: boolean;
+    /**
+     * The game ships its own in-game Coat of Arms designer, and the files that
+     * drive it (`gfx/coat_of_arms/{patterns,colored_emblems,color_palettes,
+     * emblem_layouts}/50_coa_designer_*.txt` and the `99_coa_designer_templates`
+     * coat-of-arms templates). Present = the toolkit offers the designer
+     * instead of the raw Flag Builder, when those files are actually on disk.
+     * Absent = the Flag Builder, as before.
+     */
+    coaDesigner?: boolean;
+    /**
+     * Visual content creators offered for this game, in Create-group order. A
+     * row is a definition kind the schema knows (the panel's command opens that
+     * creator), except `dynasty_tree`, which is a view over history files rather
+     * than one definition. Absent = no creator has been built against this
+     * game's own files, and the Create group shows only the scaffolds.
+     */
+    creators?: {
+        /** Schema kind, or the id of a bespoke creator that owns no single kind. */
+        kind: string;
+        label: string;
+        /** A Lucide icon name present in the client's webviews/shared/icons.ts. */
+        icon: string;
+        /** One-line hint for the panel row. */
+        tip?: string;
+    }[];
+    /**
+     * Where the game states how a modifier is PRINTED: the folder of format
+     * definitions (one block per modifier), and the `.gui` file whose `texticon`
+     * blocks map an icon name to its sprite. Both paths are relative to the game
+     * data dir. Absent = this game's print rules have not been read out of its
+     * own files, and `paradox/modifierFormats` answers null rather than guessing.
+     */
+    modifierFormats?: {
+        folder: string;
+        textIcons: string;
+    };
     /**
      * Database entry-mode prefixes legal on top-level definition keys
      * (EU5's `REPLACE:key`). The indexer strips a leading `<MODE>:` before
@@ -174,6 +219,30 @@ export interface GameMeta {
      */
     cacheSuffix: string;
 }
+/**
+ * Where a creator's condition builder gets the values of one trigger
+ * (`DefinitionForm.conditions`). Each source is something the server already
+ * holds, so a game patch changes the list without a release:
+ *
+ *   docList     the trigger's own script_docs entry enumerates them on its
+ *               metadata line ("has_dlc_feature … Traits: Valid Features: a,
+ *               b, and c", CK3 triggers.log 1.19)
+ *   kind        every indexed definition of a definition kind
+ *   innerKeys   the inner block keys of every definition of a kind, minus
+ *               `except` (a CK3 game rule's settings ARE its inner blocks;
+ *               the other two keys are `categories` and `default`, per
+ *               common/game_rules/_game_rules.info)
+ */
+export type ConditionValueSource = {
+    from: "docList";
+} | {
+    from: "kind";
+    kind: string;
+} | {
+    from: "innerKeys";
+    kind: string;
+    except?: string[];
+};
 /** A game's full knowledge bundle: meta plus the tables the engine consumes. */
 export interface GameProfile extends GameMeta {
     /** Folder→definition-kind table (see schema/types.ts). */
@@ -193,6 +262,14 @@ export interface GameProfile extends GameMeta {
      * those entries always win.
      */
     structures?: Record<string, StructureSpec>;
+    /**
+     * Definition skeletons per kind (data/<id>/skeletons.json, harvested by
+     * scripts/build-skeletons.ts): the shape a new definition of the kind takes,
+     * measured over the game's own files. Absent or empty = nobody has measured
+     * this game's vanilla tree, and completion offers no skeleton for it rather
+     * than a shape written from memory.
+     */
+    skeletons?: Record<string, KindSkeleton>;
     /**
      * Definition kinds that declare their own root scope in their body, keyed by
      * kind (scopes/inference.ts). Absent = every kind's root scope comes from the
@@ -201,6 +278,13 @@ export interface GameProfile extends GameMeta {
     defRootKeys?: Record<string, DefRootKey>;
     /** Templated-modifier placeholder table (data/modifierTemplates.ts). */
     modifierPlaceholders: Record<string, PlaceholderSpec>;
+    /**
+     * Triggers a creator's condition builder may offer a value list for, keyed
+     * by trigger name (`paradox/definitionForm`'s `conditions`). Absent = the
+     * creators offer no picker for this game and fall back to free input, which
+     * is the honest answer for a game whose sources have not been measured.
+     */
+    conditionValues?: Record<string, ConditionValueSource>;
     /**
      * Bundled `[ ... ]` data-function tables (data/<id>/dataTypes.json), when the
      * game ships one. Shape is data/dataTypes.ts's bundled-JSON shape; typed

package/dist/types/packages/server/src/schema/skeletons.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Definition skeletons: the canonical shape of one definition of a kind,
+ * derived from measured vanilla usage by scripts/build-skeletons.ts and shipped
+ * as packages/server/data/<game>/skeletons.json.
+ *
+ * Nothing here is written by hand. A key is in a skeleton because at least
+ * SKELETON_MAJORITY of the game's own definitions of that kind carry it; its
+ * order is the median position it holds in them; its pre-filled value is the
+ * value the corpus uses most, and only where the key's whole measured
+ * vocabulary is small enough to be a real choice. A key whose vocabulary is
+ * wider but entirely NUMERIC still gets the number the corpus writes most,
+ * since a key name is valid script nowhere in a numeric slot. Anything wider
+ * than that (loc keys, names, paths) gets its own name as placeholder text,
+ * which says "fill this in" without asserting a value.
+ *
+ * Both insert forms are rendered at once, exactly like features/blockSnippets.ts:
+ * `snippet` for clients that declared snippetSupport, `plain` (free of `${`) for
+ * the rest.
+ *
+ * No `vscode` imports: plain data plus pure renderers.
+ */
+/**
+ * Share of a kind's definitions a key must appear in to enter the skeleton.
+ * Half: a skeleton is what a definition of this kind USUALLY looks like, not
+ * the union of everything the folder has ever used. Applied identically to the
+ * keys of a nested block (share of that block's own occurrences).
+ */
+export declare const SKELETON_MAJORITY = 0.5;
+/** One key of a skeleton body. */
+export interface SkeletonKey {
+    key: string;
+    /**
+     * The key's whole measured value vocabulary, most-used first. Set only where
+     * the corpus uses few enough distinct values for the list to be a choice
+     * rather than a guess; absent = the value is a placeholder.
+     */
+    choices?: string[];
+    /**
+     * The single most-used measured value, set only where the vocabulary is too
+     * wide to offer as a choice AND every value the corpus writes for the key is
+     * a number. A key name is valid script nowhere in a numeric slot, so a
+     * measured number is the honest placeholder; it stays a tabstop, so it still
+     * reads as "fill this in".
+     */
+    placeholder?: string;
+    /**
+     * Nested one level: the block this key opens, carrying the keys measured in
+     * at least SKELETON_MAJORITY of its occurrences. An empty array = the block
+     * has no stable shape, so it is inserted empty.
+     */
+    block?: SkeletonKey[];
+}
+/** A named child block of a definition, offered on its own. */
+export interface SkeletonBlock {
+    /** Occurrences of the block measured across the kind's definitions. */
+    sampled: number;
+    keys: SkeletonKey[];
+}
+export interface KindSkeleton {
+    /** Vanilla definitions of this kind the skeleton was measured over. */
+    sampled: number;
+    keys: SkeletonKey[];
+    /**
+     * The file-level key the kind's definition names were measured to derive
+     * from: at least SKELETON_MAJORITY of the folder's files declare it as a
+     * top-level scalar, and at least that share of the kind's names are
+     * `<its value>.<number>` (`namespace = intrigue` → `intrigue.0001`). Absent =
+     * names are plain identifiers and files need no header line.
+     */
+    nameFromHeader?: string;
+    /** Child-block skeletons, keyed by the block's key. */
+    blocks?: Record<string, SkeletonBlock>;
+}
+export interface SkeletonData {
+    meta: {
+        generated: string;
+        sources: string[];
+        majority: number;
+    };
+    /** Definition kind, as the schema table spells it. */
+    kinds: Record<string, KindSkeleton>;
+}
+/** Both insert forms of one skeleton. */
+export interface RenderedSkeleton {
+    /** `${n:…}` tabstop form; only for clients declaring snippetSupport. */
+    snippet: string;
+    /** Plain-text skeleton, free of `${`. */
+    plain: string;
+}
+export interface SkeletonRenderOptions {
+    /**
+     * Value of the header key the target document already declares
+     * (`namespace = my_events`), so a generated name matches its own file.
+     */
+    headerValue?: string;
+    /** Write the header line above the definition (the document declares none). */
+    withHeader?: boolean;
+}
+/** The whole definition, header line included when the document lacks it. */
+export declare function renderDefinitionSkeleton(kind: string, skel: KindSkeleton, opts?: SkeletonRenderOptions): RenderedSkeleton;
+/** One named child block (`option = { name = … }`), inserted on its own. */
+export declare function renderBlockSkeleton(name: string, block: SkeletonBlock): RenderedSkeleton;

package/dist/types/packages/server/src/schema/types.d.ts

@@ -46,6 +46,13 @@ export interface KeySpec {
      * vocabulary, the completion regression rank-eval caught in 2026-07.
      */
     curated?: boolean;
+    /**
+     * Definition kinds this key's value names, where a global `RefField` would
+     * be wrong because the key means different things in different folders
+     * (`opposites` is a trait list here and a scripted_relation list there).
+     * Per-kind and therefore unambiguous; read by the creators' form request.
+     */
+    refKinds?: string[];
 }
 /** The document shape of a definition kind: top-level keys plus named sub-blocks. */
 export interface StructureSpec {
@@ -96,6 +103,29 @@ export interface SchemaEntry {
      * of this kind actually define.
      */
     requiredLoc?: string[];
+    /**
+     * Every loc key the game generates for a definition of this kind, `$` = the
+     * name, as the folder's `_*.info` doc states them. A SUPERSET of
+     * `requiredLoc`, which may only carry the patterns ≥95% of vanilla actually
+     * defines because a diagnostic hangs off it; a creator writes the whole set
+     * and asks the modder for each. Absent = `requiredLoc` is the whole set.
+     */
+    locPatterns?: string[];
+    /**
+     * Where the game looks for a definition's default icon, relative to the
+     * game/mod root, forward slashes, no trailing slash. Only set where the
+     * folder's `_*.info` doc states the path; absent = this kind has no
+     * name-derived icon and a creator offers no icon picker for it.
+     */
+    iconFolder?: string;
+    /**
+     * Key inside a definition's body whose value sorts this kind's definitions
+     * into families, when one folder holds several (`type = ethos` in
+     * common/culture/pillars). A creator that draws one picker per family reads
+     * it through paradox/definitionForm; nothing else does. Absent = the kind is
+     * one flat list.
+     */
+    groupKey?: string;
     /** Scope(s) a definition of this type pushes as root in its script blocks (Phase 3). */
     rootScopes?: string[];
     /** Include definitions of this kind in completion lists (default true).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@px-lsp/server",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "license": "GPL-3.0-or-later",
   "description": "Language server for Paradox script (Crusader Kings III first), usable over node-ipc or stdio from any LSP client.",
   "keywords": [
@@ -43,10 +43,10 @@
     "./*": "./src/*.ts"
   },
   "dependencies": {
+    "@px-lsp/protocol": "0.2.1",
     "vscode-languageserver": "^10.1.0",
     "vscode-languageserver-textdocument": "^1.0.12",
-    "vscode-uri": "^3.1.0",
-    "@px-lsp/protocol": "0.2.0"
+    "vscode-uri": "^3.1.0"
   },
   "scripts": {
     "compile": "esbuild src/server.ts --bundle --outfile=dist/server.js --format=cjs --platform=node --target=node18 --banner:js=\"#!/usr/bin/env node\"",

package/src/coa/coa.ts

@@ -31,6 +31,20 @@ export interface CoaInstance {
   rotation: number;
   scale: [number, number];
   position: [number, number];
+  /**
+   * The in-game designer's z key, absent on a hand-written instance.
+   *
+   * Measured on the vanilla corpus (game version 1.19.0.6): the 387 uses in 01_landed_titles.txt and
+   * 90_dynasties.txt hold only the values 1.01 .. 13.01, and in 229 of the 234
+   * definitions that carry any exactly one instance has none, so the designer
+   * writes `<draw index>.01` and omits the first. It spans layers (134
+   * definitions interleave them), but WITHIN one layer the file order is
+   * already the depth order in 336 of 337 layers (the exception,
+   * 90_dynasties.txt `dali_duan`, repeats 0 and 1.01), so sorting by it would
+   * change nothing there. The renderer therefore keeps file order and the
+   * value is carried only so a round trip does not drop it.
+   */
+  depth?: number;
 }
 
 export interface CoaSubInstance {
@@ -50,6 +64,22 @@ export interface CoaFlag {
   layers: CoaLayer[];
 }
 
+/**
+ * One row of a game's coat-of-arms designer catalog (a pattern or an emblem),
+ * in the order its file lists it. The reader is coaDesigner.ts; the type lives
+ * here because the webview app carries it and must not bundle the parser.
+ */
+export interface DesignerEntry {
+  /** The texture file name, e.g. `ce_fleur.dds`. */
+  file: string;
+  /** Color buttons to show. Absent in the file means "as many as the kind has". */
+  colors: number;
+  /** False for `visible = no`: the entry declares colors but stays out of the grid. */
+  visible: boolean;
+  /** Emblems only; "" for a pattern. */
+  category: string;
+}
+
 /** The slots a flag or a layer may fill, in the order the game names them. */
 export const COLOR_SLOTS = [
   "color1",
@@ -174,6 +204,7 @@ export function writeFlag(flag: CoaFlag): string {
         if (i.rotation !== 0) parts.push(`rotation = ${fmt(i.rotation)}`);
         parts.push(`scale = { ${fmt(i.scale[0])} ${fmt(i.scale[1])} }`);
         parts.push(`position = { ${fmt(i.position[0])} ${fmt(i.position[1])} }`);
+        if (i.depth !== undefined) parts.push(`depth = ${fmt(i.depth)}`);
         lines.push(`\t\tinstance = { ${parts.join(" ")} }`);
       }
     }

package/src/coa/coaDesigner.ts

@@ -0,0 +1,131 @@
+/**
+ * The files behind the game's own Coat of Arms designer, parsed.
+ *
+ * Everything the designer offers is script the game ships, and every list in
+ * it is ordered by the file rather than alphabetically (both catalog files say
+ * so in their own header comment), so these readers keep file order:
+ *
+ * - `gfx/coat_of_arms/patterns/50_coa_designer_patterns.txt` and
+ *   `gfx/coat_of_arms/colored_emblems/50_coa_designer_emblems.txt`:
+ *   `file.dds = { colors = N visible = no category = animals }`. `colors` is
+ *   how many color buttons the entry shows, `visible = no` keeps an entry out
+ *   of the grid while still declaring its color count, `category` groups the
+ *   emblem grid (emblems only).
+ * - `gfx/coat_of_arms/color_palettes/50_coa_designer_palettes.txt`:
+ *   `coa_designer_background_colors = { red = {} ... }`, names into
+ *   `common/named_colors`.
+ * - `gfx/coat_of_arms/emblem_layouts/50_coa_designer_emblem_layouts.txt`:
+ *   whole coats of arms written against the `@pattern`, `@color_1..3`,
+ *   `@texture_1..2` placeholders defined at the top of that file. They are
+ *   read UNRESOLVED (parseCoaFile leaves a non-numeric `@name` as it stands),
+ *   which is exactly what a layout is: a shape with holes for the design's own
+ *   pattern, colors and emblems.
+ * - `common/coat_of_arms/coat_of_arms/99_coa_designer_templates.txt`: the
+ *   `template = { }` block holding `coa_designer_blank_default`, whose colors
+ *   are `list "normal_colors"` references into
+ *   `common/coat_of_arms/template_lists/color_lists.txt`.
+ *
+ * Measured against the vanilla files (game version 1.19.0.6): 42 pattern rows
+ * of which 38 are visible, 1578 emblem rows of which 1576 are visible across 13
+ * categories, 13 palette colors, 35 layouts and 1 template.
+ *
+ * Host and test side only (it parses script), like coaParse.ts.
+ */
+import { parseScript } from "../parser/parser";
+import type { BlockNode } from "../parser/cst";
+import { parseFlag } from "./coaParse";
+import type { CoaFlag, DesignerEntry } from "./coa";
+
+export type { DesignerEntry };
+
+/** Every `@name = value` at the top of a designer file, as raw text. */
+export function parseAtDefaults(text: string): Record<string, string> {
+  const { root } = parseScript(text);
+  const out: Record<string, string> = {};
+  for (const s of root.statements) {
+    if (s.kind !== "assignment" || !s.value || s.value.kind !== "scalar") continue;
+    if (s.key.text.startsWith("@")) out[s.key.text] = s.value.text;
+  }
+  return out;
+}
+
+/**
+ * A designer catalog file (patterns or emblems). `maxColors` fills in the
+ * count for a row that names none, which the files' own header calls "assume
+ * maximum number of colors".
+ */
+export function parseDesignerCatalog(text: string, maxColors: number): DesignerEntry[] {
+  const { root } = parseScript(text);
+  const out: DesignerEntry[] = [];
+  for (const s of root.statements) {
+    if (s.kind !== "assignment" || s.value?.kind !== "block") continue;
+    const entry: DesignerEntry = { file: s.key.text, colors: maxColors, visible: true, category: "" };
+    for (const a of s.value.statements) {
+      if (a.kind !== "assignment" || a.value?.kind !== "scalar") continue;
+      if (a.key.text === "colors") {
+        const n = Number(a.value.text);
+        if (Number.isFinite(n)) entry.colors = n;
+      } else if (a.key.text === "visible") entry.visible = a.value.text !== "no";
+      else if (a.key.text === "category") entry.category = a.value.text;
+    }
+    out.push(entry);
+  }
+  return out;
+}
+
+/** The palette's color names, in list order: `coa_designer_background_colors = { red = {} … }`. */
+export function parseDesignerPalette(text: string): string[] {
+  const { root } = parseScript(text);
+  for (const s of root.statements) {
+    if (s.kind !== "assignment" || s.key.text !== "coa_designer_background_colors") continue;
+    if (s.value?.kind !== "block") continue;
+    return s.value.statements
+      .filter((c) => c.kind === "assignment")
+      .map((c) => (c as { key: { text: string } }).key.text);
+  }
+  return [];
+}
+
+/**
+ * The first color of each `color_lists` entry: what a template's
+ * `list "normal_colors"` resolves to here. The game rolls a weight
+ * (`30 = "red"`) against the character; a designer that has no character picks
+ * the list's first entry, which is also the heaviest one in every vanilla list.
+ */
+export function parseColorLists(text: string): Record<string, string> {
+  const { root } = parseScript(text);
+  const out: Record<string, string> = {};
+  for (const s of root.statements) {
+    if (s.kind !== "assignment" || s.key.text !== "color_lists" || s.value?.kind !== "block") continue;
+    for (const list of s.value.statements) {
+      if (list.kind !== "assignment" || list.value?.kind !== "block") continue;
+      for (const row of list.value.statements) {
+        if (row.kind !== "assignment" || row.value?.kind !== "scalar") continue;
+        if (!/^\d+$/.test(row.key.text)) continue;
+        out[list.key.text] = row.value.text;
+        break;
+      }
+    }
+  }
+  return out;
+}
+
+/**
+ * The designer templates of a `template = { }` file. `list "x"` colors are
+ * replaced by `colorLists[x]` before parsing, so the caller gets a plain flag.
+ */
+export function parseDesignerTemplates(text: string, colorLists: Record<string, string>): CoaFlag[] {
+  const resolved = text.replace(/\blist\s+"([^"]+)"/g, (whole, name: string) =>
+    colorLists[name] !== undefined ? `"${colorLists[name]}"` : whole
+  );
+  const { root } = parseScript(resolved);
+  const out: CoaFlag[] = [];
+  for (const s of root.statements) {
+    if (s.kind !== "assignment" || s.key.text !== "template" || s.value?.kind !== "block") continue;
+    for (const t of s.value.statements) {
+      if (t.kind !== "assignment" || t.value?.kind !== "block") continue;
+      out.push(parseFlag(t.key.text, t.value as BlockNode));
+    }
+  }
+  return out;
+}

package/src/coa/coaParse.ts

@@ -138,6 +138,9 @@ function parseInstances(statements: Statement[], vars: Vars): CoaInstance[] {
       if (a.key.text === "rotation" && a.value.kind === "scalar") {
         const r = resolveNumber(a.value.text, vars);
         if (Number.isFinite(r)) inst.rotation = r;
+      } else if (a.key.text === "depth" && a.value.kind === "scalar") {
+        const d = resolveNumber(a.value.text, vars);
+        if (Number.isFinite(d)) inst.depth = d;
       } else if (a.key.text === "scale" && a.value.kind === "block") inst.scale = pair(a.value, vars, [1, 1]);
       else if (a.key.text === "position" && a.value.kind === "block")
         inst.position = pair(a.value, vars, [0.5, 0.5]);