From 2cf4b037a44c68cc16ced497e04ea70996230e8f Mon Sep 17 00:00:00 2001
From: Christopher Dwyer-Perkins <chris@inverted-solutions.com>
Date: Tue, 7 Jul 2026 12:32:33 -0300
Subject: [PATCH 1/4] Add SceneGraph XML element and attribute-name completions

Provide IntelliSense in .xml component files, driven by the built-in
roku-types node metadata and project components.

- Program: getSceneGraphNodeNames/getSceneGraphNodeFields (resolves the
  extends chain across built-in nodes and project components),
  hasSceneGraphNode, getSceneGraphNode
- XmlFile.getCompletions: element (tag name) completions after `<` and in
  element content, and field (attribute) completions inside a start tag;
  adds getTokenAt for token-at-position lookups
- LanguageServer: add `<` as a completion trigger character
- SGParser: skip malformed child elements with no tag name instead of
  throwing (a lone `<` while typing)
- roku-types: add `extends` to SGNodeData
---
 src/LanguageServer.ts     |   4 +-
 src/Program.spec.ts       |  46 ++++++++++++
 src/Program.ts            | 140 ++++++++++++++++++++++++++++++++++++
 src/files/XmlFile.spec.ts |  81 ++++++++++++++++++++-
 src/files/XmlFile.ts      | 146 +++++++++++++++++++++++++++++++++++++-
 src/parser/SGParser.ts    |  16 ++++-
 src/roku-types/index.ts   |   4 ++
 7 files changed, 428 insertions(+), 9 deletions(-)

diff --git a/src/LanguageServer.ts b/src/LanguageServer.ts
index d05dd090c..7e7f82b95 100644
--- a/src/LanguageServer.ts
+++ b/src/LanguageServer.ts
@@ -219,8 +219,8 @@ export class LanguageServer {
                 // Tell the client that the server supports code completion
                 completionProvider: {
                     resolveProvider: false,
-                    //anytime the user types a period, auto-show the completion results
-                    triggerCharacters: ['.'],
+                    //`.` auto-shows brightscript completions; `<` auto-shows xml element completions
+                    triggerCharacters: ['.', '<'],
                     allCommitCharacters: ['.', '@']
                 },
                 documentSymbolProvider: true,
diff --git a/src/Program.spec.ts b/src/Program.spec.ts
index fc038d6b5..99dd0bfa1 100644
--- a/src/Program.spec.ts
+++ b/src/Program.spec.ts
@@ -50,6 +50,52 @@ describe('Program', () => {
         program.dispose();
     });
 
+    describe('scenegraph node metadata', () => {
+        it('getSceneGraphNodeNames includes built-in nodes and project components', () => {
+            program.setFile('components/widget.xml', trim`
+                <component name="Widget" extends="Group">
+                </component>
+            `);
+            const names = program.getSceneGraphNodeNames();
+            expect(names).to.include('Label');
+            expect(names).to.include('Widget');
+        });
+
+        it('hasSceneGraphNode recognizes built-in nodes and project components (case-insensitive)', () => {
+            program.setFile('components/widget.xml', trim`
+                <component name="Widget" extends="Group">
+                </component>
+            `);
+            expect(program.hasSceneGraphNode('label')).to.be.true;
+            expect(program.hasSceneGraphNode('widget')).to.be.true;
+            expect(program.hasSceneGraphNode('NotARealNode')).to.be.false;
+        });
+
+        it('getSceneGraphNodeFields walks the extends chain of a built-in node', () => {
+            //Label extends LabelBase extends ... eventually Node; `id` comes from Node
+            const fieldNames = program.getSceneGraphNodeFields('Label').map(x => x.name);
+            expect(fieldNames).to.include('text');
+            expect(fieldNames).to.include('id');
+        });
+
+        it('getSceneGraphNodeFields walks from a project component into its built-in parent', () => {
+            program.setFile('components/widget.xml', trim`
+                <component name="Widget" extends="Group">
+                    <interface>
+                        <field id="caption" type="string" />
+                    </interface>
+                </component>
+            `);
+            const fields = program.getSceneGraphNodeFields('Widget');
+            const own = fields.find(x => x.name === 'caption');
+            const inherited = fields.find(x => x.name === 'visible');
+            //own field from the component's interface
+            expect(own?.origin).to.equal('own');
+            //inherited field from the built-in Group (via Node)
+            expect(inherited?.origin).to.equal('inherited');
+        });
+    });
+
     it('does not throw exception after calling validate() after dispose()', () => {
         program.setFile('source/themes/alpha.bs', `
             sub main()
diff --git a/src/Program.ts b/src/Program.ts
index 0fa40f31c..a5c271aa8 100644
--- a/src/Program.ts
+++ b/src/Program.ts
@@ -38,11 +38,18 @@ import { SignatureHelpUtil } from './bscPlugin/SignatureHelpUtil';
 import { DiagnosticSeverityAdjuster } from './DiagnosticSeverityAdjuster';
 import { Sequencer } from './common/Sequencer';
 import { Deferred } from './deferred';
+import { nodes as builtInSceneGraphNodeData } from './roku-types';
+import type { SGNodeData } from './roku-types';
 
 const startOfSourcePkgPath = `source${path.sep}`;
 const bslibNonAliasedRokuModulesPkgPath = s`source/roku_modules/rokucommunity_bslib/bslib.brs`;
 const bslibAliasedRokuModulesPkgPath = s`source/roku_modules/bslib/bslib.brs`;
 
+/**
+ * The built-in Roku SceneGraph nodes, keyed by their lower-case name
+ */
+const builtInSceneGraphNodes = builtInSceneGraphNodeData as unknown as Record<string, SGNodeData>;
+
 export interface SourceObj {
     /**
      * @deprecated use `srcPath` instead
@@ -490,6 +497,113 @@ export class Program {
         return this.getComponent(componentName)?.scope;
     }
 
+    /**
+     * Get the names of all known SceneGraph nodes: the built-in Roku nodes plus every component
+     * defined in this program. Names keep their original casing and are deduplicated by lower-case name.
+     */
+    public getSceneGraphNodeNames(): string[] {
+        const namesByLowerName = new Map<string, string>();
+        for (const node of Object.values(builtInSceneGraphNodes)) {
+            namesByLowerName.set(node.name.toLowerCase(), node.name);
+        }
+        for (const componentName in this.components) {
+            const displayName = this.components[componentName][0]?.file.componentName?.text;
+            if (displayName) {
+                namesByLowerName.set(displayName.toLowerCase(), displayName);
+            }
+        }
+        return [...namesByLowerName.values()];
+    }
+
+    /**
+     * Determine whether a SceneGraph node with the given name exists, either as a built-in Roku node
+     * or as a component defined in this program.
+     */
+    public hasSceneGraphNode(nodeName: string): boolean {
+        if (!nodeName) {
+            return false;
+        }
+        return !!builtInSceneGraphNodes[nodeName.toLowerCase()] || !!this.getComponent(nodeName);
+    }
+
+    /**
+     * Get the built-in Roku node data and/or the project component file backing a SceneGraph node name.
+     * Returns `undefined` when no node or component matches.
+     */
+    public getSceneGraphNode(nodeName: string): SceneGraphNodeLookup | undefined {
+        if (!nodeName) {
+            return undefined;
+        }
+        const builtInNode = builtInSceneGraphNodes[nodeName.toLowerCase()];
+        const componentFile = this.getComponent(nodeName)?.file;
+        if (!builtInNode && !componentFile) {
+            return undefined;
+        }
+        return { builtInNode: builtInNode, componentFile: componentFile };
+    }
+
+    /**
+     * Get every field available on a SceneGraph node, walking the full `extends` chain across both
+     * built-in Roku nodes and project components. Fields declared closer to the node take precedence
+     * over inherited fields with the same name.
+     */
+    public getSceneGraphNodeFields(nodeName: string): ResolvedSceneGraphField[] {
+        const fieldsByLowerName = new Map<string, ResolvedSceneGraphField>();
+        const visitedNodeNames = new Set<string>();
+
+        const addField = (field: ResolvedSceneGraphField) => {
+            if (!field.name) {
+                return;
+            }
+            const lowerName = field.name.toLowerCase();
+            //the first definition we encounter is the closest one, so it wins
+            if (!fieldsByLowerName.has(lowerName)) {
+                fieldsByLowerName.set(lowerName, field);
+            }
+        };
+
+        const walk = (currentNodeName: string, origin: SceneGraphFieldOrigin) => {
+            const lowerName = currentNodeName?.toLowerCase();
+            if (!lowerName || visitedNodeNames.has(lowerName)) {
+                return;
+            }
+            visitedNodeNames.add(lowerName);
+
+            //prefer a project component (a project component can shadow a built-in of the same name)
+            const component = this.getComponent(currentNodeName);
+            if (component) {
+                for (const field of component.file.ast.component?.api?.fields ?? []) {
+                    addField({ name: field.id, type: field.type, default: field.value, origin: origin });
+                }
+                const parentName = component.file.ast.component?.extends;
+                if (parentName) {
+                    walk(parentName, 'inherited');
+                }
+                return;
+            }
+
+            const builtInNode = builtInSceneGraphNodes[lowerName];
+            if (builtInNode) {
+                for (const field of builtInNode.fields ?? []) {
+                    addField({
+                        name: field.name,
+                        type: field.type,
+                        default: field.default,
+                        description: field.description,
+                        accessPermission: field.accessPermission,
+                        origin: origin
+                    });
+                }
+                if (builtInNode.extends?.name) {
+                    walk(builtInNode.extends.name, 'inherited');
+                }
+            }
+        };
+
+        walk(nodeName, 'own');
+        return [...fieldsByLowerName.values()];
+    }
+
     /**
      * Update internal maps with this file reference
      */
@@ -1930,3 +2044,29 @@ export interface FileTranspileResult {
     map: SourceMapGenerator;
     typedef: string;
 }
+
+/**
+ * Where a resolved SceneGraph field was declared, relative to the node it was resolved for:
+ * `own` = declared on the node itself, `inherited` = declared on an ancestor in the `extends` chain
+ */
+export type SceneGraphFieldOrigin = 'own' | 'inherited';
+
+/**
+ * A field available on a SceneGraph node, resolved across the node's full `extends` chain
+ */
+export interface ResolvedSceneGraphField {
+    name: string;
+    type?: string;
+    default?: string;
+    description?: string;
+    accessPermission?: string;
+    origin: SceneGraphFieldOrigin;
+}
+
+/**
+ * The built-in Roku node data and/or project component file backing a SceneGraph node name
+ */
+export interface SceneGraphNodeLookup {
+    builtInNode?: SGNodeData;
+    componentFile?: XmlFile;
+}
diff --git a/src/files/XmlFile.spec.ts b/src/files/XmlFile.spec.ts
index 44d1700ee..5cfe116b4 100644
--- a/src/files/XmlFile.spec.ts
+++ b/src/files/XmlFile.spec.ts
@@ -36,6 +36,18 @@ describe('XmlFile', () => {
     });
 
     describe('parse', () => {
+        it('does not crash on malformed child elements (e.g. a lone `<` while typing)', () => {
+            //this used to throw in SGParser.mapNode because the element had no tag name
+            file = program.setFile('components/malformed.xml', trim`
+                <component name="Main" extends="Group">
+                    <children>
+                        <
+                    </children>
+                </component>
+            `);
+            expect(isXmlFile(file)).to.be.true;
+        });
+
         it('allows modifying the parsed XML model', () => {
             const expected = 'OtherName';
             program.plugins.add({
@@ -384,7 +396,7 @@ describe('XmlFile', () => {
         });
 
         //TODO - refine this test once cdata scripts are supported
-        it('prevents scope completions entirely', () => {
+        it('provides xml element completions, never brightscript scope completions', () => {
             program.setFile('components/component1.brs', ``);
 
             let xmlFile = program.setFile('components/component1.xml', trim`
@@ -394,7 +406,72 @@ describe('XmlFile', () => {
                 </component>
             `);
 
-            expect(program.getCompletions(xmlFile.srcPath, Position.create(1, 1))).to.be.empty;
+            const completions = program.getCompletions(xmlFile.srcPath, Position.create(1, 1));
+            //every completion is an xml element (node) completion, not a brightscript scope symbol
+            expect(completions).not.to.be.empty;
+            expect(completions.every(x => x.kind === CompletionItemKind.Class)).to.be.true;
+        });
+
+        /**
+         * Find the (line, character) position immediately after the first occurrence of `marker` in the file
+         */
+        function positionAfter(fileContents: string, marker: string): Position {
+            const index = fileContents.indexOf(marker);
+            const before = fileContents.substring(0, index + marker.length);
+            const lines = before.split('\n');
+            return Position.create(lines.length - 1, lines[lines.length - 1].length);
+        }
+
+        it('provides element completions for scenegraph nodes and project components after `<`', () => {
+            program.setFile('components/widget.xml', trim`
+                <component name="Widget" extends="Group">
+                </component>
+            `);
+            const xmlFile = program.setFile<XmlFile>('components/main.xml', trim`
+                <component name="Main" extends="Group">
+                    <children>
+                        <
+                    </children>
+                </component>
+            `);
+            //position the caret right after the lone `<` inside <children>
+            const lines = xmlFile.fileContents.split('\n');
+            const lineIndex = lines.findIndex(line => line.trim() === '<');
+            const completions = xmlFile.getCompletions(Position.create(lineIndex, lines[lineIndex].indexOf('<') + 1));
+            const labels = completions.map(x => x.label);
+            //built-in node
+            expect(labels).to.include('Label');
+            //project component
+            expect(labels).to.include('Widget');
+            //a component can't contain itself
+            expect(labels).not.to.include('Main');
+            expect(completions.every(x => x.kind === CompletionItemKind.Class)).to.be.true;
+        });
+
+        it('provides field completions inside an open element tag', () => {
+            const xmlFile = program.setFile<XmlFile>('components/main.xml', trim`
+                <component name="Main" extends="Group">
+                    <children>
+                        <Label text="hi" >
+                    </children>
+                </component>
+            `);
+            const completions = xmlFile.getCompletions(positionAfter(xmlFile.fileContents, '<Label text="hi" '));
+            const labels = completions.map(x => x.label);
+            //Label has a `color` field
+            expect(labels).to.include('color');
+            //`text` is already present on the tag, so it should not be suggested again
+            expect(labels).not.to.include('text');
+            expect(completions.every(x => x.kind === CompletionItemKind.Field)).to.be.true;
+        });
+
+        it('getTokenAt returns the token whose range contains the position', () => {
+            const xmlFile = program.setFile<XmlFile>('components/main.xml', trim`
+                <component name="Main" extends="Group">
+                </component>
+            `);
+            const token = xmlFile.getTokenAt(positionAfter(xmlFile.fileContents, '<compon'));
+            expect(token?.image).to.equal('component');
         });
     });
 
diff --git a/src/files/XmlFile.ts b/src/files/XmlFile.ts
index 06dba8268..5f3faafbb 100644
--- a/src/files/XmlFile.ts
+++ b/src/files/XmlFile.ts
@@ -2,6 +2,7 @@ import * as path from 'path';
 import type { CodeWithSourceMap } from 'source-map';
 import { SourceNode } from 'source-map';
 import type { CompletionItem, Location, Position, Range } from 'vscode-languageserver';
+import { CompletionItemKind, InsertTextFormat } from 'vscode-languageserver';
 import { diagnosticCodes } from '../DiagnosticMessages';
 import type { FunctionScope } from '../FunctionScope';
 import type { Callable, BsDiagnostic, File, FileReference, FunctionCall, CommentFlag } from '../interfaces';
@@ -17,6 +18,19 @@ import { CommentFlagProcessor } from '../CommentFlagProcessor';
 import type { IToken, TokenType } from 'chevrotain';
 import { TranspileState } from '../parser/TranspileState';
 
+/**
+ * Names of the `@xml-tools` lexer token types we inspect for completions and hover
+ */
+const XmlTokenName = {
+    open: 'OPEN',
+    slashOpen: 'SLASH_OPEN',
+    close: 'CLOSE',
+    slashClose: 'SLASH_CLOSE',
+    name: 'Name',
+    equals: 'EQUALS',
+    string: 'STRING'
+} as const;
+
 export class XmlFile {
     constructor(
         public srcPath: string,
@@ -368,12 +382,140 @@ export class XmlFile {
      * Get all available completions for the specified position
      */
     public getCompletions(position: Position): CompletionItem[] {
-        let scriptImport = util.getScriptImportAtPosition(this.scriptTagImports, position);
+        //handle script import path completions (e.g. `<script uri="|" />`)
+        const scriptImport = util.getScriptImportAtPosition(this.scriptTagImports, position);
         if (scriptImport) {
             return this.program.getScriptImportCompletions(this.pkgPath, scriptImport);
-        } else {
+        }
+
+        //don't provide completions inside an attribute value string (e.g. `text="|"`); reserved for future work
+        if (this.getTokenAt(position)?.tokenType.name === XmlTokenName.string) {
             return [];
         }
+
+        const tokens = (this.parser.tokens ?? []) as unknown as IToken[];
+        //find the most recent tag boundary (`<`, `</`, `>`, `/>`) the cursor has moved past. A boundary the
+        //cursor merely sits at the start of (e.g. the `>` the caret is right before) doesn't count, so a
+        //caret inside `<Label |>` still resolves to the opening `<Label` rather than the trailing `>`.
+        let boundaryIndex = -1;
+        for (let i = 0; i < tokens.length; i++) {
+            const startLine = (tokens[i].startLine ?? 1) - 1;
+            const startCharacter = (tokens[i].startColumn ?? 1) - 1;
+            //tokens are ordered, so stop once one starts at or after the cursor
+            if (position.line < startLine || (position.line === startLine && position.character <= startCharacter)) {
+                break;
+            }
+            const tokenName = tokens[i].tokenType.name;
+            if (tokenName === XmlTokenName.open || tokenName === XmlTokenName.slashOpen || tokenName === XmlTokenName.close || tokenName === XmlTokenName.slashClose) {
+                boundaryIndex = i;
+            }
+        }
+        const boundary = boundaryIndex >= 0 ? tokens[boundaryIndex] : undefined;
+
+        //cursor is inside an open start tag: `<` tagName [attributes...]
+        if (boundary?.tokenType.name === XmlTokenName.open) {
+            const tagNameToken = tokens[boundaryIndex + 1];
+            //no tag name yet, or the cursor is still on/within the tag name -> complete element names
+            if (tagNameToken?.tokenType.name !== XmlTokenName.name || util.comparePositionToRange(position, this.getTokenRange(tagNameToken)) <= 0) {
+                return this.getElementCompletions(false);
+            }
+            //otherwise complete attribute (field) names for the enclosing node
+            return this.getAttributeCompletions(tagNameToken.image, this.getExistingAttributeNames(boundaryIndex + 2));
+        }
+
+        //cursor is in element content (right after a `>` / `/>`) -> complete child element names
+        if (boundary?.tokenType.name === XmlTokenName.close || boundary?.tokenType.name === XmlTokenName.slashClose) {
+            return this.getElementCompletions(true);
+        }
+
+        //inside a closing tag (`</...`), before any tag, or any other position -> no completions
+        return [];
+    }
+
+    /**
+     * Get element (tag name) completions for every known SceneGraph node and project component.
+     * @param includeOpenBracket whether to prefix the inserted snippet with `<` (true when the cursor is
+     * not already immediately after an `<`)
+     */
+    private getElementCompletions(includeOpenBracket: boolean): CompletionItem[] {
+        const ownComponentName = this.componentName?.text?.toLowerCase();
+        const openBracket = includeOpenBracket ? '<' : '';
+        return this.program.getSceneGraphNodeNames()
+            //a component can't contain itself
+            .filter(name => !ownComponentName || name.toLowerCase() !== ownComponentName)
+            .map(name => ({
+                label: name,
+                kind: CompletionItemKind.Class,
+                insertTextFormat: InsertTextFormat.Snippet,
+                insertText: `${openBracket}${name} $0></${name}>`,
+                //sort project components ahead of built-in nodes
+                sortText: (this.program.getComponent(name) ? '0' : '1') + name
+            }));
+    }
+
+    /**
+     * Get attribute (field) name completions for the node with the given name, excluding attributes
+     * already present on the tag.
+     */
+    private getAttributeCompletions(nodeName: string, existingAttributeNames: string[]): CompletionItem[] {
+        const existing = new Set(existingAttributeNames.map(name => name.toLowerCase()));
+        return this.program.getSceneGraphNodeFields(nodeName)
+            .filter(field => !existing.has(field.name.toLowerCase()))
+            //built-in read-only fields can't be set in xml; project fields (no accessPermission) are always writable
+            .filter(field => !field.accessPermission || /write/i.test(field.accessPermission))
+            .map(field => ({
+                label: field.name,
+                kind: CompletionItemKind.Field,
+                insertTextFormat: InsertTextFormat.Snippet,
+                insertText: `${field.name}="$1"`,
+                detail: field.type,
+                documentation: field.description,
+                //sort a node's own fields ahead of inherited ones
+                sortText: (field.origin === 'own' ? '0' : '1') + field.name
+            }));
+    }
+
+    /**
+     * Collect the names of attributes already written on a start tag, scanning forward from the given
+     * token index until the tag closes. Used to avoid suggesting attributes that are already present.
+     */
+    private getExistingAttributeNames(startIndex: number): string[] {
+        const names: string[] = [];
+        const tokens = (this.parser.tokens ?? []) as unknown as IToken[];
+        for (let i = startIndex; i < tokens.length; i++) {
+            const tokenName = tokens[i].tokenType.name;
+            //inside a start tag the only token kinds are attribute names, `=`, and values; anything else ends the tag
+            if (tokenName !== XmlTokenName.name && tokenName !== XmlTokenName.equals && tokenName !== XmlTokenName.string) {
+                break;
+            }
+            if (tokenName === XmlTokenName.name && tokens[i + 1]?.tokenType.name === XmlTokenName.equals) {
+                names.push(tokens[i].image);
+            }
+        }
+        return names;
+    }
+
+    /**
+     * Get the xml token whose range contains the given position (used by completions and hover)
+     */
+    public getTokenAt(position: Position): IToken | undefined {
+        for (const token of (this.parser.tokens ?? []) as unknown as IToken[]) {
+            if (util.rangeContains(this.getTokenRange(token), position)) {
+                return token;
+            }
+        }
+    }
+
+    /**
+     * Build a brighterscript (0-based) range from an `@xml-tools` (1-based) token
+     */
+    private getTokenRange(token: IToken): Range {
+        return util.createRange(
+            token.startLine - 1,
+            token.startColumn - 1,
+            token.endLine - 1,
+            token.endColumn
+        );
     }
 
     /**
diff --git a/src/parser/SGParser.ts b/src/parser/SGParser.ts
index bf2b5a6ce..21f55a80b 100644
--- a/src/parser/SGParser.ts
+++ b/src/parser/SGParser.ts
@@ -171,6 +171,10 @@ interface IToken {
     endOffset?: number;
     endLine?: number;
     endColumn?: number;
+    /**
+     * The lexer token type. Present on tokens produced by `@xml-tools`; used to classify cursor context.
+     */
+    tokenType?: { name: string };
 }
 
 function mapElement({ children }: ElementCstNode, diagnostics: Diagnostic[]): SGTag {
@@ -226,8 +230,12 @@ function reportUnexpectedChildren(name: SGToken, diagnostics: Diagnostic[]) {
     });
 }
 
-function mapNode({ children }: ElementCstNode): SGNode {
-    const nameToken = children.Name[0];
+function mapNode({ children }: ElementCstNode): SGNode | undefined {
+    const nameToken = children.Name?.[0];
+    //skip malformed elements that have no tag name (e.g. a lone `<` while the user is still typing)
+    if (!nameToken) {
+        return undefined;
+    }
     let range: Range;
     const selfClosing = !!children.SLASH_CLOSE;
     if (selfClosing) {
@@ -276,7 +284,9 @@ function mapNodes(content: ContentCstNode): SGNode[] {
         return [];
     }
     const { element } = content.children;
-    return element?.map(element => mapNode(element));
+    return element
+        ?.map(element => mapNode(element))
+        .filter((node): node is SGNode => !!node);
 }
 
 function hasElements(content: ContentCstNode): boolean {
diff --git a/src/roku-types/index.ts b/src/roku-types/index.ts
index 271afcf77..05a404a60 100644
--- a/src/roku-types/index.ts
+++ b/src/roku-types/index.ts
@@ -57,6 +57,10 @@ export interface SGNodeData extends BrightScriptDocLookup {
     fields: BRSFieldData[];
     events: BrightScriptDocLookup[];
     interfaces: BrightScriptDocLookup[];
+    /**
+     * The node this node extends. Absent on the root `Node` type.
+     */
+    extends?: BrightScriptDocLookup;
 }
 
 export interface BRSComponentData extends BrightScriptDocLookup, PossiblyDeprecated {

From b5f661fdd180769c3ad3e894d33bd81384a21eba Mon Sep 17 00:00:00 2001
From: Christopher Dwyer-Perkins <chris@inverted-solutions.com>
Date: Tue, 7 Jul 2026 13:29:29 -0300
Subject: [PATCH 2/4] Validate SceneGraph node types and fields in xml
 components

Walk the <children> node tree of each component and report:
- unknown component types (error)
- unknown field/attribute names on a known node (error)
- field-name casing that differs from the declared field (warning)
- clearly-invalid scalar field values (warning)

Field/value checks are intentionally conservative: only int/float/bool/color
values are validated (everything else passes), and field-name checks are
skipped when no fields can be resolved for a known node, to avoid false
positives. New diagnostics use codes 1155-1158.
---
 src/DiagnosticMessages.ts                     |  20 ++++
 .../validation/FieldTypeValidator.ts          |  42 +++++++
 .../validation/XmlFileValidator.spec.ts       | 112 ++++++++++++++++++
 src/bscPlugin/validation/XmlFileValidator.ts  |  64 +++++++++-
 src/files/XmlFile.spec.ts                     |  16 +--
 5 files changed, 245 insertions(+), 9 deletions(-)
 create mode 100644 src/bscPlugin/validation/FieldTypeValidator.ts
 create mode 100644 src/bscPlugin/validation/XmlFileValidator.spec.ts

diff --git a/src/DiagnosticMessages.ts b/src/DiagnosticMessages.ts
index cd81e60bc..b4b3dee39 100644
--- a/src/DiagnosticMessages.ts
+++ b/src/DiagnosticMessages.ts
@@ -833,6 +833,26 @@ export let DiagnosticMessages = {
         message: `rsg_version=${rsgVersion} was removed in firmware ${removedAt}; use rsg_version=${replacement}`,
         code: 1154,
         severity: DiagnosticSeverity.Error
+    }),
+    xmlUnknownComponentType: (nodeName: string) => ({
+        message: `Unknown component type '${nodeName}'`,
+        code: 1155,
+        severity: DiagnosticSeverity.Error
+    }),
+    xmlUnknownField: (fieldName: string, componentName: string) => ({
+        message: `Field '${fieldName}' does not exist on component '${componentName}'`,
+        code: 1156,
+        severity: DiagnosticSeverity.Error
+    }),
+    xmlFieldNameCaseMismatch: (actualName: string, expectedName: string) => ({
+        message: `Field '${actualName}' should be '${expectedName}' to match the declared casing`,
+        code: 1157,
+        severity: DiagnosticSeverity.Warning
+    }),
+    xmlInvalidFieldValue: (fieldName: string, expectedType: string) => ({
+        message: `Value for field '${fieldName}' is not a valid '${expectedType}'`,
+        code: 1158,
+        severity: DiagnosticSeverity.Warning
     })
 };
 
diff --git a/src/bscPlugin/validation/FieldTypeValidator.ts b/src/bscPlugin/validation/FieldTypeValidator.ts
new file mode 100644
index 000000000..7bc2688d8
--- /dev/null
+++ b/src/bscPlugin/validation/FieldTypeValidator.ts
@@ -0,0 +1,42 @@
+/**
+ * Best-effort validation of a SceneGraph field value written as an xml attribute string.
+ *
+ * Intentionally conservative: only unambiguous scalar types are checked. Anything ambiguous (strings,
+ * nodes, uris, arrays, vectors, enums/option-strings, unknown types, etc.) passes, so we never emit a
+ * false positive for the many field types whose valid literal form is hard to pin down from xml alone.
+ *
+ * @param value the (unquoted) attribute value
+ * @param type the field's declared type (e.g. `integer`, `float`, `boolean`, `color`, `option string`)
+ * @returns true when the value is valid for the type, or when the type isn't one we confidently validate
+ */
+export function isValidSceneGraphFieldValue(value: string, type: string): boolean {
+    const validator = scalarValidators[normalizeFieldType(type)];
+    //no validator for this type -> assume valid
+    return validator ? validator(value ?? '') : true;
+}
+
+function normalizeFieldType(type: string): string {
+    let normalized = (type ?? '').trim().toLowerCase();
+    //"option string", "value string", etc. are all just strings
+    if (normalized.endsWith(' string')) {
+        normalized = 'string';
+    }
+    return normalized;
+}
+
+const integerPattern = /^[+-]?\d+$/;
+const floatPattern = /^[+-]?(\d+\.?\d*|\.\d+)$/;
+const booleanPattern = /^(true|false)$/i;
+const colorPattern = /^(#[0-9a-f]{3,4}|#[0-9a-f]{6}|#[0-9a-f]{8}|0x[0-9a-f]{6}|0x[0-9a-f]{8})$/i;
+
+const scalarValidators: Record<string, (value: string) => boolean> = {
+    integer: value => integerPattern.test(value),
+    int: value => integerPattern.test(value),
+    longinteger: value => integerPattern.test(value),
+    float: value => floatPattern.test(value),
+    double: value => floatPattern.test(value),
+    time: value => floatPattern.test(value),
+    boolean: value => booleanPattern.test(value),
+    bool: value => booleanPattern.test(value),
+    color: value => colorPattern.test(value)
+};
diff --git a/src/bscPlugin/validation/XmlFileValidator.spec.ts b/src/bscPlugin/validation/XmlFileValidator.spec.ts
new file mode 100644
index 000000000..0dc502409
--- /dev/null
+++ b/src/bscPlugin/validation/XmlFileValidator.spec.ts
@@ -0,0 +1,112 @@
+import { expect } from '../../chai-config.spec';
+import { Program } from '../../Program';
+import type { XmlFile } from '../../files/XmlFile';
+import type { BsDiagnostic } from '../../interfaces';
+import { trim, rootDir } from '../../testHelpers.spec';
+
+describe('XmlFileValidator', () => {
+    let program: Program;
+    beforeEach(() => {
+        program = new Program({ rootDir: rootDir });
+    });
+    afterEach(() => {
+        program.dispose();
+    });
+
+    //codes for the scenegraph node/field diagnostics added by this validator
+    const scenegraphCodes = [1155, 1156, 1157, 1158];
+    function scenegraphDiagnostics(file: XmlFile): BsDiagnostic[] {
+        return file.diagnostics.filter(diagnostic => scenegraphCodes.includes(diagnostic.code as number));
+    }
+
+    it('flags an unknown component type in <children>', () => {
+        const file = program.setFile<XmlFile>('components/main.xml', trim`
+            <component name="Main" extends="Group">
+                <children>
+                    <Lable />
+                </children>
+            </component>
+        `);
+        program.validate();
+        const diagnostics = scenegraphDiagnostics(file);
+        expect(diagnostics.map(x => x.code)).to.include(1155);
+        expect(diagnostics[0].message).to.include('Lable');
+    });
+
+    it('does not flag known built-in nodes or project components', () => {
+        program.setFile('components/widget.xml', trim`
+            <component name="Widget" extends="Group">
+            </component>
+        `);
+        const file = program.setFile<XmlFile>('components/main.xml', trim`
+            <component name="Main" extends="Group">
+                <children>
+                    <Label text="hi" />
+                    <Widget />
+                </children>
+            </component>
+        `);
+        program.validate();
+        expect(scenegraphDiagnostics(file)).to.be.empty;
+    });
+
+    it('flags an unknown field on a known node', () => {
+        const file = program.setFile<XmlFile>('components/main.xml', trim`
+            <component name="Main" extends="Group">
+                <children>
+                    <Label bogusField="x" />
+                </children>
+            </component>
+        `);
+        program.validate();
+        expect(scenegraphDiagnostics(file).map(x => x.code)).to.include(1156);
+    });
+
+    it('flags a field name case mismatch', () => {
+        const file = program.setFile<XmlFile>('components/main.xml', trim`
+            <component name="Main" extends="Group">
+                <children>
+                    <Label Text="hi" />
+                </children>
+            </component>
+        `);
+        program.validate();
+        expect(scenegraphDiagnostics(file).map(x => x.code)).to.include(1157);
+    });
+
+    it('flags a clearly-invalid scalar field value but allows valid and ambiguous ones', () => {
+        const badFile = program.setFile<XmlFile>('components/bad.xml', trim`
+            <component name="Bad" extends="Group">
+                <children>
+                    <Label opacity="halfway" />
+                </children>
+            </component>
+        `);
+        const goodFile = program.setFile<XmlFile>('components/good.xml', trim`
+            <component name="Good" extends="Group">
+                <children>
+                    <Label opacity="0.5" text="anything goes" />
+                </children>
+            </component>
+        `);
+        program.validate();
+        expect(scenegraphDiagnostics(badFile).map(x => x.code)).to.include(1158);
+        expect(scenegraphDiagnostics(goodFile)).to.be.empty;
+    });
+
+    it('validates fields on ContentNode against its known schema', () => {
+        const file = program.setFile<XmlFile>('components/main.xml', trim`
+            <component name="Main" extends="Group">
+                <children>
+                    <ContentNode Title="Home" bogusField="x" />
+                </children>
+            </component>
+        `);
+        program.validate();
+        const codes = scenegraphDiagnostics(file).map(x => x.code);
+        //`Title` is a real ContentNode field, correctly cased -> no diagnostic
+        expect(codes).not.to.include(1157);
+        //`bogusField` is not a ContentNode field -> unknown field
+        expect(codes).to.include(1156);
+    });
+});
diff --git a/src/bscPlugin/validation/XmlFileValidator.ts b/src/bscPlugin/validation/XmlFileValidator.ts
index 44912dced..d600db6b6 100644
--- a/src/bscPlugin/validation/XmlFileValidator.ts
+++ b/src/bscPlugin/validation/XmlFileValidator.ts
@@ -1,8 +1,9 @@
 import { DiagnosticMessages } from '../../DiagnosticMessages';
 import type { XmlFile } from '../../files/XmlFile';
 import type { OnFileValidateEvent } from '../../interfaces';
-import type { SGAst } from '../../parser/SGTypes';
+import type { SGAst, SGNode } from '../../parser/SGTypes';
 import util from '../../util';
+import { isValidSceneGraphFieldValue } from './FieldTypeValidator';
 
 export class XmlFileValidator {
     constructor(
@@ -60,6 +61,67 @@ export class XmlFileValidator {
                 range: explicitCodebehindScriptTag.filePathRange
             });
         }
+
+        //validate the node instances declared in the <children> block
+        for (const node of component.children?.children ?? []) {
+            this.validateNode(node);
+        }
+    }
+
+    /**
+     * Validate a single node instance and recurse into its children. Flags unknown node types, and (for
+     * known types) unknown/mis-cased field names and clearly-invalid field values.
+     */
+    private validateNode(node: SGNode) {
+        const nodeName = node.tag.text;
+        if (this.event.program.hasSceneGraphNode(nodeName)) {
+            this.validateNodeAttributes(node, nodeName);
+        } else {
+            this.event.file.diagnostics.push({
+                ...DiagnosticMessages.xmlUnknownComponentType(nodeName),
+                range: node.tag.range,
+                file: this.event.file
+            });
+        }
+        //recurse regardless, so nested typos are still reported
+        for (const child of node.children ?? []) {
+            this.validateNode(child);
+        }
+    }
+
+    private validateNodeAttributes(node: SGNode, nodeName: string) {
+        const fields = this.event.program.getSceneGraphNodeFields(nodeName);
+        //if we can't resolve any fields for a known node, don't guess (avoids mass false positives)
+        if (fields.length === 0) {
+            return;
+        }
+        const fieldsByLowerName = new Map(fields.map(field => [field.name.toLowerCase(), field]));
+        for (const attribute of node.attributes ?? []) {
+            const attributeName = attribute.key.text;
+            const field = fieldsByLowerName.get(attributeName.toLowerCase());
+            if (!field) {
+                this.event.file.diagnostics.push({
+                    ...DiagnosticMessages.xmlUnknownField(attributeName, nodeName),
+                    range: attribute.key.range,
+                    file: this.event.file
+                });
+                continue;
+            }
+            if (field.name !== attributeName) {
+                this.event.file.diagnostics.push({
+                    ...DiagnosticMessages.xmlFieldNameCaseMismatch(attributeName, field.name),
+                    range: attribute.key.range,
+                    file: this.event.file
+                });
+            }
+            if (field.type && !isValidSceneGraphFieldValue(attribute.value?.text, field.type)) {
+                this.event.file.diagnostics.push({
+                    ...DiagnosticMessages.xmlInvalidFieldValue(field.name, field.type),
+                    range: attribute.value?.range ?? attribute.key.range,
+                    file: this.event.file
+                });
+            }
+        }
     }
 
 }
diff --git a/src/files/XmlFile.spec.ts b/src/files/XmlFile.spec.ts
index 5cfe116b4..085f9b1bc 100644
--- a/src/files/XmlFile.spec.ts
+++ b/src/files/XmlFile.spec.ts
@@ -666,7 +666,7 @@ describe('XmlFile', () => {
                 <?xml version="1.0" encoding="utf-8" ?>
                 <component name="AnimationExample" extends="Scene">
                     <children>
-                        <Animated frames='["pkg:/images/animation-1.png"]' />
+                        <Poster uri='["pkg:/images/animation-1.png"]' />
                     </children>
                 </component>
             `, trim`
@@ -674,7 +674,7 @@ describe('XmlFile', () => {
                 <component name="AnimationExample" extends="Scene">
                     <script type="text/brightscript" uri="pkg:/source/bslib.brs" />
                     <children>
-                        <Animated frames='["pkg:/images/animation-1.png"]' />
+                        <Poster uri='["pkg:/images/animation-1.png"]' />
                     </children>
                 </component>
             `, 'none', 'components/Comp.xml');
@@ -849,9 +849,9 @@ describe('XmlFile', () => {
                     </interface>
                     <script type="text/brightscript" uri="SimpleScene.bs"/>
                     <children>
-                        <aa id="aa">
-                            <bb id="bb" />
-                        </aa>
+                        <Group id="aa">
+                            <Rectangle id="bb" />
+                        </Group>
                     </children>
                 </component>
             `, trim`
@@ -864,9 +864,9 @@ describe('XmlFile', () => {
                     <script type="text/brightscript" uri="SimpleScene.brs" />
                     <script type="text/brightscript" uri="pkg:/source/bslib.brs" />
                     <children>
-                        <aa id="aa">
-                            <bb id="bb" />
-                        </aa>
+                        <Group id="aa">
+                            <Rectangle id="bb" />
+                        </Group>
                     </children>
                 </component>
             `, 'none', 'components/SimpleScene.xml');

From a27b5e573a15fe17be91ad272edf57abfa95b037 Mon Sep 17 00:00:00 2001
From: Christopher Dwyer-Perkins <chris@inverted-solutions.com>
Date: Tue, 7 Jul 2026 17:18:04 -0300
Subject: [PATCH 3/4] Only offer node completions inside <children>

Node and component element completions were appearing everywhere in element
content (the component root, inside <interface>, etc.). Gate them on the
enclosing element so they only appear inside a <children> block or nested
inside another node; other locations now yield no node completions.
---
 src/files/XmlFile.spec.ts | 23 +++++++++---
 src/files/XmlFile.ts      | 74 ++++++++++++++++++++++++++++++++++++---
 2 files changed, 88 insertions(+), 9 deletions(-)

diff --git a/src/files/XmlFile.spec.ts b/src/files/XmlFile.spec.ts
index 5cfe116b4..373d87633 100644
--- a/src/files/XmlFile.spec.ts
+++ b/src/files/XmlFile.spec.ts
@@ -396,7 +396,7 @@ describe('XmlFile', () => {
         });
 
         //TODO - refine this test once cdata scripts are supported
-        it('provides xml element completions, never brightscript scope completions', () => {
+        it('does not provide node completions outside of <children>', () => {
             program.setFile('components/component1.brs', ``);
 
             let xmlFile = program.setFile('components/component1.xml', trim`
@@ -406,10 +406,8 @@ describe('XmlFile', () => {
                 </component>
             `);
 
-            const completions = program.getCompletions(xmlFile.srcPath, Position.create(1, 1));
-            //every completion is an xml element (node) completion, not a brightscript scope symbol
-            expect(completions).not.to.be.empty;
-            expect(completions.every(x => x.kind === CompletionItemKind.Class)).to.be.true;
+            //at the component root (not inside <children>) we should not spew node/scope completions
+            expect(program.getCompletions(xmlFile.srcPath, Position.create(1, 1))).to.be.empty;
         });
 
         /**
@@ -448,6 +446,21 @@ describe('XmlFile', () => {
             expect(completions.every(x => x.kind === CompletionItemKind.Class)).to.be.true;
         });
 
+        it('does not provide node completions inside <interface>', () => {
+            const xmlFile = program.setFile<XmlFile>('components/main.xml', trim`
+                <component name="Main" extends="Group">
+                    <interface>
+                        <
+                    </interface>
+                </component>
+            `);
+            const lines = xmlFile.fileContents.split('\n');
+            const lineIndex = lines.findIndex(line => line.trim() === '<');
+            const completions = xmlFile.getCompletions(Position.create(lineIndex, lines[lineIndex].indexOf('<') + 1));
+            //nodes/components are only valid inside <children>, not inside <interface>
+            expect(completions).to.be.empty;
+        });
+
         it('provides field completions inside an open element tag', () => {
             const xmlFile = program.setFile<XmlFile>('components/main.xml', trim`
                 <component name="Main" extends="Group">
diff --git a/src/files/XmlFile.ts b/src/files/XmlFile.ts
index 5f3faafbb..aa62d9252 100644
--- a/src/files/XmlFile.ts
+++ b/src/files/XmlFile.ts
@@ -417,7 +417,7 @@ export class XmlFile {
             const tagNameToken = tokens[boundaryIndex + 1];
             //no tag name yet, or the cursor is still on/within the tag name -> complete element names
             if (tagNameToken?.tokenType.name !== XmlTokenName.name || util.comparePositionToRange(position, this.getTokenRange(tagNameToken)) <= 0) {
-                return this.getElementCompletions(false);
+                return this.getElementCompletions(position, false);
             }
             //otherwise complete attribute (field) names for the enclosing node
             return this.getAttributeCompletions(tagNameToken.image, this.getExistingAttributeNames(boundaryIndex + 2));
@@ -425,7 +425,7 @@ export class XmlFile {
 
         //cursor is in element content (right after a `>` / `/>`) -> complete child element names
         if (boundary?.tokenType.name === XmlTokenName.close || boundary?.tokenType.name === XmlTokenName.slashClose) {
-            return this.getElementCompletions(true);
+            return this.getElementCompletions(position, true);
         }
 
         //inside a closing tag (`</...`), before any tag, or any other position -> no completions
@@ -433,11 +433,19 @@ export class XmlFile {
     }
 
     /**
-     * Get element (tag name) completions for every known SceneGraph node and project component.
+     * Get element (tag name) completions for the node/component types valid at this position. Nodes and
+     * components are only valid inside a `<children>` block (or nested inside another node), so this returns
+     * nothing at the component root, inside `<interface>`, etc. (those elements are handled by snippets).
+     * @param position the cursor position, used to determine the enclosing element
      * @param includeOpenBracket whether to prefix the inserted snippet with `<` (true when the cursor is
      * not already immediately after an `<`)
      */
-    private getElementCompletions(includeOpenBracket: boolean): CompletionItem[] {
+    private getElementCompletions(position: Position, includeOpenBracket: boolean): CompletionItem[] {
+        const container = this.getEnclosingElementName(position)?.toLowerCase();
+        //only offer node/component completions inside <children> or nested inside another node
+        if (container !== 'children' && !(container && this.program.hasSceneGraphNode(container))) {
+            return [];
+        }
         const ownComponentName = this.componentName?.text?.toLowerCase();
         const openBracket = includeOpenBracket ? '<' : '';
         return this.program.getSceneGraphNodeNames()
@@ -495,6 +503,64 @@ export class XmlFile {
         return names;
     }
 
+    /**
+     * Determine the name of the element that directly encloses the given position, by walking the tokens
+     * and tracking a stack of open (content-bearing) elements. Self-closing tags and closed tags are not
+     * on the stack, so the result is the nearest ancestor whose start tag closed before the cursor.
+     * Returns undefined at the top level of the document.
+     */
+    private getEnclosingElementName(position: Position): string | undefined {
+        const tokens = (this.parser.tokens ?? []) as unknown as IToken[];
+        const stack: string[] = [];
+        let expectingTagName = false;
+        let isCloseTag = false;
+        let currentTag: string | undefined;
+        for (const token of tokens) {
+            const startLine = (token.startLine ?? 1) - 1;
+            const startCharacter = (token.startColumn ?? 1) - 1;
+            //tokens are ordered, so stop once one starts at or after the cursor
+            if (position.line < startLine || (position.line === startLine && position.character <= startCharacter)) {
+                break;
+            }
+            switch (token.tokenType.name) {
+                case XmlTokenName.open:
+                    expectingTagName = true;
+                    isCloseTag = false;
+                    currentTag = undefined;
+                    break;
+                case XmlTokenName.slashOpen:
+                    expectingTagName = true;
+                    isCloseTag = true;
+                    currentTag = undefined;
+                    break;
+                case XmlTokenName.name:
+                    //the first Name after an opener is the tag name; later Names are attributes
+                    if (expectingTagName) {
+                        currentTag = token.image;
+                        expectingTagName = false;
+                    }
+                    break;
+                case XmlTokenName.close:
+                    if (isCloseTag) {
+                        stack.pop();
+                    } else if (currentTag) {
+                        stack.push(currentTag);
+                    }
+                    currentTag = undefined;
+                    isCloseTag = false;
+                    expectingTagName = false;
+                    break;
+                case XmlTokenName.slashClose:
+                    //self-closing start tag; nothing is pushed
+                    currentTag = undefined;
+                    isCloseTag = false;
+                    expectingTagName = false;
+                    break;
+            }
+        }
+        return stack[stack.length - 1];
+    }
+
     /**
      * Get the xml token whose range contains the given position (used by completions and hover)
      */

From 7abfbb76fd0bff89dac6dddfc9b8a7a43b9bf941 Mon Sep 17 00:00:00 2001
From: Christopher Dwyer-Perkins <chris@inverted-solutions.com>
Date: Thu, 9 Jul 2026 20:06:31 -0300
Subject: [PATCH 4/4] Address review feedback on xml validation

- Skip the unknown-component diagnostic for component-library components
  (tag names containing ':'), which can't be resolved yet
- Add an onValidateXmlAttribute plugin event so plugins can claim an
  attribute (handled: true) to opt it out of field validation
- Promote xmlInvalidFieldValue from warning to error
- Remove the field-name case-mismatch diagnostic (belongs in eslint)
- Flag mismatched opening/closing tag names in SGParser (xml-tools matches
  them case-insensitively, but Roku does not)
- Rename FieldTypeValidator -> XmlFieldTypeValidator
---
 src/DiagnosticMessages.ts                     | 12 ++---
 ...eValidator.ts => XmlFieldTypeValidator.ts} |  0
 .../validation/XmlFileValidator.spec.ts       | 50 +++++++++++++++----
 src/bscPlugin/validation/XmlFileValidator.ts  | 36 +++++++++----
 src/interfaces.ts                             | 24 +++++++++
 src/parser/SGParser.spec.ts                   | 16 ++++++
 src/parser/SGParser.ts                        | 29 ++++++++---
 7 files changed, 134 insertions(+), 33 deletions(-)
 rename src/bscPlugin/validation/{FieldTypeValidator.ts => XmlFieldTypeValidator.ts} (100%)

diff --git a/src/DiagnosticMessages.ts b/src/DiagnosticMessages.ts
index b4b3dee39..86a619121 100644
--- a/src/DiagnosticMessages.ts
+++ b/src/DiagnosticMessages.ts
@@ -844,15 +844,15 @@ export let DiagnosticMessages = {
         code: 1156,
         severity: DiagnosticSeverity.Error
     }),
-    xmlFieldNameCaseMismatch: (actualName: string, expectedName: string) => ({
-        message: `Field '${actualName}' should be '${expectedName}' to match the declared casing`,
-        code: 1157,
-        severity: DiagnosticSeverity.Warning
-    }),
     xmlInvalidFieldValue: (fieldName: string, expectedType: string) => ({
         message: `Value for field '${fieldName}' is not a valid '${expectedType}'`,
+        code: 1157,
+        severity: DiagnosticSeverity.Error
+    }),
+    xmlStartEndTagMismatch: (openName: string, closeName: string) => ({
+        message: `Opening tag '${openName}' does not match closing tag '${closeName}'`,
         code: 1158,
-        severity: DiagnosticSeverity.Warning
+        severity: DiagnosticSeverity.Error
     })
 };
 
diff --git a/src/bscPlugin/validation/FieldTypeValidator.ts b/src/bscPlugin/validation/XmlFieldTypeValidator.ts
similarity index 100%
rename from src/bscPlugin/validation/FieldTypeValidator.ts
rename to src/bscPlugin/validation/XmlFieldTypeValidator.ts
diff --git a/src/bscPlugin/validation/XmlFileValidator.spec.ts b/src/bscPlugin/validation/XmlFileValidator.spec.ts
index 0dc502409..73765c135 100644
--- a/src/bscPlugin/validation/XmlFileValidator.spec.ts
+++ b/src/bscPlugin/validation/XmlFileValidator.spec.ts
@@ -62,7 +62,7 @@ describe('XmlFileValidator', () => {
         expect(scenegraphDiagnostics(file).map(x => x.code)).to.include(1156);
     });
 
-    it('flags a field name case mismatch', () => {
+    it('does not flag a case-differing field name (no longer a diagnostic)', () => {
         const file = program.setFile<XmlFile>('components/main.xml', trim`
             <component name="Main" extends="Group">
                 <children>
@@ -71,7 +71,7 @@ describe('XmlFileValidator', () => {
             </component>
         `);
         program.validate();
-        expect(scenegraphDiagnostics(file).map(x => x.code)).to.include(1157);
+        expect(scenegraphDiagnostics(file)).to.be.empty;
     });
 
     it('flags a clearly-invalid scalar field value but allows valid and ambiguous ones', () => {
@@ -90,23 +90,53 @@ describe('XmlFileValidator', () => {
             </component>
         `);
         program.validate();
-        expect(scenegraphDiagnostics(badFile).map(x => x.code)).to.include(1158);
+        expect(scenegraphDiagnostics(badFile).map(x => x.code)).to.include(1157);
         expect(scenegraphDiagnostics(goodFile)).to.be.empty;
     });
 
-    it('validates fields on ContentNode against its known schema', () => {
+    it('does not flag component-library components', () => {
+        const file = program.setFile<XmlFile>('components/main.xml', trim`
+            <component name="Main" extends="Group">
+                <children>
+                    <MyLib:SomeView />
+                </children>
+            </component>
+        `);
+        program.validate();
+        //complib-scoped names (containing ':') can't be resolved yet, so they should not be flagged
+        expect(scenegraphDiagnostics(file)).to.be.empty;
+    });
+
+    it('lets a plugin claim an attribute to opt out of field validation', () => {
+        const file = program.setFile<XmlFile>('components/main.xml', trim`
+            <component name="Main" extends="Group">
+                <children>
+                    <Label data-custom="x" />
+                </children>
+            </component>
+        `);
+        program.plugins.add({
+            name: 'claims custom attributes',
+            onValidateXmlAttribute: (event) => {
+                if (event.attribute.key.text.startsWith('data-')) {
+                    event.handled = true;
+                }
+            }
+        });
+        program.validate();
+        //the plugin claimed `data-custom`, so brighterscript should not flag it as an unknown field
+        expect(scenegraphDiagnostics(file)).to.be.empty;
+    });
+
+    it('flags mismatched opening and closing tag names', () => {
         const file = program.setFile<XmlFile>('components/main.xml', trim`
             <component name="Main" extends="Group">
                 <children>
-                    <ContentNode Title="Home" bogusField="x" />
+                    <Rectangle></rectangle>
                 </children>
             </component>
         `);
         program.validate();
-        const codes = scenegraphDiagnostics(file).map(x => x.code);
-        //`Title` is a real ContentNode field, correctly cased -> no diagnostic
-        expect(codes).not.to.include(1157);
-        //`bogusField` is not a ContentNode field -> unknown field
-        expect(codes).to.include(1156);
+        expect(scenegraphDiagnostics(file).map(x => x.code)).to.include(1158);
     });
 });
diff --git a/src/bscPlugin/validation/XmlFileValidator.ts b/src/bscPlugin/validation/XmlFileValidator.ts
index d600db6b6..979e639db 100644
--- a/src/bscPlugin/validation/XmlFileValidator.ts
+++ b/src/bscPlugin/validation/XmlFileValidator.ts
@@ -1,9 +1,9 @@
 import { DiagnosticMessages } from '../../DiagnosticMessages';
 import type { XmlFile } from '../../files/XmlFile';
 import type { OnFileValidateEvent } from '../../interfaces';
-import type { SGAst, SGNode } from '../../parser/SGTypes';
+import type { SGAst, SGAttribute, SGNode } from '../../parser/SGTypes';
 import util from '../../util';
-import { isValidSceneGraphFieldValue } from './FieldTypeValidator';
+import { isValidSceneGraphFieldValue } from './XmlFieldTypeValidator';
 
 export class XmlFileValidator {
     constructor(
@@ -70,13 +70,14 @@ export class XmlFileValidator {
 
     /**
      * Validate a single node instance and recurse into its children. Flags unknown node types, and (for
-     * known types) unknown/mis-cased field names and clearly-invalid field values.
+     * known types) unknown field names and clearly-invalid field values.
      */
     private validateNode(node: SGNode) {
         const nodeName = node.tag.text;
         if (this.event.program.hasSceneGraphNode(nodeName)) {
             this.validateNodeAttributes(node, nodeName);
-        } else {
+        //skip component-library components (e.g. `ComplibName:SomeView`); we can't resolve those yet
+        } else if (!nodeName.includes(':')) {
             this.event.file.diagnostics.push({
                 ...DiagnosticMessages.xmlUnknownComponentType(nodeName),
                 range: node.tag.range,
@@ -97,6 +98,10 @@ export class XmlFileValidator {
         }
         const fieldsByLowerName = new Map(fields.map(field => [field.name.toLowerCase(), field]));
         for (const attribute of node.attributes ?? []) {
+            //let plugins claim an attribute (e.g. custom/transformed attributes) before we validate it
+            if (this.isAttributeHandledByPlugin(node, attribute)) {
+                continue;
+            }
             const attributeName = attribute.key.text;
             const field = fieldsByLowerName.get(attributeName.toLowerCase());
             if (!field) {
@@ -107,13 +112,6 @@ export class XmlFileValidator {
                 });
                 continue;
             }
-            if (field.name !== attributeName) {
-                this.event.file.diagnostics.push({
-                    ...DiagnosticMessages.xmlFieldNameCaseMismatch(attributeName, field.name),
-                    range: attribute.key.range,
-                    file: this.event.file
-                });
-            }
             if (field.type && !isValidSceneGraphFieldValue(attribute.value?.text, field.type)) {
                 this.event.file.diagnostics.push({
                     ...DiagnosticMessages.xmlInvalidFieldValue(field.name, field.type),
@@ -124,4 +122,20 @@ export class XmlFileValidator {
         }
     }
 
+    /**
+     * Emit the `onValidateXmlAttribute` event so plugins can claim an attribute (returning `handled: true`)
+     * to opt it out of brighterscript's built-in field validation.
+     */
+    private isAttributeHandledByPlugin(node: SGNode, attribute: SGAttribute): boolean {
+        const event = {
+            program: this.event.program,
+            file: this.event.file,
+            node: node,
+            attribute: attribute,
+            handled: false
+        };
+        this.event.program.plugins.emit('onValidateXmlAttribute', event);
+        return event.handled;
+    }
+
 }
diff --git a/src/interfaces.ts b/src/interfaces.ts
index 938167c5b..e85c653e7 100644
--- a/src/interfaces.ts
+++ b/src/interfaces.ts
@@ -8,6 +8,7 @@ import type { ParseMode } from './parser/Parser';
 import type { Program, SourceObj, TranspileObj } from './Program';
 import type { ProgramBuilder } from './ProgramBuilder';
 import type { FunctionStatement } from './parser/Statement';
+import type { SGAttribute, SGNode } from './parser/SGTypes';
 import type { Expression } from './parser/AstNode';
 import type { TranspileState } from './parser/TranspileState';
 import type { SourceMapGenerator, SourceNode } from 'source-map';
@@ -390,6 +391,12 @@ export interface Plugin {
      * Called during the file validation process. If your plugin contributes file validations, this is a good place to contribute them.
      */
     onFileValidate?: PluginHandler<OnFileValidateEvent>;
+    /**
+     * Called while validating each attribute on a SceneGraph node in an xml component. Set `handled: true`
+     * to claim the attribute so brighterscript skips its own field validation of it (useful for plugins
+     * that inject or transform custom attributes).
+     */
+    onValidateXmlAttribute?: PluginHandler<OnValidateXmlAttributeEvent>;
     /**
      * Called after each file is validated
      */
@@ -593,6 +600,23 @@ export interface OnFileValidateEvent<T extends BscFile = BscFile> {
     file: T;
 }
 
+export interface OnValidateXmlAttributeEvent {
+    program: Program;
+    file: XmlFile;
+    /**
+     * The SceneGraph node the attribute is declared on
+     */
+    node: SGNode;
+    /**
+     * The attribute being validated
+     */
+    attribute: SGAttribute;
+    /**
+     * Set to `true` from a plugin to claim this attribute, so brighterscript skips its own validation of it
+     */
+    handled: boolean;
+}
+
 export interface OnScopeValidateEvent {
     program: Program;
     scope: Scope;
diff --git a/src/parser/SGParser.spec.ts b/src/parser/SGParser.spec.ts
index 22f7f451e..cbfea3323 100644
--- a/src/parser/SGParser.spec.ts
+++ b/src/parser/SGParser.spec.ts
@@ -113,6 +113,22 @@ describe('SGParser', () => {
         });
     });
 
+    it('Adds error when opening and closing tag names do not match', () => {
+        const parser = new SGParser();
+        parser.parse(
+            'pkg:/components/ChildScene.xml', trim`
+            <?xml version="1.0" encoding="utf-8" ?>
+            <component name="ChildScene" extends="Scene">
+                <children>
+                    <Rectangle></rectangle>
+                </children>
+            </component>
+        `);
+        expect(parser.diagnostics.map(x => x.code)).to.include(
+            DiagnosticMessages.xmlStartEndTagMismatch('Rectangle', 'rectangle').code
+        );
+    });
+
     it('Adds error when a leaf tag is found to have children', () => {
         const parser = new SGParser();
         parser.parse(
diff --git a/src/parser/SGParser.ts b/src/parser/SGParser.ts
index 21f55a80b..233498a8f 100644
--- a/src/parser/SGParser.ts
+++ b/src/parser/SGParser.ts
@@ -178,6 +178,7 @@ interface IToken {
 }
 
 function mapElement({ children }: ElementCstNode, diagnostics: Diagnostic[]): SGTag {
+    validateTagNameMatch(children, diagnostics);
     const nameToken = children.Name[0];
     let range: Range;
     const selfClosing = !!children.SLASH_CLOSE;
@@ -215,10 +216,10 @@ function mapElement({ children }: ElementCstNode, diagnostics: Diagnostic[]): SG
             const cdata = getCdata(content);
             return new SGScript(name, attributes, cdata, range);
         case 'children':
-            const childrenContent = mapNodes(content);
+            const childrenContent = mapNodes(content, diagnostics);
             return new SGChildren(name, childrenContent, range);
         default:
-            const nodeContent = mapNodes(content);
+            const nodeContent = mapNodes(content, diagnostics);
             return new SGNode(name, attributes, nodeContent, range);
     }
 }
@@ -230,12 +231,13 @@ function reportUnexpectedChildren(name: SGToken, diagnostics: Diagnostic[]) {
     });
 }
 
-function mapNode({ children }: ElementCstNode): SGNode | undefined {
+function mapNode({ children }: ElementCstNode, diagnostics: Diagnostic[]): SGNode | undefined {
     const nameToken = children.Name?.[0];
     //skip malformed elements that have no tag name (e.g. a lone `<` while the user is still typing)
     if (!nameToken) {
         return undefined;
     }
+    validateTagNameMatch(children, diagnostics);
     let range: Range;
     const selfClosing = !!children.SLASH_CLOSE;
     if (selfClosing) {
@@ -248,10 +250,25 @@ function mapNode({ children }: ElementCstNode): SGNode | undefined {
     const name = mapToken(nameToken);
     const attributes = mapAttributes(children.attribute);
     const content = children.content?.[0];
-    const nodeContent = mapNodes(content);
+    const nodeContent = mapNodes(content, diagnostics);
     return new SGNode(name, attributes, nodeContent, range);
 }
 
+/**
+ * `@xml-tools` matches start/end tag names case-insensitively, but Roku's compiler does not. Flag any
+ * difference (including case) between an element's opening and closing tag names.
+ */
+function validateTagNameMatch(children: ElementCstNode['children'], diagnostics: Diagnostic[]) {
+    const openName = children.Name?.[0];
+    const closeName = children.END_NAME?.[0];
+    if (openName && closeName && openName.image !== closeName.image) {
+        diagnostics.push({
+            ...DiagnosticMessages.xmlStartEndTagMismatch(openName.image, closeName.image),
+            range: rangeFromTokens(closeName)
+        });
+    }
+}
+
 function mapElements(content: ContentCstNode, allow: string[], diagnostics: Diagnostic[]): SGTag[] {
     if (!content) {
         return [];
@@ -279,13 +296,13 @@ function mapElements(content: ContentCstNode, allow: string[], diagnostics: Diag
     return tags;
 }
 
-function mapNodes(content: ContentCstNode): SGNode[] {
+function mapNodes(content: ContentCstNode, diagnostics: Diagnostic[]): SGNode[] {
     if (!content) {
         return [];
     }
     const { element } = content.children;
     return element
-        ?.map(element => mapNode(element))
+        ?.map(element => mapNode(element, diagnostics))
         .filter((node): node is SGNode => !!node);
 }