@holoscript/robotics-plugin 2.0.2 → 2.0.3

package/dist/lexer.js

@@ -0,0 +1,251 @@
+/**
+ * HoloScript Lexer (Tokenizer)
+ *
+ * Converts HoloScript source code into a stream of tokens for parsing.
+ * Supports: keywords, identifiers, traits (@trait), strings, numbers, symbols
+ */
+export var TokenType;
+(function (TokenType) {
+    // Keywords
+    TokenType["KEYWORD"] = "KEYWORD";
+    // Identifiers & Traits
+    TokenType["IDENTIFIER"] = "IDENTIFIER";
+    TokenType["TRAIT"] = "TRAIT";
+    TokenType["STRING"] = "STRING";
+    TokenType["NUMBER"] = "NUMBER";
+    // Symbols
+    TokenType["LBRACE"] = "LBRACE";
+    TokenType["RBRACE"] = "RBRACE";
+    TokenType["LBRACKET"] = "LBRACKET";
+    TokenType["RBRACKET"] = "RBRACKET";
+    TokenType["COLON"] = "COLON";
+    TokenType["COMMA"] = "COMMA";
+    // Special
+    TokenType["COMMENT"] = "COMMENT";
+    TokenType["EOF"] = "EOF";
+})(TokenType || (TokenType = {}));
+export class Lexer {
+    constructor(source) {
+        this.position = 0;
+        this.line = 1;
+        this.column = 1;
+        this.tokens = [];
+        this.keywords = new Set([
+            'composition',
+            'object',
+            'using',
+            'template',
+            'group',
+            'scene',
+        ]);
+        this.source = source;
+    }
+    tokenize() {
+        while (this.position < this.source.length) {
+            this.scanToken();
+        }
+        this.tokens.push({
+            type: TokenType.EOF,
+            value: '',
+            line: this.line,
+            column: this.column,
+        });
+        return this.tokens;
+    }
+    scanToken() {
+        const char = this.currentChar();
+        // Skip whitespace
+        if (this.isWhitespace(char)) {
+            this.skipWhitespace();
+            return;
+        }
+        // Comments
+        if (char === '/' && this.peek() === '/') {
+            this.skipComment();
+            return;
+        }
+        // Traits (@identifier)
+        if (char === '@') {
+            this.scanTrait();
+            return;
+        }
+        // String literals ("...")
+        if (char === '"') {
+            this.scanString();
+            return;
+        }
+        // Numbers (0.1, 3.14, -2.0)
+        if (this.isDigit(char) || (char === '-' && this.isDigit(this.peek()))) {
+            this.scanNumber();
+            return;
+        }
+        // Keywords & Identifiers
+        if (this.isAlpha(char)) {
+            this.scanIdentifierOrKeyword();
+            return;
+        }
+        // Single-character tokens
+        this.scanSymbol(char);
+    }
+    scanTrait() {
+        const startLine = this.line;
+        const startColumn = this.column;
+        this.advance(); // Skip '@'
+        let trait = '';
+        while (this.position < this.source.length &&
+            this.isAlphaNumericOrUnderscore(this.currentChar())) {
+            trait += this.currentChar();
+            this.advance();
+        }
+        this.tokens.push({
+            type: TokenType.TRAIT,
+            value: trait,
+            line: startLine,
+            column: startColumn,
+        });
+    }
+    scanString() {
+        const startLine = this.line;
+        const startColumn = this.column;
+        this.advance(); // Skip opening "
+        let str = '';
+        while (this.position < this.source.length && this.currentChar() !== '"') {
+            if (this.currentChar() === '\\') {
+                // Handle escape sequences
+                this.advance();
+                if (this.position < this.source.length) {
+                    str += this.currentChar();
+                    this.advance();
+                }
+            }
+            else {
+                str += this.currentChar();
+                this.advance();
+            }
+        }
+        if (this.currentChar() === '"') {
+            this.advance(); // Skip closing "
+        }
+        else {
+            throw new Error(`Unterminated string at line ${startLine}, column ${startColumn}`);
+        }
+        this.tokens.push({
+            type: TokenType.STRING,
+            value: str,
+            line: startLine,
+            column: startColumn,
+        });
+    }
+    scanNumber() {
+        const startLine = this.line;
+        const startColumn = this.column;
+        let num = '';
+        // Handle negative sign
+        if (this.currentChar() === '-') {
+            num += this.currentChar();
+            this.advance();
+        }
+        // Integer part
+        while (this.position < this.source.length && this.isDigit(this.currentChar())) {
+            num += this.currentChar();
+            this.advance();
+        }
+        // Decimal part
+        if (this.currentChar() === '.' && this.isDigit(this.peek())) {
+            num += this.currentChar();
+            this.advance();
+            while (this.position < this.source.length && this.isDigit(this.currentChar())) {
+                num += this.currentChar();
+                this.advance();
+            }
+        }
+        this.tokens.push({
+            type: TokenType.NUMBER,
+            value: num,
+            line: startLine,
+            column: startColumn,
+        });
+    }
+    scanIdentifierOrKeyword() {
+        const startLine = this.line;
+        const startColumn = this.column;
+        let ident = '';
+        while (this.position < this.source.length &&
+            this.isAlphaNumericOrUnderscore(this.currentChar())) {
+            ident += this.currentChar();
+            this.advance();
+        }
+        const type = this.keywords.has(ident) ? TokenType.KEYWORD : TokenType.IDENTIFIER;
+        this.tokens.push({
+            type,
+            value: ident,
+            line: startLine,
+            column: startColumn,
+        });
+    }
+    scanSymbol(char) {
+        const symbolMap = {
+            '{': TokenType.LBRACE,
+            '}': TokenType.RBRACE,
+            '[': TokenType.LBRACKET,
+            ']': TokenType.RBRACKET,
+            ':': TokenType.COLON,
+            ',': TokenType.COMMA,
+        };
+        const tokenType = symbolMap[char];
+        if (tokenType) {
+            this.tokens.push({
+                type: tokenType,
+                value: char,
+                line: this.line,
+                column: this.column,
+            });
+            this.advance();
+        }
+        else {
+            throw new Error(`Unexpected character '${char}' at line ${this.line}, column ${this.column}`);
+        }
+    }
+    skipWhitespace() {
+        while (this.position < this.source.length && this.isWhitespace(this.currentChar())) {
+            if (this.currentChar() === '\n') {
+                this.line++;
+                this.column = 1;
+            }
+            else {
+                this.column++;
+            }
+            this.position++;
+        }
+    }
+    skipComment() {
+        // Skip until end of line
+        while (this.position < this.source.length && this.currentChar() !== '\n') {
+            this.position++;
+            this.column++;
+        }
+    }
+    currentChar() {
+        return this.source[this.position] || '';
+    }
+    peek(offset = 1) {
+        const peekPos = this.position + offset;
+        return this.source[peekPos] || '';
+    }
+    advance() {
+        this.position++;
+        this.column++;
+    }
+    isWhitespace(char) {
+        return /\s/.test(char);
+    }
+    isDigit(char) {
+        return /[0-9]/.test(char);
+    }
+    isAlpha(char) {
+        return /[a-z_]/i.test(char);
+    }
+    isAlphaNumericOrUnderscore(char) {
+        return /[a-z0-9_]/i.test(char);
+    }
+}

package/dist/parser.d.ts

@@ -0,0 +1,30 @@
+/**
+ * HoloScript Parser
+ *
+ * Converts token stream into Abstract Syntax Tree (AST).
+ * Uses recursive descent parsing.
+ */
+import { Token } from './lexer.js';
+import { CompositionNode } from './ast.js';
+export declare class Parser {
+    private tokens;
+    private position;
+    constructor(tokens: Token[]);
+    parse(): CompositionNode;
+    private currentToken;
+    private peek;
+    private advance;
+    private expect;
+    private parseComposition;
+    private parseObject;
+    private parseValue;
+    private parseArray;
+    private parseDomainRandomizationBlock;
+    private parsePhysicsRandomization;
+    private parseActuatorRandomization;
+    private parseObservationRandomization;
+    private parseInitialStateRandomization;
+    private parseNumberRangeMap;
+    private parseDisturbanceRandomization;
+    private parseActuatorGroupBlock;
+}

package/dist/parser.js

@@ -0,0 +1,376 @@
+/**
+ * HoloScript Parser
+ *
+ * Converts token stream into Abstract Syntax Tree (AST).
+ * Uses recursive descent parsing.
+ */
+import { TokenType } from './lexer.js';
+export class Parser {
+    constructor(tokens) {
+        this.position = 0;
+        this.tokens = tokens;
+    }
+    parse() {
+        return this.parseComposition();
+    }
+    currentToken() {
+        const token = this.tokens[this.position];
+        if (!token) {
+            throw new Error('Unexpected end of input');
+        }
+        return token;
+    }
+    peek(offset = 1) {
+        const pos = this.position + offset;
+        const token = pos < this.tokens.length ? this.tokens[pos] : this.tokens[this.tokens.length - 1];
+        if (!token) {
+            throw new Error('Unexpected end of input');
+        }
+        return token;
+    }
+    advance() {
+        const token = this.currentToken();
+        this.position++;
+        return token;
+    }
+    expect(type, value) {
+        const token = this.currentToken();
+        if (token.type !== type) {
+            throw new Error(`Expected ${type}${value ? ` "${value}"` : ''} but got ${token.type} "${token.value}" at line ${token.line}, column ${token.column}`);
+        }
+        if (value !== undefined && token.value !== value) {
+            throw new Error(`Expected "${value}" but got "${token.value}" at line ${token.line}, column ${token.column}`);
+        }
+        return this.advance();
+    }
+    parseComposition() {
+        const startToken = this.expect(TokenType.KEYWORD, 'composition');
+        const name = this.expect(TokenType.STRING).value;
+        this.expect(TokenType.LBRACE);
+        const objects = [];
+        let domainRandomization;
+        while (this.currentToken().type !== TokenType.RBRACE &&
+            this.currentToken().type !== TokenType.EOF) {
+            // Check for domain_randomization block at composition level
+            if (this.currentToken().type === TokenType.IDENTIFIER &&
+                this.currentToken().value === 'domain_randomization') {
+                this.advance();
+                this.expect(TokenType.COLON);
+                domainRandomization = this.parseDomainRandomizationBlock();
+            }
+            else {
+                objects.push(this.parseObject());
+            }
+        }
+        this.expect(TokenType.RBRACE);
+        return {
+            type: 'composition',
+            name,
+            objects,
+            domainRandomization,
+            line: startToken.line,
+            column: startToken.column,
+        };
+    }
+    parseObject() {
+        const startToken = this.expect(TokenType.KEYWORD, 'object');
+        const name = this.expect(TokenType.STRING).value;
+        // Parse traits (@trait1 @trait2 ...)
+        const traits = [];
+        while (this.currentToken().type === TokenType.TRAIT) {
+            traits.push(this.advance().value);
+        }
+        this.expect(TokenType.LBRACE);
+        // Parse properties (key: value)
+        const properties = {};
+        let domainRandomization;
+        let actuatorGroups;
+        while (this.currentToken().type !== TokenType.RBRACE &&
+            this.currentToken().type !== TokenType.EOF) {
+            // Support both object "link" @trait { ... } and object "link" { @trait ... }.
+            if (this.currentToken().type === TokenType.TRAIT) {
+                const trait = this.advance().value;
+                if (!traits.includes(trait)) {
+                    traits.push(trait);
+                }
+            }
+            // Check for domain_randomization block
+            else if (this.currentToken().type === TokenType.IDENTIFIER &&
+                this.currentToken().value === 'domain_randomization') {
+                this.advance();
+                this.expect(TokenType.COLON);
+                domainRandomization = this.parseDomainRandomizationBlock();
+            }
+            // Check for actuator_group block
+            else if (this.currentToken().type === TokenType.IDENTIFIER &&
+                this.currentToken().value === 'actuator_group') {
+                this.advance();
+                this.expect(TokenType.COLON);
+                const group = this.parseActuatorGroupBlock();
+                if (!actuatorGroups)
+                    actuatorGroups = [];
+                actuatorGroups.push(group);
+            }
+            // Regular property
+            else {
+                const keyName = this.expect(TokenType.IDENTIFIER).value;
+                this.expect(TokenType.COLON);
+                const value = this.parseValue();
+                properties[keyName] = value;
+            }
+        }
+        this.expect(TokenType.RBRACE);
+        return {
+            type: 'object',
+            name,
+            traits,
+            properties,
+            domainRandomization,
+            actuatorGroups,
+            line: startToken.line,
+            column: startToken.column,
+        };
+    }
+    parseValue() {
+        const token = this.currentToken();
+        // String value
+        if (token.type === TokenType.STRING) {
+            return this.advance().value;
+        }
+        // Number value
+        if (token.type === TokenType.NUMBER) {
+            return parseFloat(this.advance().value);
+        }
+        // Array value [1, 2, 3]
+        if (token.type === TokenType.LBRACKET) {
+            return this.parseArray();
+        }
+        // Function call (for future: diagonal([1, 2, 3]))
+        if (token.type === TokenType.IDENTIFIER && this.peek().type === TokenType.LBRACKET) {
+            this.advance(); // Skip function name for now
+            const args = this.parseArray();
+            // For now, treat function calls as arrays (e.g., diagonal([1,2,3]) -> [1,2,3])
+            // In future, could preserve function name metadata
+            return args;
+        }
+        throw new Error(`Unexpected value type ${token.type} "${token.value}" at line ${token.line}, column ${token.column}`);
+    }
+    parseArray() {
+        this.expect(TokenType.LBRACKET);
+        const values = [];
+        while (this.currentToken().type !== TokenType.RBRACKET &&
+            this.currentToken().type !== TokenType.EOF) {
+            if (this.currentToken().type === TokenType.NUMBER) {
+                values.push(parseFloat(this.advance().value));
+            }
+            else if (this.currentToken().type === TokenType.STRING) {
+                values.push(this.advance().value);
+            }
+            else if (this.currentToken().type === TokenType.LBRACKET) {
+                // Nested array
+                values.push(this.parseArray());
+            }
+            else {
+                throw new Error(`Unexpected token in array: ${this.currentToken().type} at line ${this.currentToken().line}`);
+            }
+            // Optional comma
+            if (this.currentToken().type === TokenType.COMMA) {
+                this.advance();
+            }
+        }
+        this.expect(TokenType.RBRACKET);
+        return values;
+    }
+    parseDomainRandomizationBlock() {
+        this.expect(TokenType.LBRACE);
+        const config = {};
+        while (this.currentToken().type !== TokenType.RBRACE &&
+            this.currentToken().type !== TokenType.EOF) {
+            const key = this.expect(TokenType.IDENTIFIER).value;
+            this.expect(TokenType.COLON);
+            switch (key) {
+                case 'physics':
+                    config.physics = this.parsePhysicsRandomization();
+                    break;
+                case 'actuator':
+                    config.actuator = this.parseActuatorRandomization();
+                    break;
+                case 'observation':
+                    config.observation = this.parseObservationRandomization();
+                    break;
+                case 'initialState':
+                    config.initialState = this.parseInitialStateRandomization();
+                    break;
+                case 'disturbance':
+                    config.disturbance = this.parseDisturbanceRandomization();
+                    break;
+                default:
+                    // Skip unknown keys
+                    this.parseValue();
+            }
+        }
+        this.expect(TokenType.RBRACE);
+        return config;
+    }
+    parsePhysicsRandomization() {
+        this.expect(TokenType.LBRACE);
+        const physics = {};
+        while (this.currentToken().type !== TokenType.RBRACE &&
+            this.currentToken().type !== TokenType.EOF) {
+            const key = this.expect(TokenType.IDENTIFIER).value;
+            this.expect(TokenType.COLON);
+            const value = this.parseValue();
+            if (key === 'massScale' && Array.isArray(value)) {
+                physics.massScale = [value[0], value[1]];
+            }
+            else if (key === 'frictionRange' && Array.isArray(value)) {
+                physics.frictionRange = [value[0], value[1]];
+            }
+            else if (key === 'dampingRange' && Array.isArray(value)) {
+                physics.dampingRange = [value[0], value[1]];
+            }
+            else if (key === 'armatureRange' && Array.isArray(value)) {
+                physics.armatureRange = [value[0], value[1]];
+            }
+        }
+        this.expect(TokenType.RBRACE);
+        return physics;
+    }
+    parseActuatorRandomization() {
+        this.expect(TokenType.LBRACE);
+        const actuator = {};
+        while (this.currentToken().type !== TokenType.RBRACE &&
+            this.currentToken().type !== TokenType.EOF) {
+            const key = this.expect(TokenType.IDENTIFIER).value;
+            this.expect(TokenType.COLON);
+            const value = this.parseValue();
+            if (key === 'kpNoise' && typeof value === 'number') {
+                actuator.kpNoise = value;
+            }
+            else if (key === 'kdNoise' && typeof value === 'number') {
+                actuator.kdNoise = value;
+            }
+            else if (key === 'latencyNoise' && typeof value === 'number') {
+                actuator.latencyNoise = value;
+            }
+        }
+        this.expect(TokenType.RBRACE);
+        return actuator;
+    }
+    parseObservationRandomization() {
+        this.expect(TokenType.LBRACE);
+        const observation = {};
+        while (this.currentToken().type !== TokenType.RBRACE &&
+            this.currentToken().type !== TokenType.EOF) {
+            const key = this.expect(TokenType.IDENTIFIER).value;
+            this.expect(TokenType.COLON);
+            const value = this.parseValue();
+            if (key === 'jointPosNoise' && typeof value === 'number') {
+                observation.jointPosNoise = value;
+            }
+            else if (key === 'jointVelNoise' && typeof value === 'number') {
+                observation.jointVelNoise = value;
+            }
+            else if (key === 'imuNoise' && typeof value === 'number') {
+                observation.imuNoise = value;
+            }
+        }
+        this.expect(TokenType.RBRACE);
+        return observation;
+    }
+    parseInitialStateRandomization() {
+        this.expect(TokenType.LBRACE);
+        const initialState = {};
+        while (this.currentToken().type !== TokenType.RBRACE &&
+            this.currentToken().type !== TokenType.EOF) {
+            const key = this.expect(TokenType.IDENTIFIER).value;
+            this.expect(TokenType.COLON);
+            if (key === 'jointPosRange') {
+                initialState.jointPosRange = this.parseNumberRangeMap();
+            }
+            else {
+                const value = this.parseValue();
+                if (key === 'rootPoseRange' && Array.isArray(value)) {
+                    initialState.rootPoseRange = value;
+                }
+            }
+        }
+        this.expect(TokenType.RBRACE);
+        return initialState;
+    }
+    parseNumberRangeMap() {
+        this.expect(TokenType.LBRACE);
+        const ranges = {};
+        while (this.currentToken().type !== TokenType.RBRACE &&
+            this.currentToken().type !== TokenType.EOF) {
+            const key = this.expect(TokenType.IDENTIFIER).value;
+            this.expect(TokenType.COLON);
+            const value = this.parseValue();
+            if (Array.isArray(value)) {
+                ranges[key] = [value[0], value[1]];
+            }
+        }
+        this.expect(TokenType.RBRACE);
+        return ranges;
+    }
+    parseDisturbanceRandomization() {
+        this.expect(TokenType.LBRACE);
+        const disturbance = {};
+        while (this.currentToken().type !== TokenType.RBRACE &&
+            this.currentToken().type !== TokenType.EOF) {
+            const key = this.expect(TokenType.IDENTIFIER).value;
+            this.expect(TokenType.COLON);
+            const value = this.parseValue();
+            if (key === 'forceRange' && Array.isArray(value)) {
+                disturbance.forceRange = [value[0], value[1]];
+            }
+            else if (key === 'intervalRange' && Array.isArray(value)) {
+                disturbance.intervalRange = [value[0], value[1]];
+            }
+        }
+        this.expect(TokenType.RBRACE);
+        return disturbance;
+    }
+    parseActuatorGroupBlock() {
+        // Parse actuator_group { name: "foo" type: "DelayedPDActuator" joints: ["joint1", "joint2"] ... }
+        this.expect(TokenType.LBRACE);
+        const group = {
+            name: '',
+            type: 'IdealPDActuator',
+            jointNames: [],
+        };
+        while (this.currentToken().type !== TokenType.RBRACE &&
+            this.currentToken().type !== TokenType.EOF) {
+            const key = this.expect(TokenType.IDENTIFIER).value;
+            this.expect(TokenType.COLON);
+            const value = this.parseValue();
+            switch (key) {
+                case 'name':
+                    group.name = value;
+                    break;
+                case 'type':
+                    group.type = value;
+                    break;
+                case 'joints':
+                    if (Array.isArray(value)) {
+                        group.jointNames = value;
+                    }
+                    break;
+                case 'stiffness':
+                    group.stiffness = value;
+                    break;
+                case 'damping':
+                    group.damping = value;
+                    break;
+                case 'friction':
+                    group.friction = value;
+                    break;
+                case 'latency':
+                    group.latency = value;
+                    break;
+            }
+        }
+        this.expect(TokenType.RBRACE);
+        return group;
+    }
+}

package/dist/runtime.d.ts

@@ -0,0 +1,5 @@
+export declare const ROBOTICS_PLUGIN_ID: "robotics";
+export interface TraitRegistrar {
+    registerTrait(name: string, handler: unknown): void;
+}
+export declare function registerRoboticsTraitHandlers(registrar: TraitRegistrar): void;

package/dist/runtime.js

@@ -0,0 +1,6 @@
+import { registerPluginTraits } from '@holoscript/core/runtime';
+import { createROS2HardwareLoopHandler } from './traits/ROS2HardwareLoopTrait.js';
+export const ROBOTICS_PLUGIN_ID = 'robotics';
+export function registerRoboticsTraitHandlers(registrar) {
+    registerPluginTraits(registrar, ROBOTICS_PLUGIN_ID, [createROS2HardwareLoopHandler()]);
+}

package/dist/traits/ROS2HardwareLoopTrait.d.ts

@@ -0,0 +1,15 @@
+/** @ros2_hardware_loop Trait — Bidirectional hardware-in-the-loop bridge for physical robotics. @trait ros2_hardware_loop */
+export interface ROS2Config {
+    nodeName: string;
+    topicPrefix: string;
+    updateFrequencyHz: number;
+    bidirectional: boolean;
+}
+export interface ROS2State {
+    connected: boolean;
+    lastPingMs: number;
+    activeTopics: string[];
+    hardwareSyncDriftMs: number;
+}
+import type { TraitHandler } from './types.js';
+export declare function createROS2HardwareLoopHandler(): TraitHandler<ROS2Config>;