Merge pull request 'Cross-file navigation and rename for PSC .def templates and addresses' (#46) from DEF_file into main

Add client and server support to navigate, inspect, reference, and rename block
template and address symbols declared in PSC .def files:

- Client: register language providers for .def (definition, hover, references,
  prepare/provide rename) and send the current document text with each request.
- Server: parse .def files into DefDocument/DefDeclaration/DefReference, expose
  def-specific LSP endpoints (definition/hover/references/prepareRename/rename),
  and integrate .def lookups into existing Tcl hover/definition/references/rename
  flows so Tcl calls jump to .def declarations.
- Tcl server keeps a snapshot API for .def documents (current editor content can
  replace file on request); only declared names in loaded .def files can be
  renamed. Name validation uses DEF_NAME_RE.

Update README and CHANGELOG to document navigation features.

.gitignore

@@ -9,4 +9,5 @@ __pycache__
 .nox
 *.g4
 .antlr
-.claude
+.claude
+/test/postprocessor/

.vscode/launch.json

@@ -13,7 +13,7 @@
             "args": [
                 "--extensionDevelopmentPath=${env:TEMP}/nx-post-support-vscode-debug",
                 "${env:TEMP}/nx-post-support-vscode-debug",
-                "${env:TEMP}/nx-post-support-vscode-debug/test/test.tcl"
+                "${env:TEMP}/nx-post-support-vscode-debug/test/postprocessor"
             ],
             "cwd": "${env:TEMP}/nx-post-support-vscode-debug",
             "outFiles": ["${env:TEMP}/nx-post-support-vscode-debug/dist/**/*.js"],
@@ -21,7 +21,7 @@
                 "args": [
                     "--extensionDevelopmentPath=${workspaceFolder}",
                     "${workspaceFolder}",
-                    "${workspaceFolder}/test/test.tcl"
+                    "${workspaceFolder}/test/postprocessor"
                 ],
                 "cwd": "${workspaceFolder}",
                 "outFiles": ["${workspaceFolder}/dist/**/*.js"],
@@ -39,6 +39,48 @@
             "autoAttachChildProcesses": true,
             "preLaunchTask": "NX Post Support: Compile Debug"
         },
+        {
+            // Linux workaround: js-debug's extensionHost attach probes localhost and [::1]
+            // in parallel and aborts when [::1] is refused. Start the dev host ourselves
+            // with a fixed inspector port and attach directly to 127.0.0.1.
+            "name": "Run Extension (Linux)",
+            "type": "node",
+            "request": "attach",
+            "address": "127.0.0.1",
+            "port": 9333,
+            "timeout": 30000,
+            "continueOnAttach": true,
+            "sourceMaps": true,
+            "outFiles": ["${workspaceFolder}/dist/**/*.js"],
+            "resolveSourceMapLocations": [
+                "${workspaceFolder}/dist/**/*.js",
+                "!**/node_modules/**"
+            ],
+            "skipFiles": ["<node_internals>/**"],
+            "preLaunchTask": "NX Post Support: Start Dev Host (Linux)"
+        },
+        {
+            "name": "Debug Extension (Linux, hidden)",
+            "type": "node",
+            "request": "attach",
+            "address": "127.0.0.1",
+            "port": 9333,
+            "timeout": 30000,
+            "continueOnAttach": true,
+            "sourceMaps": true,
+            "outFiles": ["${workspaceFolder}/dist/**/*.js"],
+            "resolveSourceMapLocations": [
+                "${workspaceFolder}/dist/**/*.js",
+                "!**/node_modules/**"
+            ],
+            "skipFiles": ["<node_internals>/**"],
+            "preLaunchTask": "NX Post Support: Start Dev Host with debugpy (Linux)",
+            "presentation": {
+                "hidden": true,
+                "group": "",
+                "order": 4
+            }
+        },
         {
             "name": "Python Attach",
             "type": "debugpy",
@@ -59,7 +101,7 @@
             "args": [
                 "--extensionDevelopmentPath=${env:TEMP}/nx-post-support-vscode-debug",
                 "${env:TEMP}/nx-post-support-vscode-debug",
-                "${env:TEMP}/nx-post-support-vscode-debug/test/test.tcl"
+                "${env:TEMP}/nx-post-support-vscode-debug/test/postprocessor"
             ],
             "cwd": "${env:TEMP}/nx-post-support-vscode-debug",
             "outFiles": ["${env:TEMP}/nx-post-support-vscode-debug/dist/**/*.js"],
@@ -67,7 +109,7 @@
                 "args": [
                     "--extensionDevelopmentPath=${workspaceFolder}",
                     "${workspaceFolder}",
-                    "${workspaceFolder}/test/test.tcl"
+                    "${workspaceFolder}/test/postprocessor"
                 ],
                 "cwd": "${workspaceFolder}",
                 "outFiles": ["${workspaceFolder}/dist/**/*.js"],
@@ -118,6 +160,16 @@
                 "group": "",
                 "order": 1
             }
+        },
+        {
+            "name": "Debug Extension and Python (Linux)",
+            "configurations": ["Python debug server (hidden)", "Debug Extension (Linux, hidden)"],
+            "stopAll": true,
+            "presentation": {
+                "hidden": false,
+                "group": "",
+                "order": 2
+            }
         }
     ]
 }

.vscode/tasks.json

@@ -28,6 +28,47 @@
                 "panel": "dedicated",
                 "clear": true
             }
+        },
+        {
+            "label": "NX Post Support: Start Dev Host (Linux)",
+            "detail": "Opens the Extension Development Host with the inspector on 127.0.0.1:9333 (workaround for js-debug localhost/::1 attach bug).",
+            "type": "shell",
+            "command": "\"$(dirname \"${execPath}\")/bin/$(basename \"${execPath}\")\" --new-window --inspect-brk-extensions=9333 --extensionDevelopmentPath=\"${workspaceFolder}\" \"${workspaceFolder}\" \"${workspaceFolder}/test/postprocessor\"",
+            "options": {
+                "shell": {
+                    "executable": "/bin/bash",
+                    "args": ["-c"]
+                }
+            },
+            "dependsOn": "NX Post Support: Compile Debug",
+            "problemMatcher": [],
+            "presentation": {
+                "reveal": "silent",
+                "panel": "dedicated"
+            }
+        },
+        {
+            "label": "NX Post Support: Start Dev Host with debugpy (Linux)",
+            "detail": "Same as above, but the language server connects to the debugpy listener on 127.0.0.1:5678.",
+            "type": "shell",
+            "command": "\"$(dirname \"${execPath}\")/bin/$(basename \"${execPath}\")\" --new-window --inspect-brk-extensions=9333 --extensionDevelopmentPath=\"${workspaceFolder}\" \"${workspaceFolder}\" \"${workspaceFolder}/test/postprocessor\"",
+            "options": {
+                "shell": {
+                    "executable": "/bin/bash",
+                    "args": ["-c"]
+                },
+                "env": {
+                    "USE_DEBUGPY": "True",
+                    "NXPS_DEBUG_HOST": "127.0.0.1",
+                    "NXPS_DEBUG_PORT": "5678"
+                }
+            },
+            "dependsOn": "NX Post Support: Compile Debug",
+            "problemMatcher": [],
+            "presentation": {
+                "reveal": "silent",
+                "panel": "dedicated"
+            }
         }
     ]
 }

CHANGELOG.md

@@ -1,46 +1,313 @@
+# Changelog
+
+All notable changes to NX Postprocessor Support are listed here, newest release first.
+Versions correspond to the Git tags of this repository.
+
 ## Unreleased
 
-- Add incoming and outgoing call hierarchy for custom TCL procedures and MOM event handlers
-- Add document highlights for procedure and variable occurrences
-- Make completion context-aware and prioritize local, current-file, workspace, and built-in symbols
-- Add command-aware completion for Tcl subcommands, fixed arguments, and valid options
-- Add semantic argument completion for variables, procedures, namespaces, and local file paths
-- Add placeholder-based snippets for common Tcl structures and `dict for`
-- Integrate the NX Tcl Remote Debugger directly into NX Postprocessor Support
-- Add `nx-tcl` attach configurations and breakpoint support for TCL and DEF files
-- Support breakpoints, stepping, stack frames, variables, watches, evaluation, logpoints, hit conditions, and Tcl error stops
-- Add generation-safe stack and variable references so delayed VS Code requests cannot address stale NX frames
-- Add command-buffer breakpoint handling for `LIB_GE_command_buffer_edit_*` source bodies
-- Extend the README with launch configuration, path mapping, and debugger usage
-- Prevent truncated TCL inlay hints and add configurable parameter hint modes
-- Add inlay hints for built-in NX procedures, variadic arguments, and visible ranges
-- Add inlay hint documentation and navigation to custom procedure definitions
-- Add signature help for custom TCL procedures and built-in NX/MOM procedures
-- Clean stale TCL indexes on close, delete, and rename operations
-- Make background parsing and index updates thread-safe
-- Improve TCL response times with debounced edits and cached semantic, inlay, hover, completion, and variable indexes
-- Debounce CDL/DEF diagnostics and remove per-line diagnostic logging
+### Added
 
-## [0.0.1]
+- Go to Definition from block template and address arguments in Tcl (`MOM_do_template`, `MOM_force`, `MOM_suppress`, `MOM_ask_address_value`, ...) to the `BLOCK_TEMPLATE`/`ADDRESS` declaration in the PSC `.def` files
+- Hover over block templates shows the template body; hover over addresses shows format, leader, trailer, min/max, and modality
+- Find References and Rename for block templates and addresses across Tcl and `.def` files, including addresses used inside block templates
+- Go to Definition, hover, references, and rename also work inside `.def` files
 
-- Initial release
+### Documentation
 
-## [0.0.2]
+- Document DEF block templates, addresses, `BLOCK_LIST`/`ADDR_LIST`, and the formatting changes in the README
 
-- Add Autocomp for TYPE
+## [2026.9.700] - 2026-09-24
 
-## [0.1.0]
+### Added
 
-- Add Hover Feature
+- `BLOCK_LIST` and `ADDR_LIST` completion keywords that list all loaded block templates or addresses; the keyword is replaced by the selected quoted name
 
-## [0.2.0]
+### Changed
 
-- Add DEF File Support
+- Format comments with a space after `#` (`#Comment` becomes `# Comment`); `##` separators, `#!`, and comments that already start with whitespace stay unchanged
 
-## [2026.6.100]
+## [2026.9.600] - 2026-09-24
 
-- Fix several bugs
+### Added
 
-## [2026.6.200]
+- Read `BLOCK_TEMPLATE` and `ADDRESS` names from the `.def` files listed under `<DefinedEvents>` in PSC layers; changes to PSC and DEF files are picked up automatically
+- Suggest block templates for `MOM_do_template` and addresses for `MOM_ask_address_value`, `MOM_force`, and `MOM_suppress`, each followed by variables
+- Suggest `Always`, `Once`, and `Off` for the first argument of `MOM_force` and `MOM_suppress`
+- Insert block templates, addresses, and modes in quotes without doubling typed or auto-closed quotes; insert variables with a leading `$`
+- Persistent workspace index in the extension storage, so restarts skip reparsing unchanged files; the cache is discarded automatically when the server or bundled tclint changes
 
-- Fix foramtting bug
+### Changed
+
+- Reparse only the top-level Tcl commands touched by an edit instead of the whole file
+- Speed up TclOO completion, signature help, inlay hints, and Go to Definition by reusing the cached syntax tree and skipping files without classes
+- Speed up references, document highlights, and call hierarchy with cached definition lookups
+- Keep background indexing from blocking requests that need a fresh syntax tree
+
+### Fixed
+
+- Format and lint `uplevel` bodies as Tcl scripts instead of leaving them untouched
+- Stop the Python debug bootstrap with a clear error instead of hanging when no debugpy listener or only a stale one is available
+
+## [2026.9.501] - 2026-09-21
+
+### Fixed
+
+- Highlight braced stored-procedure names in `lappend` arguments
+
+## [2026.9.500] - 2026-09-21
+
+### Added
+
+- Index Tcl scripts referenced by PSC layers, including external folders, environment-variable folders, and legacy Windows encoding
+- Share TclOO class metadata across files for completion, signature help, inlay hints, and highlighting
+- Go to Definition for TclOO classes, constructors, and resolved methods, including PSC library definitions
+- CDL event handler snippets declare an extra `<var>_defined` global for parameters marked `TOGGLE Off`
+- Allow `INVALID` in the CDL `CATEGORY` grammar
+
+## [2026.9.400] - 2026-09-11
+
+### Added
+
+- Document-local TclOO method completion for `new`/`create` instances, `my`, and statically inferred return chains
+- Signature help and parameter inlay hints for resolved TclOO methods and constructors, including optional and variadic arguments
+- Suggest TclOO class names as classes and semantically highlight their declarations and calls
+- Keep completion working while the file has syntax errors
+
+## [2026.9.300] - 2026-09-10
+
+### Added
+
+- Array key completion, including keys built with substitutions
+- Generated CDL event handler snippets declare `args`
+
+## [2026.9.220] - 2026-09-08
+
+### Fixed
+
+- Completion inside unfinished braced arguments now recognizes nested commands
+
+## [2026.9.210] - 2026-09-04
+
+### Added
+
+- Highlight escaped quoted strings and embedded variables in DEF files
+
+## [2026.9.200] - 2026-09-03
+
+### Added
+
+- Command-aware completion for Tcl subcommands, fixed argument values, and options such as `string compare -nocase`
+- Semantic argument completion for variables, procedures, namespaces, and local file paths
+- Placeholder-based snippets for `if`, `foreach`, `proc`, `switch`, `try`, and `dict for`
+
+## [2026.9.100] - 2026-09-03
+
+### Added
+
+- Incoming and outgoing call hierarchy for custom Tcl procedures and MOM event handlers
+- Document highlights for procedure and variable occurrences
+- Context-aware completion that ranks local, current-file, workspace, and built-in symbols in that order
+
+### Changed
+
+- Update lsprotocol to 2025.0.0
+
+## [2026.8.300] - 2026-08-28
+
+### Added
+
+- Integrate the NX Tcl Remote Debugger; the separate `local-nx.nx-tcl-debug` extension is no longer needed
+- `nx-tcl` attach configurations and breakpoints in Tcl and DEF files
+- Stepping, call stack, scopes, variables, watches, evaluation, logpoints, hit conditions, and Tcl error stops
+- Breakpoints in `LIB_GE_command_buffer_edit_*` bodies, mapped back to their source and owning procedure
+
+## [2026.8.200] - 2026-08-19
+
+### Added
+
+- Configurable parameter-name inlay hints (`inlayHints.parameterNames`, `inlayHints.suppressWhenArgumentMatchesName`) for custom and built-in NX procedures, including variadic arguments
+- Unlimited inlay hint length for Tcl files, so later parameter names are not truncated
+
+### Changed
+
+- Cache semantic tokens, inlay hints, hover, completion, and variable indexes and debounce edits and diagnostics for faster responses
+
+## [2026.8.100] - 2026-08-19
+
+### Added
+
+- Workspace symbol index with Go to Definition, references, and rename
+- Signature help for custom Tcl procedures and built-in NX/MOM procedures
+- CDL event handler snippets and hover with generated handler and `mom_` parameter hints
+- Keep indexes in sync when Tcl files are changed, deleted, or renamed on disk
+
+## [2026.6.201] - 2026-06-22
+
+### Fixed
+
+- Preserve whitespace inside single-line braced expressions when formatting
+
+## [2026.6.200] - 2026-06-22
+
+### Fixed
+
+- Tcl formatting bug caused by the formatter options
+
+## [2026.6.100] - 2026-06-18
+
+### Changed
+
+- Folding ranges for Tcl are computed by the language server, avoiding duplicate regions
+- Language server restarts are serialized so only one server runs at a time
+- Pin the Python dependencies of the server and update the bundled libraries
+
+### Fixed
+
+- Several stability fixes
+
+## [2025.9.200] - 2025-09-01
+
+### Changed
+
+- Install server dependencies with uv instead of pip
+- Relicense to AGPL-3.0-or-later
+
+## [2025.9.101] - 2025-08-16
+
+### Added
+
+- Signature help
+- Variable checks and additional semantic tokens
+
+### Fixed
+
+- `incr` on variables that already exist and `foreach` loop variables
+
+## [2025.8.400] - 2025-08-15
+
+### Added
+
+- Outline for DEF and CDL files
+
+### Fixed
+
+- Duplicate `MOM_add_to_block_buffer` entry renamed to `MOM_add_to_line_buffer`
+
+## [2025.8.300] - 2025-08-12
+
+### Added
+
+- Go to Definition and document outline for Tcl
+- Variable index with positions
+- Procedure documentation in hover
+
+### Fixed
+
+- Formatter deleting line continuations (`\`)
+- Wrong semantic highlighting in several cases
+
+## [2025.8.202] - 2025-08-12
+
+### Fixed
+
+- Formatter deleting line continuations (`\`)
+
+## [2025.8.201] - 2025-08-11
+
+### Fixed
+
+- Highlighting errors
+
+## [2025.8.200] - 2025-08-09
+
+- Version change only
+
+## [2025.8.2] - 2025-08-09
+
+- Version change only
+
+## [2025.08.1] - 2025-08-09
+
+### Added
+
+- Load procedures from all workspace files and PSC-referenced scripts for completion
+- Extension icon
+
+## [0.4.14] - 2025-08-04
+
+### Added
+
+- `LIB_GE_command_buffer_edit_*` support in the parser
+
+### Fixed
+
+- Namespace calls in POCO code
+- Semantic highlighting of variables in arrays
+
+## [0.4.12] - 2025-08-03
+
+### Added
+
+- More semantic tokens and completion items
+
+## [0.4.10] - 2025-07-28
+
+### Added
+
+- Linter based on tclint
+
+### Changed
+
+- Use tclint as parser and formatter
+
+## [0.4.9] - 2025-07-22
+
+### Added
+
+- More completion items
+
+## [0.4.8] - 2025-07-21
+
+### Added
+
+- More NX functions and hover documentation
+
+## [0.4.7] - 2025-07-21
+
+### Added
+
+- Formatter settings
+
+### Fixed
+
+- Formatter fixes
+
+## [0.4.6] - 2025-07-21
+
+### Fixed
+
+- `@` in buffers when formatting
+
+## [0.4.5] - 2025-07-21
+
+### Fixed
+
+- Formatting of buffers
+
+## [0.4.4] - 2025-07-21
+
+### Fixed
+
+- Formatter fixes
+
+## [0.4.3] - 2025-07-21
+
+### Fixed
+
+- Formatting fixes
+
+## [0.4.2] - 2025-07-20
+
+### Added
+
+- Initial release with syntax highlighting, formatting, auto-completion (including `TYPE`), hover, and DEF file support

README.md

@@ -13,6 +13,8 @@ A comprehensive VS Code extension providing language support and remote debuggin
 - **Call Hierarchy** - Traces incoming and outgoing calls between custom TCL procedures and MOM event handlers
 - **Document Highlights** - Highlights all reads, writes, and calls of the symbol under the cursor
 - **Context-aware Completion** - Prioritizes local symbols and suggests variables, procedures, namespaces, paths, Tcl subcommands, valid argument values, and options based on cursor context
+- **PSC and TclOO Classes** - Indexes Tcl scripts referenced by PSC layers, including external folders. Classes from indexed files provide method completion, signature help, parameter hints, and class highlighting in other files. PSC script names may omit `.tcl`; relative folders resolve from the PSC directory, and environment-variable folders are supported. Missing scripts are reported in the output channel; encrypted libraries cannot supply static class metadata.
+- **DEF Block Templates and Addresses** - Reads the `.def` files listed under `<DefinedEvents>` in PSC layers and suggests their `BLOCK_TEMPLATE` and `ADDRESS` names, see [DEF block templates and addresses](#def-block-templates-and-addresses)
 - **Tcl Snippets** - Inserts placeholder-based structures for `if`, `foreach`, `proc`, `switch`, `try`, and `dict for`
 - **NX Tcl Remote Debugger** - Breakpoints, stepping, call stack, scopes, variables, watches, evaluation, logpoints, hit conditions, and Tcl error stops directly in a running NX Post process
 
@@ -47,6 +49,52 @@ TCL files default to unlimited inlay hint length so that VS Code does not
 truncate later parameter names on a line. An explicit user setting for
 `editor.inlayHints.maximumLength` still takes precedence.
 
+## DEF Block Templates and Addresses
+
+The language server resolves the `.def` files of every PSC layer's `<DefinedEvents>` section the
+same way as layer scripts (relative to the PSC, `SubFolder`, environment variables, missing `.def`
+extension) and collects all `BLOCK_TEMPLATE` and `ADDRESS` declarations. Changes to PSC or DEF files
+are picked up automatically.
+
+| Command | Suggestions |
+|---|---|
+| `MOM_do_template` | Block templates, then variables |
+| `MOM_ask_address_value` | Addresses, then variables |
+| `MOM_force`, `MOM_suppress` | 1st argument: `Always`, `Once`, `Off`, then variables; further arguments: addresses, then variables |
+
+Block templates, addresses, and `Always|Once|Off` are inserted in quotes (`"steady_rest"`); a quote
+that is already typed or auto-closed is replaced instead of doubled. Variables are inserted with a
+leading `$`. Typing `$` yourself still shows variables only.
+
+Two keywords list all loaded names anywhere in a Tcl file:
+
+- `BLOCK_LIST` - shows all block templates
+- `ADDR_LIST` - shows all addresses
+
+Select the keyword from the completion list (or type it completely) to open the list; text typed
+directly after the keyword, such as `ADDR_LISTSP`, narrows it. The keyword is replaced by the
+selected quoted name.
+
+### Navigation between Tcl and DEF files
+
+Block template and address names are linked to their declarations in the PSC `.def` files:
+
+- **Go to Definition** (F12) on `MOM_do_template "steady_rest"` or `MOM_force Once X` jumps to
+  `BLOCK_TEMPLATE steady_rest` or `ADDRESS X`. Inside a `.def` file, an address used in a block
+  template (`X[$mom_pos(0)]`) jumps to its `ADDRESS` declaration.
+- **Hover** shows the body of a block template, or the format (resolved to its `FORMAT`
+  definition), leader, trailer, min/max, and modality (`FORCE`) of an address.
+- **Find All References** (Shift+F12) lists the declaration, all Tcl calls, and all block templates
+  that use an address.
+- **Rename** (F2) changes the declaration and all usages in Tcl and `.def` files together. Only
+  names declared in a loaded `.def` file can be renamed.
+
+Recognized Tcl commands: `MOM_do_template`, `MOM_add_to_block_buffer`, `MOM_polar_motion`,
+`MOM_force_block`, `MOM_ask_address_value`, `MOM_add_to_address_buffer`, `MOM_enable_address`,
+`MOM_disable_address`, `MOM_force`, `MOM_suppress`, `MOM_incremental`, and
+`MOM_ask_definition_element`/`MOM_has_definition_element` with `ADDRESS` or `BLOCK`. Names built
+from variables (`MOM_do_template $name`) cannot be resolved statically.
+
 ## NX Tcl Remote Debugger
 
 ### Add a VS Code attach configuration
@@ -97,13 +145,15 @@ Simply open any supported file type and enjoy:
 - Syntax highlighting
 - Error detection and linting
 - Code completion
-- Code formatting (Format Document command)
+- Code formatting (Format Document command), including `uplevel` bodies and a space after `#` in comments
 - Hover information
 - Signature help while entering procedure arguments
 - Incoming and outgoing call hierarchy for custom procedures and MOM event handlers
 - Document-wide highlights for procedure and variable occurrences
 - Context-aware completion with local symbols ranked before workspace and built-in symbols, plus semantic arguments, local paths, Tcl subcommands, and options such as `string compare -nocase`
 - Placeholder-based snippets for common Tcl control structures and procedures
+- Block template and address suggestions from PSC DEF files, including `BLOCK_LIST` and `ADDR_LIST`
+- Go to Definition, hover, references, and rename for block templates and addresses across Tcl and DEF files
 - Remote NX Tcl debugging with breakpoints and full stepping
 
 ## Contributing

client/src/common/cdlEventHandler.ts

@@ -1,6 +1,7 @@
 export interface CdlEventHandler {
     eventName: string
     parameterNames: string[]
+    toggleOffParameterNames?: string[]
 }
 
 function structuralCode(line: string): string {
@@ -33,18 +34,6 @@ function structuralCode(line: string): string {
     return result
 }
 
-function braceDelta(line: string): number {
-    let delta = 0
-    for (const character of structuralCode(line)) {
-        if (character === "{") {
-            delta += 1
-        } else if (character === "}") {
-            delta -= 1
-        }
-    }
-    return delta
-}
-
 export function cdlEventHandlerAtLine(
     source: string,
     declarationLine: number
@@ -61,35 +50,44 @@ export function cdlEventHandlerAtLine(
     }
 
     const parameterNames: string[] = []
+    const toggleOffParameterNames: string[] = []
+    let currentParameter: string | undefined
     let eventOpened = false
     let depth = 0
 
-    for (let lineNumber = declarationLine; lineNumber < lines.length; lineNumber++) {
+    eventLines: for (let lineNumber = declarationLine; lineNumber < lines.length; lineNumber++) {
         const line = lines[lineNumber]
         const code = structuralCode(line)
 
-        if (eventOpened && depth === 1) {
-            const parameterMatch = /^\s*PARAM\s+([^\s{]+)/.exec(code)
-            if (parameterMatch) {
-                parameterNames.push(parameterMatch[1])
-            }
-        }
-
-        const delta = braceDelta(line)
-        if (!eventOpened && delta > 0) {
-            eventOpened = true
-        }
-        if (eventOpened) {
-            depth += delta
-            if (depth <= 0) {
-                break
+        const tokens = code.match(/[{}]|[^\s{}]+/g) ?? []
+        for (let index = 0; index < tokens.length; index++) {
+            const token = tokens[index]
+            if (token === "{") {
+                eventOpened = true
+                depth++
+            } else if (token === "}" && eventOpened) {
+                depth--
+                if (depth === 1) currentParameter = undefined
+                if (depth <= 0) break eventLines
+            } else if (depth === 1 && token === "PARAM") {
+                const name = tokens[index + 1]
+                if (name && name !== "{" && name !== "}") {
+                    currentParameter = name
+                    parameterNames.push(name)
+                    index++
+                }
+            } else if (depth === 2 && currentParameter && token === "TOGGLE") {
+                if (tokens[index + 1]?.toLowerCase() === "off") {
+                    toggleOffParameterNames.push(currentParameter)
+                }
             }
         }
     }
 
     return {
         eventName: eventMatch[1],
-        parameterNames
+        parameterNames,
+        toggleOffParameterNames
     }
 }
 
@@ -102,10 +100,14 @@ function momVariableName(parameterName: string): string {
 }
 
 export function createCdlEventHandlerSnippet(handler: CdlEventHandler): string {
+    const toggleOffParameters = new Set(handler.toggleOffParameterNames ?? [])
     const globals = [
-        ...new Set(handler.parameterNames.map((parameter) => momVariableName(parameter)))
+        ...new Set(handler.parameterNames.flatMap((parameter) => {
+            const variable = momVariableName(parameter)
+            return toggleOffParameters.has(parameter) ? [variable, `${variable}_defined`] : [variable]
+        }))
     ]
-    const lines = [`proc ${momEventName(handler.eventName)} { } {`]
+    const lines = [`proc ${momEventName(handler.eventName)} {args} {`]
 
     if (globals.length > 0) {
         lines.push(...globals.map((variable) => `    global ${variable}`), "")

client/src/common/defProviders.ts

@@ -0,0 +1,81 @@
+import * as vscode from "vscode"
+import { LanguageClient, Range, State } from "vscode-languageclient/node"
+
+// .def files are not synchronized with the language server, so each request
+// carries the current text of the document.
+const DEF_SELECTOR: vscode.DocumentSelector = { scheme: "file", language: "def" }
+
+function params(document: vscode.TextDocument, position: vscode.Position, extra: object = {}) {
+    return {
+        textDocument: { uri: document.uri.toString() },
+        position: { line: position.line, character: position.character },
+        text: document.getText(),
+        ...extra
+    }
+}
+
+export function registerDefProviders(getClient: () => LanguageClient | undefined): vscode.Disposable[] {
+    const request = async <T>(
+        method: string,
+        document: vscode.TextDocument,
+        position: vscode.Position,
+        token: vscode.CancellationToken,
+        extra: object = {}
+    ): Promise<{ client: LanguageClient; result: T } | undefined> => {
+        const client = getClient()
+        if (!client || client.state !== State.Running) {
+            return undefined
+        }
+        const result = await client.sendRequest<T>(method, params(document, position, extra), token)
+        return result ? { client, result } : undefined
+    }
+
+    return [
+        vscode.languages.registerDefinitionProvider(DEF_SELECTOR, {
+            async provideDefinition(document, position, token) {
+                const response = await request<any>("nxPostSupport/def/definition", document, position, token)
+                return response && response.client.protocol2CodeConverter.asDefinitionResult(response.result, token)
+            }
+        }),
+        vscode.languages.registerHoverProvider(DEF_SELECTOR, {
+            async provideHover(document, position, token) {
+                const response = await request<any>("nxPostSupport/def/hover", document, position, token)
+                return response && response.client.protocol2CodeConverter.asHover(response.result)
+            }
+        }),
+        vscode.languages.registerReferenceProvider(DEF_SELECTOR, {
+            async provideReferences(document, position, context, token) {
+                const response = await request<any>("nxPostSupport/def/references", document, position, token, {
+                    includeDeclaration: context.includeDeclaration
+                })
+                return response && response.client.protocol2CodeConverter.asReferences(response.result, token)
+            }
+        }),
+        vscode.languages.registerRenameProvider(DEF_SELECTOR, {
+            async prepareRename(document, position, token) {
+                const response = await request<{ range: Range; placeholder: string }>(
+                    "nxPostSupport/def/prepareRename",
+                    document,
+                    position,
+                    token
+                )
+                if (!response) {
+                    throw new Error("Only declared block templates and addresses can be renamed.")
+                }
+                return {
+                    range: response.client.protocol2CodeConverter.asRange(response.result.range),
+                    placeholder: response.result.placeholder
+                }
+            },
+            async provideRenameEdits(document, position, newName, token) {
+                const response = await request<any>("nxPostSupport/def/rename", document, position, token, {
+                    newName
+                })
+                if (!response) {
+                    throw new Error(`"${newName}" is not a valid block template or address name.`)
+                }
+                return response.client.protocol2CodeConverter.asWorkspaceEdit(response.result, token)
+            }
+        })
+    ]
+}

client/src/common/handlers.ts

@@ -1,8 +1,5 @@
 import * as vscode from "vscode"
-import {
-    cdlEventHandlerAtLine,
-    createCdlEventHandlerSnippet
-} from "./cdlEventHandler"
+import { cdlEventHandlerAtLine, createCdlEventHandlerSnippet } from "./cdlEventHandler"
 
 const MACHINE_HEADER_REGEX = /^MACHINE\s+\S+/
 
@@ -65,10 +62,7 @@ export function diagnosticHandler(document: vscode.TextDocument) {
     if (document.languageId === "cdl" || document.languageId === "def") {
         const text = document.getText()
         if (!isFirstLineMachine(text)) {
-            const range = new vscode.Range(
-                document.positionAt(0),
-                document.positionAt(text.length)
-            )
+            const range = new vscode.Range(document.positionAt(0), document.positionAt(text.length))
             const diagnostic = new vscode.Diagnostic(
                 range,
                 "The first line should contain 'MACHINE'.",
@@ -82,7 +76,7 @@ export function diagnosticHandler(document: vscode.TextDocument) {
 
 export function completionHandlerCdl(document: vscode.TextDocument, position: vscode.Position) {
     const linePrefix = document.lineAt(position).text.substring(0, position.character)
-    const categories = ["MILL", "LATHE", "DRILL"]
+    const categories = ["MILL", "LATHE", "DRILL", "INVALID"]
 
     if (linePrefix.endsWith("TYPE ")) {
         return [
@@ -193,8 +187,7 @@ export async function definitionCdlEventHandler(
             .filter(
                 (symbol) =>
                     symbol.kind === vscode.SymbolKind.Function &&
-                    (symbol.name === handlerName ||
-                        symbol.name.endsWith(`::${handlerName}`))
+                    (symbol.name === handlerName || symbol.name.endsWith(`::${handlerName}`))
             )
             .map((symbol) => symbol.location)
         if (indexedLocations.length > 0) {
@@ -204,9 +197,7 @@ export async function definitionCdlEventHandler(
         // The Tcl language server may still be starting; use the file fallback below.
     }
 
-    const declaration = new RegExp(
-        `^\\s*proc\\s+(?:::)?${escapeRegExp(handlerName)}(?=\\s|\\{)`
-    )
+    const declaration = new RegExp(`^\\s*proc\\s+(?:::)?${escapeRegExp(handlerName)}(?=\\s|\\{)`)
     const tclFiles = await vscode.workspace.findFiles(
         "**/*.tcl",
         "**/{.git,.nox,.venv,dist,node_modules,out}/**"
@@ -233,12 +224,7 @@ export async function definitionCdlEventHandler(
             locations.push(
                 new vscode.Location(
                     uri,
-                    new vscode.Range(
-                        lineNumber,
-                        start,
-                        lineNumber,
-                        start + handlerName.length
-                    )
+                    new vscode.Range(lineNumber, start, lineNumber, start + handlerName.length)
                 )
             )
         }

client/src/common/server.ts

@@ -22,7 +22,12 @@ import {
 import { getLSClientTraceLevel, getProjectRoot } from "./utilities"
 import { isVirtualWorkspace } from "./vscodeapi"
 
-export type IInitOptions = { settings: ISettings[]; globalSettings: ISettings }
+export type IInitOptions = {
+    settings: ISettings[]
+    globalSettings: ISettings
+    // Folder for the server's persistent index cache; omitted without a workspace.
+    indexCachePath?: string
+}
 
 let _disposables: Disposable[] = []
 
@@ -86,7 +91,7 @@ async function createServer(
     }
 
     // Options to control the language client
-    const tclFileWatcher = workspace.createFileSystemWatcher("**/*.tcl")
+    const tclFileWatcher = workspace.createFileSystemWatcher("**/*.{tcl,psc,def}")
     const clientOptions: LanguageClientOptions = {
         // Register the server for python documents
         documentSelector: isVirtualWorkspace()
@@ -114,7 +119,8 @@ export async function restartServer(
     serverId: string,
     serverName: string,
     outputChannel: LogOutputChannel,
-    lsClient?: LanguageClient
+    lsClient?: LanguageClient,
+    indexCachePath?: string
 ): Promise<LanguageClient | undefined> {
     if (lsClient) {
         traceInfo(`Server: Stop requested`)
@@ -132,7 +138,8 @@ export async function restartServer(
             outputChannel,
             {
                 settings: await getExtensionSettings(serverId, true),
-                globalSettings: await getGlobalSettings(serverId, false)
+                globalSettings: await getGlobalSettings(serverId, false),
+                indexCachePath
             }
         )
         traceInfo(`Server: Start requested.`)

client/src/extension.ts

@@ -16,6 +16,7 @@ import {
     defDocumentSymbolProvider,
     definitionCdlEventHandler
 } from "./common/handlers"
+import { registerDefProviders } from "./common/defProviders"
 import { registerLogger, traceError, traceLog, traceVerbose } from "./common/log/logging"
 import {
     checkVersion,
@@ -73,7 +74,13 @@ export async function activate(context: vscode.ExtensionContext) {
                 traceVerbose(
                     `Using interpreter from ${serverInfo.module}.interpreter: ${interpreter.join(" ")}`
                 )
-                client = await restartServer(serverId, serverName, outputChannel, client)
+                client = await restartServer(
+                    serverId,
+                    serverName,
+                    outputChannel,
+                    client,
+                    context.storageUri?.fsPath
+                )
             }
             return
         }
@@ -83,7 +90,13 @@ export async function activate(context: vscode.ExtensionContext) {
             traceVerbose(
                 `Using interpreter from Python extension: ${interpreterDetails.path.join(" ")}`
             )
-            client = await restartServer(serverId, serverName, outputChannel, client)
+            client = await restartServer(
+                serverId,
+                serverName,
+                outputChannel,
+                client,
+                context.storageUri?.fsPath
+            )
             return
         }
 
@@ -222,6 +235,7 @@ export async function activate(context: vscode.ExtensionContext) {
     )
 
     context.subscriptions.push(formatDefProvider)
+    context.subscriptions.push(...registerDefProviders(() => client))
 
     const cdlSymbolProvider = vscode.languages.registerDocumentSymbolProvider(
         { scheme: "file", language: "cdl" },

package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "nx-post-support",
-  "version": "2026.8.201",
+  "version": "2026.9.501",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "nx-post-support",
-      "version": "2026.8.201",
+      "version": "2026.9.501",
       "devDependencies": {
         "@types/vscode": "^1.96.0",
         "@vscode/vsce": "^3.2.1",

package.json

@@ -2,7 +2,7 @@
   "name": "nx-post-support",
   "displayName": "NX Postprocessor Support",
   "description": "VS Code extension for NX CAM postprocessor development with language support and remote Tcl debugging for CDL, TCL, and DEF files",
-  "version": "2026.9.210",
+  "version": "2026.9.701",
   "publisher": "Christoph",
   "icon": "images/nx-1.png",
   "activationEvents": [

server/src/_debug_server.py

@@ -6,7 +6,7 @@ import os
 import pathlib
 import runpy
 import sys
-import time
+import threading
 
 
 def update_sys_path(path_to_add: str) -> None:
@@ -27,21 +27,35 @@ def _debug_endpoint() -> tuple[str, int]:
     return host, port
 
 
-def _connect_debugger(debugpy, host: str, port: int, timeout: float = 15.0) -> None:
-    deadline = time.monotonic() + timeout
-    last_error: OSError | None = None
-    while time.monotonic() < deadline:
+def _connect_debugger(debugpy, host: str, port: int, timeout: float = 30.0) -> None:
+    errors: list[BaseException] = []
+
+    def attach() -> None:
+        # debugpy.connect() cannot be retried: after a refused connection a second
+        # call terminates the process silently. Connect exactly once.
         try:
             debugpy.connect((host, port))
             debugpy.wait_for_client()
-            return
-        except (ConnectionRefusedError, OSError) as error:
-            last_error = error
-            time.sleep(0.25)
+        except BaseException as error:  # pylint: disable=broad-exception-caught
+            errors.append(error)
 
-    raise RuntimeError(
-        f"Could not connect debugpy to {host}:{port} within {timeout:.0f} seconds"
-    ) from last_error
+    # A stale debugpy adapter from an earlier debug session can still own the port.
+    # It accepts the connection but never attaches, so bound the wait.
+    waiter = threading.Thread(target=attach, daemon=True)
+    waiter.start()
+    waiter.join(timeout)
+    if waiter.is_alive():
+        raise RuntimeError(
+            f"Connected to {host}:{port}, but no VS Code debug session attached within "
+            f"{timeout:.0f} seconds. A stale debugpy adapter probably still owns the "
+            f"port; stop it (e.g. 'fuser -k {port}/tcp') and restart debugging."
+        )
+    if errors:
+        raise RuntimeError(
+            f"No debugpy listener on {host}:{port}. Start the launch configuration "
+            "'Python debug server (hidden)' (e.g. via a 'Debug Extension and Python' "
+            "compound) before the language server."
+        ) from errors[0]
 
 
 def main() -> None:
@@ -61,7 +75,12 @@ def main() -> None:
 
     host, port = _debug_endpoint()
     print(f"debugpy: waiting for VS Code at {host}:{port}", file=sys.stderr)
-    _connect_debugger(debugpy, host, port)
+    try:
+        _connect_debugger(debugpy, host, port)
+    except RuntimeError as error:
+        print(f"debugpy: {error}", file=sys.stderr, flush=True)
+        # debugpy's background threads can keep the interpreter alive; exit hard.
+        os._exit(1)
     print("debugpy: VS Code attached; starting language server", file=sys.stderr)
 
     server_path = os.fspath(pathlib.Path(__file__).parent / "lsp_server.py")

server/src/lsp_server.py

@@ -11,6 +11,7 @@ import pathlib
 import re
 import sys
 import threading
+import time
 from collections import ChainMap
 from functools import reduce
 from typing import Any, Optional
@@ -47,19 +48,30 @@ from common.load_data import standard_items
 from lsp_tclserver import TclLanguageServer
 from tools.completion_items import (
     CompletionContext,
+    array_element_completions,
     completion_context,
     ranked_completion_items,
 )
+from tools.def_navigation import (
+    all_def_target_locations,
+    def_declarations,
+    def_definition_locations,
+    def_hover_markdown,
+    def_rename_edits,
+    def_symbol_at,
+)
+from tools.def_symbols import parse_def_document
 from tools.folding_ranges import build_folding_ranges
+from tools.index_cache import IndexCache
 from tools.inlay_hint import (
     InlayHintGenerator,
     build_builtin_inlay_signatures,
 )
 from tools.navigation import (
+    DEF_SYMBOL_KINDS,
     SymbolIdentity,
     call_hierarchy_identity,
     call_hierarchy_items,
-    definition_identities,
     document_highlights,
     incoming_call_hierarchy,
     matching_occurrences,
@@ -74,53 +86,39 @@ from tools.semantic_tokens import (
     _Highlighter,
 )
 from tools.signature_help import build_signature_help
+from tools.tcloo_arguments import method_signature_help
+from tclint.lexer import TclSyntaxError
+from tools.tcloo_completion import may_contain_classes, parse_completion_source, tcloo_completions
+from tools.tcloo_symbols import class_completion_items
+from tools.tcloo_navigation import tcloo_definition
 from tools.tcl_command_completion import (
     TCL_COMMAND_ITEMS,
     TCL_COMMAND_NAMES,
     DynamicCompletionKind,
+    line_prefix_at_position,
     path_completion_items,
     tcl_argument_completion,
 )
 
 WORKSPACE_SETTINGS = {}
 GLOBAL_SETTINGS = {}
+# Extension storage folder of the workspace; without it nothing is persisted.
+INDEX_CACHE_PATH: dict[str, str | None] = {}
 
 
 MAX_WORKERS = 5
-LSP_SERVER = TclLanguageServer(
-    name="NX Postprocessor Support", version="0.0.1", max_workers=MAX_WORKERS
-)
+LSP_SERVER = TclLanguageServer(name="NX Postprocessor Support", version="0.0.1", max_workers=MAX_WORKERS)
 
-BUILTIN_PROC_NAMES = {
-    item.label
-    for item in standard_items.tcl_keyword_list + standard_items.nx_procs
-} | set(TCL_COMMAND_NAMES)
+BUILTIN_PROC_NAMES = {item.label for item in standard_items.tcl_keyword_list + standard_items.nx_procs} | set(TCL_COMMAND_NAMES)
 BUILTIN_VARIABLE_NAMES = {item.label for item in standard_items.nx_variables}
-_TCL_COMMAND_ITEMS_BY_LABEL = {
-    item.label: item for item in TCL_COMMAND_ITEMS
-}
-_TCL_KEYWORD_ITEMS = [
-    _TCL_COMMAND_ITEMS_BY_LABEL.get(item.label, item)
-    for item in standard_items.tcl_keyword_list
-]
+_TCL_COMMAND_ITEMS_BY_LABEL = {item.label: item for item in TCL_COMMAND_ITEMS}
+_TCL_KEYWORD_ITEMS = [_TCL_COMMAND_ITEMS_BY_LABEL.get(item.label, item) for item in standard_items.tcl_keyword_list]
 _STATIC_TCL_LABELS = {item.label for item in standard_items.tcl_keyword_list}
-STATIC_COMPLETION_ITEMS = tuple(
-    _TCL_KEYWORD_ITEMS
-    + [item for item in TCL_COMMAND_ITEMS if item.label not in _STATIC_TCL_LABELS]
-    + standard_items.nx_procs
-    + standard_items.nx_variables
-)
-STATIC_VARIABLE_ITEMS = {
-    item.label: item for item in standard_items.nx_variables
-}
-BUILTIN_INLAY_SIGNATURES = build_builtin_inlay_signatures(
-    standard_items.json_data.get("MOM_procs", [])
-)
+STATIC_COMPLETION_ITEMS = tuple(_TCL_KEYWORD_ITEMS + [item for item in TCL_COMMAND_ITEMS if item.label not in _STATIC_TCL_LABELS] + standard_items.nx_procs + standard_items.nx_variables)
+STATIC_VARIABLE_ITEMS = {item.label: item for item in standard_items.nx_variables}
+BUILTIN_INLAY_SIGNATURES = build_builtin_inlay_signatures(standard_items.json_data.get("MOM_procs", []))
 BUILTIN_HOVER_ITEMS = {}
-for _hover_item in (
-    standard_items.json_data.get("MOM_procs", [])
-    + standard_items.json_data.get("mom_variables", [])
-):
+for _hover_item in standard_items.json_data.get("MOM_procs", []) + standard_items.json_data.get("mom_variables", []):
     BUILTIN_HOVER_ITEMS.setdefault(_hover_item.get("label"), _hover_item)
 
 # **********************************************************
@@ -192,6 +190,7 @@ def _index_tcl_file_from_disk(uri: str) -> None:
             document,
             cache_tree=False,
             require_file_exists=True,
+            from_disk=True,
         )
     except (OSError, UnicodeError) as error:
         log_warning(f"Could not re-index {path}: {error}")
@@ -231,12 +230,31 @@ def did_rename_files(params: lsp.RenameFilesParams) -> None:
 def did_change_watched_files(params: lsp.DidChangeWatchedFilesParams) -> None:
     """Keep indexes for closed Tcl files synchronized with disk changes."""
     for change in params.changes:
+        suffix = pathlib.Path(uris.to_fs_path(change.uri)).suffix.lower()
+        if suffix == ".psc":
+            _refresh_psc_index()
+            continue
+        if suffix == ".def":
+            LSP_SERVER.refresh_def_symbols(_workspace_roots(), report=log_warning)
+            continue
         if change.type == lsp.FileChangeType.Deleted:
             LSP_SERVER.remove_file_state(change.uri)
         else:
             _index_tcl_file_from_disk(change.uri)
 
 
+def _workspace_roots() -> list[pathlib.Path]:
+    folders = LSP_SERVER.workspace.folders
+    roots = [pathlib.Path(uris.to_fs_path(uri)) for uri in folders]
+    if not roots and LSP_SERVER.workspace.root_path:
+        roots = [pathlib.Path(LSP_SERVER.workspace.root_path)]
+    return roots
+
+
+def _refresh_psc_index():
+    LSP_SERVER.refresh_psc_scripts(_workspace_roots(), report=log_warning)
+
+
 @LSP_SERVER.feature(
     lsp.TEXT_DOCUMENT_DIAGNOSTIC,
     lsp.DiagnosticOptions(
@@ -250,9 +268,7 @@ def document_diagnostic(params: lsp.DocumentDiagnosticParams):
     uri = params.text_document.uri
     doc = LSP_SERVER.workspace.get_text_document(uri)
     diagnostic_state = LSP_SERVER.diagnostic_snapshot(uri)
-    was_cached = (
-        diagnostic_state is not None and diagnostic_state[0] == doc.version
-    )
+    was_cached = diagnostic_state is not None and diagnostic_state[0] == doc.version
     if not was_cached:
         LSP_SERVER.compute_diagnostics(doc)
         diagnostic_state = LSP_SERVER.diagnostic_snapshot(uri)
@@ -271,33 +287,110 @@ def document_diagnostic(params: lsp.DocumentDiagnosticParams):
 
 @LSP_SERVER.feature(
     lsp.TEXT_DOCUMENT_COMPLETION,
-    lsp.CompletionOptions(trigger_characters=["$", " ", "-"]),
+    lsp.CompletionOptions(trigger_characters=["$", " ", "-", "(", ","]),
 )
 def on_completion(params: lsp.CompletionParams) -> lsp.CompletionList:
+    result = _on_completion(params)
+    doc = LSP_SERVER.workspace.get_text_document(params.text_document.uri)
+    symbol_list = _symbol_list_completion(LSP_SERVER.get_lines(doc), params.position)
+    if symbol_list is not None and symbol_list.is_incomplete:
+        # Re-request while typing so the full list appears at BLOCK_LIST/ADDR_LIST.
+        result.items = [*symbol_list.items, *result.items]
+        result.is_incomplete = True
+    return result
+
+
+# Keywords that expand to all loaded .def names: keyword -> (items, description).
+SYMBOL_LIST_KEYWORDS = {
+    "BLOCK_LIST": (lambda: LSP_SERVER.block_template_items(), "block templates"),
+    "ADDR_LIST": (lambda: LSP_SERVER.address_items(), "addresses"),
+}
+DEF_NAME_RE = re.compile(r"[A-Za-z_][A-Za-z0-9_]*")
+_WORD_BEFORE_CURSOR_RE = re.compile(r"(?<![$\w])[A-Za-z_]+$")
+
+
+def _symbol_list_completion(source_lines, position: lsp.Position) -> lsp.CompletionList | None:
+    """Complete BLOCK_LIST/ADDR_LIST to all loaded block templates/addresses.
+
+    While the typed word is a prefix of a keyword, an incomplete list with the
+    keyword itself is returned. Once the keyword is typed, the complete list of
+    quoted names replaces it.
+    """
+    line_prefix = line_prefix_at_position(source_lines, position)
+    match = _WORD_BEFORE_CURSOR_RE.search(line_prefix or "")
+    if match is None:
+        return None
+    word = match.group()
+    for keyword, (symbol_items, _) in SYMBOL_LIST_KEYWORDS.items():
+        if not word.startswith(keyword):
+            continue
+        items = []
+        ranked = ranked_completion_items(((0, item) for item in symbol_items()), CompletionContext.GENERAL)
+        for item in ranked:
+            item = _quoted_item(item, source_lines, position, word)
+            # Keep every name visible for the typed keyword; text after it narrows.
+            item.filter_text = f"{keyword}{item.label}"
+            items.append(item)
+        return lsp.CompletionList(is_incomplete=False, items=items)
+
+    keywords = [
+        lsp.CompletionItem(
+            label=keyword,
+            kind=lsp.CompletionItemKind.Snippet,
+            detail=f"Show all loaded {description}",
+            insert_text=keyword,
+            sort_text=f"000:{keyword.casefold()}",
+            command=lsp.Command(title=f"Show {description}", command="editor.action.triggerSuggest"),
+        )
+        for keyword, (_, description) in SYMBOL_LIST_KEYWORDS.items()
+        if keyword.startswith(word)
+    ]
+    if keywords:
+        return lsp.CompletionList(is_incomplete=True, items=keywords)
+    return None
+
+
+def _on_completion(params: lsp.CompletionParams) -> lsp.CompletionList:
     doc = LSP_SERVER.workspace.get_text_document(params.text_document.uri)
     position = params.position
     source_lines = LSP_SERVER.get_lines(doc)
+
+    def current_tree():
+        try:
+            return LSP_SERVER.get_tree(doc)
+        except TclSyntaxError:
+            return None
+
+    oo_items = tcloo_completions(source_lines, position, LSP_SERVER.class_snapshot(doc.path), current_tree)
+    if oo_items is not None:
+        return lsp.CompletionList(is_incomplete=False, items=oo_items)
+    array_items = array_element_completions(
+        source_lines,
+        position,
+        LSP_SERVER.navigation_snapshot().values(),
+        str(pathlib.Path(uris.to_fs_path(doc.uri))),
+    )
+    if array_items is not None:
+        return lsp.CompletionList(is_incomplete=False, items=array_items)
     context = completion_context(source_lines, position)
 
+    symbol_list = _symbol_list_completion(source_lines, position)
+    if symbol_list is not None and symbol_list.is_incomplete is False:
+        return symbol_list
+
     # Variable completion wins inside command arguments. Otherwise prefer the
     # narrow command grammar when the cursor is at a known subcommand/option.
     argument_completion = None
     if context != CompletionContext.VARIABLE:
         argument_completion = tcl_argument_completion(source_lines, position)
-        if (
-            argument_completion is not None
-            and argument_completion.dynamic_kind is None
-        ):
+        if argument_completion is not None and argument_completion.dynamic_kind is None:
             items = ranked_completion_items(
                 ((0, item) for item in argument_completion.items),
                 CompletionContext.GENERAL,
             )
             return lsp.CompletionList(is_incomplete=False, items=items)
 
-        if (
-            argument_completion is not None
-            and argument_completion.dynamic_kind == DynamicCompletionKind.PATH
-        ):
+        if argument_completion is not None and argument_completion.dynamic_kind == DynamicCompletionKind.PATH:
             dynamic_items: tuple[lsp.CompletionItem, ...] = ()
             if doc.uri.startswith("file:"):
                 document_path = pathlib.Path(uris.to_fs_path(doc.uri))
@@ -306,9 +399,7 @@ def on_completion(params: lsp.CompletionParams) -> lsp.CompletionList:
                     argument_completion,
                     position,
                 )
-            path_candidates = [
-                (0, item) for item in argument_completion.items
-            ]
+            path_candidates = [(0, item) for item in argument_completion.items]
             path_candidates.extend((10, item) for item in dynamic_items)
             items = ranked_completion_items(
                 path_candidates,
@@ -321,16 +412,18 @@ def on_completion(params: lsp.CompletionParams) -> lsp.CompletionList:
     if (
         argument_completion is None
         and params.context is not None
-        and params.context.trigger_kind
-        == lsp.CompletionTriggerKind.TriggerCharacter
-        and params.context.trigger_character in {" ", "-"}
+        and params.context.trigger_kind == lsp.CompletionTriggerKind.TriggerCharacter
+        and params.context.trigger_character in {" ", "-", "(", ","}
     ):
         return lsp.CompletionList(is_incomplete=False, items=[])
 
-    tree = LSP_SERVER.get_tree(doc)
-    globals_set, procs_locals, proc_ranges = LSP_SERVER.variable_index_for_document(
-        doc, tree
-    )
+    try:
+        tree = LSP_SERVER.get_tree(doc)
+    except TclSyntaxError:
+        tree = parse_completion_source(doc.source)
+        if tree is None:
+            return lsp.CompletionList(is_incomplete=False, items=[])
+    globals_set, procs_locals, proc_ranges = LSP_SERVER.variable_index_for_document(doc, tree)
 
     local_names: set[str] = set()
     for proc_range in proc_ranges:
@@ -340,17 +433,16 @@ def on_completion(params: lsp.CompletionParams) -> lsp.CompletionList:
             break
 
     candidates: list[tuple[int, lsp.CompletionItem]] = []
+    candidates.extend((0, item) for item in class_completion_items(tree))
     for name in sorted(local_names - globals_set):
-        candidates.append(
-            (
-                0,
-                lsp.CompletionItem(
-                    label=name,
-                    kind=lsp.CompletionItemKind.Variable,
-                    detail="Local variable",
-                ),
-            )
-        )
+        candidates.append((
+            0,
+            lsp.CompletionItem(
+                label=name,
+                kind=lsp.CompletionItemKind.Variable,
+                detail="Local variable",
+            ),
+        ))
 
     for name in sorted(globals_set):
         item = STATIC_VARIABLE_ITEMS.get(name)
@@ -360,12 +452,10 @@ def on_completion(params: lsp.CompletionParams) -> lsp.CompletionList:
                 kind=lsp.CompletionItemKind.Variable,
                 detail="Workspace variable",
             )
-        candidates.append(
-            (
-                100,
-                item,
-            )
-        )
+        candidates.append((
+            100,
+            item,
+        ))
 
     filepath = str(pathlib.Path(uris.to_fs_path(doc.uri)))
     items_by_file = LSP_SERVER.completion_items_by_file_snapshot()
@@ -376,30 +466,49 @@ def on_completion(params: lsp.CompletionParams) -> lsp.CompletionList:
     if argument_completion is not None:
         static_candidates = [(0, item) for item in argument_completion.items]
         if argument_completion.dynamic_kind == DynamicCompletionKind.VARIABLE:
-            variable_candidates = [*static_candidates, *candidates]
-            variable_candidates.extend(
-                (300, item) for item in standard_items.nx_variables
-            )
+            variable_candidates = list(candidates)
+            variable_candidates.extend((300, item) for item in standard_items.nx_variables)
             items = ranked_completion_items(
                 variable_candidates,
                 CompletionContext.VARIABLE,
             )
+            # Command options are valid alongside variables, even though they
+            # are keywords and must not pass through the variable-only filter.
+            items = [*ranked_completion_items(static_candidates, CompletionContext.GENERAL), *items]
             return lsp.CompletionList(is_incomplete=False, items=items)
 
+        def_symbol_items = {
+            DynamicCompletionKind.BLOCK_TEMPLATE: LSP_SERVER.block_template_items,
+            DynamicCompletionKind.ADDRESS: LSP_SERVER.address_items,
+            DynamicCompletionKind.VALUE: list,
+        }.get(argument_completion.dynamic_kind)
+        if def_symbol_items is not None:
+            # MOM_do_template, MOM_force, ... take a .def name, a fixed value (e.g.
+            # Always|Once|Off) or a variable holding one.
+            def_symbols = [*static_candidates, *((0, item) for item in def_symbol_items())]
+            variable_candidates = list(candidates)
+            variable_candidates.extend((300, item) for item in standard_items.nx_variables)
+            variables = []
+            for item in ranked_completion_items(variable_candidates, CompletionContext.VARIABLE):
+                # Without a typed "$" the variable must be substituted.
+                item.insert_text = f"${item.label}"
+                item.filter_text = item.label
+                item.text_edit = None
+                variables.append(item)
+            quoted = [
+                _quoted_item(item, source_lines, position, argument_completion.active_prefix)
+                for item in ranked_completion_items(def_symbols, CompletionContext.GENERAL)
+            ]
+            return lsp.CompletionList(is_incomplete=False, items=[*quoted, *variables])
+
         if argument_completion.dynamic_kind == DynamicCompletionKind.PROCEDURE:
             procedure_kinds = {
                 lsp.CompletionItemKind.Constructor,
                 lsp.CompletionItemKind.Function,
                 lsp.CompletionItemKind.Method,
             }
-            procedure_candidates = [
-                (priority, item)
-                for priority, item in candidates
-                if item.kind in procedure_kinds
-            ]
-            procedure_candidates.extend(
-                (300, item) for item in standard_items.nx_procs
-            )
+            procedure_candidates = [(priority, item) for priority, item in candidates if item.kind in procedure_kinds]
+            procedure_candidates.extend((300, item) for item in standard_items.nx_procs)
             items = ranked_completion_items(
                 [*static_candidates, *procedure_candidates],
                 CompletionContext.GENERAL,
@@ -410,26 +519,20 @@ def on_completion(params: lsp.CompletionParams) -> lsp.CompletionList:
             namespace_candidates = list(static_candidates)
             prefix_is_absolute = argument_completion.active_prefix.startswith("::")
             for index in LSP_SERVER.navigation_snapshot().values():
-                priority = (
-                    100
-                    if LSP_SERVER.paths_equal(index.path, filepath)
-                    else 200
-                )
+                priority = 100 if LSP_SERVER.paths_equal(index.path, filepath) else 200
                 for occurrence in index.occurrences:
                     if occurrence.identity.kind != "namespace":
                         continue
                     name = occurrence.identity.name
                     label = name if prefix_is_absolute else name.removeprefix("::")
-                    namespace_candidates.append(
-                        (
-                            priority,
-                            lsp.CompletionItem(
-                                label=label,
-                                kind=lsp.CompletionItemKind.Module,
-                                detail="Tcl namespace",
-                            ),
-                        )
-                    )
+                    namespace_candidates.append((
+                        priority,
+                        lsp.CompletionItem(
+                            label=label,
+                            kind=lsp.CompletionItemKind.Module,
+                            detail="Tcl namespace",
+                        ),
+                    ))
             items = ranked_completion_items(
                 namespace_candidates,
                 CompletionContext.GENERAL,
@@ -441,6 +544,35 @@ def on_completion(params: lsp.CompletionParams) -> lsp.CompletionList:
     return lsp.CompletionList(is_incomplete=False, items=items)
 
 
+def _quoted_item(
+    item: lsp.CompletionItem,
+    source_lines,
+    position: lsp.Position,
+    active_prefix: str,
+) -> lsp.CompletionItem:
+    """Insert ``item`` as a quoted word, replacing quotes the user already typed."""
+    line = source_lines[position.line] if position.line < len(source_lines) else ""
+    utf16 = line.encode("utf-16-le")
+    start = position.character - len(active_prefix.encode("utf-16-le")) // 2
+    end = position.character
+    opened = start > 0 and utf16[(start - 1) * 2 : start * 2].decode("utf-16-le") == '"'
+    if opened:
+        start -= 1
+        # Also replace a closing quote the editor inserted automatically.
+        if utf16[end * 2 : (end + 1) * 2].decode("utf-16-le") == '"':
+            end += 1
+    item.text_edit = lsp.TextEdit(
+        range=lsp.Range(
+            start=lsp.Position(line=position.line, character=start),
+            end=lsp.Position(line=position.line, character=end),
+        ),
+        new_text=f'"{item.label}"',
+    )
+    item.insert_text = None
+    item.filter_text = f'"{item.label}' if opened else item.label
+    return item
+
+
 @LSP_SERVER.feature(
     lsp.TEXT_DOCUMENT_SIGNATURE_HELP,
     lsp.SignatureHelpOptions(
@@ -450,11 +582,17 @@ def on_completion(params: lsp.CompletionParams) -> lsp.CompletionList:
 )
 def signature_help(params: lsp.SignatureHelpParams) -> lsp.SignatureHelp | None:
     document = LSP_SERVER.workspace.get_text_document(params.text_document.uri)
-    tree = LSP_SERVER.get_tree(document)
+    try:
+        tree = LSP_SERVER.get_tree(document)
+    except TclSyntaxError:
+        tree = parse_completion_source(document.source)
+        if tree is None:
+            return None
+    method_help = method_signature_help(document.source, params.position, LSP_SERVER.class_snapshot(document.path), tree)
+    if method_help is not None:
+        return method_help
 
-    custom_signatures, custom_docs = LSP_SERVER.proc_metadata_snapshot(
-        document.path
-    )
+    custom_signatures, custom_docs = LSP_SERVER.proc_metadata_snapshot(document.path)
 
     return build_signature_help(
         document.source,
@@ -500,20 +638,17 @@ def inlay_hints(params: lsp.InlayHintParams):
 
     # Built-in NX procedures are the fallback. Workspace procedures replace them,
     # and a declaration in the current file wins over duplicate workspace names.
-    custom_signatures = LSP_SERVER.custom_inlay_signatures_snapshot(
-        document.path
-    )
+    custom_signatures = LSP_SERVER.custom_inlay_signatures_snapshot(document.path)
     signatures = ChainMap(custom_signatures, BUILTIN_INLAY_SIGNATURES)
 
     generator = InlayHintGenerator(
         document.source,
         signatures,
+        external_classes=LSP_SERVER.class_snapshot(document.path),
         source_lines=LSP_SERVER.get_lines(document),
         requested_range=params.range,
         parameter_names=parameter_names,
-        suppress_when_argument_matches_name=inlay_settings.get(
-            "suppressWhenArgumentMatchesName", True
-        ),
+        suppress_when_argument_matches_name=inlay_settings.get("suppressWhenArgumentMatchesName", True),
     )
     return generator.generate(tree)
 
@@ -534,19 +669,21 @@ def semantic_tokens(params: lsp.SemanticTokensParams):
 
     # Reuse cached AST
     tree = LSP_SERVER.get_tree(document)
+    classes = LSP_SERVER.class_snapshot(document.path)
+    if may_contain_classes(document.source, classes):
+        hl.highlight_classes(tree, classes)
+        hl.highlight_methods(tree, document.source, document.uri, classes)
     tree.accept(hl, recurse=True)
 
     tokens = hl.tokens()
     for token in tokens:
-        data.extend(
-            [
-                token.line,
-                token.offset,
-                token.length,
-                TOKEN_TYPE_INDEX[token.tok_type],
-                reduce(operator.or_, token.tok_modifiers, 0),
-            ]
-        )
+        data.extend([
+            token.line,
+            token.offset,
+            token.length,
+            TOKEN_TYPE_INDEX[token.tok_type],
+            reduce(operator.or_, token.tok_modifiers, 0),
+        ])
     return lsp.SemanticTokens(data=data)
 
 
@@ -583,14 +720,16 @@ def hover(params: lsp.HoverParams) -> lsp.Hover:
     else:
         return None
 
+    def_hover = _tcl_def_hover(document_uri, pos, token)
+    if def_hover is not None:
+        return def_hover
+
     # 1) If token is a known MOM proc/variable, return built-in hover
     match = BUILTIN_HOVER_ITEMS.get(token)
     if match and match.get("kind") == "function":
         label = match.get("label", "")
         parameters = match.get("parameters", [])
-        param_lines = (
-            "\n".join(f"- `{p['name']}`: {p['desc']}" for p in parameters) or "_None_"
-        )
+        param_lines = "\n".join(f"- `{p['name']}`: {p['desc']}" for p in parameters) or "_None_"
         example_data = match.get("example", [])
         example_md = "\n".join(f"{line}" for line in example_data)
         returns_data = match.get("returns", ["None"])
@@ -619,44 +758,68 @@ def hover(params: lsp.HoverParams) -> lsp.Hover:
     # Build a merged map of proc -> docs gathered during initialization and updates
     proc_doc = LSP_SERVER.proc_documentation(token, document.path)
     if proc_doc is not None:
-        return lsp.Hover(
-            lsp.MarkupContent(kind=lsp.MarkupKind.Markdown, value=proc_doc)
-        )
+        return lsp.Hover(lsp.MarkupContent(kind=lsp.MarkupKind.Markdown, value=proc_doc))
 
     return None
 
 
+def _def_target(identity: SymbolIdentity) -> tuple[str, str] | None:
+    return (identity.kind, identity.name) if identity.kind in DEF_SYMBOL_KINDS else None
+
+
+def _tcl_def_hover(uri: str, position: lsp.Position, token: str) -> lsp.Hover | None:
+    documents = LSP_SERVER.def_documents_snapshot()
+    if not any(token in document.names(kind) for document in documents.values() for kind in DEF_SYMBOL_KINDS):
+        return None
+    context = _navigation_context(uri, position)
+    target = context and _def_target(context[3])
+    markdown = target and def_hover_markdown(documents, target)
+    if not markdown:
+        return None
+    return lsp.Hover(lsp.MarkupContent(kind=lsp.MarkupKind.Markdown, value=markdown), range=context[2].range)
+
+
 @LSP_SERVER.feature(lsp.TEXT_DOCUMENT_DEFINITION)
 def goto_definition(params: lsp.DefinitionParams):
-    """Resolve Tcl proc and variable definitions through the symbol index."""
+    """Resolve TclOO declarations, then indexed proc and variable definitions."""
+    try:
+        workspace = LSP_SERVER.workspace
+    except RuntimeError:
+        workspace = None
+    if workspace is not None:
+        document = workspace.get_text_document(params.text_document.uri)
+        try:
+            tree = LSP_SERVER.get_tree(document)
+        except TclSyntaxError:
+            tree = None  # tcloo_definition repairs open delimiters itself.
+        target = tcloo_definition(document.source, document.uri, params.position,
+                                  LSP_SERVER.class_snapshot(document.path), tree)
+        if target is not None:
+            return [target]
     context = _navigation_context(params.text_document.uri, params.position)
     if context is None:
         return None
 
     indexes, definitions, _, identity = context
-    locations = [
-        lsp.Location(uri=index.uri, range=occurrence.range)
-        for index, occurrence in matching_occurrences(
-            identity, indexes, definitions
-        )
-        if occurrence.is_definition
-    ]
+    target = _def_target(identity)
+    if target is not None:
+        return _sorted_locations(def_definition_locations(LSP_SERVER.def_documents_snapshot(), target)) or None
+    locations = [lsp.Location(uri=index.uri, range=occurrence.range) for index, occurrence in matching_occurrences(identity, indexes, definitions) if occurrence.is_definition]
     return _sorted_locations(locations) or None
 
 
 def _navigation_context(uri: str, position: lsp.Position):
-    indexes = LSP_SERVER.navigation_snapshot()
+    indexes, definitions = LSP_SERVER.navigation_state()
     filepath = str(pathlib.Path(uris.to_fs_path(uri)))
     index = indexes.get(filepath)
     if index is None or LSP_SERVER.index_update_pending(filepath):
         document = LSP_SERVER.workspace.get_text_document(uri)
         LSP_SERVER.update_poco_completion_for_file(document)
-        indexes = LSP_SERVER.navigation_snapshot()
+        indexes, definitions = LSP_SERVER.navigation_state()
         index = indexes.get(filepath)
     if index is None:
         return None
 
-    definitions = definition_identities(indexes)
     result = symbol_at_position(index, position, definitions)
     if result is None:
         return None
@@ -682,11 +845,14 @@ def references(params: lsp.ReferenceParams) -> list[lsp.Location]:
         return []
 
     indexes, definitions, _, identity = context
+    target = _def_target(identity)
+    if target is not None:
+        return all_def_target_locations(
+            LSP_SERVER.def_documents_snapshot(), indexes, target, params.context.include_declaration
+        )
     locations = [
         lsp.Location(uri=index.uri, range=occurrence.range)
-        for index, occurrence in matching_occurrences(
-            identity, indexes, definitions
-        )
+        for index, occurrence in matching_occurrences(identity, indexes, definitions)
         if params.context.include_declaration or not occurrence.is_definition
     ]
     return _sorted_locations(locations)
@@ -718,11 +884,7 @@ def _is_renamable(
     if identity.kind == "proc":
         if basename in BUILTIN_PROC_NAMES:
             return False
-        definition_count = sum(
-            occurrence.is_definition and occurrence.identity == identity
-            for index in indexes.values()
-            for occurrence in index.occurrences
-        )
+        definition_count = sum(occurrence.is_definition and occurrence.identity == identity for index in indexes.values() for occurrence in index.occurrences)
         return definition_count == 1
 
     return basename not in BUILTIN_VARIABLE_NAMES
@@ -735,11 +897,13 @@ def prepare_rename(params: lsp.PrepareRenameParams):
         return None
 
     indexes, definitions, occurrence, identity = context
-    if not _is_renamable(identity, indexes, definitions):
+    target = _def_target(identity)
+    if target is not None:
+        if not def_declarations(LSP_SERVER.def_documents_snapshot(), target):
+            return None
+    elif not _is_renamable(identity, indexes, definitions):
         return None
-    return lsp.PrepareRenamePlaceholder(
-        range=occurrence.range, placeholder=occurrence.placeholder
-    )
+    return lsp.PrepareRenamePlaceholder(range=occurrence.range, placeholder=occurrence.placeholder)
 
 
 @LSP_SERVER.feature(
@@ -747,7 +911,7 @@ def prepare_rename(params: lsp.PrepareRenameParams):
     lsp.RenameOptions(prepare_provider=True),
 )
 def rename(params: lsp.RenameParams) -> lsp.WorkspaceEdit | None:
-    if not re.fullmatch(r"[A-Za-z_][A-Za-z0-9_]*", params.new_name):
+    if not DEF_NAME_RE.fullmatch(params.new_name):
         return None
 
     context = _navigation_context(params.text_document.uri, params.position)
@@ -755,6 +919,9 @@ def rename(params: lsp.RenameParams) -> lsp.WorkspaceEdit | None:
         return None
 
     indexes, definitions, _, identity = context
+    target = _def_target(identity)
+    if target is not None:
+        return def_rename_edits(LSP_SERVER.def_documents_snapshot(), indexes, target, params.new_name)
     if not _is_renamable(identity, indexes, definitions):
         return None
 
@@ -771,9 +938,7 @@ def rename(params: lsp.RenameParams) -> lsp.WorkspaceEdit | None:
         if key in seen:
             continue
         seen.add(key)
-        changes.setdefault(index.uri, []).append(
-            lsp.TextEdit(range=occurrence.range, new_text=params.new_name)
-        )
+        changes.setdefault(index.uri, []).append(lsp.TextEdit(range=occurrence.range, new_text=params.new_name))
 
     for edits in changes.values():
         edits.sort(
@@ -786,6 +951,83 @@ def rename(params: lsp.RenameParams) -> lsp.WorkspaceEdit | None:
     return lsp.WorkspaceEdit(changes=changes)
 
 
+# .def files are not synchronized with the server; the client sends their
+# current text with each request.
+DEF_REQUEST_DEFINITION = "nxPostSupport/def/definition"
+DEF_REQUEST_HOVER = "nxPostSupport/def/hover"
+DEF_REQUEST_REFERENCES = "nxPostSupport/def/references"
+DEF_REQUEST_PREPARE_RENAME = "nxPostSupport/def/prepareRename"
+DEF_REQUEST_RENAME = "nxPostSupport/def/rename"
+
+
+def _def_request_context(params):
+    uri = params.textDocument.uri
+    position = lsp.Position(line=params.position.line, character=params.position.character)
+    path = uris.to_fs_path(uri)
+    documents = LSP_SERVER.def_documents_snapshot(path, params.text)
+    symbol = def_symbol_at(parse_def_document(params.text), position)
+    if symbol is None:
+        return None
+    target, range_, _ = symbol
+    current = next(key for key in documents if LSP_SERVER.paths_equal(key, path))
+    return documents, {current: uri}, target, range_
+
+
+@LSP_SERVER.feature(DEF_REQUEST_DEFINITION)
+def def_definition(params) -> list[lsp.Location] | None:
+    context = _def_request_context(params)
+    if context is None:
+        return None
+    documents, def_uris, target, _ = context
+    return _sorted_locations(def_definition_locations(documents, target, def_uris)) or None
+
+
+@LSP_SERVER.feature(DEF_REQUEST_HOVER)
+def def_hover(params) -> lsp.Hover | None:
+    context = _def_request_context(params)
+    if context is None:
+        return None
+    documents, _, target, range_ = context
+    markdown = def_hover_markdown(documents, target)
+    if markdown is None:
+        return None
+    return lsp.Hover(lsp.MarkupContent(kind=lsp.MarkupKind.Markdown, value=markdown), range=range_)
+
+
+@LSP_SERVER.feature(DEF_REQUEST_REFERENCES)
+def def_references(params) -> list[lsp.Location]:
+    context = _def_request_context(params)
+    if context is None:
+        return []
+    documents, def_uris, target, _ = context
+    include_declaration = bool(getattr(params, "includeDeclaration", True))
+    indexes, _ = LSP_SERVER.navigation_state()
+    return all_def_target_locations(documents, indexes, target, include_declaration, def_uris)
+
+
+@LSP_SERVER.feature(DEF_REQUEST_PREPARE_RENAME)
+def def_prepare_rename(params):
+    context = _def_request_context(params)
+    if context is None:
+        return None
+    documents, _, target, range_ = context
+    if not def_declarations(documents, target):
+        return None
+    return lsp.PrepareRenamePlaceholder(range=range_, placeholder=target[1])
+
+
+@LSP_SERVER.feature(DEF_REQUEST_RENAME)
+def def_rename(params) -> lsp.WorkspaceEdit | None:
+    if not DEF_NAME_RE.fullmatch(params.newName):
+        return None
+    context = _def_request_context(params)
+    if context is None:
+        return None
+    documents, def_uris, target, _ = context
+    indexes, _ = LSP_SERVER.navigation_state()
+    return def_rename_edits(documents, indexes, target, params.newName, def_uris)
+
+
 @LSP_SERVER.feature(lsp.WORKSPACE_SYMBOL)
 def workspace_symbol(params: lsp.WorkspaceSymbolParams):
     return workspace_symbols(LSP_SERVER.navigation_snapshot(), params.query)
@@ -808,12 +1050,8 @@ def incoming_calls(params: lsp.CallHierarchyIncomingCallsParams):
     if identity is None:
         return []
 
-    indexes = LSP_SERVER.navigation_snapshot()
-    return incoming_call_hierarchy(
-        identity,
-        indexes,
-        definition_identities(indexes),
-    )
+    indexes, definitions = LSP_SERVER.navigation_state()
+    return incoming_call_hierarchy(identity, indexes, definitions)
 
 
 @LSP_SERVER.feature(lsp.CALL_HIERARCHY_OUTGOING_CALLS)
@@ -822,12 +1060,8 @@ def outgoing_calls(params: lsp.CallHierarchyOutgoingCallsParams):
     if identity is None:
         return []
 
-    indexes = LSP_SERVER.navigation_snapshot()
-    return outgoing_call_hierarchy(
-        identity,
-        indexes,
-        definition_identities(indexes),
-    )
+    indexes, definitions = LSP_SERVER.navigation_state()
+    return outgoing_call_hierarchy(identity, indexes, definitions)
 
 
 # **********************************************************
@@ -881,15 +1115,12 @@ def initialize(params: lsp.InitializeParams) -> lsp.InitializeResult:
     log_to_output(f"sys.path used to run Server:\r\n   {paths}")
 
     GLOBAL_SETTINGS.update(**params.initialization_options.get("globalSettings", {}))
+    INDEX_CACHE_PATH["path"] = params.initialization_options.get("indexCachePath")
 
     settings = params.initialization_options["settings"]
     _update_workspace_settings(settings)
-    log_to_output(
-        f"Settings used to run Server:\r\n{json.dumps(settings, indent=4, ensure_ascii=False)}\r\n"
-    )
-    log_to_output(
-        f"Global settings:\r\n{json.dumps(GLOBAL_SETTINGS, indent=4, ensure_ascii=False)}\r\n"
-    )
+    log_to_output(f"Settings used to run Server:\r\n{json.dumps(settings, indent=4, ensure_ascii=False)}\r\n")
+    log_to_output(f"Global settings:\r\n{json.dumps(GLOBAL_SETTINGS, indent=4, ensure_ascii=False)}\r\n")
     semantic_tokens_legend = lsp.SemanticTokensLegend(
         token_types=TOKEN_TYPES,
         token_modifiers=[m.name for m in TokenModifier],
@@ -898,9 +1129,7 @@ def initialize(params: lsp.InitializeParams) -> lsp.InitializeResult:
         capabilities=lsp.ServerCapabilities(
             document_formatting_provider=GLOBAL_SETTINGS.get("formatter", True),
             folding_range_provider=True,
-            semantic_tokens_provider=lsp.SemanticTokensOptions(
-                legend=semantic_tokens_legend, full=True, range=False
-            ),
+            semantic_tokens_provider=lsp.SemanticTokensOptions(legend=semantic_tokens_legend, full=True, range=False),
             definition_provider=True,
             document_highlight_provider=True,
             references_provider=True,
@@ -925,6 +1154,8 @@ def initialized(_params: lsp.InitializedParams):
                 log_to_output("Background indexing skipped: no workspace folder is open.")
                 return
             log_to_output("Background indexing started...")
+            started = time.perf_counter()
+            LSP_SERVER.index_cache = IndexCache.load(INDEX_CACHE_PATH.get("path"))
             root_path = pathlib.Path(root)
             skipped_directories = {
                 ".git",
@@ -934,27 +1165,21 @@ def initialized(_params: lsp.InitializedParams):
                 "node_modules",
                 "out",
             }
-            tcl_files = (
-                path
-                for path in root_path.rglob("*.tcl")
-                if not any(
-                    part.casefold() in skipped_directories
-                    for part in path.relative_to(root_path).parts[:-1]
-                )
-            )
+            tcl_files = (path for path in root_path.rglob("*.tcl") if not any(part.casefold() in skipped_directories for part in path.relative_to(root_path).parts[:-1]))
             for filepath in sorted(tcl_files, key=lambda path: str(path).casefold()):
                 try:
-                    document = TextDocument(
-                        uri=filepath.as_uri(), language_id="tcl"
-                    )
+                    document = TextDocument(uri=filepath.as_uri(), language_id="tcl")
                     LSP_SERVER.update_poco_completion_for_file(
                         document,
                         cache_tree=False,
                         require_file_exists=True,
+                        from_disk=True,
                     )
                 except Exception as error:
                     log_to_output(f"Fehler beim Parsen von {filepath}: {error}")
-            log_to_output("Background indexing completed.")
+            _refresh_psc_index()
+            LSP_SERVER.index_cache.save()
+            log_to_output(f"Background indexing completed in {time.perf_counter() - started:.1f}s.")
         except Exception as e:
             log_to_output(f"Background indexing failed: {e}")
 
@@ -1060,36 +1285,26 @@ def _get_settings_by_document(document: TextDocument | None):
 # *****************************************************
 # Logging and notification.
 # *****************************************************
-def log_to_output(
-    message: str, msg_type: lsp.MessageType = lsp.MessageType.Log
-) -> None:
-    LSP_SERVER.window_log_message(
-        lsp.LogMessageParams(message=message, type=msg_type)
-    )
+def log_to_output(message: str, msg_type: lsp.MessageType = lsp.MessageType.Log) -> None:
+    LSP_SERVER.window_log_message(lsp.LogMessageParams(message=message, type=msg_type))
 
 
 def log_error(message: str) -> None:
     log_to_output(message, lsp.MessageType.Error)
     if os.getenv("LS_SHOW_NOTIFICATION", "off") in ["onError", "onWarning", "always"]:
-        LSP_SERVER.window_show_message(
-            lsp.ShowMessageParams(message=message, type=lsp.MessageType.Error)
-        )
+        LSP_SERVER.window_show_message(lsp.ShowMessageParams(message=message, type=lsp.MessageType.Error))
 
 
 def log_warning(message: str) -> None:
     log_to_output(message, lsp.MessageType.Warning)
     if os.getenv("LS_SHOW_NOTIFICATION", "off") in ["onWarning", "always"]:
-        LSP_SERVER.window_show_message(
-            lsp.ShowMessageParams(message=message, type=lsp.MessageType.Warning)
-        )
+        LSP_SERVER.window_show_message(lsp.ShowMessageParams(message=message, type=lsp.MessageType.Warning))
 
 
 def log_always(message: str) -> None:
     log_to_output(message, lsp.MessageType.Info)
     if os.getenv("LS_SHOW_NOTIFICATION", "off") in ["always"]:
-        LSP_SERVER.window_show_message(
-            lsp.ShowMessageParams(message=message, type=lsp.MessageType.Info)
-        )
+        LSP_SERVER.window_show_message(lsp.ShowMessageParams(message=message, type=lsp.MessageType.Info))
 
 
 # *****************************************************

server/src/lsp_tclserver.py

@@ -2,6 +2,8 @@ import logging
 import os
 import pathlib
 import threading
+import xml.etree.ElementTree as ET
+from dataclasses import dataclass
 from typing import List, Optional, Tuple
 
 import lsprotocol.types as lsp
@@ -12,11 +14,21 @@ from pygls.workspace.text_document import TextDocument
 from tclint.format import FormatterOpts
 from tclint.lexer import TclSyntaxError
 from tclint.violations import Violation
-from tools import checks, parser
+from tools import checks, incremental_parse, parser
 from tools.completion_items import CompletionCollector
+from tools.tcloo_symbols import class_completion_items
+from tools.tcloo_completion import indexed_classes
+from tools.def_symbols import ADDRESS, BLOCK_TEMPLATE, DefDocument, parse_def_document, read_def_source
+from tools.file_sourcing import get_all_psc_files, psc_defined_event_files, psc_script_files
 from tools.formatter import NxFormatter as Formatter
+from tools.index_cache import FileStat, IndexCache, file_stat
 from tools.inlay_hint import InlayHintSignature, build_custom_inlay_signatures
-from tools.navigation import FileSymbolIndex, build_file_symbol_index
+from tools.navigation import (
+    FileSymbolIndex,
+    SymbolIdentity,
+    build_file_symbol_index,
+    definition_identities,
+)
 from tools.proc_docs import build_proc_docs
 from tools.variable_index import ProcRange, build_variable_index
 
@@ -24,6 +36,18 @@ DIAGNOSTIC_SOURCE = "nx-post-support"
 LOGGER = logging.getLogger(__name__)
 
 
+@dataclass(frozen=True)
+class _FileIndex:
+    """Everything indexed for one file; also the persistent cache entry."""
+
+    completion_items: list[lsp.CompletionItem]
+    proc_signatures: dict[str, list[str]]
+    proc_docs: dict[str, str]
+    classes: dict
+    navigation_index: FileSymbolIndex
+    variable_index: tuple[set[str], dict[str, set[str]], list[ProcRange]]
+
+
 class TclLanguageServer(LanguageServer):
     def __init__(self, *args, **kwargs):
         super().__init__(*args, **kwargs)
@@ -34,6 +58,12 @@ class TclLanguageServer(LanguageServer):
         self.poco_completion: dict = {}
         self.proc_signatures: dict = {}
         self.proc_docs: dict = {}
+        self.class_indexes: dict = {}
+        self.psc_script_paths: list[str] = []
+        self._psc_files: dict[str, list[pathlib.Path]] = {}
+        self._psc_lock = threading.RLock()
+        # .def path -> parsed declarations, in PSC DefinedEvents order.
+        self.def_documents: dict[str, DefDocument] = {}
         self.navigation_indexes: dict[str, FileSymbolIndex] = {}
         self.variable_indexes: dict[
             str,
@@ -46,6 +76,11 @@ class TclLanguageServer(LanguageServer):
         self._ast_cache = {}
         self._line_cache: dict[tuple[str, int | None], tuple[str, ...]] = {}
         self._parser_lock = threading.RLock()
+        self._thread_parsers = threading.local()
+        # uri -> (normalized source, tree, violations) of the last successful
+        # parse; survives version changes so edits can be reparsed partially.
+        self._last_parse: dict[str, tuple[str, object, list]] = {}
+        self.index_cache = IndexCache()
         self._index_lock = threading.RLock()
         self._index_tokens: dict[str, int] = {}
         self._index_versions: dict[str, int | None] = {}
@@ -59,6 +94,9 @@ class TclLanguageServer(LanguageServer):
             -1,
             frozenset(),
         )
+        self._definition_identities_cache: tuple[
+            int, frozenset[SymbolIdentity]
+        ] = (-1, frozenset())
         self._proc_metadata_cache: dict[
             str, tuple[int, dict[str, list[str]], dict[str, str]]
         ] = {}
@@ -70,16 +108,44 @@ class TclLanguageServer(LanguageServer):
         self._analysis_tokens: dict[str, int] = {}
         self._next_analysis_token = 0
 
-    def _parse_source(self, source: str):
+    def _parse_source(self, source: str, pos=None):
         self.parser.violations = []
-        tree = self.parser.parse(source)
+        tree = self.parser.parse(source, pos=pos)
         return tree, list(self.parser.violations)
 
+    def _parse_document(self, document: TextDocument):
+        """Parse a document version, reusing unchanged parts of the last one.
+
+        Callers hold the parser lock.
+        """
+        source = incremental_parse.normalize_newlines(document.source)
+        previous = self._last_parse.get(document.uri)
+        result = None
+        if previous is not None:
+            try:
+                result = incremental_parse.reparse(
+                    *previous, source, self._parse_source
+                )
+            except TclSyntaxError:
+                # E.g. a quote opened in the edit closes further down.
+                result = None
+        if result is None:
+            result = self._parse_source(source)
+        self._last_parse[document.uri] = (source, *result)
+        return result
+
     def parse_source(self, source: str):
-        """Parse without retaining an AST, serialized around the shared parser."""
-        with self._parser_lock:
-            tree, _ = self._parse_source(source)
-            return tree
+        """Parse without retaining an AST, on a parser owned by this thread.
+
+        Background indexing must not hold the shared parser lock for whole
+        files while request handlers wait for their document's tree.
+        """
+        local_parser = getattr(self._thread_parsers, "parser", None)
+        if local_parser is None:
+            # Plugin commands live in tclint's shared registry, see __init__.
+            local_parser = self._thread_parsers.parser = parser.CustomParser()
+        local_parser.violations = []
+        return local_parser.parse(source)
 
     def get_tree(self, document: TextDocument):
         key = (document.uri, document.version)
@@ -87,7 +153,7 @@ class TclLanguageServer(LanguageServer):
             cached = self._ast_cache.get(key)
             if cached is not None:
                 return cached[0]
-            tree, violations = self._parse_source(document.source)
+            tree, violations = self._parse_document(document)
             self._ast_cache[key] = (tree, violations)
             return tree
 
@@ -97,7 +163,7 @@ class TclLanguageServer(LanguageServer):
             cached = self._ast_cache.get(key)
             if cached is not None:
                 return cached
-            tree, violations = self._parse_source(document.source)
+            tree, violations = self._parse_document(document)
             self._ast_cache[key] = (tree, violations)
             return tree, violations
 
@@ -146,6 +212,7 @@ class TclLanguageServer(LanguageServer):
         self._index_generation += 1
         self._workspace_completion_cache = (-1, ())
         self._custom_function_names_cache = (-1, frozenset())
+        self._definition_identities_cache = (-1, frozenset())
         self._proc_metadata_cache.clear()
         self._custom_inlay_cache.clear()
 
@@ -170,6 +237,123 @@ class TclLanguageServer(LanguageServer):
             self._workspace_completion_cache = (self._index_generation, items)
             return items
 
+    def class_snapshot(self, current_path) -> dict:
+        """Share class metadata, without stale definitions from the active file.
+
+        PSC scripts override other workspace files in their listed load order.
+        The request parser adds the current document's declarations last.
+        """
+        with self._index_lock:
+            indexes = {self._normalized_path(path): classes for path, classes in self.class_indexes.items()}
+            paths = sorted(self.class_indexes, key=str.casefold)
+            psc_paths = {self._normalized_path(path) for path in self.psc_script_paths}
+            paths = [path for path in paths if self._normalized_path(path) not in psc_paths]
+            paths.extend(self.psc_script_paths)
+            classes = {}
+            for path in paths:
+                if not self.paths_equal(path, current_path):
+                    classes.update(indexes.get(self._normalized_path(path), {}))
+            return classes
+
+    def refresh_def_symbols(self, roots, report=LOGGER.warning):
+        """Read the block templates and addresses of all .def files listed as PSC DefinedEvents."""
+        documents: dict[str, DefDocument] = {}
+        for root in roots:
+            for psc in get_all_psc_files(root):
+                try:
+                    def_files = psc_defined_event_files(psc)
+                except (OSError, ET.ParseError) as error:
+                    report(f"Could not read PSC {psc}: {error}")
+                    continue
+                for def_file in def_files:
+                    if str(def_file) in documents:
+                        continue
+                    try:
+                        documents[str(def_file)] = parse_def_document(read_def_source(def_file))
+                    except OSError as error:
+                        report(f"Could not read DEF file {def_file}: {error}")
+        with self._index_lock:
+            self.def_documents = documents
+
+    def def_documents_snapshot(self, current_path=None, current_source: str | None = None) -> dict[str, DefDocument]:
+        """Return the PSC .def documents; ``current_source`` replaces the file being edited."""
+        with self._index_lock:
+            documents = dict(self.def_documents)
+        if current_path is not None and current_source is not None:
+            key = next((path for path in documents if self.paths_equal(path, current_path)), os.fspath(current_path))
+            documents[key] = parse_def_document(current_source)
+        return documents
+
+    def _def_symbol_items(self, kind: str, item_kind, description: str) -> list[lsp.CompletionItem]:
+        return [
+            lsp.CompletionItem(
+                label=name,
+                kind=item_kind,
+                detail=f"{description} ({pathlib.Path(path).name})",
+            )
+            for path, document in self.def_documents_snapshot().items()
+            for name in document.names(kind)
+        ]
+
+    def block_template_items(self) -> list[lsp.CompletionItem]:
+        return self._def_symbol_items(BLOCK_TEMPLATE, lsp.CompletionItemKind.Struct, "Block template")
+
+    def address_items(self) -> list[lsp.CompletionItem]:
+        return self._def_symbol_items(ADDRESS, lsp.CompletionItemKind.Field, "Address")
+
+    def refresh_psc_scripts(self, roots, report=LOGGER.warning):
+        """Index PSC dependencies through the same pipeline as workspace procs."""
+        self.refresh_def_symbols(roots, report=report)
+        with self._psc_lock:
+            discovered = {}
+            for root in roots:
+                for psc in get_all_psc_files(root):
+                    try:
+                        discovered[str(psc)] = psc_script_files(psc)
+                    except (OSError, ET.ParseError) as error:
+                        report(f"Could not read PSC {psc}: {error}")
+                        discovered[str(psc)] = self._psc_files.get(str(psc), [])
+            paths = [str(path) for scripts in discovered.values() for path in scripts]
+            with self._index_lock:
+                previous = set(self.psc_script_paths)
+                self.psc_script_paths = paths
+                self._psc_files = discovered
+            try:
+                open_documents = {
+                    self._normalized_path(document.path): document
+                    for document in self.workspace.text_documents.values()
+                }
+            except RuntimeError:
+                open_documents = {}
+            for removed in previous - set(paths):
+                path = pathlib.Path(removed)
+                if (not any(self._is_same_or_child(path, root) for root in roots)
+                        and self._normalized_path(path) not in open_documents):
+                    self.remove_file_state(path.as_uri())
+            for path_string in dict.fromkeys(paths):
+                path = pathlib.Path(path_string)
+                uri = path.as_uri()
+                document = open_documents.get(self._normalized_path(path))
+                if document is None and not path.is_file():
+                    self.remove_file_state(uri)
+                    report(f"PSC script not found: {path}")
+                    continue
+                try:
+                    source_stat = None
+                    if document is None:
+                        source_stat = file_stat(path_string)
+                        data = path.read_bytes()
+                        try:
+                            source = data.decode("utf-8-sig")
+                        except UnicodeDecodeError:
+                            # Older Windows NX layers use the ANSI code page.
+                            source = data.decode("cp1252")
+                        document = TextDocument(uri=uri, source=source, language_id="tcl")
+                    if not self.update_poco_completion_for_file(document, cache_tree=False, source_stat=source_stat):
+                        report(f"Could not index PSC script: {path}")
+                except (OSError, UnicodeError) as error:
+                    report(f"Could not read PSC script {path}: {error}")
+
     def completion_items_by_file_snapshot(
         self,
     ) -> dict[str, tuple[lsp.CompletionItem, ...]]:
@@ -190,6 +374,7 @@ class TclLanguageServer(LanguageServer):
                 item.label
                 for path_items in self.poco_completion.values()
                 for item in path_items
+                if item.kind != lsp.CompletionItemKind.Class
             )
             self._custom_function_names_cache = (self._index_generation, names)
             return names
@@ -428,6 +613,22 @@ class TclLanguageServer(LanguageServer):
         with self._index_lock:
             return dict(self.navigation_indexes)
 
+    def navigation_state(
+        self,
+    ) -> tuple[dict[str, FileSymbolIndex], frozenset[SymbolIdentity]]:
+        """Return indexes plus their definitions, cached by index generation."""
+        with self._index_lock:
+            generation, definitions = self._definition_identities_cache
+            if generation != self._index_generation:
+                definitions = frozenset(
+                    definition_identities(self.navigation_indexes)
+                )
+                self._definition_identities_cache = (
+                    self._index_generation,
+                    definitions,
+                )
+            return dict(self.navigation_indexes), definitions
+
     def _begin_index_update(self, filepath: str, version: int | None) -> int | None:
         with self._index_lock:
             indexed_version = self._index_versions.get(filepath)
@@ -453,6 +654,7 @@ class TclLanguageServer(LanguageServer):
             self.poco_completion.pop(filepath, None)
             self.proc_signatures.pop(filepath, None)
             self.proc_docs.pop(filepath, None)
+            self.class_indexes.pop(filepath, None)
             self.navigation_indexes.pop(filepath, None)
             self.variable_indexes.pop(filepath, None)
             self._committed_index_versions.pop(filepath, None)
@@ -484,6 +686,7 @@ class TclLanguageServer(LanguageServer):
                 self.poco_completion,
                 self.proc_signatures,
                 self.proc_docs,
+                self.class_indexes,
                 self.navigation_indexes,
                 self.variable_indexes,
                 self._index_tokens,
@@ -520,6 +723,33 @@ class TclLanguageServer(LanguageServer):
                 if self._is_same_or_child(cached_path, target):
                     self._ast_cache.pop(key, None)
                     self._line_cache.pop(key, None)
+            for uri in list(self._last_parse):
+                try:
+                    parsed_path = pathlib.Path(uris.to_fs_path(uri))
+                except (TypeError, ValueError):
+                    continue
+                if self._is_same_or_child(parsed_path, target):
+                    del self._last_parse[uri]
+
+    def _build_file_index(
+        self, document: TextDocument, filepath: str, cache_tree: bool
+    ) -> "_FileIndex":
+        tree = (
+            self.get_tree(document)
+            if cache_tree
+            else self.parse_source(document.source)
+        )
+        collector = CompletionCollector()
+        tree.accept(collector, recurse=True)
+        collector.custom_functions.extend(class_completion_items(tree))
+        return _FileIndex(
+            completion_items=list(collector.custom_functions),
+            proc_signatures=dict(collector.proc_signatures),
+            proc_docs=build_proc_docs(tree, document.source),
+            classes=indexed_classes(tree, document.uri, document.source),
+            navigation_index=build_file_symbol_index(filepath, document.uri, tree),
+            variable_index=build_variable_index(document.source, tree),
+        )
 
     def update_poco_completion_for_file(
         self,
@@ -527,30 +757,32 @@ class TclLanguageServer(LanguageServer):
         *,
         cache_tree: bool = True,
         require_file_exists: bool = False,
+        from_disk: bool = False,
+        source_stat: FileStat | None = None,
     ):
-        """Update poco_completion for a specific file when it changes"""
+        """Update poco_completion for a specific file when it changes.
+
+        `from_disk` marks documents that read their source from disk lazily;
+        `source_stat` is the file's stat taken before a caller read it. Such
+        results are served from and stored in the persistent index cache.
+        """
         filepath = str(pathlib.Path(uris.to_fs_path(document.uri)))
         token = self._begin_index_update(filepath, document.version)
         if token is None:
             return False
 
-        collector = CompletionCollector()
-        try:
-            tree = (
-                self.get_tree(document)
-                if cache_tree
-                else self.parse_source(document.source)
-            )
-            tree.accept(collector, recurse=True)
-            docs = build_proc_docs(tree, document.source)
-            navigation_index = build_file_symbol_index(
-                filepath, document.uri, tree
-            )
-            variable_index = build_variable_index(document.source, tree)
-        except Exception as e:
-            LOGGER.debug("Error parsing %s: %s", filepath, e)
-            self._discard_index_update(filepath, token)
-            return False
+        stat = source_stat or (file_stat(filepath) if from_disk else None)
+        index = self.index_cache.get(filepath, stat) if stat is not None else None
+        if index is None:
+            try:
+                index = self._build_file_index(document, filepath, cache_tree)
+            except Exception as e:
+                LOGGER.debug("Error parsing %s: %s", filepath, e)
+                self._discard_index_update(filepath, token)
+                return False
+            # Only cache results whose file did not change while being read.
+            if stat is not None and file_stat(filepath) == stat:
+                self.index_cache.put(filepath, stat, index)
 
         if require_file_exists and not pathlib.Path(filepath).is_file():
             self._discard_index_update(filepath, token)
@@ -559,11 +791,12 @@ class TclLanguageServer(LanguageServer):
         with self._index_lock:
             if self._index_tokens.get(filepath) != token:
                 return False
-            self.poco_completion[filepath] = list(collector.custom_functions)
-            self.proc_signatures[filepath] = dict(collector.proc_signatures)
-            self.proc_docs[filepath] = docs
-            self.navigation_indexes[filepath] = navigation_index
-            self.variable_indexes[filepath] = (document.version, variable_index)
+            self.poco_completion[filepath] = list(index.completion_items)
+            self.proc_signatures[filepath] = dict(index.proc_signatures)
+            self.proc_docs[filepath] = index.proc_docs
+            self.class_indexes[filepath] = index.classes
+            self.navigation_indexes[filepath] = index.navigation_index
+            self.variable_indexes[filepath] = (document.version, index.variable_index)
             self._committed_index_versions[filepath] = document.version
             self._invalidate_workspace_caches_locked()
         return True

server/src/tools/completion_items.py

@@ -9,7 +9,13 @@ import lsprotocol.types as lsp
 from tclint.syntax_tree import BareWord, Command, List, Visitor
 
 from common.load_data import standard_items
-from tools.tcl_command_completion import line_prefix_at_position
+from tools.navigation import FileSymbolIndex
+from tools.variable_names import variable_name
+from tools.tcl_command_completion import (
+    DynamicCompletionKind,
+    line_prefix_at_position,
+    tcl_argument_completion,
+)
 
 BUILTIN_VAR_LABELS = {ci.label for ci in standard_items.nx_variables}
 BUILTIN_PROC_LABELS = {ci.label for ci in standard_items.nx_procs}
@@ -27,6 +33,7 @@ VARIABLE_KINDS = {
     lsp.CompletionItemKind.Constant,
 }
 COMMAND_KINDS = {
+    lsp.CompletionItemKind.Class,
     lsp.CompletionItemKind.Function,
     lsp.CompletionItemKind.Method,
     lsp.CompletionItemKind.Constructor,
@@ -36,6 +43,94 @@ COMMAND_KINDS = {
 
 _VARIABLE_PREFIX_RE = re.compile(r"(?<!\\)\$(?:\{)?[A-Za-z0-9_:]*$")
 _COMMAND_PREFIX_RE = re.compile(r"(?:^|[;\[\{])\s*[^\s;\[\]\{\}]*$")
+_ARRAY_PREFIX_RE = re.compile(
+    r"(?P<name>(?:::)?[A-Za-z_][A-Za-z0-9_:]*)\((?P<key>[^()\n]*)$"
+)
+
+
+def array_element_completions(
+    source_lines: Sequence[str],
+    position: lsp.Position,
+    indexes: Iterable[FileSymbolIndex],
+    current_path: str,
+) -> list[lsp.CompletionItem] | None:
+    """Complete literal array keys, replacing only the text inside parentheses."""
+    prefix = line_prefix_at_position(source_lines, position)
+    if prefix is None:
+        return None
+    match = _ARRAY_PREFIX_RE.search(prefix)
+    if match is None:
+        return None
+    before = prefix[:match.start()]
+    if not before.endswith("$"):
+        argument = tcl_argument_completion(source_lines, position)
+        if argument is None or argument.dynamic_kind != DynamicCompletionKind.VARIABLE:
+            return None
+    name, key_prefix = match.group("name", "key")
+    part_index = key_prefix.count(",")
+    key_prefix = key_prefix.rsplit(",", 1)[-1]
+    if any(char in key_prefix for char in "$[]{}\\"):
+        return None
+    indexes = list(indexes)
+    local_scope = None
+    for index in indexes:
+        if index.path != current_path:
+            continue
+        for occurrence in index.occurrences:
+            span = occurrence.declaration_range
+            if (
+                occurrence.identity.kind == "proc"
+                and occurrence.is_definition
+                and span is not None
+                and span.start.line <= position.line <= span.end.line
+            ):
+                local_scope = f"{index.path}::proc::{occurrence.identity.name}"
+    keys: dict[str, set[tuple[str | None, ...]]] = {}
+    for index in indexes:
+        for occurrence in index.occurrences:
+            parts = occurrence.array_parts
+            key = parts[part_index] if part_index < len(parts) else None
+            if (
+                key
+                and (
+                    occurrence.identity.scope is None
+                    or occurrence.identity.scope == local_scope
+                )
+                and key.startswith(key_prefix)
+                and not any(char in key for char in "$[]\\")
+                and occurrence.identity.name.removeprefix("::") == name.removeprefix("::")
+            ):
+                keys.setdefault(key, set()).add(occurrence.array_template_parts[part_index + 1:])
+    line = source_lines[position.line]
+    suffix = line[len(prefix):]
+    remaining = re.match(r"[^(),\s$\[\]{}]*", suffix).group()
+    has_close = suffix[len(remaining):].startswith((")", ","))
+    start = position.character - len(key_prefix.encode("utf-16-le")) // 2
+    end = position.character + len(remaining.encode("utf-16-le")) // 2
+    items = []
+    for key in sorted(keys):
+        new_text = key
+        # Fill missing index components only; keep an existing comma and suffix.
+        if not suffix[len(remaining):].startswith(","):
+            tails = sorted(keys[key], key=lambda tail: (len(tail), repr(tail)))
+            tail = tails[0]
+            if all(part is not None for part in tail) and any("$" in part for part in tail):
+                new_text = ",".join([key, *tail])
+        new_text += "" if has_close else ")"
+        items.append(lsp.CompletionItem(
+            label=key,
+            kind=lsp.CompletionItemKind.Field,
+            detail=f"{name}({key})",
+            insert_text_format=lsp.InsertTextFormat.PlainText,
+            text_edit=lsp.TextEdit(
+                range=lsp.Range(
+                    start=lsp.Position(line=position.line, character=start),
+                    end=lsp.Position(line=position.line, character=end),
+                ),
+                new_text=new_text,
+            ),
+        ))
+    return items
 
 
 def completion_context(
@@ -167,8 +262,8 @@ class CompletionCollector(Visitor):
         # Collect variables set with explicit global namespace: set ::var_name ...
         elif routine.contents == "set" and command.args:
             first = command.args[0]
-            if isinstance(first, BareWord) and getattr(first, "value", None):
-                var_name = first.value
+            var_name = variable_name(first)
+            if var_name:
                 if var_name.startswith("::"):
                     base_name = var_name.split("(", 1)[0]
                     clean_name = base_name[2:]  # remove leading '::' for completion display

server/src/tools/def_symbols.py

@@ -0,0 +1,180 @@
+"""Block templates, addresses and formats declared in NX post definition (.def) files."""
+
+import re
+from dataclasses import dataclass
+from pathlib import Path
+
+BLOCK_TEMPLATE = "block_template"
+ADDRESS = "address"
+FORMAT = "format"
+
+_KINDS = {"BLOCK_TEMPLATE": BLOCK_TEMPLATE, "ADDRESS": ADDRESS, "FORMAT": FORMAT}
+_HEADER_RE = re.compile(r"^\s*(BLOCK_TEMPLATE|ADDRESS|FORMAT)\s+([^\s{]+)")
+# A block template element is an address followed by its expression: X[$mom_pos(0)].
+_ELEMENT_RE = re.compile(r"^\s*([A-Za-z_]\w*)\[")
+_PROPERTY_RE = re.compile(r"^\s*([A-Za-z_]+)\s*(.*?)\s*$")
+
+
+@dataclass(frozen=True)
+class DefDeclaration:
+    kind: str
+    name: str
+    # 0-based line and UTF-16 columns of the name.
+    line: int
+    start: int
+    end: int
+    end_line: int
+    text: str
+    # ADDRESS: body properties such as ("LEADER", '"X"'); FORMAT: (("FORMAT", '"%d"'),).
+    properties: tuple[tuple[str, str], ...] = ()
+
+
+@dataclass(frozen=True)
+class DefReference:
+    """An address used as element of a block template."""
+
+    kind: str
+    name: str
+    line: int
+    start: int
+    end: int
+    container: str
+
+
+@dataclass(frozen=True)
+class DefDocument:
+    declarations: tuple[DefDeclaration, ...] = ()
+    references: tuple[DefReference, ...] = ()
+
+    def names(self, kind: str) -> tuple[str, ...]:
+        return tuple(dict.fromkeys(item.name for item in self.declarations if item.kind == kind))
+
+
+@dataclass(frozen=True)
+class DefSymbols:
+    block_templates: tuple[str, ...] = ()
+    addresses: tuple[str, ...] = ()
+
+
+def _utf16_length(text: str) -> int:
+    return len(text.encode("utf-16-le")) // 2
+
+
+def _is_comment(line: str) -> bool:
+    return line.lstrip().startswith("#")
+
+
+def _body(lines: list[str], header: int, rest: str) -> tuple[int, int, int] | None:
+    """Return (first body line, first body column, closing line) of a braced body.
+
+    The body starts after the first "{" on the header line or on a following
+    line and ends at the next line starting with "}".
+    """
+    if "{" in rest:
+        after = rest.split("{", 1)[1]
+        if "}" in after:
+            return None
+        start = header + 1
+    else:
+        start = header + 1
+        while start < len(lines) and (not lines[start].strip() or _is_comment(lines[start])):
+            start += 1
+        if start >= len(lines) or not lines[start].lstrip().startswith("{"):
+            return None
+        start += 1
+    end = start
+    while end < len(lines) and not lines[end].lstrip().startswith("}"):
+        end += 1
+    return start, 0, min(end, len(lines) - 1)
+
+
+def parse_def_document(source: str) -> DefDocument:
+    """Parse the block templates, addresses and formats of a .def source."""
+    lines = source.splitlines()
+    declarations: list[DefDeclaration] = []
+    references: list[DefReference] = []
+    index = 0
+    while index < len(lines):
+        line = lines[index]
+        match = None if _is_comment(line) else _HEADER_RE.match(line)
+        if match is None:
+            index += 1
+            continue
+
+        kind = _KINDS[match.group(1)]
+        name = match.group(2)
+        start = _utf16_length(line[: match.start(2)])
+        end = start + _utf16_length(name)
+        rest = line[match.end(2) :]
+
+        if kind == FORMAT:
+            declarations.append(
+                DefDeclaration(kind, name, index, start, end, index, line.strip(), (("FORMAT", rest.strip()),))
+            )
+            index += 1
+            continue
+
+        body = _body(lines, index, rest)
+        end_line = index if body is None else body[2]
+        properties: list[tuple[str, str]] = []
+        if body is not None:
+            for number in range(body[0], body[2]):
+                body_line = lines[number]
+                if _is_comment(body_line) or not body_line.strip():
+                    continue
+                if kind == BLOCK_TEMPLATE:
+                    element = _ELEMENT_RE.match(body_line)
+                    if element is not None:
+                        element_start = _utf16_length(body_line[: element.start(1)])
+                        references.append(
+                            DefReference(
+                                ADDRESS,
+                                element.group(1),
+                                number,
+                                element_start,
+                                element_start + _utf16_length(element.group(1)),
+                                name,
+                            )
+                        )
+                else:
+                    prop = _PROPERTY_RE.match(body_line)
+                    if prop is not None:
+                        properties.append((prop.group(1).upper(), prop.group(2)))
+
+        declarations.append(
+            DefDeclaration(
+                kind,
+                name,
+                index,
+                start,
+                end,
+                end_line,
+                "\n".join(lines[index : end_line + 1]),
+                tuple(properties),
+            )
+        )
+        index = end_line + 1
+
+    return DefDocument(tuple(declarations), tuple(references))
+
+
+def parse_def_symbols(source: str) -> DefSymbols:
+    """Return the BLOCK_TEMPLATE and ADDRESS names of a .def source in declaration order."""
+    document = parse_def_document(source)
+    return DefSymbols(
+        block_templates=document.names(BLOCK_TEMPLATE),
+        addresses=document.names(ADDRESS),
+    )
+
+
+def read_def_source(path: Path) -> str:
+    data = path.read_bytes()
+    try:
+        return data.decode("utf-8-sig")
+    except UnicodeDecodeError:
+        # Older Windows NX layers use the ANSI code page.
+        return data.decode("cp1252")
+
+
+def read_def_symbols(path: Path) -> DefSymbols:
+    return parse_def_symbols(read_def_source(path))

server/src/tools/file_sourcing.py

@@ -1,5 +1,6 @@
 import xml.etree.ElementTree as ET
-from dataclasses import dataclass
+import os
+from dataclasses import dataclass, field
 from typing import List, Optional
 from pathlib import Path
 
@@ -9,11 +10,15 @@ class SourcedFile:
     layer_name: str
     subfolder: Optional[str]
     files: List[str]
+    defined_events: List[str] = field(default_factory=list)
 
 
 def read_psc_file(psc_file: Path) -> List[SourcedFile]:
     tree = ET.parse(psc_file)
     root = tree.getroot()
+    # PSC exports may use a default XML namespace.
+    for element in root.iter():
+        element.tag = element.tag.rsplit("}", 1)[-1]
 
     layers = root.findall(".//Layer")
 
@@ -30,22 +35,54 @@ def read_psc_file(psc_file: Path) -> List[SourcedFile]:
                 if name:
                     script_names.append(name)
 
+        # DefinedEvents-Filenames (.def files)
+        defined_events = layer.find("DefinedEvents")
+        event_names = []
+        if defined_events is not None:
+            for filename in defined_events.findall("Filename"):
+                name = filename.attrib.get("Name")
+                if name:
+                    event_names.append(name)
+
         layer_info_list.append(
-            SourcedFile(layer_name=layer_name, subfolder=subfolder, files=script_names)
+            SourcedFile(
+                layer_name=layer_name,
+                subfolder=subfolder,
+                files=script_names,
+                defined_events=event_names,
+            )
         )
     return layer_info_list
 
 
 def get_all_psc_files(root_path: Path) -> list[Path]:
-    return [path for path in root_path.rglob("*.psc")]
+    return sorted(root_path.rglob("*.psc"), key=lambda path: str(path).casefold())
 
 
-if __name__ == "__main__":
-    test = get_all_psc_files(
-        Path(
-            r"H:\janus-engineering-customers\KSB_Frankenthal\custom\library\machine\installed_machines\ksb_pe_grob_g550_sone\postprocessor"
-        )
-    )
-    print(test)
-    for pp in test:
-        read_psc_file(pp)
+def _expanded(value) -> Path:
+    return Path(os.path.expandvars(value).replace("\\", "/"))
+
+
+def _layer_files(psc_file: Path, attribute: str, suffix: str) -> list[Path]:
+    paths = []
+    for layer in read_psc_file(psc_file):
+        folder = layer.subfolder or "."
+        base = psc_file.parent / _expanded(os.environ.get(folder, folder))
+        for name in getattr(layer, attribute):
+            filename = _expanded(name)
+            if not filename.suffix:
+                filename = filename.with_suffix(suffix)
+            path = (base / filename).resolve()
+            if path.suffix.lower() == suffix:
+                paths.append(path)
+    return paths
+
+
+def psc_script_files(psc_file: Path) -> list[Path]:
+    """Resolve layer script paths relative to the PSC, preserving load order."""
+    return _layer_files(psc_file, "files", ".tcl")
+
+
+def psc_defined_event_files(psc_file: Path) -> list[Path]:
+    """Resolve the layers' DefinedEvents (.def) paths relative to the PSC."""
+    return _layer_files(psc_file, "defined_events", ".def")

server/src/tools/formatter.py

@@ -12,6 +12,14 @@ class NxFormatter(BaseFormatter):
     while leaving all other formatting behavior unchanged.
     """
 
+    def format_comment(self, comment) -> List[str]:  # type: ignore[override]
+        # "#Comment" -> "# Comment". Leave "#", "##..." separators, "#!" and
+        # comments that already start with whitespace untouched.
+        value = comment.value
+        if value and not value[0].isspace() and value[0] not in "#!":
+            value = " " + value
+        return [f"#{value}"]
+
     def format_braced_expression(self, expr) -> List[str]:  # type: ignore[override]
         # This method mirrors BaseFormatter.format_braced_expression but inserts
         # a line continuation (" \") between continuation lines similar to

server/src/tools/incremental_parse.py

@@ -0,0 +1,156 @@
+"""Reparse only the top-level commands touched by an edit.
+
+Tcl top-level commands are independent once the previous command ended on its
+own line: the parser keeps no state between them. An edit is therefore
+reparsed from the first to the last top-level command it touches, commands
+before it are reused as-is and commands after it are reused with their line
+numbers shifted. Whenever that assumption could break, the caller falls back
+to a full parse.
+"""
+
+from __future__ import annotations
+
+import copy
+from collections.abc import Callable
+
+from tclint.syntax_tree import Node, Script
+from tclint.violations import Violation
+
+ParseChunk = Callable[[str, tuple[int, int]], tuple[Script, list[Violation]]]
+
+
+def normalize_newlines(source: str) -> str:
+    """Match the universal newline handling of the tclint parser."""
+    return source.replace("\r\n", "\n").replace("\r", "\n")
+
+
+def _shifted_tree(node: Node, delta: int) -> Node:
+    """Copy a subtree with its line numbers moved by `delta`.
+
+    Cached trees may still be read by other requests, so nodes are never
+    mutated. Attributes such as `Command.routine` alias entries of `children`,
+    so every reference is remapped to the same copy.
+    """
+    copies: dict[int, Node] = {}
+
+    def shifted(original: Node) -> Node:
+        existing = copies.get(id(original))
+        if existing is not None:
+            return existing
+        clone = object.__new__(type(original))
+        copies[id(original)] = clone
+        state = dict(original.__dict__)
+        if state.get("line") is not None:
+            state["line"] += delta
+        end = state.get("end_pos")
+        if end is not None:
+            state["end_pos"] = (end[0] + delta, end[1])
+        for key, value in state.items():
+            if isinstance(value, Node):
+                state[key] = shifted(value)
+            elif isinstance(value, (list, tuple)) and value and isinstance(value[0], Node):
+                state[key] = type(value)(shifted(item) for item in value)
+        clone.__dict__.update(state)
+        return clone
+
+    return shifted(node)
+
+
+def _shifted_violation(violation: Violation, delta: int) -> Violation:
+    clone = copy.copy(violation)
+    clone.start = (violation.start[0] + delta, violation.start[1])
+    clone.end = (violation.end[0] + delta, violation.end[1])
+    return clone
+
+
+def reparse(
+    old_source: str,
+    old_tree: Script,
+    old_violations: list[Violation],
+    new_source: str,
+    parse_chunk: ParseChunk,
+) -> tuple[Script, list[Violation]] | None:
+    """Return the tree of `new_source`, or None when a full parse is needed.
+
+    Both sources must already be newline-normalized. `parse_chunk` parses a
+    top-level fragment starting at the given (line, column) and may raise
+    TclSyntaxError, which the caller handles like any failed parse.
+    """
+    if old_source == new_source:
+        return old_tree, list(old_violations)
+
+    # Changed line range (1-indexed); lines outside it are identical. A pure
+    # insertion leaves last_changed_old == first_changed_line - 1.
+    old_lines = old_source.split("\n")
+    new_lines = new_source.split("\n")
+    limit = min(len(old_lines), len(new_lines))
+    same_before = 0
+    while same_before < limit and old_lines[same_before] == new_lines[same_before]:
+        same_before += 1
+    same_after = 0
+    while (
+        same_after < limit - same_before
+        and old_lines[-1 - same_after] == new_lines[-1 - same_after]
+    ):
+        same_after += 1
+
+    first_changed_line = same_before + 1
+    last_changed_old = len(old_lines) - same_after
+    delta = len(new_lines) - len(old_lines)
+
+    commands = old_tree.children
+    if any(command.line is None or command.end_pos is None for command in commands):
+        return None
+
+    # Commands overlapping the changed lines, widened so that no reused
+    # command shares a line with the reparsed range.
+    first = next(
+        (index for index, command in enumerate(commands) if command.end_pos[0] >= first_changed_line),
+        len(commands),
+    )
+    start_line = first_changed_line
+    if first < len(commands):
+        start_line = min(start_line, commands[first].line)
+    while first > 0 and commands[first - 1].end_pos[0] >= start_line:
+        first -= 1
+        start_line = min(start_line, commands[first].line)
+
+    last = first - 1
+    end_line_old = last_changed_old
+    while last + 1 < len(commands) and commands[last + 1].line <= end_line_old:
+        last += 1
+        end_line_old = max(end_line_old, commands[last].end_pos[0])
+    end_line_new = end_line_old + delta
+
+    if end_line_new < start_line - 1 or end_line_new > len(new_lines):
+        return None
+    # A trailing backslash joins a line with the next one across the boundary.
+    if start_line > 1 and new_lines[start_line - 2].endswith("\\"):
+        return None
+    if end_line_new >= start_line and new_lines[end_line_new - 1].endswith("\\"):
+        return None
+
+    chunk_commands: list[Node] = []
+    chunk_violations: list[Violation] = []
+    if end_line_new >= start_line:
+        chunk = "\n".join(new_lines[start_line - 1 : end_line_new])
+        chunk_tree, chunk_violations = parse_chunk(chunk, (start_line, 1))
+        chunk_commands = chunk_tree.children
+
+    reused_after = [_shifted_tree(command, delta) for command in commands[last + 1 :]]
+    tree = Script(
+        *commands[:first],
+        *chunk_commands,
+        *reused_after,
+        pos=(old_tree.line, old_tree.col),
+    )
+    tree.end_pos = (len(new_lines), len(new_lines[-1]) + 1)
+
+    violations = [violation for violation in old_violations if violation.start[0] < start_line]
+    violations += chunk_violations
+    violations += [
+        _shifted_violation(violation, delta)
+        for violation in old_violations
+        if violation.start[0] > end_line_old
+    ]
+    return tree, violations

server/src/tools/index_cache.py

@@ -0,0 +1,128 @@
+"""Persist per-file index results across server restarts.
+
+Entries are keyed by path and validated by the file's size and mtime. The
+whole cache is tied to a fingerprint of the code that produced it: the
+indexing sources of this server, the bundled tclint sources and the versions
+of all bundled libraries. Any change to them, including a tclint update or a
+local patch, discards the cache instead of loading stale results.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import logging
+import os
+import pathlib
+import pickle
+import sys
+import tempfile
+import threading
+import zlib
+from typing import Any
+
+LOGGER = logging.getLogger(__name__)
+
+# Bump when the cached data layout changes without a source change above.
+CACHE_FORMAT = 1
+CACHE_FILE = "index-cache.pickle.z"
+
+_SRC_DIR = pathlib.Path(__file__).resolve().parent.parent
+_LIBS_DIR = _SRC_DIR.parent / "libs"
+
+FileStat = tuple[int, int]
+
+
+def code_fingerprint() -> str:
+    digest = hashlib.sha256()
+    digest.update(f"{CACHE_FORMAT}|{sys.version}".encode())
+    sources = [
+        _SRC_DIR / "lsp_tclserver.py",
+        *sorted((_SRC_DIR / "tools").glob("*.py")),
+        *sorted((_SRC_DIR / "plugins").glob("*.py")),
+        *sorted((_LIBS_DIR / "tclint").rglob("*.py")),
+    ]
+    for source in sources:
+        digest.update(source.relative_to(_SRC_DIR.parent).as_posix().encode())
+        digest.update(source.read_bytes())
+    for dist_info in sorted(_LIBS_DIR.glob("*.dist-info")):
+        digest.update(dist_info.name.encode())
+    return digest.hexdigest()
+
+
+def file_stat(path: str) -> FileStat | None:
+    try:
+        stat = os.stat(path)
+    except OSError:
+        return None
+    return stat.st_mtime_ns, stat.st_size
+
+
+class IndexCache:
+    def __init__(self, directory: pathlib.Path | None = None, fingerprint: str = ""):
+        self._path = directory / CACHE_FILE if directory is not None else None
+        self._fingerprint = fingerprint
+        self._entries: dict[str, tuple[FileStat, Any]] = {}
+        self._used: set[str] = set()
+        self._dirty = False
+        self._lock = threading.Lock()
+
+    @classmethod
+    def load(cls, directory: pathlib.Path | str | None) -> IndexCache:
+        """Open the cache in `directory`; without one, nothing is persisted."""
+        if not directory:
+            return cls()
+        cache = cls(pathlib.Path(directory), code_fingerprint())
+        try:
+            with open(cache._path, "rb") as file:
+                fingerprint, entries = pickle.loads(zlib.decompress(file.read()))
+        except FileNotFoundError:
+            return cache
+        except Exception as error:  # A damaged cache must never stop indexing.
+            LOGGER.warning("Ignoring unreadable index cache %s: %s", cache._path, error)
+            cache._dirty = True
+            return cache
+        if fingerprint == cache._fingerprint:
+            cache._entries = entries
+        else:
+            cache._dirty = True
+        return cache
+
+    def get(self, path: str, stat: FileStat) -> Any | None:
+        with self._lock:
+            entry = self._entries.get(path)
+            if entry is None or entry[0] != stat:
+                return None
+            self._used.add(path)
+            return entry[1]
+
+    def put(self, path: str, stat: FileStat, data: Any) -> None:
+        if self._path is None:
+            return
+        with self._lock:
+            self._entries[path] = (stat, data)
+            self._used.add(path)
+            self._dirty = True
+
+    def save(self) -> None:
+        """Write entries used in this session atomically; others are dropped."""
+        if self._path is None:
+            return
+        with self._lock:
+            if not self._dirty and self._used == self._entries.keys():
+                return
+            entries = {path: self._entries[path] for path in self._used if path in self._entries}
+            self._entries = entries
+            self._dirty = False
+        try:
+            self._path.parent.mkdir(parents=True, exist_ok=True)
+            with tempfile.NamedTemporaryFile(dir=self._path.parent, delete=False) as file:
+                data = pickle.dumps((self._fingerprint, entries), protocol=pickle.HIGHEST_PROTOCOL)
+                # Pickled indexes are very repetitive; fast compression cuts ~90%.
+                file.write(zlib.compress(data, 1))
+            os.replace(file.name, self._path)
+        except Exception as error:
+            LOGGER.warning("Could not write index cache %s: %s", self._path, error)
+            try:
+                os.unlink(file.name)
+            except (OSError, NameError):
+                pass

server/src/tools/inlay_hint.py

@@ -9,6 +9,8 @@ from typing import Any
 import lsprotocol.types as lsp
 from tclint.syntax_tree import Command, VarSub, Visitor
 from tools.navigation import FileSymbolIndex
+from tools.tcloo_arguments import method_parameters
+from tools.tcloo_completion import resolved_method_calls
 
 
 @dataclass(frozen=True)
@@ -156,10 +158,13 @@ class InlayHintGenerator(Visitor):
         requested_range: lsp.Range | None = None,
         parameter_names: str = "all",
         suppress_when_argument_matches_name: bool = True,
+        external_classes=None,
     ):
         self.source_lines = (
             source_lines if source_lines is not None else source.splitlines()
         )
+        self.source = source
+        self.external_classes = external_classes
         self.proc_signatures = proc_signatures
         self.requested_range = requested_range
         self.parameter_names = parameter_names
@@ -194,6 +199,17 @@ class InlayHintGenerator(Visitor):
                 walk(child)
 
         walk(tree)
+        if self.parameter_names != "none":
+            for call in resolved_method_calls(self.source, self.external_classes, tree):
+                if not self._node_intersects_requested_range(call.command):
+                    continue
+                parameters = method_parameters(call.parameters)
+                signature = InlayHintSignature(
+                    parameters=tuple(InlayHintParameter(p.name, variadic=p.variadic) for p in parameters),
+                    display_label=" ".join([call.label, *(p.label for p in parameters)]),
+                )
+                self._argument_hints(signature, call.command.args[call.argument_offset:])
+        self.hints.sort(key=lambda hint: (hint.position.line, hint.position.character))
         return self.hints
 
     def _position(self, line: int, column: int) -> lsp.Position:
@@ -238,7 +254,10 @@ class InlayHintGenerator(Visitor):
         if signature is None or self.parameter_names == "none":
             return
 
-        for argument_index, argument in enumerate(command.args):
+        self._argument_hints(signature, command.args)
+
+    def _argument_hints(self, signature, arguments):
+        for argument_index, argument in enumerate(arguments):
             parameter = self._parameter_for_argument(signature, argument_index)
             if parameter is None:
                 break

server/src/tools/navigation.py

@@ -4,7 +4,8 @@ from dataclasses import dataclass
 from pathlib import Path
 
 import lsprotocol.types as lsp
-from tclint.syntax_tree import Command, List, Node, Script, VarSub
+from tclint.syntax_tree import Command, List, Node, QuotedWord, Script, VarSub
+from tools.variable_names import array_key_parts, variable_name
 
 ROOT_NAMESPACE = "::"
 
@@ -27,6 +28,9 @@ class SymbolOccurrence:
     fallback_identity: SymbolIdentity | None = None
     caller: SymbolIdentity | None = None
     declaration_range: lsp.Range | None = None
+    array_element: str | None = None
+    array_parts: tuple[str | None, ...] = ()
+    array_template_parts: tuple[str | None, ...] = ()
 
 
 @dataclass(frozen=True)
@@ -96,6 +100,8 @@ def _name_range(node: Node, raw_name: str, *, variable_sub: bool = False) -> lsp
         column += 2 if getattr(node, "braced", False) else 1
     else:
         position = getattr(node, "contents_pos", None) or node.pos
+        if isinstance(node, QuotedWord) and node.contents is None and node.children:
+            position = node.children[0].pos
         line, column = position
 
     normalized = _without_array_index(raw_name)
@@ -108,6 +114,49 @@ def _name_range(node: Node, raw_name: str, *, variable_sub: bool = False) -> lsp
     )
 
 
+DEF_BLOCK_TEMPLATE = "block_template"
+DEF_ADDRESS = "address"
+DEF_SYMBOL_KINDS = frozenset({DEF_BLOCK_TEMPLATE, DEF_ADDRESS})
+
+# NX commands taking .def names: command -> (first argument index, last index or
+# None for all following arguments, kind).
+_DEF_ARGUMENTS: dict[str, tuple[tuple[int, int | None, str], ...]] = {
+    "MOM_do_template": ((0, 0, DEF_BLOCK_TEMPLATE),),
+    "MOM_add_to_block_buffer": ((0, 0, DEF_BLOCK_TEMPLATE),),
+    "MOM_polar_motion": ((0, 0, DEF_BLOCK_TEMPLATE),),
+    "MOM_force_block": ((1, None, DEF_BLOCK_TEMPLATE),),
+    "MOM_ask_address_value": ((0, 0, DEF_ADDRESS),),
+    "MOM_add_to_address_buffer": ((0, 0, DEF_ADDRESS),),
+    "MOM_enable_address": ((0, None, DEF_ADDRESS),),
+    "MOM_disable_address": ((0, None, DEF_ADDRESS),),
+    "MOM_force": ((1, None, DEF_ADDRESS),),
+    "MOM_suppress": ((1, None, DEF_ADDRESS),),
+    "MOM_incremental": ((1, None, DEF_ADDRESS),),
+}
+_DEFINITION_ELEMENT_KINDS = {"ADDRESS": DEF_ADDRESS, "BLOCK": DEF_BLOCK_TEMPLATE}
+
+
+def def_argument_kinds(command: Command) -> list[tuple[Node, str]]:
+    """Return the arguments of ``command`` that name a .def block template or address."""
+    routine = _static_contents(command.routine)
+    if routine in {"MOM_ask_definition_element", "MOM_has_definition_element"}:
+        kind = _DEFINITION_ELEMENT_KINDS.get((_static_contents(command.args[0]) or "").upper()) if command.args else None
+        return [(command.args[1], kind)] if kind and len(command.args) >= 2 else []
+    result = []
+    for first, last, kind in _DEF_ARGUMENTS.get(routine or "", ()):
+        for position, argument in enumerate(command.args):
+            if position >= first and (last is None or position <= last):
+                result.append((argument, kind))
+    return result
+
+
+def _def_name(node: Node) -> str | None:
+    name = _static_contents(node)
+    if not name or node.contents_pos is None or any(char.isspace() or char in "$[]{}\\\"" for char in name):
+        return None
+    return name
+
+
 def _node_range(node: Node) -> lsp.Range | None:
     if node.pos is None or node.end_pos is None:
         return None
@@ -259,6 +308,12 @@ def build_file_symbol_index(
     filepath: str, uri: str, tree: Node
 ) -> FileSymbolIndex:
     occurrences: list[SymbolOccurrence] = []
+    # Most occurrences repeat a few identities; sharing one object per identity
+    # keeps the index (and its persistent cache) small.
+    identities: dict[SymbolIdentity, SymbolIdentity] = {}
+
+    def shared(identity: SymbolIdentity | None) -> SymbolIdentity | None:
+        return None if identity is None else identities.setdefault(identity, identity)
 
     def add_proc(
         node: Node,
@@ -268,7 +323,7 @@ def build_file_symbol_index(
         is_definition: bool,
         declaration_range: lsp.Range | None = None,
     ) -> None:
-        identity = _proc_identity(raw_name, scope.namespace)
+        identity = shared(_proc_identity(raw_name, scope.namespace))
         caller = None
         if not is_definition:
             caller = (
@@ -282,14 +337,14 @@ def build_file_symbol_index(
                 fallback_identity=(
                     None
                     if is_definition
-                    else _proc_fallback(raw_name, scope.namespace)
+                    else shared(_proc_fallback(raw_name, scope.namespace))
                 ),
                 range=_name_range(node, raw_name),
                 placeholder=_basename(raw_name),
                 is_definition=is_definition,
                 symbol_kind=lsp.SymbolKind.Function,
                 container_name=_container_name(identity),
-                caller=caller,
+                caller=shared(caller),
                 declaration_range=declaration_range,
             )
         )
@@ -303,7 +358,7 @@ def build_file_symbol_index(
         variable_sub: bool = False,
         identity: SymbolIdentity | None = None,
     ) -> None:
-        symbol_identity = identity or _variable_identity(raw_name, scope)
+        symbol_identity = shared(identity or _variable_identity(raw_name, scope))
         occurrences.append(
             SymbolOccurrence(
                 identity=symbol_identity,
@@ -312,6 +367,13 @@ def build_file_symbol_index(
                 is_definition=is_definition,
                 symbol_kind=lsp.SymbolKind.Variable,
                 container_name=_container_name(symbol_identity),
+                array_element=(
+                    raw_name.split("(", 1)[1][:-1]
+                    if "(" in raw_name and raw_name.endswith(")")
+                    else None
+                ),
+                array_parts=array_key_parts(node),
+                array_template_parts=array_key_parts(node, preserve_variables=True),
             )
         )
 
@@ -417,6 +479,23 @@ def build_file_symbol_index(
         if routine:
             add_proc(command.routine, routine, scope, is_definition=False)
 
+        for node, kind in def_argument_kinds(command):
+            name = _def_name(node)
+            if name is None:
+                continue
+            line, column = node.contents_pos
+            occurrences.append(
+                SymbolOccurrence(
+                    identity=shared(SymbolIdentity(kind=kind, name=name)),
+                    range=lsp.Range(
+                        start=lsp.Position(line=line - 1, character=column - 1),
+                        end=lsp.Position(line=line - 1, character=column - 1 + len(name)),
+                    ),
+                    placeholder=name,
+                    symbol_kind=lsp.SymbolKind.Struct if kind == DEF_BLOCK_TEMPLATE else lsp.SymbolKind.Field,
+                )
+            )
+
         declaration_nodes = _variable_declaration_nodes(command)
         declaration_ids = {id(node) for node in declaration_nodes}
         for node in declaration_nodes:
@@ -444,7 +523,7 @@ def build_file_symbol_index(
         for node, is_definition in _variable_command_nodes(command):
             if id(node) in declaration_ids:
                 continue
-            raw_name = _static_contents(node)
+            raw_name = variable_name(node)
             if raw_name:
                 add_variable(
                     node,
@@ -493,6 +572,15 @@ def resolve_identity(
     return occurrence.identity
 
 
+def _may_resolve_to(occurrence: SymbolOccurrence, identity: SymbolIdentity) -> bool:
+    """Cheap name pre-filter; resolve_identity only returns one of these two."""
+    name = identity.name
+    fallback = occurrence.fallback_identity
+    return occurrence.identity.name == name or (
+        fallback is not None and fallback.name == name
+    )
+
+
 def symbol_at_position(
     index: FileSymbolIndex,
     position: lsp.Position,
@@ -517,6 +605,8 @@ def matching_occurrences(
     matches = []
     for index in indexes.values():
         for occurrence in index.occurrences:
+            if not _may_resolve_to(occurrence, identity):
+                continue
             if resolve_identity(occurrence, definitions) == identity:
                 matches.append((index, occurrence))
     return matches
@@ -530,6 +620,8 @@ def document_highlights(
     """Return all occurrences of one symbol in the active document."""
     highlights = []
     for occurrence in index.occurrences:
+        if not _may_resolve_to(occurrence, identity):
+            continue
         if resolve_identity(occurrence, definitions) != identity:
             continue
 

server/src/tools/parser.py

@@ -1,7 +1,9 @@
 import io
+import re
 from typing import Optional, Tuple
 from tclint.parser import Parser
 from tclint.commands import CommandArgError
+from tclint.commands.checks import eval as eval_script_args
 from tclint.syntax_tree import (
     BracedWord,
     BareWord,
@@ -13,9 +15,32 @@ from tclint.syntax_tree import (
 from tclint.lexer import TclSyntaxError, Lexer, TOK_EOF
 
 
+_UPLEVEL_LEVEL_RE = re.compile(r"^#?\d+$")
+
+
+def _uplevel(args, parser):
+    """uplevel ?level? arg ?arg ...?"""
+    # ref: https://www.tcl.tk/man/tcl/TclCmd/uplevel.html
+    if len(args) == 0:
+        raise CommandArgError("not enough args to 'uplevel': got 0, expected at least 1")
+
+    # The level can only be omitted when the first arg doesn't look like one.
+    # A non-literal first arg (e.g. $level) is treated as a level as well.
+    level = []
+    if len(args) > 1:
+        first = args[0].contents
+        if first is None or _UPLEVEL_LEVEL_RE.match(first):
+            level = args[0:1]
+
+    return level + eval_script_args(args[len(level) :], parser, "uplevel")
+
+
 class CustomParser(Parser):
     def __init__(self, debug=False, command_plugins=None):
         super().__init__(debug, command_plugins)
+        # tclint only checks the arg count of uplevel; parse its body as a script
+        # so it gets formatted and linted like eval/namespace eval bodies.
+        self._commands = {**self._commands, "uplevel": _uplevel}
         # Used to normalize newlines consistently with open()'s universal newlines mode.
         self._decoder = io.IncrementalNewlineDecoder(None, True)
 

server/src/tools/semantic_tokens.py

@@ -4,7 +4,10 @@ from typing import List
 import attrs
 from common.load_data import standard_items
 from tclint.commands.plugins import PluginManager
-from tclint.syntax_tree import BareWord, Command, QuotedWord, Visitor
+from tclint.syntax_tree import BareWord, BracedWord, Command, QuotedWord, Visitor
+from tools.variable_names import variable_name
+from tools.tcloo_symbols import class_symbols
+from tools.tcloo_completion import _analyze
 
 # Constructing a PluginManager scans entry points, and get_commands() rebuilds
 # the builtin command set on every call. Semantic tokens are requested often, so
@@ -69,12 +72,10 @@ class _Highlighter(Visitor):
     def __init__(self, plugins, custom_functions):
         self._commands = _load_commands(plugins)
         self._tokens = []
+        self._class_tokens = {}
+        self._method_tokens = {}
         if isinstance(custom_functions, dict):
-            self._custom_function_names = frozenset(
-                item.label
-                for items in custom_functions.values()
-                for item in items
-            )
+            self._custom_function_names = frozenset(item.label for items in custom_functions.values() for item in items)
         else:
             self._custom_function_names = frozenset(custom_functions)
 
@@ -83,6 +84,20 @@ class _Highlighter(Visitor):
             return
         self._tokens.append((position, length, tok_type, modifiers or []))
 
+    def highlight_classes(self, tree, external_classes=None):
+        declarations, references = class_symbols(tree, external_classes)
+        for node, modifiers in [
+            *((node, [TokenModifier.declaration]) for node in declarations.values()),
+            *((node, []) for node in references),
+        ]:
+            line, col = node.contents_pos
+            self._class_tokens[(line - 1, col - 1)] = (
+                (line - 1, col - 1),
+                len(node.contents),
+                "class",
+                modifiers,
+            )
+
     def _get_token_info(self, node):
         """Hilfsmethode um Token-Informationen aus verschiedenen Node-Typen zu extrahieren."""
         if not hasattr(node, "pos"):
@@ -110,6 +125,28 @@ class _Highlighter(Visitor):
 
         return None
 
+    def highlight_methods(self, tree, source, uri, external_classes=None):
+        """Use the same function token as procs for resolved TclOO methods."""
+        classes, _, calls = _analyze(tree, external_classes=external_classes, uri=uri, source=source)
+        lines = source.splitlines()
+        for info in classes.values():
+            for location in info.method_definitions.values():
+                if location.uri != uri:
+                    continue
+                start, end = location.range.start, location.range.end
+                encoded = lines[start.line].encode("utf-16-le")
+                column = len(encoded[:start.character * 2].decode("utf-16-le"))
+                length = len(encoded[start.character * 2:end.character * 2].decode("utf-16-le"))
+                position = (start.line, column)
+                self._method_tokens[position] = (position, length, "function", [TokenModifier.declaration])
+        for call in calls:
+            node = call.command.args[0]
+            if node.contents is None or node.contents_pos is None:
+                continue
+            line, column = node.contents_pos
+            position = (line - 1, column - 1)
+            self._method_tokens[position] = (position, len(node.contents), "function", [])
+
     def visit_quoted_word(self, word: QuotedWord):
         if not word.contents:
             return
@@ -136,6 +173,15 @@ class _Highlighter(Visitor):
     def visit_command(self, command: Command):
         routine = command.routine
 
+        # Stored procedure names in braced lappend arguments use the same
+        # highlighting as calls, without treating the literal as executable Tcl.
+        if routine.contents in {"lappend", "::lappend"}:
+            for argument in command.args:
+                if (isinstance(argument, BracedWord)
+                        and argument.contents in self._custom_function_names | _STANDARD_PROC_NAMES):
+                    line, col = argument.contents_pos
+                    self._append_token((line - 1, col - 1), len(argument.contents), "function", [])
+
         # Highlight functions (custom or standard) when used as the routine
         name = getattr(routine, "contents", None)
         if name:
@@ -156,9 +202,14 @@ class _Highlighter(Visitor):
         if routine.contents == "puts":
             line, col = routine.contents_pos
             self._append_token((line - 1, col - 1), len(routine.contents), "function", [TokenModifier.builtin])
-        if routine.contents == "set" and command.args:
+        if routine.contents in ["set", "append", "lappend"] and command.args:
             first_arg = command.args[0]
             token_info = self._get_token_info(first_arg)
+            if first_arg.contents is None:
+                name = variable_name(first_arg)
+                if name:
+                    line, col = first_arg.children[0].pos
+                    token_info = ((line - 1, col - 1), len(name))
             if token_info:
                 (line, col), length = token_info
                 self._append_token((line, col), length, "variable", [TokenModifier.declaration])
@@ -198,7 +249,10 @@ class _Highlighter(Visitor):
         tokens = []
         last_line = 0
         last_col = 0
-        for (line, col), length, tok_type, tok_modifier in sorted(self._tokens, key=lambda x: x[0]):
+        overrides = {**self._method_tokens, **self._class_tokens}
+        raw_tokens = [token for token in self._tokens if token[0] not in overrides]
+        raw_tokens.extend(overrides.values())
+        for (line, col), length, tok_type, tok_modifier in sorted(raw_tokens, key=lambda x: x[0]):
             line_delta = line - last_line
             col_delta = col
             if line == last_line:

server/src/tools/tcl_command_completion.py

@@ -24,6 +24,10 @@ class DynamicCompletionKind(Enum):
     PROCEDURE = "procedure"
     NAMESPACE = "namespace"
     PATH = "path"
+    BLOCK_TEMPLATE = "block_template"
+    ADDRESS = "address"
+    # A variable substituted as a value, inserted with a leading "$".
+    VALUE = "value"
 
 
 @dataclass(frozen=True)
@@ -284,6 +288,7 @@ def _options(*labels: str) -> tuple[OptionSpec, ...]:
 
 
 OPTIONS_BY_PATH: dict[tuple[str, ...], tuple[OptionSpec, ...]] = {
+    ("unset",): _options("nocomplain"),
     ("binary", "decode", "base64"): (OptionSpec("-strict"),),
     ("binary", "encode", "base64"): (
         OptionSpec("-maxlen", takes_value=True),
@@ -423,6 +428,9 @@ for _string_class in STRING_CLASSES:
 
 VALUES_BY_POSITION: dict[tuple[tuple[str, ...], int], tuple[str, ...]] = {
     (("array", "names"), 3): ("-exact", "-glob", "-regexp"),
+    (("MOM_force",), 1): ("Always", "Once", "Off"),
+    (("MOM_suppress",), 1): ("Always", "Once", "Off"),
+    (("MOM_do_template",), 2): ("CREATE", "BUFFER"),
     (("close",), 2): ("read", "write"),
     (("open",), 2): ("r", "r+", "w", "w+", "a", "a+"),
     (("package", "prefer"), 2): ("latest", "stable"),
@@ -437,109 +445,60 @@ _REPEATED_SUBCOMMAND_ARGUMENTS = frozenset(range(2, 33))
 DYNAMIC_COMPLETION_RULES = (
     # Variable-taking commands.
     DynamicCompletionRule(("append",), frozenset({1}), DynamicCompletionKind.VARIABLE),
-    DynamicCompletionRule(
-        ("array", "exists"), frozenset({2}), DynamicCompletionKind.VARIABLE
-    ),
-    DynamicCompletionRule(
-        ("array", "get"), frozenset({2}), DynamicCompletionKind.VARIABLE
-    ),
-    DynamicCompletionRule(
-        ("array", "names"), frozenset({2}), DynamicCompletionKind.VARIABLE
-    ),
-    DynamicCompletionRule(
-        ("array", "set"), frozenset({2}), DynamicCompletionKind.VARIABLE
-    ),
-    DynamicCompletionRule(
-        ("array", "size"), frozenset({2}), DynamicCompletionKind.VARIABLE
-    ),
-    DynamicCompletionRule(
-        ("array", "statistics"), frozenset({2}), DynamicCompletionKind.VARIABLE
-    ),
-    DynamicCompletionRule(
-        ("array", "unset"), frozenset({2}), DynamicCompletionKind.VARIABLE
-    ),
-    DynamicCompletionRule(
-        ("catch",), frozenset({2, 3}), DynamicCompletionKind.VARIABLE
-    ),
-    DynamicCompletionRule(
-        ("dict", "append"), frozenset({2}), DynamicCompletionKind.VARIABLE
-    ),
-    DynamicCompletionRule(
-        ("dict", "incr"), frozenset({2}), DynamicCompletionKind.VARIABLE
-    ),
-    DynamicCompletionRule(
-        ("dict", "lappend"), frozenset({2}), DynamicCompletionKind.VARIABLE
-    ),
-    DynamicCompletionRule(
-        ("dict", "set"), frozenset({2}), DynamicCompletionKind.VARIABLE
-    ),
-    DynamicCompletionRule(
-        ("dict", "unset"), frozenset({2}), DynamicCompletionKind.VARIABLE
-    ),
-    DynamicCompletionRule(
-        ("dict", "update"), frozenset({2}), DynamicCompletionKind.VARIABLE
-    ),
-    DynamicCompletionRule(
-        ("dict", "with"), frozenset({2}), DynamicCompletionKind.VARIABLE
-    ),
-    DynamicCompletionRule(
-        ("global",), _REPEATED_ARGUMENTS, DynamicCompletionKind.VARIABLE
-    ),
+    DynamicCompletionRule(("array", "exists"), frozenset({2}), DynamicCompletionKind.VARIABLE),
+    DynamicCompletionRule(("array", "get"), frozenset({2}), DynamicCompletionKind.VARIABLE),
+    DynamicCompletionRule(("array", "names"), frozenset({2}), DynamicCompletionKind.VARIABLE),
+    DynamicCompletionRule(("array", "set"), frozenset({2}), DynamicCompletionKind.VARIABLE),
+    DynamicCompletionRule(("array", "size"), frozenset({2}), DynamicCompletionKind.VARIABLE),
+    DynamicCompletionRule(("array", "statistics"), frozenset({2}), DynamicCompletionKind.VARIABLE),
+    DynamicCompletionRule(("array", "unset"), frozenset({2}), DynamicCompletionKind.VARIABLE),
+    DynamicCompletionRule(("catch",), frozenset({2, 3}), DynamicCompletionKind.VARIABLE),
+    DynamicCompletionRule(("dict", "append"), frozenset({2}), DynamicCompletionKind.VARIABLE),
+    DynamicCompletionRule(("dict", "incr"), frozenset({2}), DynamicCompletionKind.VARIABLE),
+    DynamicCompletionRule(("dict", "lappend"), frozenset({2}), DynamicCompletionKind.VARIABLE),
+    DynamicCompletionRule(("dict", "set"), frozenset({2}), DynamicCompletionKind.VARIABLE),
+    DynamicCompletionRule(("dict", "unset"), frozenset({2}), DynamicCompletionKind.VARIABLE),
+    DynamicCompletionRule(("dict", "update"), frozenset({2}), DynamicCompletionKind.VARIABLE),
+    DynamicCompletionRule(("dict", "with"), frozenset({2}), DynamicCompletionKind.VARIABLE),
+    DynamicCompletionRule(("global",), _REPEATED_ARGUMENTS, DynamicCompletionKind.VARIABLE),
     DynamicCompletionRule(("incr",), frozenset({1}), DynamicCompletionKind.VARIABLE),
-    DynamicCompletionRule(
-        ("info", "exists"), frozenset({2}), DynamicCompletionKind.VARIABLE
-    ),
+    DynamicCompletionRule(("info", "exists"), frozenset({2}), DynamicCompletionKind.VARIABLE),
     DynamicCompletionRule(("lappend",), frozenset({1}), DynamicCompletionKind.VARIABLE),
     DynamicCompletionRule(("set",), frozenset({1}), DynamicCompletionKind.VARIABLE),
-    DynamicCompletionRule(
-        ("unset",), _REPEATED_ARGUMENTS, DynamicCompletionKind.VARIABLE
-    ),
-    DynamicCompletionRule(
-        ("variable",), frozenset({1}), DynamicCompletionKind.VARIABLE
-    ),
+    DynamicCompletionRule(("unset",), _REPEATED_ARGUMENTS, DynamicCompletionKind.VARIABLE),
+    DynamicCompletionRule(("variable",), frozenset({1}), DynamicCompletionKind.VARIABLE),
     DynamicCompletionRule(("vwait",), frozenset({1}), DynamicCompletionKind.VARIABLE),
     # Procedure-taking commands.
-    DynamicCompletionRule(
-        ("info", "args"), frozenset({2}), DynamicCompletionKind.PROCEDURE
-    ),
-    DynamicCompletionRule(
-        ("info", "body"), frozenset({2}), DynamicCompletionKind.PROCEDURE
-    ),
-    DynamicCompletionRule(
-        ("info", "default"), frozenset({2}), DynamicCompletionKind.PROCEDURE
-    ),
-    DynamicCompletionRule(
-        ("namespace", "origin"), frozenset({2}), DynamicCompletionKind.PROCEDURE
-    ),
+    DynamicCompletionRule(("info", "args"), frozenset({2}), DynamicCompletionKind.PROCEDURE),
+    DynamicCompletionRule(("info", "body"), frozenset({2}), DynamicCompletionKind.PROCEDURE),
+    DynamicCompletionRule(("info", "default"), frozenset({2}), DynamicCompletionKind.PROCEDURE),
+    DynamicCompletionRule(("namespace", "origin"), frozenset({2}), DynamicCompletionKind.PROCEDURE),
     DynamicCompletionRule(("rename",), frozenset({1}), DynamicCompletionKind.PROCEDURE),
     # Namespace-taking commands.
-    DynamicCompletionRule(
-        ("namespace", "children"), frozenset({2}), DynamicCompletionKind.NAMESPACE
-    ),
+    DynamicCompletionRule(("MOM_do_template",), frozenset({1}), DynamicCompletionKind.BLOCK_TEMPLATE),
+    DynamicCompletionRule(("MOM_do_template",), frozenset({2}), DynamicCompletionKind.VALUE),
+    DynamicCompletionRule(("MOM_ask_address_value",), frozenset({1}), DynamicCompletionKind.ADDRESS),
+    DynamicCompletionRule(("MOM_force",), frozenset({1}), DynamicCompletionKind.VALUE),
+    DynamicCompletionRule(("MOM_force",), _REPEATED_SUBCOMMAND_ARGUMENTS, DynamicCompletionKind.ADDRESS),
+    DynamicCompletionRule(("MOM_suppress",), frozenset({1}), DynamicCompletionKind.VALUE),
+    DynamicCompletionRule(("MOM_suppress",), _REPEATED_SUBCOMMAND_ARGUMENTS, DynamicCompletionKind.ADDRESS),
+    DynamicCompletionRule(("MOM_disable_address",), frozenset(range(1, 33)), DynamicCompletionKind.ADDRESS),
+    DynamicCompletionRule(("MOM_enable_address",), _REPEATED_SUBCOMMAND_ARGUMENTS, DynamicCompletionKind.ADDRESS),
+    DynamicCompletionRule(("namespace", "children"), frozenset({2}), DynamicCompletionKind.NAMESPACE),
     DynamicCompletionRule(
         ("namespace", "delete"),
         _REPEATED_SUBCOMMAND_ARGUMENTS,
         DynamicCompletionKind.NAMESPACE,
     ),
-    DynamicCompletionRule(
-        ("namespace", "eval"), frozenset({2}), DynamicCompletionKind.NAMESPACE
-    ),
-    DynamicCompletionRule(
-        ("namespace", "exists"), frozenset({2}), DynamicCompletionKind.NAMESPACE
-    ),
-    DynamicCompletionRule(
-        ("namespace", "parent"), frozenset({2}), DynamicCompletionKind.NAMESPACE
-    ),
+    DynamicCompletionRule(("namespace", "eval"), frozenset({2}), DynamicCompletionKind.NAMESPACE),
+    DynamicCompletionRule(("namespace", "exists"), frozenset({2}), DynamicCompletionKind.NAMESPACE),
+    DynamicCompletionRule(("namespace", "parent"), frozenset({2}), DynamicCompletionKind.NAMESPACE),
     # Path-taking commands. Source files are narrowed to Tcl while directories
     # remain visible so users can continue navigating.
     DynamicCompletionRule(("cd",), frozenset({1}), DynamicCompletionKind.PATH),
-    DynamicCompletionRule(
-        ("load",), frozenset({1}), DynamicCompletionKind.PATH, (".dll", ".so", ".dylib")
-    ),
+    DynamicCompletionRule(("load",), frozenset({1}), DynamicCompletionKind.PATH, (".dll", ".so", ".dylib")),
     DynamicCompletionRule(("open",), frozenset({1}), DynamicCompletionKind.PATH),
-    DynamicCompletionRule(
-        ("source",), frozenset({1, 3}), DynamicCompletionKind.PATH, (".tcl",)
-    ),
+    DynamicCompletionRule(("source",), frozenset({1, 3}), DynamicCompletionKind.PATH, (".tcl",)),
     *(
         DynamicCompletionRule(
             ("file", subcommand),
@@ -666,12 +625,7 @@ SUBCOMMAND_SNIPPET_ITEMS = {
 
 
 TCL_COMMAND_NAMES = tuple(
-    sorted(
-        {path[0] for path in SUBCOMMANDS_BY_PATH}
-        | {path[0] for path in OPTIONS_BY_PATH}
-        | set(TCL_COMMAND_SNIPPET_ITEMS)
-        | {rule.path[0] for rule in DYNAMIC_COMPLETION_RULES}
-    )
+    sorted({path[0] for path in SUBCOMMANDS_BY_PATH} | {path[0] for path in OPTIONS_BY_PATH} | set(TCL_COMMAND_SNIPPET_ITEMS) | {rule.path[0] for rule in DYNAMIC_COMPLETION_RULES})
 )
 
 TCL_COMMAND_ITEMS = tuple(
@@ -688,9 +642,7 @@ TCL_COMMAND_ITEMS = tuple(
 )
 
 
-def line_prefix_at_position(
-    source_lines: Sequence[str], position: Position
-) -> str | None:
+def line_prefix_at_position(source_lines: Sequence[str], position: Position) -> str | None:
     """Return the current line before an LSP UTF-16 position."""
 
     if position.line < 0 or position.line >= len(source_lines):
@@ -703,9 +655,7 @@ def line_prefix_at_position(
     return line[:codepoint_offset]
 
 
-def tcl_argument_completion(
-    source_lines: Sequence[str], position: Position
-) -> TclArgumentCompletion | None:
+def tcl_argument_completion(source_lines: Sequence[str], position: Position) -> TclArgumentCompletion | None:
     """Describe static and dynamic argument completion at ``position``.
 
     ``None`` means that the cursor is not at a command-specific completion
@@ -751,13 +701,14 @@ def tcl_argument_completion(
 
     for (path, argument_index), values in VALUES_BY_POSITION.items():
         if active_index == argument_index and tuple(words[: len(path)]) == path:
-            return TclArgumentCompletion(
-                items=_completion_items(
+            return _merge_dynamic_completion(
+                _completion_items(
                     values,
                     CompletionItemKind.Value,
                     f"{' '.join(path)} value",
                 ),
-                active_prefix=active_prefix,
+                dynamic_completion,
+                active_prefix,
             )
 
     for path in sorted(OPTIONS_BY_PATH, key=len, reverse=True):
@@ -771,7 +722,7 @@ def tcl_argument_completion(
             active_prefix,
         )
         if option_completion is not None:
-            if active_prefix.startswith("-"):
+            if active_prefix.startswith("-") or (path == ("unset",) and active_index == 1 and not active_prefix):
                 return option_completion
             return _merge_dynamic_completion(
                 (*argument_items, *option_completion.items),
@@ -780,9 +731,7 @@ def tcl_argument_completion(
             )
 
     if argument_items:
-        return _merge_dynamic_completion(
-            argument_items, dynamic_completion, active_prefix
-        )
+        return _merge_dynamic_completion(argument_items, dynamic_completion, active_prefix)
     return dynamic_completion
 
 
@@ -827,9 +776,7 @@ def _option_completion(
     if active_prefix and not active_prefix.startswith("-"):
         return None
 
-    remaining_options = tuple(
-        option.label for option in options if option.label not in used_options
-    )
+    remaining_options = tuple(option.label for option in options if option.label not in used_options)
     return TclArgumentCompletion(
         items=_completion_items(
             remaining_options,
@@ -840,16 +787,9 @@ def _option_completion(
     )
 
 
-def _dynamic_completion(
-    words: Sequence[str], active_index: int, active_prefix: str
-) -> TclArgumentCompletion | None:
-    for rule in sorted(
-        DYNAMIC_COMPLETION_RULES, key=lambda item: len(item.path), reverse=True
-    ):
-        if (
-            active_index in rule.argument_indices
-            and tuple(words[: len(rule.path)]) == rule.path
-        ):
+def _dynamic_completion(words: Sequence[str], active_index: int, active_prefix: str) -> TclArgumentCompletion | None:
+    for rule in sorted(DYNAMIC_COMPLETION_RULES, key=lambda item: len(item.path), reverse=True):
+        if active_index in rule.argument_indices and tuple(words[: len(rule.path)]) == rule.path:
             return TclArgumentCompletion(
                 dynamic_kind=rule.kind,
                 active_prefix=active_prefix,
@@ -873,9 +813,7 @@ def _merge_dynamic_completion(
     )
 
 
-def _completion_items(
-    labels: Sequence[str], kind: CompletionItemKind, detail: str
-) -> tuple[CompletionItem, ...]:
+def _completion_items(labels: Sequence[str], kind: CompletionItemKind, detail: str) -> tuple[CompletionItem, ...]:
     return tuple(
         CompletionItem(
             label=label,
@@ -913,9 +851,7 @@ def path_completion_items(
     except (OSError, ValueError):
         return ()
 
-    allowed_extensions = {
-        extension.casefold() for extension in completion.path_extensions
-    }
+    allowed_extensions = {extension.casefold() for extension in completion.path_extensions}
     replace_start = max(
         0,
         position.character - len(raw_prefix.encode("utf-16-le")) // 2,
@@ -933,28 +869,17 @@ def path_completion_items(
             is_directory = entry.is_dir()
         except OSError:
             continue
-        if (
-            not is_directory
-            and allowed_extensions
-            and entry.suffix.casefold() not in allowed_extensions
-        ):
+        if not is_directory and allowed_extensions and entry.suffix.casefold() not in allowed_extensions:
             continue
 
-        escaped_name = "".join(
-            f"\\{character}" if character.isspace() else character
-            for character in entry.name
-        )
+        escaped_name = "".join(f"\\{character}" if character.isspace() else character for character in entry.name)
         new_text = f"{normalized_directory}{escaped_name}"
         if is_directory:
             new_text += "/"
         items.append(
             CompletionItem(
                 label=new_text,
-                kind=(
-                    CompletionItemKind.Folder
-                    if is_directory
-                    else CompletionItemKind.File
-                ),
+                kind=(CompletionItemKind.Folder if is_directory else CompletionItemKind.File),
                 detail="Directory" if is_directory else "File",
                 text_edit=TextEdit(range=replace_range, new_text=new_text),
             )

server/src/tools/tcloo_arguments.py

@@ -0,0 +1,79 @@
+"""Parameter presentation for statically resolved TclOO calls."""
+
+from dataclasses import dataclass
+
+import lsprotocol.types as lsp
+from tclint.lexer import TclSyntaxError
+from tclint.syntax_tree import BracedWord, Command
+
+from tools.parser import CustomParser
+from tools.signature_help import _active_argument, _contains_cursor
+from tools.tcloo_completion import resolved_method_calls
+
+
+@dataclass(frozen=True)
+class MethodParameter:
+    name: str
+    label: str
+    variadic: bool = False
+
+
+def method_parameters(parameters: str) -> list[MethodParameter]:
+    parser = CustomParser()
+    try:
+        words = parser.parse_list(BracedWord(parameters, pos=(1, 1))).children
+        result = []
+        for index, word in enumerate(words):
+            parts = parser.parse_list(word).children
+            if not parts or len(parts) > 2:
+                return []
+            name = parts[0].contents
+            if name is None:
+                return []
+            variadic = name == "args" and len(parts) == 1 and index == len(words) - 1
+            label = "{" + word.contents + "}" if len(parts) == 2 else name
+            result.append(MethodParameter(name, label, variadic))
+        return result
+    except TclSyntaxError:
+        return []
+
+
+def method_signature_help(source: str, position: lsp.Position, external_classes=None, tree=None) -> lsp.SignatureHelp | None:
+    lines = source.split("\n")
+    if position.line >= len(lines):
+        return None
+    # AST columns are codepoints; LSP columns are UTF-16 code units.
+    prefix = lines[position.line].encode("utf-16-le")[:position.character * 2].decode("utf-16-le", errors="ignore")
+    cursor = (position.line, len(prefix))
+    candidates = [call for call in resolved_method_calls(source, external_classes, tree)
+                  if _contains_cursor(call.command, lines, cursor)]
+    if not candidates:
+        return None
+    call = max(candidates, key=lambda candidate: candidate.command.pos)
+
+    def nested_active(node):
+        return any(
+            isinstance(child, Command) and _contains_cursor(child, lines, cursor)
+            or nested_active(child)
+            for child in node.children
+        )
+
+    # Let the inner command's own signature provider handle its arguments.
+    if nested_active(call.command):
+        return None
+    argument = _active_argument(call.command, cursor) - call.argument_offset
+    if argument < 0:
+        return None
+    parameters = method_parameters(call.parameters)
+    label = call.label
+    infos = []
+    for parameter in parameters:
+        label += " "
+        start = len(label.encode("utf-16-le")) // 2
+        label += parameter.label
+        infos.append(lsp.ParameterInformation(label=(start, len(label.encode("utf-16-le")) // 2)))
+    active = min(argument, len(parameters) - 1) if parameters else None
+    return lsp.SignatureHelp(
+        signatures=[lsp.SignatureInformation(label=label, parameters=infos, active_parameter=active)],
+        active_signature=0, active_parameter=active,
+    )

server/src/tools/tcloo_completion.py

@@ -0,0 +1,333 @@
+"""Static TclOO inference using local and indexed classes, without executing Tcl."""
+
+from collections.abc import Callable, Sequence
+from dataclasses import dataclass, field
+import re
+
+import lsprotocol.types as lsp
+from tclint.lexer import TclSyntaxError
+from tclint.syntax_tree import BracedWord, Command, CommandSub, Script, VarSub
+
+from tools.parser import CustomParser
+from tools.signature_help import _active_argument, _contains_cursor
+from tools.tcl_command_completion import line_prefix_at_position
+
+_LEADING_RECEIVER = re.compile(r"\s*([A-Za-z_]\w*)\s+[\w:]*$")
+
+
+def may_contain_classes(source, external_classes=None) -> bool:
+    """Cheap pre-check: without any class, TclOO analysis yields nothing."""
+    return bool(external_classes) or "oo::class" in source
+
+
+def _may_be_receiver(name, source_lines, external_classes) -> bool:
+    """Whether a bare command word can name a class, an object or `my`.
+
+    Objects and local classes only come from `... create <name>`, so a word
+    never created anywhere cannot resolve and needs no full-document parse.
+    """
+    if name in {"my", "self", "next"}:
+        return True
+    if any(key.rsplit("::", 1)[-1] == name for key in external_classes or ()):
+        return True
+    created = re.compile(rf"\bcreate\s+[{{\"]?(?:[\w:]*::)?{re.escape(name)}\b")
+    return any("create" in line and created.search(line) for line in source_lines)
+
+
+@dataclass
+class ClassInfo:
+    methods: dict[str, tuple[str, Script | None]] = field(default_factory=dict)
+    namespace: str = ""
+    constructor: str = ""
+    definition: lsp.Location | None = None
+    method_definitions: dict[str, lsp.Location] = field(default_factory=dict)
+    constructor_definition: lsp.Location | None = None
+
+
+@dataclass
+class MethodCall:
+    command: Command
+    label: str
+    parameters: str
+    argument_offset: int = 1
+    definition: lsp.Location | None = None
+
+
+def name_location(node, uri, source):
+    """Locate the literal name, excluding braces/quotes, using UTF-16 columns."""
+    if not uri or node.contents is None or node.contents_pos is None:
+        return None
+    line, column = node.contents_pos
+    lines = source.splitlines()
+    prefix = lines[line - 1][:column - 1] if line <= len(lines) else ""
+    start = len(prefix.encode("utf-16-le")) // 2
+    end = start + len(node.contents.encode("utf-16-le")) // 2
+    return lsp.Location(uri=uri, range=lsp.Range(
+        start=lsp.Position(line=line - 1, character=start),
+        end=lsp.Position(line=line - 1, character=end)))
+
+
+def parse_completion_source(source, pos=None):
+    # Complete open delimiters while editing; never evaluate the user's code.
+    for _ in range(16):
+        try:
+            return CustomParser().parse(source, pos=pos)
+        except TclSyntaxError as error:
+            message = str(error)
+            closing = next((char for text, char in (
+                ("end of command substitution", "]"),
+                ("match for brace", "}"), ("match for quote", '"'),
+            ) if text in message), None)
+            if closing is None:
+                return None
+            source += closing
+    return None
+
+
+def _body(node):
+    if isinstance(node, Script):
+        return node
+    if isinstance(node, BracedWord):
+        return parse_completion_source(node.contents, node.contents_pos)
+    return None
+
+
+def _qualified(name, namespace):
+    return name if name.startswith("::") else f"{namespace}::{name}"
+
+
+def _cursor_may_be_method_word(tree, source_lines, position) -> bool:
+    """Whether the innermost command at the cursor is at its first argument.
+
+    The marker parse below can only succeed there, and the current document's
+    tree has the same structure apart from the marker.
+    """
+    line = source_lines[position.line]
+    # AST columns are codepoints; LSP columns are UTF-16 code units.
+    prefix = line.encode("utf-16-le")[:position.character * 2].decode("utf-16-le", errors="ignore")
+    cursor = (position.line, len(prefix))
+    lines = list(source_lines)
+    innermost = None
+
+    def walk(node):
+        nonlocal innermost
+        start, end = getattr(node, "pos", None), getattr(node, "end_pos", None)
+        if start is not None and end is not None and not start[0] - 1 <= cursor[0] <= end[0] - 1:
+            return
+        if isinstance(node, Command) and _contains_cursor(node, lines, cursor):
+            innermost = node
+        for child in node.children:
+            walk(child)
+
+    walk(tree)
+    return innermost is None or _active_argument(innermost, cursor) == 0
+
+
+def tcloo_completions(
+    source_lines: Sequence[str], position: lsp.Position, external_classes=None,
+    current_tree: Callable[[], Script | None] | None = None,
+) -> list[lsp.CompletionItem] | None:
+    """Return receiver-specific methods, or None outside a known OO context.
+
+    `current_tree` lazily returns the parsed, unmodified document (or None) so
+    cursors that cannot hold a method name skip the full marker reparse.
+    """
+    prefix = line_prefix_at_position(source_lines, position)
+    if prefix is None:
+        return None
+    match = re.search(r"[\w:]*$", prefix)
+    typed = match.group()
+    # Only a method word, never a variable substitution or method argument.
+    word_start = len(prefix) - len(typed)
+    if word_start == 0 or prefix[word_start - 1] not in " \t":
+        return None
+    if not external_classes and not any("oo::class" in line for line in source_lines):
+        return None
+    continued = position.line > 0 and source_lines[position.line - 1].endswith("\\")
+    if not continued:
+        # The first word is the command itself, never a method name.
+        if not prefix[:word_start].strip():
+            return None
+        receiver = _LEADING_RECEIVER.match(prefix)
+        if receiver is not None and not _may_be_receiver(receiver.group(1), source_lines, external_classes):
+            return None
+    tree = current_tree() if current_tree is not None else None
+    if tree is not None and not _cursor_may_be_method_word(tree, source_lines, position):
+        return None
+    marker = "__nx_tcloo_completion_cursor__"
+    lines = list(source_lines)
+    suffix = lines[position.line][len(prefix):]
+    remaining = re.match(r"[\w:]*", suffix).group()
+    lines[position.line] = prefix + marker + suffix[len(remaining):]
+    tree = parse_completion_source("\n".join(lines))
+    if tree is None:
+        return None
+    classes, result, _ = _analyze(tree, typed, marker, external_classes)
+    if result is None:
+        return None
+    cls, internal = result
+    methods = classes[cls].methods if cls else {"new": ("args", None), "create": ("name args", None)}
+    methods = dict(methods)
+    if cls:
+        methods.setdefault("destroy", ("", None))
+    suffix = source_lines[position.line][len(prefix):]
+    remaining = re.match(r"[\w:]*", suffix).group()
+    start = position.character - len(typed.encode("utf-16-le")) // 2
+    end = position.character + len(remaining.encode("utf-16-le")) // 2
+    return [lsp.CompletionItem(
+        label=name, kind=lsp.CompletionItemKind.Method,
+        detail=f"{cls or 'class'} {name} {signature}".rstrip(),
+        text_edit=lsp.TextEdit(range=lsp.Range(
+            start=lsp.Position(line=position.line, character=start),
+            end=lsp.Position(line=position.line, character=end)), new_text=name),
+    ) for name, (signature, _) in sorted(methods.items())
+        if name.startswith(typed) and (internal or not name.startswith("_") and not name[:1].isupper())]
+
+
+def _collect_classes(tree, classes, uri=None, source=""):
+    contexts = []
+    def collect(script, namespace=""):
+        if script is None:
+            return
+        for cmd in script.children:
+            if not isinstance(cmd, Command):
+                continue
+            args = cmd.args
+            routine = (cmd.routine.contents or "").removeprefix("::")
+            if routine == "namespace" and len(args) == 3 and args[0].contents == "eval" and args[1].contents:
+                collect(_body(args[2]), _qualified(args[1].contents, namespace))
+            elif routine == "oo::class" and len(args) == 3 and args[0].contents == "create" and args[1].contents:
+                name = _qualified(args[1].contents, namespace)
+                info = ClassInfo(namespace=namespace)
+                info.definition = name_location(args[1], uri, source)
+                classes[name] = info
+                body = _body(args[2])
+                if body is None:
+                    continue
+                for method in body.children:
+                    if not isinstance(method, Command):
+                        continue
+                    ma = method.args
+                    if method.routine.contents == "method" and len(ma) == 3 and ma[0].contents:
+                        method_body = _body(ma[2])
+                        info.methods[ma[0].contents] = (ma[1].contents or "", method_body)
+                        location = name_location(ma[0], uri, source)
+                        if location is not None:
+                            info.method_definitions[ma[0].contents] = location
+                        contexts.append((method_body, namespace, name))
+                    elif method.routine.contents in {"constructor", "destructor"} and ma:
+                        if method.routine.contents == "constructor" and len(ma) == 2:
+                            info.constructor = ma[0].contents or ""
+                            info.constructor_definition = name_location(method.routine, uri, source)
+                        contexts.append((_body(ma[-1]), namespace, name))
+
+    collect(tree)
+    return contexts
+
+
+def indexed_classes(tree, uri=None, source=""):
+    classes = {}
+    _collect_classes(tree, classes, uri, source)
+    return classes
+
+
+def _analyze(tree, typed="", marker="", external_classes=None, uri=None, source=""):
+    classes = dict(external_classes or {})
+    calls = []
+
+    contexts = _collect_classes(tree, classes, uri, source)
+    result = None
+
+    def receiver(node, env, objects, namespace, owner, depth=0):
+        if depth > 12:
+            return None
+        if isinstance(node, VarSub):
+            return env.get(node.value)
+        if isinstance(node, CommandSub) and len(node.children) == 1:
+            return returned(node.children[0], env, objects, namespace, owner, depth + 1)
+        name = node.contents
+        return objects.get(_qualified(name, namespace)) if name else None
+
+    def returned(cmd, env, objects, namespace, owner, depth=0):
+        if not isinstance(cmd, Command) or depth > 12:
+            return None
+        args = cmd.args
+        name = cmd.routine.contents
+        if name == "self" and not args:
+            return owner
+        qualified = _qualified(name, namespace) if name else None
+        if qualified in classes and args and args[0].contents in {"new", "create"}:
+            return qualified
+        cls = owner if name == "my" else receiver(cmd.routine, env, objects, namespace, owner, depth + 1)
+        if cls not in classes or not args:
+            return None
+        method = classes[cls].methods.get(args[0].contents)
+        if method is None or method[1] is None:
+            return None
+        # Only infer unconditional final returns; conditional results stay unknown.
+        commands = [c for c in method[1].children if isinstance(c, Command)]
+        if commands and commands[-1].routine.contents == "return" and len(commands[-1].args) == 1:
+            return receiver(commands[-1].args[0], {}, objects, classes[cls].namespace, cls, depth + 1)
+        return None
+
+    def walk(script, env, objects, namespace="", owner=None):
+        nonlocal result
+        if script is None:
+            return
+        for cmd in script.children:
+            if not isinstance(cmd, Command):
+                continue
+            args = cmd.args
+            name = cmd.routine.contents
+            cls = owner if name == "my" else receiver(cmd.routine, env, objects, namespace, owner)
+            method_name = args[0].contents if args else None
+            if cls in classes and method_name in classes[cls].methods:
+                calls.append(MethodCall(cmd, f"{cls} {method_name}", classes[cls].methods[method_name][0],
+                                        definition=classes[cls].method_definitions.get(method_name)))
+            elif name and _qualified(name, namespace) in classes and method_name in {"new", "create"}:
+                cls = _qualified(name, namespace)
+                parameters = classes[cls].constructor
+                if method_name == "create":
+                    parameters = "objectName " + parameters
+                calls.append(MethodCall(cmd, f"{cls} {method_name}", parameters,
+                                        definition=classes[cls].constructor_definition or classes[cls].definition))
+            if marker and args and args[0].contents == typed + marker:
+                cls = owner if name == "my" else receiver(cmd.routine, env, objects, namespace, owner)
+                if cls in classes:
+                    result = (cls, name == "my")
+                elif name and _qualified(name, namespace) in classes:
+                    result = (None, False)
+                return
+            # Command substitutions can contain the completion receiver.
+            for node in cmd.children:
+                if isinstance(node, CommandSub):
+                    walk(node, env, objects, namespace, owner)
+            if name == "set" and len(args) == 2 and args[0].contents:
+                env[args[0].contents] = receiver(args[1], env, objects, namespace, owner)
+            elif name == "unset":
+                for arg in args:
+                    env.pop(arg.contents, None)
+            elif name == "proc" and len(args) == 3:
+                walk(_body(args[2]), {}, objects.copy(), namespace)
+            elif name == "namespace" and len(args) == 3 and args[0].contents == "eval" and args[1].contents:
+                walk(_body(args[2]), {}, objects, _qualified(args[1].contents, namespace))
+            elif name and _qualified(name, namespace) in classes and len(args) >= 2 and args[0].contents == "create" and args[1].contents:
+                objects[_qualified(args[1].contents, namespace)] = _qualified(name, namespace)
+            else:
+                for arg in args:
+                    if isinstance(arg, Script):
+                        # Branch-local facts are not propagated beyond the branch.
+                        walk(arg, env.copy(), objects.copy(), namespace, owner)
+
+    walk(tree, {}, {})
+    for body, namespace, owner in contexts:
+        walk(body, {}, {}, namespace, owner)
+    return classes, result, calls
+
+
+def resolved_method_calls(source, external_classes=None, tree=None):
+    if not may_contain_classes(source, external_classes):
+        return []
+    if tree is None:
+        tree = parse_completion_source(source)
+    return _analyze(tree, external_classes=external_classes)[2] if tree is not None else []

server/src/tools/tcloo_navigation.py

@@ -0,0 +1,38 @@
+"""Definition targets for literal TclOO classes and resolved method calls."""
+
+from tools.tcloo_completion import _analyze, may_contain_classes, name_location, parse_completion_source
+from tools.tcloo_symbols import class_symbols
+
+
+def tcloo_definition(source, uri, position, external_classes=None, tree=None):
+    if not may_contain_classes(source, external_classes):
+        return None
+    if tree is None:
+        tree = parse_completion_source(source)
+    if tree is None:
+        return None
+    classes, _, calls = _analyze(tree, external_classes=external_classes, uri=uri, source=source)
+
+    def contains(location):
+        if location is None:
+            return False
+        start, end = location.range.start, location.range.end
+        return (start.line, start.character) <= (position.line, position.character) < (end.line, end.character)
+
+    targets = {}
+    declarations, references = class_symbols(tree, classes, targets)
+    for node in references:
+        if contains(name_location(node, uri, source)):
+            return classes[targets[node.pos]].definition
+    for name, node in declarations.items():
+        if contains(name_location(node, uri, source)):
+            return classes[name].definition
+    for call in calls:
+        if call.command.args and contains(name_location(call.command.args[0], uri, source)):
+            return call.definition
+    # F12 on a declaration itself should stay on that declaration.
+    for info in classes.values():
+        for location in [*info.method_definitions.values(), info.constructor_definition]:
+            if location is not None and location.uri == uri and contains(location):
+                return location
+    return None

server/src/tools/tcloo_symbols.py

@@ -0,0 +1,57 @@
+"""Class declarations and references shared by completion and highlighting."""
+
+import lsprotocol.types as lsp
+from tclint.syntax_tree import Command
+
+from tools.tcloo_completion import _body, _qualified
+
+
+def class_symbols(tree, external_classes=None, reference_targets=None):
+    """Return qualified class declarations and statically resolved name nodes."""
+    declarations = {}
+    commands = []
+
+    def walk(node, namespace="", in_class=False):
+        if node is None:
+            return
+        if isinstance(node, Command):
+            args = node.args
+            name = (node.routine.contents or "").removeprefix("::")
+            commands.append((node, namespace))
+            if (name == "namespace" and len(args) == 3
+                    and args[0].contents == "eval" and args[1].contents):
+                walk(_body(args[2]), _qualified(args[1].contents, namespace), in_class)
+                return
+            if (name == "oo::class" and len(args) == 3
+                    and args[0].contents == "create" and args[1].contents):
+                declarations[_qualified(args[1].contents, namespace)] = args[1]
+                walk(_body(args[2]), namespace, True)
+                return
+            if in_class and name in {"method", "constructor", "destructor"} and args:
+                walk(_body(args[-1]), namespace, True)
+                return
+        for child in node.children:
+            walk(child, namespace, in_class)
+
+    walk(tree)
+    known_classes = set(external_classes or ()) | declarations.keys()
+    references = []
+    for command, namespace in commands:
+        name = command.routine.contents
+        target = next((candidate for candidate in (
+            _qualified(name, namespace), _qualified(name, ""),
+        ) if candidate in known_classes), None) if name else None
+        if target:
+            references.append(command.routine)
+            if reference_targets is not None:
+                reference_targets[command.routine.pos] = target
+    return declarations, references
+
+
+def class_completion_items(tree):
+    declarations, _ = class_symbols(tree)
+    return [lsp.CompletionItem(
+        label=name.removeprefix("::"),
+        kind=lsp.CompletionItemKind.Class,
+        detail=f"TclOO class {name}",
+    ) for name in sorted(declarations)]

server/src/tools/variable_index.py

@@ -4,6 +4,7 @@ from dataclasses import dataclass
 
 from tclint.syntax_tree import Command, Node, Script
 from tclint.syntax_tree import List as TclList
+from tools.variable_names import variable_name
 
 
 @dataclass
@@ -81,7 +82,7 @@ def build_variable_index(
                 return
 
             if routine == "set" and node.args:
-                raw_name = getattr(node.args[0], "contents", None)
+                raw_name = variable_name(node.args[0])
                 base = _normalize_var_name(raw_name)
                 if base is not None:
                     if raw_name and raw_name.startswith("::"):

server/src/tools/variable_names.py

@@ -0,0 +1,44 @@
+"""Extract statically known variable names without evaluating Tcl substitutions."""
+
+from tclint.syntax_tree import BareWord, CompoundBareWord, Node, QuotedWord, VarSub
+
+
+def variable_name(node: Node) -> str | None:
+    contents = node.contents
+    if isinstance(contents, str):
+        return contents
+    if isinstance(node, (CompoundBareWord, QuotedWord)) and node.children:
+        first = node.children[0]
+        last = node.children[-1]
+        if (
+            isinstance(first, BareWord)
+            and isinstance(last, BareWord)
+            and "(" in first.value
+            and last.value.endswith(")")
+        ):
+            # Substitutions in an array index do not change the array's name.
+            return first.value.split("(", 1)[0] or None
+    return None
+
+
+def array_key_parts(node: Node, *, preserve_variables: bool = False) -> tuple[str | None, ...]:
+    """Keep comma-separated literal index components; substitutions are unknown."""
+    contents = node.contents
+    if not isinstance(contents, str):
+        if not isinstance(node, (CompoundBareWord, QuotedWord)) or not variable_name(node):
+            return ()
+        chunks = []
+        for child in node.children:
+            if isinstance(child, BareWord):
+                chunks.append(child.value)
+            elif preserve_variables and isinstance(child, VarSub) and not child.children:
+                chunks.append("${" + child.value + "}" if child.braced else "$" + child.value)
+            else:
+                chunks.append("\0")
+        contents = "".join(chunks)
+    if "(" not in contents or not contents.endswith(")"):
+        return ()
+    return tuple(
+        part if part and not any(char in part for char in ("\0[]\\" if preserve_variables else "\0$[]\\")) else None
+        for part in contents.split("(", 1)[1][:-1].split(",")
+    )

server/tests/python_tests/test_completion_context.py

@@ -103,6 +103,153 @@ def _argument_completion_labels(source: str) -> set[str] | None:
     return {item.label for item in completion.items}
 
 
+def test_unset_space_shows_options_then_variables(tmp_path, monkeypatch):
+    server, document, _ = _completion_server(tmp_path, monkeypatch)
+    document = server.workspace.get_text_document(document.uri)
+    for version, tail in enumerate(["unset ", "unset -", "unset -nocomplain ", "unset -- ", "unset global"], start=2):
+        source = "set globalValue 1\n" + tail
+        document._source = source
+        document.version = version
+        items = _complete(document, lsp.Position(line=1, character=len(tail)))
+        labels = {item.label for item in items}
+        if tail in {"unset ", "unset -"}:
+            assert labels == {"-nocomplain", "--"}
+        else:
+            assert "globalValue" in labels
+            assert "-nocomplain" not in labels
+            if tail == "unset -nocomplain ":
+                assert "--" in labels
+            else:
+                assert "--" not in labels
+
+
+def test_array_keys_complete_in_set_and_substitution(tmp_path: Path, monkeypatch):
+    server, _, _ = _completion_server(tmp_path, monkeypatch)
+    workspace = _document(
+        tmp_path / "arrays.tcl",
+        "set ::lib_flag(enabled) 1\nset ::lib_flag(external) 1\n",
+    )
+    assert server.update_poco_completion_for_file(workspace)
+    source = (
+        "set lib_flag(enabled) 0\n"
+        "set lib_flag(empty) 1\n"
+        "set other(wrong) 1\n"
+        "proc hidden {} { set lib_flag(private) 1 }\n"
+        "set lib_flag()\n"
+        "puts $lib_flag(en)\n"
+        "puts 😀; set lib_flag(em\n"
+    )
+    current = _document(tmp_path / "arrays-current.tcl", source)
+    server.workspace.put_text_document(lsp.TextDocumentItem(
+        uri=current.uri, language_id="tcl", version=1, text=source,
+    ))
+    assert server.update_poco_completion_for_file(current)
+    items = _complete(current, _position_after(source, "set lib_flag(", 3))
+    assert [item.label for item in items] == ["empty", "enabled", "external"]
+    assert all(item.text_edit.new_text == item.label for item in items)
+    items = _complete(current, _position_after(source, "puts $lib_flag(en"))
+    assert [item.label for item in items] == ["enabled"]
+    assert items[0].text_edit.new_text == "enabled"
+    position = lsp.Position(line=6, character=len(source.splitlines()[6].encode("utf-16-le")) // 2)
+    items = _complete(current, position)
+    assert [item.label for item in items] == ["empty"]
+    assert items[0].text_edit.new_text == "empty)"
+    assert items[0].text_edit.range.start.character == position.character - 2
+
+
+def test_dynamic_array_index_keeps_variable_identity(tmp_path: Path, monkeypatch):
+    from tools.navigation import build_file_symbol_index
+    from tools.parser import CustomParser
+    from tools.semantic_tokens import _Highlighter
+    from tools.variable_index import build_variable_index
+    from tools.variable_names import variable_name
+
+    source = (
+        "set custom_flag(from_move,$::mom_path_name) 1\n"
+        'set "::quoted_flag(from_move,$::mom_path_name)" 1\n'
+        "set ::command_flag([info hostname]) 1\n"
+        "set ${dynamic_name}(entry) 1\n"
+        "proc example {} { set local_flag($::mom_path_name) 1 }\n"
+        "puts $custom_flag\n"
+    )
+    tree = CustomParser().parse(source)
+    globals_, locals_, _ = build_variable_index(source, tree)
+    assert {"custom_flag", "quoted_flag", "command_flag"} <= globals_
+    assert locals_["example"] == {"local_flag"}
+    assert variable_name(tree.children[3].args[0]) is None
+    path = tmp_path / "dynamic.tcl"
+    index = build_file_symbol_index(str(path), path.as_uri(), tree)
+    definition = next(
+        item for item in index.occurrences
+        if item.identity.name == "::custom_flag" and item.is_definition
+    )
+    assert definition.range.start.character == 4
+    assert definition.range.end.character == 15
+    assert definition.array_element is None
+    assert any(item.identity.name == "::mom_path_name" for item in index.occurrences)
+    highlighter = _Highlighter([], {})
+    tree.accept(highlighter, recurse=True)
+    assert any(
+        position == (0, 4) and length == 11 and kind == "variable"
+        for position, length, kind, _ in highlighter._tokens
+    )
+    server, _, _ = _completion_server(tmp_path, monkeypatch)
+    current = _document(path, source)
+    server.workspace.put_text_document(lsp.TextDocumentItem(
+        uri=current.uri, language_id="tcl", version=1, text=source,
+    ))
+    assert server.update_poco_completion_for_file(current)
+    items = _complete(current, _position_after(source, "puts $custom"))
+    assert "custom_flag" in {item.label for item in items}
+    workspace_items = next(
+        items for item_path, items in server.completion_items_by_file_snapshot().items()
+        if server.paths_equal(item_path, str(path))
+    )
+    assert {"quoted_flag", "command_flag"} <= {item.label for item in workspace_items}
+
+
+def test_literal_array_components_complete_around_substitutions(tmp_path: Path, monkeypatch):
+    from tools.completion_items import array_element_completions
+
+    server, _, _ = _completion_server(tmp_path, monkeypatch)
+    source = (
+        "set custom_flag(from_move,$::mom_path_name) 1\n"
+        "set custom_flag(to_move,$::mom_path_name) 1\n"
+        "set custom_flag($::mom_path_name,finished) 1\n"
+        "set custom_flag(prefix_$::mom_path_name,other) 1\n"
+        "set custom_flag([info hostname],command_tail) 1\n"
+        "set other_flag(wrong,$::mom_path_name) 1\n"
+        "set multi_flag(move,$first,axis,$second) 1\n"
+    )
+    document = _document(tmp_path / "components.tcl", source)
+    assert server.update_poco_completion_for_file(document)
+    cases = [
+        ("set custom_flag(|,$::mom_path_name)", {"from_move", "to_move"}, "from_move", "set custom_flag(from_move,$::mom_path_name)"),
+        ("set custom_flag(fr|om_old,$::mom_path_name)", {"from_move"}, "from_move", "set custom_flag(from_move,$::mom_path_name)"),
+        ("puts $custom_flag($::mom_path_name,fi|)", {"finished"}, "finished", "puts $custom_flag($::mom_path_name,finished)"),
+        ("set custom_flag($::mom_path_name,|)", {"finished", "other", "command_tail"}, "other", "set custom_flag($::mom_path_name,other)"),
+        ("set custom_flag(fr|", {"from_move"}, "from_move", "set custom_flag(from_move,$::mom_path_name)"),
+        ("set custom_flag(fr|)", {"from_move"}, "from_move", "set custom_flag(from_move,$::mom_path_name)"),
+        ("set multi_flag(m|)", {"move"}, "move", "set multi_flag(move,$first,axis,$second)"),
+    ]
+    for marked, labels, selected, expected in cases:
+        offset = marked.index("|")
+        line = marked.replace("|", "")
+        items = array_element_completions(
+            [line], lsp.Position(line=0, character=offset),
+            server.navigation_snapshot().values(), str(tmp_path / "caller.tcl"),
+        )
+        assert {item.label for item in items} == labels
+        edit = next(item.text_edit for item in items if item.label == selected)
+        item = next(item for item in items if item.label == selected)
+        assert item.insert_text_format == lsp.InsertTextFormat.PlainText
+        assert line[:edit.range.start.character] + edit.new_text + line[edit.range.end.character:] == expected
+    assert array_element_completions(
+        ["set custom_flag(from_move,$::mom"], lsp.Position(line=0, character=31),
+        server.navigation_snapshot().values(), str(tmp_path / "caller.tcl"),
+    ) is None
+
+
 def _argument_completion_request(source: str):
     lines = source.split("\n")
     character = len(lines[-1].encode("utf-16-le")) // 2

server/tests/python_tests/test_debug_server.py

@@ -1,4 +1,5 @@
 import sys
+import threading
 from pathlib import Path
 
 import pytest
@@ -27,27 +28,46 @@ def test_debug_endpoint_rejects_invalid_port(monkeypatch, port):
         _debug_server._debug_endpoint()
 
 
-def test_connect_debugger_retries_until_adapter_is_ready(monkeypatch):
-    class FakeDebugpy:
-        def __init__(self):
-            self.connect_calls = 0
-            self.wait_calls = 0
+class FakeDebugpy:
+    def __init__(self, refuse=False, block_wait=False):
+        self.refuse = refuse
+        self.block_wait = block_wait
+        self.connect_calls = 0
+        self.wait_calls = 0
 
-        def connect(self, endpoint):
-            assert endpoint == ("127.0.0.1", 5678)
-            self.connect_calls += 1
-            if self.connect_calls < 3:
-                raise ConnectionRefusedError("listener is starting")
+    def connect(self, endpoint):
+        assert endpoint == ("127.0.0.1", 5678)
+        self.connect_calls += 1
+        if self.refuse:
+            raise ConnectionRefusedError("no listener")
 
-        def wait_for_client(self):
-            self.wait_calls += 1
+    def wait_for_client(self):
+        self.wait_calls += 1
+        if self.block_wait:
+            threading.Event().wait()
 
+
+def test_connect_debugger_connects_once_and_waits_for_client():
     fake_debugpy = FakeDebugpy()
-    monkeypatch.setattr(_debug_server.time, "sleep", lambda _seconds: None)
 
-    _debug_server._connect_debugger(
-        fake_debugpy, "127.0.0.1", 5678, timeout=1.0
-    )
+    _debug_server._connect_debugger(fake_debugpy, "127.0.0.1", 5678, timeout=1.0)
 
-    assert fake_debugpy.connect_calls == 3
+    assert fake_debugpy.connect_calls == 1
     assert fake_debugpy.wait_calls == 1
+
+
+def test_connect_debugger_does_not_retry_refused_connection():
+    # debugpy.connect() cannot be called a second time after a refused connection.
+    fake_debugpy = FakeDebugpy(refuse=True)
+
+    with pytest.raises(RuntimeError, match="No debugpy listener"):
+        _debug_server._connect_debugger(fake_debugpy, "127.0.0.1", 5678, timeout=1.0)
+
+    assert fake_debugpy.connect_calls == 1
+
+
+def test_connect_debugger_times_out_on_stale_adapter():
+    fake_debugpy = FakeDebugpy(block_wait=True)
+
+    with pytest.raises(RuntimeError, match="stale debugpy adapter"):
+        _debug_server._connect_debugger(fake_debugpy, "127.0.0.1", 5678, timeout=0.1)

server/tests/python_tests/test_def_symbols.py

@@ -0,0 +1,260 @@
+"""Completion of .def block templates and addresses from PSC DefinedEvents."""
+
+import itertools
+from pathlib import Path
+
+import lsprotocol.types as lsp  # type: ignore
+from pygls.workspace import Workspace
+
+import lsp_server
+from lsp_tclserver import TclLanguageServer
+from tools.def_symbols import parse_def_symbols
+from tools.file_sourcing import psc_defined_event_files
+
+PSC = """<?xml version="1.0" encoding="UTF-8"?>
+<Configuration>
+  <Sourcing><Sequence>
+    <Layer Name="Service" SubFolder="service">
+      <Scripts><Filename Name="service"/></Scripts>
+      <DefinedEvents><Filename Name="service" Processing="auto"/></DefinedEvents>
+    </Layer>
+    <Layer Name="Empty"><DefinedEvents/></Layer>
+  </Sequence></Sourcing>
+</Configuration>
+"""
+
+DEF = """MACHINE Default
+
+FORMATTING
+{
+	ADDRESS SPOS
+	{
+		FORMAT      Coordinate
+	}
+	ADDRESS X {
+	}
+\tBLOCK_TEMPLATE external_subprogram
+\t{
+\t\tText[$lib_spf(value,subprogram_output_name)]
+\t}
+\tBLOCK_TEMPLATE steady_rest
+\t{
+\t\tText[M60]
+\t}
+#\tBLOCK_TEMPLATE commented_out
+}
+"""
+
+
+def _project(tmp_path: Path, monkeypatch):
+    (tmp_path / "service").mkdir()
+    psc = tmp_path / "post.psc"
+    psc.write_text(PSC, encoding="utf-8")
+    (tmp_path / "service" / "service.def").write_text(DEF, encoding="utf-8")
+    (tmp_path / "service" / "service.tcl").write_text("proc svc {} {}\n", encoding="utf-8")
+
+    server = TclLanguageServer(name="block-template-test", version="1", max_workers=1)
+    server.protocol._workspace = Workspace(  # pylint: disable=protected-access
+        root_uri=tmp_path.as_uri(),
+        sync_kind=lsp.TextDocumentSyncKind.Incremental,
+        workspace_folders=[lsp.WorkspaceFolder(uri=tmp_path.as_uri(), name="root")],
+        position_encoding=lsp.PositionEncodingKind.Utf16,
+    )
+    monkeypatch.setattr(lsp_server, "LSP_SERVER", server)
+    server.refresh_psc_scripts([tmp_path])
+    return server, psc
+
+
+_versions = itertools.count(1)
+
+
+def _complete(server, tmp_path: Path, source: str, trigger: str | None = None):
+    uri = (tmp_path / "caller.tcl").as_uri()
+    # A new version per request, the server caches lines by (uri, version).
+    server.workspace.put_text_document(
+        lsp.TextDocumentItem(uri=uri, language_id="tcl", version=next(_versions), text=source)
+    )
+    lines = source.split("\n")
+    context = None
+    if trigger is not None:
+        context = lsp.CompletionContext(
+            trigger_kind=lsp.CompletionTriggerKind.TriggerCharacter,
+            trigger_character=trigger,
+        )
+    result = lsp_server.on_completion(
+        lsp.CompletionParams(
+            text_document=lsp.TextDocumentIdentifier(uri=uri),
+            position=lsp.Position(line=len(lines) - 1, character=len(lines[-1])),
+            context=context,
+        )
+    )
+    return sorted(result.items, key=lambda item: item.sort_text or "")
+
+
+def test_parse_def_symbols_ignores_comments():
+    symbols = parse_def_symbols(DEF)
+    assert symbols.block_templates == ("external_subprogram", "steady_rest")
+    assert symbols.addresses == ("SPOS", "X")
+
+
+def test_psc_defined_event_files_resolve_def_paths(tmp_path, monkeypatch):
+    _, psc = _project(tmp_path, monkeypatch)
+    assert psc_defined_event_files(psc) == [(tmp_path / "service" / "service.def").resolve()]
+
+
+def test_mom_do_template_offers_templates_then_variables_on_space(tmp_path, monkeypatch):
+    server, _ = _project(tmp_path, monkeypatch)
+    items = _complete(server, tmp_path, "set globalValue 1\nMOM_do_template ", trigger=" ")
+    labels = [item.label for item in items]
+    assert labels[:2] == ["external_subprogram", "steady_rest"]
+    assert items[0].detail == "Block template (service.def)"
+    variable = next(item for item in items if item.label == "globalValue")
+    assert variable.insert_text == "$globalValue"
+    assert "svc" not in labels
+
+
+def test_mom_do_template_ranks_templates_before_variables(tmp_path, monkeypatch):
+    server, _ = _project(tmp_path, monkeypatch)
+    items = _complete(server, tmp_path, "set globalValue 1\nMOM_do_template st")
+    labels = [item.label for item in items]
+    assert labels[:2] == ["external_subprogram", "steady_rest"]
+    assert "globalValue" in labels
+
+
+def test_mom_do_template_dollar_still_completes_variables(tmp_path, monkeypatch):
+    server, _ = _project(tmp_path, monkeypatch)
+    items = _complete(server, tmp_path, "set globalValue 1\nMOM_do_template $glob")
+    labels = {item.label for item in items}
+    assert "globalValue" in labels
+    assert "steady_rest" not in labels
+
+
+def test_def_change_refreshes_block_templates(tmp_path, monkeypatch):
+    server, _ = _project(tmp_path, monkeypatch)
+    def_file = tmp_path / "service" / "service.def"
+    def_file.write_text("BLOCK_TEMPLATE new_block\n{\n}\n", encoding="utf-8")
+    lsp_server.did_change_watched_files(lsp.DidChangeWatchedFilesParams(changes=[
+        lsp.FileEvent(uri=def_file.as_uri(), type=lsp.FileChangeType.Changed)]))
+    assert [item.label for item in server.block_template_items()] == ["new_block"]
+    assert server.address_items() == []
+
+
+def test_mom_ask_address_value_offers_addresses_then_variables(tmp_path, monkeypatch):
+    server, _ = _project(tmp_path, monkeypatch)
+    items = _complete(server, tmp_path, "set globalValue 1\nMOM_ask_address_value ", trigger=" ")
+    labels = [item.label for item in items]
+    assert labels[:2] == ["SPOS", "X"]
+    assert items[0].detail == "Address (service.def)"
+    assert "globalValue" in labels
+    assert "steady_rest" not in labels
+
+
+def test_mom_force_and_suppress_offer_mode_or_variable_then_addresses(tmp_path, monkeypatch):
+    server, _ = _project(tmp_path, monkeypatch)
+    for command in ("MOM_force", "MOM_suppress"):
+        items = _complete(server, tmp_path, f"set globalValue 1\n{command} ", trigger=" ")
+        labels = [item.label for item in items]
+        assert set(labels[:3]) == {"Always", "Once", "Off"}
+        variable = next(item for item in items if item.label == "globalValue")
+        assert variable.insert_text == "$globalValue"
+        assert "SPOS" not in labels
+
+        for source in (f"{command} Once ", f"{command} Always SPOS "):
+            labels = [item.label for item in _complete(server, tmp_path, source, trigger=" ")]
+            assert labels[:2] == ["SPOS", "X"]
+            assert "Once" not in labels
+
+
+def _edit(items, label):
+    item = next(item for item in items if item.label == label)
+    return item.text_edit.new_text, (item.text_edit.range.start.character, item.text_edit.range.end.character)
+
+
+def test_def_symbols_and_modes_are_inserted_quoted(tmp_path, monkeypatch):
+    server, _ = _project(tmp_path, monkeypatch)
+    source = "MOM_do_template st"
+    assert _edit(_complete(server, tmp_path, source), "steady_rest") == ('"steady_rest"', (16, 18))
+    source = "MOM_force "
+    assert _edit(_complete(server, tmp_path, source, trigger=" "), "Once") == ('"Once"', (10, 10))
+    source = "MOM_force Once SP"
+    assert _edit(_complete(server, tmp_path, source), "SPOS") == ('"SPOS"', (15, 17))
+
+
+def test_typed_quotes_are_replaced_not_doubled(tmp_path, monkeypatch):
+    server, _ = _project(tmp_path, monkeypatch)
+    # Opening quote typed by the user.
+    source = 'MOM_ask_address_value "SP'
+    assert _edit(_complete(server, tmp_path, source), "SPOS") == ('"SPOS"', (22, 25))
+    # Closing quote inserted by the editor after the cursor.
+    uri = (tmp_path / "caller.tcl").as_uri()
+    source = 'MOM_ask_address_value "SP"'
+    server.workspace.put_text_document(
+        lsp.TextDocumentItem(uri=uri, language_id="tcl", version=next(_versions), text=source)
+    )
+    items = lsp_server.on_completion(
+        lsp.CompletionParams(
+            text_document=lsp.TextDocumentIdentifier(uri=uri),
+            position=lsp.Position(line=0, character=25),
+        )
+    ).items
+    assert _edit(items, "SPOS") == ('"SPOS"', (22, 26))
+
+
+def test_block_list_prefix_offers_keyword_and_stays_incomplete(tmp_path, monkeypatch):
+    server, _ = _project(tmp_path, monkeypatch)
+    uri = (tmp_path / "caller.tcl").as_uri()
+    source = "MOM_do_template BLOCK_L"
+    server.workspace.put_text_document(
+        lsp.TextDocumentItem(uri=uri, language_id="tcl", version=next(_versions), text=source)
+    )
+    result = lsp_server.on_completion(
+        lsp.CompletionParams(
+            text_document=lsp.TextDocumentIdentifier(uri=uri),
+            position=lsp.Position(line=0, character=len(source)),
+        )
+    )
+    assert result.is_incomplete
+    keyword = result.items[0]
+    assert keyword.label == "BLOCK_LIST"
+    assert keyword.command.command == "editor.action.triggerSuggest"
+
+
+def test_block_list_shows_all_templates_quoted(tmp_path, monkeypatch):
+    server, _ = _project(tmp_path, monkeypatch)
+    items = _complete(server, tmp_path, "set a 1\n    BLOCK_LIST")
+    assert [item.label for item in items] == ["external_subprogram", "steady_rest"]
+    assert _edit(items, "steady_rest") == ('"steady_rest"', (4, 14))
+    assert all(item.filter_text.startswith("BLOCK_LIST") for item in items)
+
+
+def test_block_list_ignores_variables_and_other_words(tmp_path, monkeypatch):
+    server, _ = _project(tmp_path, monkeypatch)
+    for source in ("set x $BLOCK_LIST", "set x MY_BLOCK_LIST", "set x steady"):
+        labels = [item.label for item in _complete(server, tmp_path, source)]
+        assert "BLOCK_LIST" not in labels
+
+
+def test_addr_list_shows_all_addresses_quoted(tmp_path, monkeypatch):
+    server, _ = _project(tmp_path, monkeypatch)
+    items = _complete(server, tmp_path, "MOM_force Once ADDR_LIST")
+    assert [item.label for item in items] == ["SPOS", "X"]
+    assert _edit(items, "SPOS") == ('"SPOS"', (15, 24))
+    assert all(item.filter_text.startswith("ADDR_LIST") for item in items)
+
+
+def test_addr_list_prefix_offers_keyword(tmp_path, monkeypatch):
+    server, _ = _project(tmp_path, monkeypatch)
+    uri = (tmp_path / "caller.tcl").as_uri()
+    source = "ADDR"
+    server.workspace.put_text_document(
+        lsp.TextDocumentItem(uri=uri, language_id="tcl", version=next(_versions), text=source)
+    )
+    result = lsp_server.on_completion(
+        lsp.CompletionParams(
+            text_document=lsp.TextDocumentIdentifier(uri=uri),
+            position=lsp.Position(line=0, character=len(source)),
+        )
+    )
+    assert result.is_incomplete
+    assert result.items[0].label == "ADDR_LIST"
+    assert "BLOCK_LIST" not in {item.label for item in result.items}

server/tests/python_tests/test_formatter.py

@@ -0,0 +1,58 @@
+"""Formatting with NxFormatter."""
+
+from tclint.format import FormatterOpts
+from tools.formatter import NxFormatter
+from tools.parser import CustomParser
+
+
+def _format(source: str) -> str:
+    formatter = NxFormatter(
+        FormatterOpts(
+            indent="\t",
+            spaces_in_braces=False,
+            balanced_spaces_in_braces=False,
+            max_blank_lines=500,
+            indent_namespace_eval=True,
+            indent_mixed_tab_size=0,
+            emacs=False,
+            debug_whitespace=False,
+        )
+    )
+    return formatter.format_top(source, CustomParser())
+
+
+def test_uplevel_body_is_indented():
+    source = "proc a {} {\n\tuplevel #0 {\n\tset x 1\n\t\tset y 2\n   }\n}\n"
+    assert _format(source) == "proc a {} {\n\tuplevel #0 {\n\t\tset x 1\n\t\tset y 2\n\t}\n}\n"
+
+
+def test_uplevel_without_level_and_with_variable_level():
+    source = "uplevel {\nset x 1\n}\nuplevel $lvl {\nset y 2\n}\nuplevel set z 3\n"
+    assert _format(source) == (
+        "uplevel {\n\tset x 1\n}\nuplevel $lvl {\n\tset y 2\n}\nuplevel set z 3\n"
+    )
+
+
+def test_comment_gets_space_after_hash():
+    source = (
+        "#Comment\n"
+        "# already spaced\n"
+        "#\tTabbed\n"
+        "#\n"
+        "##########\n"
+        "set x 1 ;#inline\n"
+        "proc a {} {\n"
+        "\t#nested\n"
+        "}\n"
+    )
+    assert _format(source) == (
+        "# Comment\n"
+        "# already spaced\n"
+        "#\tTabbed\n"
+        "#\n"
+        "##########\n"
+        "set x 1 ;# inline\n"
+        "proc a {} {\n"
+        "\t# nested\n"
+        "}\n"
+    )

server/tests/python_tests/test_incremental_parse.py

@@ -0,0 +1,131 @@
+import sys
+from pathlib import Path
+
+import pytest
+
+THIS_DIR = Path(__file__).parent
+SRC_DIR = THIS_DIR.parent.parent / "src"
+if str(SRC_DIR) not in sys.path:
+    sys.path.insert(0, str(SRC_DIR))
+
+from lsp_tclserver import TclLanguageServer  # noqa: E402
+from pygls.workspace.text_document import TextDocument  # noqa: E402
+from tclint.lexer import TclSyntaxError  # noqa: E402
+from tclint.syntax_tree import Node  # noqa: E402
+from tools.incremental_parse import reparse  # noqa: E402
+from tools.parser import CustomParser  # noqa: E402
+
+SOURCE = """\
+# header comment
+set a 1; set b 2
+proc first {x} {
+    global mom_pos
+    if {$x > 0} {
+        MOM_output_literal "first $x"
+    }
+    return [expr {$x + 1}]
+}
+
+proc second {} {
+    set list [list a b \\
+        c d]
+    return $list
+}
+lappend ::handlers {second}
+"""
+
+
+def _parse(text, pos=None):
+    parser = CustomParser()
+    tree = parser.parse(text, pos=pos)
+    return tree, list(parser.violations)
+
+
+def _differences(a, b, path="root"):
+    if type(a) is not type(b):
+        return f"{path}: {type(a).__name__} != {type(b).__name__}"
+    for key in a.__dict__.keys() | b.__dict__.keys():
+        first, second = a.__dict__.get(key), b.__dict__.get(key)
+        if isinstance(first, Node):
+            difference = _differences(first, second, f"{path}.{key}")
+        elif isinstance(first, (list, tuple)) and first and isinstance(first[0], Node):
+            if len(first) != len(second):
+                return f"{path}.{key}: {len(first)} != {len(second)}"
+            difference = next(
+                (d for i, (x, y) in enumerate(zip(first, second)) if (d := _differences(x, y, f"{path}.{key}[{i}]"))),
+                None,
+            )
+        else:
+            difference = None if first == second else f"{path}.{key}: {first!r} != {second!r}"
+        if difference:
+            return difference
+    return None
+
+
+def _violations(violations):
+    return [(str(v.id), v.message, v.start, v.end) for v in violations]
+
+
+@pytest.mark.parametrize("old, new", [
+    ("MOM_output_literal \"first $x\"", "MOM_output_literal \"first $x\" extra"),
+    ("    return $list\n", "    return $list\n    puts done\n"),
+    ("proc second {} {", "\nproc second {} {"),
+    ("set a 1; set b 2\n", ""),
+    ("# header comment\n", "# header comment\nset inserted 0\n"),
+    ("lappend ::handlers {second}\n", "lappend ::handlers {second}\nproc third {} {}\n"),
+    ("        c d]", "        c d e]"),
+    ("global mom_pos", "global mom_pos mom_out_angle_pos"),
+])
+def test_incremental_tree_matches_full_parse(old, new):
+    edited = SOURCE.replace(old, new, 1)
+    assert edited != SOURCE
+    previous = (SOURCE, *_parse(SOURCE))
+    result = reparse(*previous, edited, _parse)
+    assert result is not None
+    expected = _parse(edited)
+    assert _differences(result[0], expected[0]) is None
+    assert _violations(result[1]) == _violations(expected[1])
+
+
+def test_continuation_across_the_edit_forces_full_parse():
+    edited = SOURCE.replace("set a 1; set b 2", "set a 1; set b 2 \\")
+    assert reparse(SOURCE, *_parse(SOURCE), edited, _parse) is None
+
+
+def test_quote_closing_outside_the_edit_is_left_to_the_full_parse():
+    edited = SOURCE.replace("set a 1; set b 2", 'set a "1; set b 2')
+    try:
+        result = reparse(SOURCE, *_parse(SOURCE), edited, _parse)
+    except TclSyntaxError:
+        result = None
+    assert result is None
+
+
+def test_unchanged_commands_are_reused_and_never_mutated():
+    tree, violations = _parse(SOURCE)
+    edited = SOURCE.replace("return $list", "return [lsort $list]")
+    new_tree, _ = reparse(SOURCE, tree, violations, edited, _parse)
+    assert new_tree.children[0] is tree.children[0]
+    # Commands after the edit are shifted copies; the old tree stays valid.
+    inserted = SOURCE.replace("proc first", "\n\nproc first")
+    shifted_tree, _ = reparse(SOURCE, tree, violations, inserted, _parse)
+    assert shifted_tree.children[-1] is not tree.children[-1]
+    assert shifted_tree.children[-1].line == tree.children[-1].line + 2
+    assert tree.children[-1].line == _parse(SOURCE)[0].children[-1].line
+
+
+def test_server_reparses_edits_incrementally(tmp_path, monkeypatch):
+    server = TclLanguageServer(name="incremental-test", version="1", max_workers=1)
+    uri = (tmp_path / "edit.tcl").as_uri()
+    first = server.get_tree(TextDocument(uri=uri, source=SOURCE, version=1, language_id="tcl"))
+
+    parsed_sources = []
+    parse_source = server._parse_source
+    monkeypatch.setattr(server, "_parse_source", lambda text, pos=None: parsed_sources.append(text) or parse_source(text, pos))
+    server.clear_cache_for_uri(uri)
+    edited = SOURCE.replace("return $list", "return [lsort $list]")
+    second = server.get_tree(TextDocument(uri=uri, source=edited, version=2, language_id="tcl"))
+
+    assert parsed_sources and all(text != edited for text in parsed_sources)
+    assert second.children[0] is first.children[0]
+    assert _differences(second, _parse(edited)[0]) is None

server/tests/python_tests/test_index_cache.py

@@ -0,0 +1,109 @@
+import os
+import sys
+from pathlib import Path
+
+THIS_DIR = Path(__file__).parent
+SRC_DIR = THIS_DIR.parent.parent / "src"
+if str(SRC_DIR) not in sys.path:
+    sys.path.insert(0, str(SRC_DIR))
+
+import tools.index_cache as index_cache  # noqa: E402
+from lsp_tclserver import TclLanguageServer  # noqa: E402
+from pygls.workspace.text_document import TextDocument  # noqa: E402
+from tools.index_cache import IndexCache  # noqa: E402
+
+
+def _index_from_disk(server, path: Path) -> bool:
+    return server.update_poco_completion_for_file(
+        TextDocument(uri=path.as_uri(), language_id="tcl"),
+        cache_tree=False,
+        require_file_exists=True,
+        from_disk=True,
+    )
+
+
+def _warm_server(cache_dir: Path) -> TclLanguageServer:
+    server = TclLanguageServer(name="cache-test", version="1", max_workers=1)
+    server.index_cache = IndexCache.load(cache_dir)
+    return server
+
+
+def _fail_build(*_args, **_kwargs):
+    raise AssertionError("file was parsed although it is cached")
+
+
+def test_second_start_uses_cached_index(tmp_path: Path, monkeypatch):
+    source = tmp_path / "post.tcl"
+    source.write_text("proc cached_proc {a b} { return $a }\n", encoding="utf-8")
+    cache_dir = tmp_path / "storage"
+
+    server = _warm_server(cache_dir)
+    assert _index_from_disk(server, source)
+    server.index_cache.save()
+
+    restarted = _warm_server(cache_dir)
+    monkeypatch.setattr(restarted, "_build_file_index", _fail_build)
+    assert _index_from_disk(restarted, source)
+    assert "cached_proc" in restarted.custom_function_names_snapshot()
+    assert restarted.proc_metadata_snapshot(str(source))[0]["cached_proc"] == ["a", "b"]
+
+
+def test_changed_file_is_parsed_again(tmp_path: Path):
+    source = tmp_path / "post.tcl"
+    source.write_text("proc old_proc {} {}\n", encoding="utf-8")
+    cache_dir = tmp_path / "storage"
+    server = _warm_server(cache_dir)
+    assert _index_from_disk(server, source)
+    server.index_cache.save()
+
+    source.write_text("proc new_proc {} {}\n", encoding="utf-8")
+    stat = source.stat()
+    os.utime(source, ns=(stat.st_atime_ns, stat.st_mtime_ns + 1_000_000_000))
+    restarted = _warm_server(cache_dir)
+    assert _index_from_disk(restarted, source)
+    names = restarted.custom_function_names_snapshot()
+    assert "new_proc" in names and "old_proc" not in names
+
+
+def test_code_change_discards_the_cache(tmp_path: Path, monkeypatch):
+    source = tmp_path / "post.tcl"
+    source.write_text("proc cached_proc {} {}\n", encoding="utf-8")
+    cache_dir = tmp_path / "storage"
+    server = _warm_server(cache_dir)
+    assert _index_from_disk(server, source)
+    server.index_cache.save()
+
+    # E.g. an updated tclint: a different fingerprint must not load old entries.
+    monkeypatch.setattr(index_cache, "code_fingerprint", lambda: "other tclint")
+    restarted = _warm_server(cache_dir)
+    built = []
+    build = restarted._build_file_index
+    monkeypatch.setattr(restarted, "_build_file_index", lambda *args: built.append(args) or build(*args))
+    assert _index_from_disk(restarted, source)
+    assert built
+
+
+def test_damaged_cache_is_ignored(tmp_path: Path, monkeypatch):
+    cache_dir = tmp_path / "storage"
+    cache_dir.mkdir()
+    (cache_dir / index_cache.CACHE_FILE).write_bytes(b"not a cache")
+    source = tmp_path / "post.tcl"
+    source.write_text("proc fresh_proc {} {}\n", encoding="utf-8")
+
+    server = _warm_server(cache_dir)
+    assert _index_from_disk(server, source)
+    server.index_cache.save()
+
+    restarted = _warm_server(cache_dir)
+    monkeypatch.setattr(restarted, "_build_file_index", _fail_build)
+    assert _index_from_disk(restarted, source)
+
+
+def test_open_documents_never_touch_the_cache(tmp_path: Path):
+    source = tmp_path / "post.tcl"
+    source.write_text("proc on_disk {} {}\n", encoding="utf-8")
+    server = _warm_server(tmp_path / "storage")
+    unsaved = TextDocument(uri=source.as_uri(), source="proc unsaved {} {}\n", version=3, language_id="tcl")
+    assert server.update_poco_completion_for_file(unsaved)
+    server.index_cache.save()
+    assert not (tmp_path / "storage" / index_cache.CACHE_FILE).exists()

server/tests/python_tests/test_index_stability.py

@@ -267,3 +267,35 @@ def test_variable_and_workspace_request_caches_are_reused(tmp_path: Path):
     assert first_completions is second_completions
     assert first_names is second_names
     assert "cached_proc" in first_names
+
+
+def test_navigation_definitions_are_cached_until_the_index_changes(tmp_path: Path):
+    server = _server()
+    first = _document(tmp_path / "first.tcl", "proc first_proc {} {}")
+    assert server.update_poco_completion_for_file(first)
+
+    indexes, definitions = server.navigation_state()
+    assert server.navigation_state()[1] is definitions
+    assert {identity.name for identity in definitions} >= {"::first_proc"}
+
+    second = _document(tmp_path / "second.tcl", "proc second_proc {} {}")
+    assert server.update_poco_completion_for_file(second)
+    indexes, definitions = server.navigation_state()
+    assert second.path in indexes
+    assert {identity.name for identity in definitions} >= {"::first_proc", "::second_proc"}
+
+
+def test_background_parse_does_not_wait_for_the_request_parser(tmp_path: Path):
+    server = _server()
+    document = _document(tmp_path / "background.tcl", "proc background_proc {} {}")
+    finished = Event()
+
+    def index():
+        assert server.update_poco_completion_for_file(document, cache_tree=False)
+        finished.set()
+
+    with server._parser_lock:
+        with ThreadPoolExecutor(max_workers=1) as executor:
+            executor.submit(index)
+            assert finished.wait(timeout=5)
+    assert "background_proc" in server.custom_function_names_snapshot()

server/tests/python_tests/test_psc_classes.py

@@ -0,0 +1,131 @@
+from pathlib import Path
+
+import lsprotocol.types as lsp
+from pygls.workspace import Workspace
+from pygls.workspace.text_document import TextDocument
+
+import lsp_server
+from lsp_tclserver import TclLanguageServer
+from tools.file_sourcing import psc_script_files
+from tools.tcloo_completion import tcloo_completions
+from tools.semantic_tokens import TOKEN_TYPE_INDEX
+
+
+CLASS = '''oo::class create MCS {
+    method initOrg {dx dy dz} {return [self]}
+    method toStr {{precision 7}} {}
+}
+proc helper {value} {}
+'''
+
+
+def setup_project(tmp_path, monkeypatch):
+    root = tmp_path / "project"
+    root.mkdir()
+    library = tmp_path / "external library"
+    library.mkdir()
+    script = library / "geometry.tcl"
+    script.write_text(CLASS, encoding="utf-8")
+    psc = root / "post.psc"
+    psc.write_text('''<Post><Layer Name="Geometry" SubFolder="../external library">
+      <Scripts><Filename Name="geometry" /></Scripts>
+    </Layer></Post>''', encoding="utf-8")
+    server = TclLanguageServer(name="psc-test", version="1")
+    server.protocol._workspace = Workspace(root_uri=root.as_uri(), sync_kind=lsp.TextDocumentSyncKind.Incremental,
+                                          workspace_folders=[], position_encoding=lsp.PositionEncodingKind.Utf16)
+    monkeypatch.setattr(lsp_server, "LSP_SERVER", server)
+    return server, root, psc, script
+
+
+def caller(server, root, source):
+    uri = (root / "caller.tcl").as_uri()
+    server.clear_cache_for_uri(uri)
+    server.workspace.put_text_document(lsp.TextDocumentItem(uri=uri, language_id="tcl", version=1, text=source))
+    return uri, lsp.Position(line=len(source.splitlines()) - 1, character=len(source.splitlines()[-1]))
+
+
+def test_psc_external_class_available_in_all_language_features(tmp_path, monkeypatch):
+    server, root, _, script = setup_project(tmp_path, monkeypatch)
+    lsp_server._refresh_psc_index()
+    assert any(server.paths_equal(script, path) for path in server.class_indexes)
+    assert {"MCS", "helper"} <= {item.label for item in server.completion_items_snapshot()}
+
+    uri, position = caller(server, root, "set mcs [MCS new]\n$mcs ")
+    result = lsp_server.on_completion(lsp.CompletionParams(text_document=lsp.TextDocumentIdentifier(uri=uri), position=position))
+    assert {"initOrg", "toStr"} <= {item.label for item in result.items}
+
+    uri, position = caller(server, root, "set mcs [MCS new]\n$mcs initOrg 1 ")
+    result = lsp_server.signature_help(lsp.SignatureHelpParams(text_document=lsp.TextDocumentIdentifier(uri=uri), position=position))
+    assert result.signatures[0].label == "::MCS initOrg dx dy dz"
+    assert result.active_parameter == 1
+
+    uri, _ = caller(server, root, "set mcs [MCS new]\n$mcs initOrg 1 2 3")
+    monkeypatch.setattr(lsp_server, "_get_settings_by_document", lambda doc: {"inlayHint": True})
+    hints = lsp_server.inlay_hints(lsp.InlayHintParams(text_document=lsp.TextDocumentIdentifier(uri=uri), range=lsp.Range(
+        start=lsp.Position(line=0, character=0), end=lsp.Position(line=2, character=0))))
+    assert [hint.label[0].value for hint in hints] == ["dx:", "dy:", "dz:"]
+    tokens = lsp_server.semantic_tokens(lsp.SemanticTokensParams(text_document=lsp.TextDocumentIdentifier(uri=uri))).data
+    assert TOKEN_TYPE_INDEX["class"] in tokens[3::5]
+
+    uri, position = caller(server, root, "set mcs [MC")
+    result = lsp_server.on_completion(lsp.CompletionParams(text_document=lsp.TextDocumentIdentifier(uri=uri), position=position))
+    assert any(item.label == "MCS" and item.kind == lsp.CompletionItemKind.Class for item in result.items)
+
+
+def test_psc_refresh_removes_unlinked_external_classes(tmp_path, monkeypatch):
+    server, root, psc, script = setup_project(tmp_path, monkeypatch)
+    server.refresh_psc_scripts([root])
+    psc.write_text("<Post/>", encoding="utf-8")
+    lsp_server.did_change_watched_files(lsp.DidChangeWatchedFilesParams(changes=[
+        lsp.FileEvent(uri=psc.as_uri(), type=lsp.FileChangeType.Changed)]))
+    assert "::MCS" not in server.class_snapshot(root / "caller.tcl")
+    assert not any(server.paths_equal(script, path) for path in server.class_indexes)
+    assert "MCS" not in {item.label for item in server.completion_items_snapshot()}
+
+
+def test_class_metadata_updates_and_local_override_does_not_mutate_index(tmp_path, monkeypatch):
+    server, root, _, script = setup_project(tmp_path, monkeypatch)
+    server.refresh_psc_scripts([root])
+    classes = server.class_snapshot(root / "caller.tcl")
+    source = "oo::class create MCS {method local {} {}}\nset mcs [MCS new]\n$mcs "
+    items = tcloo_completions(source.splitlines(), lsp.Position(line=2, character=5), classes)
+    assert {item.label for item in items} == {"local", "destroy"}
+    assert "local" not in classes["::MCS"].methods
+    document = TextDocument(uri=script.as_uri(), source="oo::class create MCS {method changed {} {}}", version=2)
+    assert server.update_poco_completion_for_file(document)
+    assert set(server.class_snapshot(root / "caller.tcl")["::MCS"].methods) == {"changed"}
+    server.remove_file_state(script.as_uri())
+    assert "::MCS" not in server.class_snapshot(root / "caller.tcl")
+
+
+def test_psc_load_order_missing_files_and_xml_namespace(tmp_path, monkeypatch):
+    server, root, psc, script = setup_project(tmp_path, monkeypatch)
+    override = root / "override.tcl"
+    override.write_text("oo::class create MCS {method override {} {}}", encoding="utf-8")
+    psc.write_text(f'''<Post xmlns="urn:psc">
+      <Layer Name="Base" SubFolder="..\\external library"><Scripts><Filename Name="geometry.tcl"/></Scripts></Layer>
+      <Layer Name="Custom"><Scripts><Filename Name="{override.as_posix()}"/><Filename Name="missing.tcl"/></Scripts></Layer>
+    </Post>''', encoding="utf-8")
+    assert psc_script_files(psc) == [script, override, root / "missing.tcl"]
+    messages = []
+    server.refresh_psc_scripts([root], messages.append)
+    assert set(server.class_snapshot(root / "caller.tcl")["::MCS"].methods) == {"override"}
+    assert any("missing.tcl" in message for message in messages)
+
+
+def test_psc_refresh_preserves_unsaved_open_library(tmp_path, monkeypatch):
+    server, root, _, script = setup_project(tmp_path, monkeypatch)
+    server.workspace.put_text_document(lsp.TextDocumentItem(uri=script.as_uri(), language_id="tcl", version=3,
+        text="oo::class create MCS {method unsaved {} {}}"))
+    server.refresh_psc_scripts([root])
+    assert set(server.class_snapshot(root / "caller.tcl")["::MCS"].methods) == {"unsaved"}
+
+
+def test_psc_environment_folder_and_legacy_encoding(tmp_path, monkeypatch):
+    server, root, psc, script = setup_project(tmp_path, monkeypatch)
+    monkeypatch.setenv("UGII_CAM_SHOP_DOC_DIR", str(script.parent))
+    psc.write_text('''<Post><Layer SubFolder="UGII_CAM_SHOP_DOC_DIR">
+      <Scripts><Filename Name="geometry"/></Scripts></Layer></Post>''', encoding="utf-8")
+    script.write_bytes(("# Ältere Bibliothek\n" + CLASS).encode("cp1252"))
+    server.refresh_psc_scripts([root])
+    assert "::MCS" in server.class_snapshot(root / "caller.tcl")

server/tests/python_tests/test_tcloo_arguments.py

@@ -0,0 +1,118 @@
+import lsprotocol.types as lsp
+import pytest
+
+from tools.inlay_hint import InlayHintGenerator
+from tools.parser import CustomParser
+from tools.tcloo_arguments import method_parameters, method_signature_help
+
+
+CLASS = """oo::class create MCS {
+    constructor {name {size 3}} {}
+    method initValue {i value} {return [self]}
+    method format {value {precision 7}} {}
+    method many {first args} {}
+    method empty {} {}
+    method internal {} {my initValue 0 10}
+}
+"""
+
+
+def signature(source):
+    prefix, suffix = source.split("|")
+    position = lsp.Position(line=prefix.count("\n"), character=len(prefix.rsplit("\n", 1)[-1].encode("utf-16-le")) // 2)
+    return method_signature_help(prefix + suffix, position)
+
+
+@pytest.mark.parametrize("tail, label, active", [
+    ("set mcs [MCS new test]\n$mcs initValue |", "::MCS initValue i value", 0),
+    ("set mcs [MCS new test]\n$mcs initValue 0 |", "::MCS initValue i value", 1),
+    ("set mcs [MCS new test]\n$mcs format 12 |", "::MCS format value {precision 7}", 1),
+    ("set mcs [MCS new test]\n$mcs many 1 2 3 |", "::MCS many first args", 1),
+    ("set mcs [MCS new test]\n$mcs empty |", "::MCS empty", None),
+    ("MCS create instance test\ninstance initValue 0 |", "::MCS initValue i value", 1),
+    ("set mcs [[MCS new test] initValue 0 0]\n$mcs initValue |", "::MCS initValue i value", 0),
+    ("set mcs [MCS new test]\nputs [$mcs initValue 0 |", "::MCS initValue i value", 1),
+    ("set mcs [MCS new |", "::MCS new name {size 3}", 0),
+    ("MCS create instance |", "::MCS create objectName name {size 3}", 1),
+    ("set mcs [MCS new test]\nputs 😀; $mcs initValue 0 |", "::MCS initValue i value", 1),
+])
+def test_method_signatures(tail, label, active):
+    result = signature(CLASS + tail)
+    assert result is not None
+    assert result.signatures[0].label == label
+    assert result.active_parameter == active
+
+
+def test_my_signature_and_parameter_spans():
+    result = signature(CLASS.replace("my initValue 0 10", "my initValue 0 |"))
+    assert result.active_parameter == 1
+    info = result.signatures[0]
+    assert [info.label[start:end] for start, end in (p.label for p in info.parameters)] == ["i", "value"]
+
+
+@pytest.mark.parametrize("tail", [
+    "$unknown initValue |",
+    "set mcs [MCS new test]\nset mcs text\n$mcs initValue |",
+    "set mcs [MCS new test]\n$mcs initValue [unknown |] 3",
+    "set mcs [MCS new test]\n$mcs initValue|",
+])
+def test_unknown_receivers_and_nested_commands(tail):
+    assert signature(CLASS + tail) is None
+
+
+def test_optional_parameter_with_spaced_default():
+    parameters = method_parameters('value {description {hello world}} args')
+    assert [p.name for p in parameters] == ["value", "description", "args"]
+    assert parameters[1].label == "{description {hello world}}"
+    assert parameters[-1].variadic
+
+
+def test_method_inlay_hints_and_existing_preferences():
+    source = CLASS + "set mcs [MCS new test]\n$mcs initValue 0 10\n$mcs many 1 2 3\n$mcs initValue $i $other"
+    tree = CustomParser().parse(source)
+    start = len(CLASS.splitlines()) + 1
+    requested = lsp.Range(start=lsp.Position(line=start, character=0), end=lsp.Position(line=start + 2, character=100))
+    generator = InlayHintGenerator(source, {}, requested_range=requested)
+    hints = generator.generate(tree)
+    assert [hint.label[0].value for hint in hints] == ["i:", "value:", "first:", "args:", "args:", "value:"]
+    assert [source.splitlines()[hint.position.line][hint.position.character:] for hint in hints[:2]] == ["0 10", "10"]
+    assert "::MCS initValue i value" in hints[0].tooltip.value
+    generator = InlayHintGenerator(source, {}, requested_range=requested, parameter_names="literals")
+    assert len(generator.generate(tree)) == 5
+    generator = InlayHintGenerator(source, {}, parameter_names="none")
+    assert generator.generate(tree) == []
+
+
+def test_lsp_signature_help_with_unfinished_bracket(tmp_path, monkeypatch):
+    import lsp_server
+    from test_completion_context import _completion_server
+
+    server, document, _ = _completion_server(tmp_path, monkeypatch)
+    source = CLASS + "set mcs [MCS new test]\nputs [$mcs initValue 0 "
+    document = server.workspace.get_text_document(document.uri)
+    document._source = source
+    document.version = 2
+    result = lsp_server.signature_help(lsp.SignatureHelpParams(
+        text_document=lsp.TextDocumentIdentifier(uri=document.uri),
+        position=lsp.Position(line=len(source.splitlines()) - 1, character=len(source.splitlines()[-1])),
+    ))
+    assert result.active_parameter == 1
+    assert result.signatures[0].label == "::MCS initValue i value"
+
+
+def test_cached_tree_gives_same_signature_without_reparsing(monkeypatch):
+    import tools.tcloo_completion as tcloo
+
+    source = CLASS + "set mcs [MCS new test]\n$mcs initValue 0 "
+    position = lsp.Position(line=source.count("\n"), character=len(source.rsplit("\n", 1)[-1]))
+    expected = method_signature_help(source, position)
+    tree = CustomParser().parse(source)
+    parse_body = tcloo.parse_completion_source
+
+    def parse(text, pos=None):
+        # Braced class bodies are still parsed on demand, the document is not.
+        assert text != source, "unexpected full-document parse"
+        return parse_body(text, pos)
+
+    monkeypatch.setattr(tcloo, "parse_completion_source", parse)
+    assert method_signature_help(source, position, tree=tree) == expected

server/tests/python_tests/test_tcloo_completion.py

@@ -0,0 +1,231 @@
+import lsprotocol.types as lsp
+import pytest
+
+from tools.tcloo_completion import ClassInfo, tcloo_completions
+
+
+CLASS = """oo::class create MCS {
+    constructor {} {my initValue 0 0}
+    method initValue {i value} {return [self]}
+    method initOrg {x y z} {return [my initValue 0 $x]}
+    method toLst {} {return {1 2 3}}
+    method _private {} {return [self]}
+}
+"""
+
+
+def complete(source):
+    offset = source.index("|")
+    before = source[:offset]
+    position = lsp.Position(line=before.count("\n"), character=len(before.rsplit("\n", 1)[-1].encode("utf-16-le")) // 2)
+    return tcloo_completions(source.replace("|", "").splitlines(), position)
+
+
+@pytest.mark.parametrize("code", [
+    "set mcs [MCS new]\n$mcs |",
+    "set mcs [::MCS new]\n$mcs |",
+    "MCS create instance\ninstance |",
+    "set mcs [MCS create instance]\n$mcs |",
+    "set mcs [[MCS new] initValue 0 0]\n$mcs |",
+    "set mcs [[MCS new] initOrg 1 2 3]\n$mcs |",
+    "set a [MCS new]\nset mcs $a\n$mcs |",
+    "proc run {} {set mcs [MCS new]; $mcs |}",
+    "set mcs [MCS new]\nputs [$mcs |]",
+    "set mcs [MCS new]\nputs [$mcs |",
+    "[MCS new] |",
+])
+def test_instances_and_chains(code):
+    items = complete(CLASS + code)
+    assert {item.label for item in items} == {"initValue", "initOrg", "toLst", "destroy"}
+    assert next(item for item in items if item.label == "initValue").detail == "::MCS initValue i value"
+
+
+def test_my_and_constructor():
+    for source in [CLASS.replace("my initValue 0 0", "my |"), CLASS.replace("return {1 2 3}", "my |")]:
+        assert "_private" in {item.label for item in complete(source)}
+
+
+@pytest.mark.parametrize("code", [
+    "set mcs [MCS new]\nset mcs text\n$mcs |",
+    "set mcs [MCS new]\nunset mcs\n$mcs |",
+    "proc a {} {set mcs [MCS new]}\nproc b {} {$mcs |}",
+    "set mcs [MCS new]\nproc b {mcs} {$mcs |}",
+    "set mcs [[MCS new] toLst]\n$mcs |",
+    "$mcs |\nset mcs [MCS new]",
+    "set mcs [MCS new]\n$mcs initValue |",
+    "# my |",
+    "puts {my |}",
+])
+def test_unknown_and_non_command_contexts(code):
+    assert complete(CLASS + code) is None
+
+
+def test_prefix_and_replacement():
+    items = complete(CLASS + "set mcs [MCS new]\n$mcs initV|alue")
+    assert [item.label for item in items] == ["initValue"]
+    assert items[0].text_edit.new_text == "initValue"
+    assert items[0].text_edit.range.start.character == 5
+    assert items[0].text_edit.range.end.character == 14
+
+
+def test_namespace():
+    source = "namespace eval geometry {\n" + CLASS + "set mcs [MCS new]\n$mcs |\n}"
+    assert "initOrg" in {item.label for item in complete(source)}
+
+
+def test_lsp_space_trigger(tmp_path, monkeypatch):
+    import lsp_server
+    from test_completion_context import _completion_server
+
+    server, document, _ = _completion_server(tmp_path, monkeypatch)
+    source = CLASS + "set mcs [MCS new]\n$mcs "
+    document = server.workspace.get_text_document(document.uri)
+    document._source = source
+    document.version = 2
+    items = lsp_server.on_completion(lsp.CompletionParams(
+        text_document=lsp.TextDocumentIdentifier(uri=document.uri),
+        position=lsp.Position(line=len(source.splitlines()) - 1, character=5),
+        context=lsp.CompletionContext(trigger_kind=lsp.CompletionTriggerKind.TriggerCharacter, trigger_character=" "),
+    )).items
+    assert "initOrg" in {item.label for item in items}
+
+
+@pytest.mark.parametrize("tail", ["set mcs [MC", "set mcs [MC]", "MC"])
+def test_class_name_completion_while_editing(tmp_path, monkeypatch, tail):
+    import lsp_server
+    from test_completion_context import _completion_server
+
+    server, document, _ = _completion_server(tmp_path, monkeypatch)
+    source = CLASS + tail
+    document = server.workspace.get_text_document(document.uri)
+    document._source = source
+    document.version = 2
+    items = lsp_server.on_completion(lsp.CompletionParams(
+        text_document=lsp.TextDocumentIdentifier(uri=document.uri),
+        position=lsp.Position(line=len(source.splitlines()) - 1,
+                              character=len(tail.rstrip("]"))),
+    )).items
+    classes = [item for item in items if item.label == "MCS"]
+    assert len(classes) == 1
+    assert classes[0].kind == lsp.CompletionItemKind.Class
+
+
+def test_classes_are_indexed_with_their_own_kind(tmp_path, monkeypatch):
+    from test_completion_context import _completion_server, _document
+
+    server, _, _ = _completion_server(tmp_path, monkeypatch)
+    assert server.update_poco_completion_for_file(_document(tmp_path / "class.tcl", CLASS))
+    items = server.completion_items_snapshot()
+    assert any(item.label == "MCS" and item.kind == lsp.CompletionItemKind.Class for item in items)
+    assert "MCS" not in server.custom_function_names_snapshot()
+
+
+def test_class_command_completions():
+    assert {item.label for item in complete(CLASS + "set mcs [MCS |]")} == {"new", "create"}
+
+
+def test_semantic_class_declarations_and_uses():
+    from tools.parser import CustomParser
+    from tools.semantic_tokens import _Highlighter, TokenModifier
+
+    source = CLASS + 'set mcs [MCS new]\nset second [::MCS new]\nputs "MCS"\n'
+    tree = CustomParser().parse(source)
+    highlighter = _Highlighter([], {"MCS"})
+    highlighter.highlight_classes(tree)
+    tree.accept(highlighter, recurse=True)
+    line = col = 0
+    classified = []
+    for token in highlighter.tokens():
+        col = col + token.offset if token.line == 0 else token.offset
+        line += token.line
+        text = source.splitlines()[line][col:col + token.length]
+        classified.append((line, col, text, token.tok_type, token.tok_modifiers))
+    classes = [entry for entry in classified if entry[3] == "class"]
+    assert [entry[2] for entry in classes] == ["MCS", "MCS", "::MCS"]
+    assert TokenModifier.declaration in classes[0][4]
+    assert not any(entry[2] in {"MCS", "::MCS"} and entry[3] == "function" for entry in classified)
+    assert len({entry[:2] for entry in classified}) == len(classified)
+
+
+def test_namespaced_class_symbols_and_method_body_references():
+    from tools.parser import CustomParser
+    from tools.tcloo_symbols import class_completion_items, class_symbols
+
+    tree = CustomParser().parse('''namespace eval geometry {
+        oo::class create MCS {
+            method duplicate {} {return [MCS new]}
+        }
+        set mcs [MCS new]
+    }
+    set mcs [geometry::MCS new]
+    set mcs [::geometry::MCS new]
+    ''')
+    declarations, references = class_symbols(tree)
+    assert set(declarations) == {"::geometry::MCS"}
+    assert [node.contents for node in references] == ["MCS", "MCS", "geometry::MCS", "::geometry::MCS"]
+    assert class_completion_items(tree)[0].label == "geometry::MCS"
+
+
+@pytest.mark.parametrize("code", [
+    "set mcs [MCS new]\nputs |",
+    "set mcs [MCS new]\n    se|",
+    "set mcs [MCS new]\nMOM_output_literal |",
+])
+def test_non_receivers_skip_the_completion_reparse(code, monkeypatch):
+    import tools.tcloo_completion as tcloo
+
+    def fail(*_args, **_kwargs):
+        raise AssertionError("unexpected full-document parse")
+
+    monkeypatch.setattr(tcloo, "parse_completion_source", fail)
+    assert complete(CLASS + code) is None
+
+
+def test_documents_without_classes_skip_the_completion_reparse(monkeypatch):
+    import tools.tcloo_completion as tcloo
+
+    monkeypatch.setattr(tcloo, "parse_completion_source", lambda *_: pytest.fail("parsed"))
+    assert complete("set value [expr 1]\n$value |") is None
+
+
+def test_external_class_receiver_still_completes():
+    source = "Logger |"
+    position = lsp.Position(line=0, character=len(source) - 1)
+    items = tcloo_completions([source.replace("|", "")], position, {"::Logger": ClassInfo()})
+    assert {item.label for item in items} == {"new", "create"}
+
+
+def complete_with_tree(source):
+    from tclint.lexer import TclSyntaxError
+    from tools.parser import CustomParser
+
+    offset = source.index("|")
+    before = source[:offset]
+    position = lsp.Position(line=before.count("\n"), character=len(before.rsplit("\n", 1)[-1].encode("utf-16-le")) // 2)
+    text = source.replace("|", "")
+    try:
+        tree = CustomParser().parse(text)
+    except TclSyntaxError:
+        tree = None
+    return tcloo_completions(text.splitlines(), position, current_tree=lambda: tree)
+
+
+@pytest.mark.parametrize("code", [
+    "set mcs [MCS new]\n$mcs |",
+    "MCS create instance\ninstance |",
+    "set mcs [[MCS new] initOrg 1 2 3]\n$mcs |",
+    "proc run {} {set mcs [MCS new]; $mcs |}",
+    "set mcs [MCS new]\nputs [$mcs |]",
+    "set mcs [MCS new]\nputs [$mcs |",
+    "[MCS new] |",
+    "set mcs [MCS new]\n$mcs initV|alue",
+])
+def test_cached_tree_keeps_method_completions(code):
+    assert "initValue" in {item.label for item in complete_with_tree(CLASS + code)}
+
+
+def test_cached_tree_skips_reparse_outside_first_argument(monkeypatch):
+    import tools.tcloo_completion as tcloo
+
+    monkeypatch.setattr(tcloo, "parse_completion_source", lambda *_: pytest.fail("parsed"))
+    assert complete_with_tree(CLASS + "set mcs [MCS new]\nif {$mcs ne {}} |{ puts 1 }") is None

server/tests/python_tests/test_tcloo_highlighting.py

@@ -0,0 +1,56 @@
+import lsprotocol.types as lsp
+
+from tools.parser import CustomParser
+from tools.semantic_tokens import _Highlighter, TOKEN_TYPE_INDEX, TokenModifier
+
+
+def test_methods_use_proc_colors_without_coloring_plain_arguments():
+    source = '''oo::class create MCS {
+    method initOrg {x y z} {return [self]}
+    method reset {} {my initOrg 0 0 0}
+}
+set obj [MCS new]
+$obj initOrg 1 2 3
+puts initOrg
+# initOrg
+'''
+    tree = CustomParser().parse(source)
+    highlighter = _Highlighter([], {})
+    highlighter.highlight_classes(tree)
+    highlighter.highlight_methods(tree, source, "file:///test.tcl")
+    tree.accept(highlighter, recurse=True)
+    line = column = 0
+    tokens = []
+    for token in highlighter.tokens():
+        column = column + token.offset if token.line == 0 else token.offset
+        line += token.line
+        text = source.splitlines()[line][column:column + token.length]
+        tokens.append((line, column, text, token.tok_type, token.tok_modifiers))
+    methods = [token for token in tokens if token[2] in {"initOrg", "reset"}]
+    assert [token[2] for token in methods] == ["initOrg", "reset", "initOrg", "initOrg"]
+    assert all(token[3] == "function" for token in methods)
+    assert TokenModifier.declaration in methods[0][4]
+    assert TokenModifier.declaration in methods[1][4]
+    assert all(token[3] == "class" for token in tokens if token[2] == "MCS")
+    assert len({token[:2] for token in tokens}) == len(tokens)
+
+
+def test_psc_method_calls_are_function_tokens(tmp_path, monkeypatch):
+    import lsp_server
+    from test_psc_classes import setup_project, caller
+
+    server, root, _, _ = setup_project(tmp_path, monkeypatch)
+    server.refresh_psc_scripts([root])
+    source = "set obj [MCS new]\n$obj initOrg 1 2 3"
+    uri, _ = caller(server, root, source)
+    data = lsp_server.semantic_tokens(lsp.SemanticTokensParams(
+        text_document=lsp.TextDocumentIdentifier(uri=uri))).data
+    line = column = 0
+    tokens = {}
+    for index in range(0, len(data), 5):
+        delta, offset, length, kind, _ = data[index:index + 5]
+        column = column + offset if delta == 0 else offset
+        line += delta
+        tokens[(line, source.splitlines()[line][column:column + length])] = kind
+    assert tokens[(1, "initOrg")] == TOKEN_TYPE_INDEX["function"]
+    assert tokens[(0, "MCS")] == TOKEN_TYPE_INDEX["class"]

server/tests/python_tests/test_tcloo_navigation.py

@@ -0,0 +1,94 @@
+import lsprotocol.types as lsp
+import pytest
+from pygls import uris
+
+from tools.tcloo_navigation import tcloo_definition
+
+
+CLASS = '''oo::class create MCS {
+    constructor {value} {}
+    method initOrg {dx dy dz} {return [self]}
+    method toStr {} {my initOrg 1 2 3}
+}
+'''
+
+
+def locate(source, classes=None):
+    prefix, suffix = source.split("|")
+    return tcloo_definition(prefix + suffix, "file:///caller.tcl", lsp.Position(
+        line=prefix.count("\n"),
+        character=len(prefix.rsplit("\n", 1)[-1].encode("utf-16-le")) // 2), classes)
+
+
+def target_text(location, source):
+    assert location is not None
+    span = location.range
+    line = source.splitlines()[span.start.line].encode("utf-16-le")
+    return line[span.start.character * 2:span.end.character * 2].decode("utf-16-le")
+
+
+@pytest.mark.parametrize("code, expected", [
+    ("set mcs [M|CS new 0]", "MCS"),
+    ("set mcs [::M|CS new 0]", "MCS"),
+    ("set mcs [MCS n|ew 0]", "constructor"),
+    ("MCS cr|eate instance 0", "constructor"),
+    ("set mcs [MCS new 0]\n$mcs init|Org 1 2 3", "initOrg"),
+    ("MCS create instance 0\ninstance to|Str", "toStr"),
+    ("set mcs [[MCS new 0] initOrg 1 2 3]\n$mcs to|Str", "toStr"),
+    ("set mcs [MCS new 0]\nputs [$mcs init|Org", "initOrg"),
+    ("puts 😀; set mcs [M|CS new 0]", "MCS"),
+])
+def test_local_class_method_and_constructor_targets(code, expected):
+    source = CLASS + code
+    target = locate(source)
+    assert target.uri == "file:///caller.tcl"
+    assert target_text(target, source.replace("|", "")) == expected
+
+
+def test_my_and_method_declaration():
+    for source in [CLASS.replace("my initOrg", "my init|Org"), CLASS.replace("method initOrg", "method init|Org")]:
+        assert target_text(locate(source), CLASS) == "initOrg"
+
+
+@pytest.mark.parametrize("code", [
+    "set mcs [MCS new 0]\nset mcs text\n$mcs init|Org 1 2 3",
+    "$unknown init|Org 1 2 3",
+    "puts {M|CS}",
+    "# M|CS",
+    "set mcs [MCS new 0]\n$mcs initOrg to|Str 2 3",
+])
+def test_no_guessing_for_unknown_receivers_or_plain_text(code):
+    assert locate(CLASS + code) is None
+
+
+def test_same_method_name_resolves_to_correct_class():
+    source = CLASS + "oo::class create Other {method initOrg {} {}}\nset obj [Other new]\n$obj init|Org"
+    target = locate(source)
+    assert target.range.start.line == 5
+
+
+def test_namespaced_class_and_utf16_definition():
+    source = 'namespace eval geo {\nputs 😀; ' + CLASS + '\nset obj [MCS new 0]\n$obj init|Org 1 2 3\n}'
+    assert target_text(locate(source), source.replace("|", "")) == "initOrg"
+    source = 'puts 😀; ' + CLASS + '\nset obj [M|CS new 0]'
+    target = locate(source)
+    assert target_text(target, source.replace("|", "")) == "MCS"
+
+
+def test_psc_definition_navigation_uses_library_uri(tmp_path, monkeypatch):
+    import lsp_server
+    from test_psc_classes import setup_project, caller, CLASS as LIBRARY_SOURCE
+
+    server, root, _, script = setup_project(tmp_path, monkeypatch)
+    server.refresh_psc_scripts([root])
+    for word, source in [
+        ("MCS", "set obj [MCS new]"),
+        ("initOrg", "set obj [MCS new]\n$obj initOrg 1 2 3"),
+    ]:
+        uri, _ = caller(server, root, source)
+        lines = source.splitlines()
+        position = lsp.Position(line=len(lines) - 1, character=lines[-1].index(word) + 1)
+        result = lsp_server.goto_definition(lsp.DefinitionParams(text_document=lsp.TextDocumentIdentifier(uri=uri), position=position))
+        assert result is not None and len(result) == 1
+        assert server.paths_equal(script, uris.to_fs_path(result[0].uri))
+        assert target_text(result[0], LIBRARY_SOURCE) == word

syntaxes/cdl.tmLanguage.json

@@ -2,27 +2,13 @@
 	"$schema": "https://raw.githubusercontent.com/martinring/tmlanguage/master/tmlanguage.json",
 	"name": "CDL Support",
 	"patterns": [
-		{
-			"include": "#comment"
-		},
-		{
-			"include": "#function"
-		},
-		{
-			"include": "#variables"
-		},
-		{
-			"include": "#types"
-		},
-		{
-			"include": "#keywords"
-		},
-		{
-			"include": "#numbers"
-		},
-		{
-			"include": "#strings"
-		}
+		{ "include": "#comment" },
+		{ "include": "#function" },
+		{ "include": "#variables" },
+		{ "include": "#types" },
+		{ "include": "#keywords" },
+		{ "include": "#numbers" },
+		{ "include": "#strings" }
 	],
 	"repository": {
 		"keywords": {
@@ -70,11 +56,7 @@
 				{
 					"name": "keyword.control.cdl",
 					"match": "TYPE\\s+(o|g|i|d|b|s)\\b",
-					"captures": {
-						"1": {
-							"name": "storage.type.cs"
-						}
-					}
+					"captures": { "1": { "name": "storage.type.cs" } }
 				}
 			]
 		},
@@ -83,38 +65,22 @@
 				{
 					"name": "keyword.control.cdl",
 					"match": "\\b(PARAM|EVENT)\\s+([a-zA-Z_]\\w*)\\b",
-					"captures": {
-						"2": {
-							"name": "variable.other.cdl"
-						}
-					}
+					"captures": { "2": { "name": "variable.other.cdl" } }
 				},
 				{
 					"name": "keyword.control.cdl",
 					"match": "\\bMACHINE\\s+([a-zA-Z_]\\w*)\\b",
-					"captures": {
-						"1": {
-							"name": "variable.other.cdl"
-						}
-					}
+					"captures": { "1": { "name": "variable.other.cdl" } }
 				},
 				{
 					"name": "keyword.control.cdl",
-					"match": "\\bCATEGORY\\s+((MILL|LATHE|DRILL)(\\s+(MILL|LATHE|DRILL))*)\\b",
-					"captures": {
-						"1": {
-							"name": "variable.language.cdl"
-						}
-					}
+					"match": "\\bCATEGORY\\s+((MILL|LATHE|DRILL|INVALID)(\\s+(MILL|LATHE|DRILL|INVALID))*)\\b",
+					"captures": { "1": { "name": "variable.language.cdl" } }
 				},
 				{
 					"name": "keyword.control.cdl",
 					"match": "\\bTOGGLE\\s+(OFF|ON|off|on)\\b",
-					"captures": {
-						"1": {
-							"name": "variable.other.constant"
-						}
-					}
+					"captures": { "1": { "name": "variable.other.constant" } }
 				}
 			]
 		},
@@ -123,11 +89,7 @@
 				{
 					"name": "storage.type.function.cdl",
 					"match": "\\bEVENT\\s+([a-zA-Z_]\\w*)\\b",
-					"captures": {
-						"1": {
-							"name": "entity.name.function"
-						}
-					}
+					"captures": { "1": { "name": "entity.name.function" } }
 				}
 			]
 		},

test/cdlEventHandler.test.js

@@ -0,0 +1,51 @@
+const assert = require("node:assert/strict")
+const fs = require("node:fs")
+const path = require("node:path")
+const vm = require("node:vm")
+const { test } = require("node:test")
+const { transformSync } = require("esbuild")
+
+const source = fs.readFileSync(path.join(__dirname, "../client/src/common/cdlEventHandler.ts"), "utf8")
+const compiled = transformSync(source, { loader: "ts", format: "cjs" }).code
+const context = { module: { exports: {} } }
+vm.runInNewContext(compiled, context)
+const { cdlEventHandlerAtLine, createCdlEventHandlerSnippet } = context.module.exports
+
+test("TOGGLE Off adds the defined globals to the event handler", () => {
+    const cdl = `EVENT GDM_header
+{
+    PARAM product_status {
+        TYPE o
+        OPTIONS "Serie", "Prototyp"
+    }
+    PARAM stm_param_mpf_name
+    {
+        TYPE s
+        TOGGLE Off
+    }
+    PARAM stm_param_wks_path {
+        TYPE s
+        TOGGLE Off
+    }
+}`
+    const snippet = createCdlEventHandlerSnippet(cdlEventHandlerAtLine(cdl, 0))
+    assert.match(snippet, /global mom_stm_param_mpf_name_defined/)
+    assert.match(snippet, /global mom_stm_param_wks_path_defined/)
+    assert.match(snippet, /global mom_product_status\n/)
+    assert.doesNotMatch(snippet, /mom_product_status_defined/)
+})
+
+test("toggle detection ignores comments, strings, other events, and TOGGLE On", () => {
+    const cdl = `EVENT first {
+        PARAM plain { TYPE s UI_LABEL "TOGGLE Off { ignored }" }
+        PARAM enabled { TOGGLE On }
+        PARAM commented { TYPE s # TOGGLE Off
+        }
+        PARAM mom_disabled { TOGGLE off }
+    }
+    EVENT second { PARAM other { TOGGLE Off } }`
+    const snippet = createCdlEventHandlerSnippet(cdlEventHandlerAtLine(cdl, 0))
+    assert.match(snippet, /global mom_disabled_defined/)
+    assert.equal((snippet.match(/_defined/g) ?? []).length, 1)
+    assert.doesNotMatch(snippet, /mom_mom_|mom_other/)
+})

test/test.tcl

@@ -6,24 +6,24 @@ set te875st 11111
 #set ::custom_flag(from_move,$::mom_path_name) 1
 
 if {$main == 1 && 1 == 1} {
-    puts "main"
+	puts "main"
 }
 
 proc test {} {
-    puts "main"
-    proc llll {} {}
-    set rrrrrrr
+	puts "main"
+	proc llll {} {}
+	set rrrrrrr
 }
 LIB_GE_command_buffer_edit_insert MOM_tool_change_LIB TOOL_CHANGE_AUTO {CUSTOM_after_tool_change_call} mytag after @TOOL_CHANGE_AUTO
 
 MOM_abort
 
 namespace eval myns {
-    proc add {a b} {
-        set sum [expr {$a + $b}]
-        return $sum
-    }
-    set config "debug"
+	proc add {a b} {
+		set sum [expr {$a + $b}]
+		return $sum
+	}
+	set config "debug"
 }
 
 #_________________________________________________________________________________________________
@@ -31,7 +31,7 @@ namespace eval myns {
 # Function to output a spacer line or empty line
 #_________________________________________________________________________________________________
 proc SERVICE_spacer_output {type {length 20} {line_num 0} {output 1}} {
-    LIB_GE_message [string repeat $type $length] "output_$output" $line_num
+	LIB_GE_message [string repeat $type $length] "output_$output" $line_num
 }
 
 
@@ -42,8 +42,8 @@ SERVICE_spacer_output "*" 2 0 0
 # Function to delete the file
 #_________________________________________________________________________________________________
 proc SERVICE_remove_file {file} {
-    if {![SERVICE_check_file_exists $file]} {return}
-    MOM_remove_file $file
+	if {![SERVICE_check_file_exists $file]} {return}
+	MOM_remove_file $file
 }
 
 #_________________________________________________________________________________________________
@@ -51,8 +51,8 @@ proc SERVICE_remove_file {file} {
 # Function to check if the file exists
 #_________________________________________________________________________________________________
 proc SERVICE_check_file_exists {file} {
-    if {[file exists $file]} {return 1}
-    return 0
+	if {[file exists $file]} {return 1}
+	return 0
 }
 
 #_________________________________________________________________________________________________
@@ -60,19 +60,19 @@ proc SERVICE_check_file_exists {file} {
 # Ask UDE Info for the Tool
 #_________________________________________________________________________________________________
 proc SERVICE_ask_ude_tool {pos ude_name tool_name} {
-    MOM_ask_ude_info $tool_name "tool" $pos
+	MOM_ask_ude_info $tool_name "tool" $pos
 
-    if {[lsearch $::mom_result $ude_name] != -1} {
-        return 1
-    }
-    return 0
+	if {[lsearch $::mom_result $ude_name] != -1} {
+		return 1
+	}
+	return 0
 }
 
 proc MOM_dummy_event_start {} {
-    global mom_new_item
-    global mom_new_item_end
+	global mom_new_item
+	global mom_new_item_end
 
-    #Put your UDE Handler Tcl here
+	#Put your UDE Handler Tcl here
 }
 
 #_________________________________________________________________________________________________
@@ -80,12 +80,12 @@ proc MOM_dummy_event_start {} {
 # Ask UDE Info for the Operation
 #_________________________________________________________________________________________________
 proc SERVICE_ask_ude_operation {pos ude_name path_name} {
-    MOM_ask_ude_info $path_name "operation" $pos
+	MOM_ask_ude_info $path_name "operation" $pos
 
-    if {[lsearch $::mom_result $ude_name] != -1} {
-        return 1
-    }
-    return 0
+	if {[lsearch $::mom_result $ude_name] != -1} {
+		return 1
+	}
+	return 0
 }
 
 #_________________________________________________________________________________________________
@@ -96,7 +96,7 @@ proc SERVICE_ask_ude_operation {pos ude_name path_name} {
 #              restore
 #_________________________________________________________________________________________________
 proc SERVICE_output_handling {handler} {
-    set ::lib_ge(hidden_output) $handler
+	set ::lib_ge(hidden_output) $handler
 }
 
 #_________________________________________________________________________________________________
@@ -105,21 +105,305 @@ proc SERVICE_output_handling {handler} {
 # this function is called in start of program
 #_________________________________________________________________________________________________
 proc SERVICE_get_tool_data {} {
-    global mom_tool_data
-    global mom_operation_info
+	global mom_tool_data
+	global mom_operation_info
 
-    set mom_tool_data(toollist) ""
-    set operations $::mom_operation_name_list
-    foreach operation $operations {
-        if {[lsearch -exact $mom_tool_data(toollist) $mom_operation_info($operation,tool_name)] == -1} {
-            lappend mom_tool_data(toollist) $mom_operation_info($operation,tool_name)
-        }
-    }
+	set mom_tool_data(toollist) ""
+	set operations $::mom_operation_name_list
+	foreach operation $operations {
+		if {[lsearch -exact $mom_tool_data(toollist) $mom_operation_info($operation,tool_name)] == -1} {
+			lappend mom_tool_data(toollist) $mom_operation_info($operation,tool_name)
+		}
+	}
 }
 
 LIB_GE_command_buffer_edit_replace MOM_end_of_program_LIB END_OF_PROGRAM @END_OF_PROG {
-    MOM_do_template "end_of_program_rewind"
+	MOM_do_template "end_of_program_rewind"
 } EndOfProgramRewind
 
 
 SERVICE_remove_file "test"
+
+
+oo::class create MCS {
+	variable values
+
+	constructor {args} {
+		for {set i 0} {$i <= 11} {incr i} {
+			my initValue $i 0.
+		}
+	}
+	destructor {
+		#puts "[self] is now deleted"
+	}
+
+	method fformat {value {precision 7}} {return [expr {round( 10.0 ** $precision * $value) / (10.0 ** $precision)}]}
+	method radtodeg {rad} {return [expr {$rad*180.0/(4.0*atan(1.0))}]}
+	method degtorad {deg} {return [expr {$deg*(4.0*atan(1.0))/180.0}]}
+
+	method duplicate {args} {return [[MCS new] initMCS [self]]}
+	method type {args} {return "::MCS"}
+
+	method toArray {args} {
+		for {set i 0} {$i < [array size values]} {incr i} {
+			append arr [string cat $i " "] ; append arr [string cat $values($i) " "]
+		}
+		return [string trimright $arr]
+	}
+	method toLst {args} {
+		for {set i 0} {$i < [array size values]} {incr i} {
+			lappend lst $values($i)
+		}
+		return $lst
+	}
+	method toStr {args} {
+		for {set i 0} {$i < [array size values]} {incr i} {
+			if {$i>0} {set str [string cat $str ", "]}
+			append str $values($i)
+		}
+		return $str
+	}
+	method toStrF {{precision 7}} {
+		for {set i 0} {$i < [array size values]} {incr i} {
+			if {$i>0} {set str [string cat $str ", "]}
+			append str [my fformat $values($i) 10]
+		}
+		return $str
+	}
+
+	method initValue {i value} {set values($i) [expr double($value)] ; return [self]}
+	method initArray {a} {upvar $a arr ; for {set i 0} {$i < [array size arr]} {incr i} {my initValue $i $arr($i)} ; return [self]}
+	method initArrayLst {arr_lst} {array set arr $arr_lst ; for {set i 0} {$i < [array size arr]} {incr i} {my initValue $i $arr($i)} ; return [self]}
+	method initLst {lst} {for {set i 0} {$i < [llength $lst]} {incr i} {my initValue $i [lindex $lst $i]} ; return [self]}
+
+	method initMCS {mcs} {
+		my identity
+		set p [$mcs org] ; my initOrgP $p ; $p destroy
+		set v [$mcs xVct] ; my initXvctV $v ; $v destroy
+		set v [$mcs yVct] ; my initYvctV $v ; $v destroy
+		set v [$mcs zVct] ; my initZvctV $v ; $v destroy
+		return [self]
+	}
+	method initMTX {mtx} {
+		set p [$mtx org] ; my initOrg $p ; $p destroy
+		set v [$mtx xVct] ; my initXvct $v ; $v destroy
+		set v [$mtx yVct] ; my initYvct $v ; $v destroy
+		set v [$mtx zVct] ; my initZvct $v ; $v destroy
+		return [self]
+	}
+
+	method initOrg {dx dy dz} {my initValue 0 $dx ; my initValue 1 $dy ; my initValue 2 $dz ; return [self]}
+	method initOrgP {p} {return [my initOrg [$p x] [$p y] [$p z]]}
+
+	method initXvct {dx dy dz} {my initValue 3 $dx ; my initValue 4 $dy ; my initValue 5 $dz ; return [self]}
+	method initXvctV {v} {return [my initXvct [$v x] [$v y] [$v z]]}
+
+	method initYvct {dx dy dz} {my initValue 6 $dx ; my initValue 7 $dy ; my initValue 8 $dz ; return [self]}
+	method initYvctV {v} {return [my initYvct [$v x] [$v y] [$v z]]}
+
+	method initZvct {dx dy dz} {my initValue 9 $dx ; my initValue 10 $dy ; my initValue 11 $dz ; return [self]}
+	method initZvctV {v} {return [my initZvct [$v x] [$v y] [$v z]]}
+
+	method initOrgArray {a} {upvar $a arr ; return [my initOrg $arr(0) $arr(1) $arr(2)]}
+	method initVctsArray {a} {
+		upvar $a arr
+		my initXvct $arr(0) $arr(1) $arr(2)
+		my initYvct $arr(3) $arr(4) $arr(5)
+		my initZvct $arr(6) $arr(7) $arr(8)
+		return [self]
+	}
+
+	method value {i} {return $values($i)}
+
+	method org {args} {return [Point3D new $values(0) $values(1) $values(2)]}
+	method xVct {args} {return [Vector3D new $values(3) $values(4) $values(5)]}
+	method yVct {args} {return [Vector3D new $values(6) $values(7) $values(8)]}
+	method zVct {args} {return [Vector3D new $values(9) $values(10) $values(11)]}
+
+	method same {mcs {precision 7}} {
+		set org [[self] org] ; set org_1 [$mcs org]
+		set vx [[self] xVct] ; set vx_1 [$mcs xVct]
+		set vy [[self] yVct] ; set vy_1 [$mcs yVct]
+		set vz [[self] zVct] ; set vz_1 [$mcs zVct]
+
+		if {[$org same $org_1 $precision] && [$vx same $vx_1 $precision] && [$vy same $vy_1 $precision] && [$vz same $vz_1 $precision]} {
+			set value 1
+		} else {
+			set value 0
+		}
+
+		$org destroy ; $org_1 destroy
+		$vx destroy ; $vx_1 destroy
+		$vy destroy ; $vy_1 destroy
+		$vz destroy ; $vz_1 destroy
+		return $value
+	}
+}
+
+set point [Point3D new]
+
+$point add 1 2 3
+
+$custom_flag(from_move,$::mom_path_name)
+
+oo::class create Point3D {
+	variable x 0. ; variable y 0. ; variable z 0.
+
+	constructor {{dx 0.} {dy 0.} {dz 0.}} {my initX $dx ; my initY $dy ; my initZ $dz}
+	destructor {
+		#puts "[self] is now deleted"
+	}
+
+	method fformat {value {precision 7}} {return [expr {round( 10.0 ** $precision * $value) / (10.0 ** $precision)}]}
+	method radtodeg {rad} {return [expr {$rad*180.0/(4.0*atan(1.0))}]}
+	method degtorad {deg} {return [expr {$deg*(4.0*atan(1.0))/180.0}]}
+
+	method duplicate {args} {return [[Point3D new] initP [self]]}
+	method type {args} {return "::Point3D"}
+
+	method toArray {{i 0}} {return [list [incr i 0] $x [incr i] $y [incr i] $z]}
+	method toLst {args} {return [list $x $y $z]}
+	method toStr {args} {return "$x, $y, $z"}
+	method toStrF {{precision 7}} {return "[my fformat $x $precision], [my fformat $y $precision], [my fformat $z $precision]"}
+
+	method x {args} {return $x}
+	method y {args} {return $y}
+	method z {args} {return $z}
+
+	method initX {dx} {set x [expr double($dx)]}
+	method initY {dy} {set y [expr double($dy)]}
+	method initZ {dz} {set z [expr double($dz)]}
+
+	method init {dx dy dz} {my initX $dx ; my initY $dy ; my initZ $dz ; return [self]}
+	method initArray {a} {upvar $a arr ; return [my init $arr(0) $arr(1) $arr(2)]}
+	method initArrayLst {arr_lst} {array set arr $arr_lst ; return [my init $arr(0) $arr(1) $arr(2)]}
+	method initLst {lst} {return [my init [lindex $lst 0] [lindex $lst 1] [lindex $lst 2]]}
+	method initP {p} {return [my init [$p x] [$p y] [$p z]]}
+
+	method reset {args} {my init 0. 0. 0. ; return [self]}
+
+	method add {dx dy dz} {my init [expr {$x + $dx}] [expr {$y + $dy}] [expr {$z + $dz}] ; return [self]}
+	method addArray {a} {upvar $a arr ; return [my add $arr(0) $arr(1) $arr(2)]}
+	method addArrayLst {arr_lst} {array set arr $arr_lst ; return [my add $arr(0) $arr(1) $arr(2)]}
+	method addLst {lst} {return [my add [lindex $lst 0] [lindex $lst 1] [lindex $lst 2]]}
+	method addP {p} {return [my add [$p x] [$p y] [$p z]]}
+
+	method sub {dx dy dz} {my init [expr {$x - $dx}] [expr {$y - $dy}] [expr {$z - $dz}] ; return [self]}
+	method subArray {a} {upvar $a arr ; return [my sub $arr(0) $arr(1) $arr(2)]}
+	method subArrayLst {arr_lst} {array set arr $arr_lst ; return [my sub $arr(0) $arr(1) $arr(2)]}
+	method subLst {lst} {return [my sub [lindex $lst 0] [lindex $lst 1] [lindex $lst 2]]}
+	method subP {p} {return [my sub [$p x] [$p y] [$p z]]}
+
+	method dist {dx dy dz} {return [expr {sqrt([expr {$x - $dx}]**2 + [expr {$y - $dy}]**2 + [expr {$z - $dz}]**2)}]}
+	method distArray {a} {upvar $a arr ; return [my dist $arr(0) $arr(1) $arr(2)]}
+	method distArrayLst {arr_lst} {array set arr $arr_lst ; return [my dist $arr(0) $arr(1) $arr(2)]}
+	method distLst {lst} {return [my dist [lindex $lst 0] [lindex $lst 1] [lindex $lst 2]]}
+	method distP {p} {return [my dist [$p x] [$p y] [$p z]]}
+
+	method dist_to_line {pl1 pl2} {
+		set pl [[$pl2 duplicate] subP $pl1]
+		set pp [[$pl1 duplicate] subP [self]]
+
+		set vl [[Vector3D new] initV $pl]
+		set vp [[Vector3D new] initV $pp]
+
+		set l [$vl magnitude]
+
+		if {[my fformat $l 5]==0} {
+			set value 0.
+		} else {
+			set vc [$vl cross $vp]
+			set value [expr [$vc magnitude]/$l]
+			$vc destroy
+		}
+
+		$pl destroy ; $vl destroy
+		$pp destroy ; $vp destroy
+		return $value
+	}
+	method dist_to_lineV {v} {
+		set p1 [[Point3D new] init 0. 0. 0.]
+		set p2 [[Point3D new] initP $v]
+
+		set value [my dist_to_line $p1 $p2]
+		$p1 destroy
+		$p2 destroy
+		return $value
+	}
+
+	#midpoint method to calculate the midpoint between this point and another point. This can be done by averaging the x, y, and z coordinates of the two points.
+	method midpoint {dx dy dz} {return [Point3D new [expr {double([[self] x] + $dx)/2}] [expr {double([[self] y] + $dy)/2}] [expr {double([[self] z] + $dz)/2}]]}
+	method midpointArr {a} {upvar $a arr ; return [my midpoint $arr(0) $arr(1) $arr(2)]}
+	method midpointArrLst {arr} {array set arr $arr_lst ; return [my midpoint $arr(0) $arr(1) $arr(2)]}
+	method midpointLst {lst} {return [my midpoint [lindex $lst 0] [lindex $lst 1] [lindex $lst 2]]}
+	method midpointP {p} {return [my midpoint [$p x] [$p y] [$p z]]}
+
+	method same {p {precision 7}} {
+		if {[my fformat [expr {[[self] x] - [$p x]}] $precision] == 0. && [my fformat [expr {[[self] y] - [$p y]}] $precision] == 0. && [my fformat [expr {[[self] z] - [$p z]}] $precision] == 0.} {return 1} else {return 0}
+	}
+
+	#This method takes three arguments: a vector object "axis" as the axis of rotation, an angle of rotation, and a point object "center" as the center of rotation.
+	#First, it translates the point by subtracting the center of rotation,
+	#then it applies the Rodrigues' rotation formula to calculate the new coordinates of the point, and finally,
+	#it translates back the point by adding the center of rotation.
+	#The center parameter is defined as an optional parameter with a default value of a new Point3D object, initialized with the values (0,0,0).
+	method rotAround {u v w angle {x0 0.} {y0 0.} {z0 0.}} {
+		set x1 [expr {double($x) - $x0}] ; set y1 [expr {double($y) - $y0}] ; set z1 [expr {double($z) - $z0}]
+		set u [expr {double($u)}] ; set v [expr {double($v)}] ; set w [expr {double($w)}]
+		set a [my degtorad $angle]
+
+		set coss [expr {cos($a)}]
+		set sinn [expr {sin($a)}]
+
+		set x2 [expr {$u*($u*$x1 + $v*$y1 + $w*$z1)*(1 - $coss) + $x1*$coss + (-$w*$y1 + $v*$z1)*$sinn + $x0}]
+		set y2 [expr {$v*($u*$x1 + $v*$y1 + $w*$z1)*(1 - $coss) + $y1*$coss + ($w*$x1 - $u*$z1)*$sinn + $y0}]
+		set z2 [expr {$w*($u*$x1 + $v*$y1 + $w*$z1)*(1 - $coss) + $z1*$coss + (-$v*$x1 + $u*$y1)*$sinn + $z0}]
+
+		my init $x2 $y2 $z2
+		return [self]
+	}
+	method rotAroundLst {aLst angle {cLst {0. 0. 0.}}} {
+		return [my rotAround [lindex $aLst 0] [lindex $aLst 1] [lindex $aLst 2] $angle [lindex $cLst 0] [lindex $cLst 1] [lindex $cLst 2]]
+	}
+	method rotAroundVP {axis angle {center {}}} {
+		if {[catch {set s [$center type]}] || (![string equal [$center type] "::Point3D"] && ![string equal [$center type] "::Vector3D"])} {
+			set center [Point3D new]
+			set b_center true
+		}
+
+		my rotAround [$axis x] [$axis y] [$axis z] $angle [$center x] [$center y] [$center z]
+		if {[info exists b_center]} {$center destroy}
+		return [self]
+	}
+
+	method transform {mtx_from mtx_to} {
+		if {[catch {set s [$mtx_from type]}] || ![string equal [$mtx_from type] "::Matrix4x4"]} {
+			set mtx_from [[Matrix4x4 new] identity]
+			set b_mtx_from true
+		}
+		if {[catch {set s [$mtx_to type]}] || ![string equal [$mtx_to type] "::Matrix4x4"]} {
+			set mtx_to [[Matrix4x4 new] identity]
+			set b_mtx_to true
+		}
+
+		set m [[Matrix4x4 new] identity]
+		$m initValue 0 [my x]
+		$m initValue 4 [my y]
+		$m initValue 8 [my z]
+		$m initValue 12 1.
+
+		set trs [[[[$mtx_from duplicate] inverse] multiply $mtx_to false] inverse]
+		$m multiply $trs true
+
+		my init [$m value 0] [$m value 4] [$m value 8]
+		$m destroy
+		$trs destroy
+		if {[info exists b_mtx_from]} {$mtx_from destroy}
+		if {[info exists b_mtx_to]} {$mtx_to destroy}
+		return [self]
+	}
+}
+
+set v1 [MCS new]
+
+$v1 initArray