@xano/xanoscript-language-server 11.0.3

package/.claude/settings.local.json

@@ -0,0 +1,27 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(npm test:*)",
+      "Bash(npm run lint)",
+      "Bash(npm run test:*)",
+      "Bash(npx eslint:*)",
+      "Bash(node:*)",
+      "Bash(npm install)",
+      "Bash(grep:*)",
+      "Bash(git -C /Users/justinalbrecht/git/xs-language-server log --all --pretty=format:\"%h %s\")",
+      "Bash(git -C /Users/justinalbrecht/git/xs-language-server log --all -S \"password\\\\|secret\\\\|api_key\\\\|token\" --oneline)",
+      "Bash(xargs file:*)",
+      "Bash(find:*)",
+      "Bash(git -C /Users/justinalbrecht/git/xs-language-server log -p --all -S \"webhook\\\\|Bearer\\\\|discord\\\\|slack\\\\|xano_insiders\" -- \"*.xs\" \"*.js\")",
+      "Bash(git -C /Users/justinalbrecht/git/xs-language-server ls-files:*)",
+      "Bash(git -C /Users/justinalbrecht/git/xs-language-server status)",
+      "Bash(git -C /Users/justinalbrecht/git/xs-language-server diff --stat)",
+      "Bash(git -C /Users/justinalbrecht/git/xs-language-server log --oneline -5)",
+      "Bash(git -C /Users/justinalbrecht/git/xs-language-server add README.md LICENSE package.json lexer/tests/query/valid_sources/basic_query.xs parser/functions/stream/streamFromRequestFn.js parser/functions/stream/streamFromRequestFn.spec.js parser/tests/function/valid_sources/discord_poll_send_to_slack.xs parser/tests/query/valid_sources/all_basics.xs)",
+      "Bash(git -C /Users/justinalbrecht/git/xs-language-server commit -m \"$\\(cat <<''EOF''\nPrepare package for public npm release as @xano/xanoscript-language-server\n\n- Rename package to @xano/xanoscript-language-server\n- Add MIT LICENSE file\n- Add npm metadata \\(description, repository, author, license, bugs, homepage\\)\n- Remove private flag to allow publishing\n- Sanitize test files: replace internal URLs, IDs, and env var names with placeholders\n- Simplify README maintainer section\n\nCo-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>\nEOF\n\\)\")",
+      "Bash(git -C /Users/justinalbrecht/git/xs-language-server log -1 --oneline)"
+    ],
+    "deny": [],
+    "ask": []
+  }
+}

package/.github/copilot-instructions.md

@@ -0,0 +1,190 @@
+# XanoScript Language Server - Copilot Instructions
+
+## Repository Overview
+
+This repository implements a Language Server Protocol (LSP) server for **XanoScript**, a domain-specific language used by Xano for defining API queries, functions, scheduled tasks, and data schemas. The language server provides VS Code with features like auto-completion, syntax highlighting, hover documentation, and real-time error checking.
+
+**Key Facts:**
+
+- **Size:** ~540 files, 35MB, 457 JavaScript files, 171 test files
+- **Language:** JavaScript ES modules (Node.js 20+)
+- **Framework:** Chevrotain parser generator + VS Code Language Server Protocol
+- **Testing:** Mocha + Chai (1041 tests, comprehensive coverage)
+- **Architecture:** Lexer → Parser → Language Server Features
+
+## Build Instructions
+
+### Dependencies and Setup
+
+```bash
+npm install  # Install dependencies (~2s, always run before any other commands)
+```
+
+### Core Commands
+
+```bash
+npm run lint     # ESLint validation (required for CI, ~1s)
+npm test         # Run all tests (1041 tests, ~45s, required for CI)
+npm test -- -g "test name"  # Run specific tests
+npm run tm       # Generate TextMate language definition (optional tool)
+```
+
+### Validation Sequence
+
+Always run in this order for reliable builds:
+
+1. `npm install` (always required first)
+2. `npm run lint`
+3. `npm test`
+
+**Important:** Tests take ~45 seconds to complete. Set adequate timeouts (60+ seconds) for test commands. Clean installs work reliably and are fast after initial package download.
+
+### Build Validation
+
+- **No compilation step required** - pure JavaScript ES modules
+- **Node.js 20+ required** (as specified in CI)
+- **ES modules** - uses `import`/`export`, requires Node.js with proper module support
+- **No build artifacts** - all source files are directly executed
+
+### Common Issues & Workarounds
+
+- **Test timeouts:** Use 60+ second timeouts for `npm test`
+- **ES module errors:** Ensure Node.js 20+ with ES module support
+- **Dependency conflicts:** Run `rm -rf node_modules && npm install` for clean state
+- **3 low-severity npm audit warnings** are known and acceptable
+
+## Project Layout & Architecture
+
+### Core Directories
+
+- **`lexer/`** - Token definitions for XanoScript language elements
+
+  - `tokens.js` - Main token registry and export
+  - `lexer.js` - Chevrotain lexer implementation
+  - Domain-specific tokens: `api.js`, `db.js`, `cloud.js`, `function.js`, etc.
+  - `utils.js` - Token creation utilities (`createToken`, `createTokenByName`)
+
+- **`parser/`** - Grammar rules and parsing logic
+
+  - `base_parser.js` - Core XanoBaseParser extending Chevrotain
+  - `query_parser.js`, `function_parser.js`, `task_parser.js` - Main parsers
+  - `attributes/` - Field attributes (description, disabled, sensitive, etc.)
+  - `clauses/` - Language blocks (stack, input, response, security)
+  - `definitions/` - Type and column definitions
+  - `functions/` - Built-in function implementations organized by domain
+  - `generic/` - Reusable parsing components
+
+- **Language Server Features**
+  - `server.js` - Main LSP server setup and capability registration
+  - `onCompletion/` - Auto-completion logic and content assist
+  - `onDidChangeContent/` - Live diagnostics and error reporting
+  - `onHover/` - Documentation and hover information providers
+  - `onSemanticCheck/` - Syntax highlighting token generation
+
+### Configuration Files
+
+- **`package.json`** - Dependencies, scripts, ES module configuration
+- **`eslint.config.js`** - ESLint configuration (ES modules format)
+- **`.github/workflows/ci.yml`** - GitHub Actions CI pipeline
+- **`.gitignore`** - Standard Node.js exclusions
+
+### XanoScript Language Structure
+
+XanoScript defines these primary constructs:
+
+- **`query`** - API endpoints with HTTP verbs, input validation, processing logic, responses
+- **`function`** - Reusable logic blocks with testing capabilities
+- **`task`** - Scheduled operations with cron-like triggers
+- **`api_group`** - Collections of related API endpoints
+- **`table`** - Database schema definitions with column types
+
+**Core Language Patterns:**
+
+```xs
+query my_endpoint verb=GET {
+  input { text name filters=trim }
+  stack {
+    var $result { value = $input.name|upper }
+    db.add 123 { data = {name: $result} }
+  }
+  response = $result
+}
+```
+
+### Critical Development Patterns
+
+**Token Creation** (in `lexer/` files):
+
+```javascript
+export const MyToken = createTokenByName("keyword", {
+  longer_alt: Identifier,
+  categories: [Identifier],
+});
+```
+
+**Parser Rules** (in `parser/` files):
+
+```javascript
+myRule = this.RULE("myRule", () => {
+  this.CONSUME(MyToken);
+  this.SUBRULE(this.otherRule);
+});
+```
+
+**Testing Pattern:**
+
+```javascript
+function parse(inputText) {
+  const lexResult = lexDocument(inputText);
+  const parser = new Parser();
+  parser.input = lexResult.tokens;
+  parser.myRule();
+  return parser;
+}
+```
+
+### Dependencies & Runtime
+
+- **`chevrotain`** - Parser generator and runtime
+- **`vscode-languageserver`** - LSP implementation
+- **`lodash-es`** - Utility functions (ES module version)
+- **`mocha`/`chai`** - Testing framework
+- **Runtime:** Node.js 20+ (ES modules, required for CI compatibility)
+
+### Testing Strategy
+
+- **171 test files** using `.spec.js` naming convention
+- **Test organization:** Mirror source structure (`lexer/` tests, `parser/` tests)
+- **Example test files:** `lexer/tests/query/valid_sources/`, `parser/tests/function/valid_sources/`
+- **Test data:** Real XanoScript files in `valid_sources/` directories
+- **CI Integration:** All tests must pass for merge approval
+
+### CI/CD Pipeline
+
+**GitHub Actions** (`.github/workflows/ci.yml`):
+
+1. Ubuntu latest, Node.js 20, npm cache enabled
+2. `npm install`
+3. `npm run lint`
+4. `npm test`
+
+**Pre-commit validation:** Lint and test failures block commits. Always run locally before pushing.
+
+### Key Files Reference
+
+- **Root:** `README.md`, `package.json`, `server.js` (main entry)
+- **Core Logic:** `lexer/tokens.js`, `parser/base_parser.js`
+- **Examples:** `lexer/tests/*/valid_sources/*.xs`, `parser/tests/*/valid_sources/*.xs`
+- **Documentation:** `onHover/functions.md` (function documentation)
+
+### Agent Guidelines
+
+1. **Always run `npm install` before any build/test commands**
+2. **Use 60+ second timeouts for `npm test`** (1041 tests take time)
+3. **Follow existing patterns** - check similar files in same directory for conventions
+4. **Test incrementally** - use `npm test -- -g "specific test"` during development
+5. **Validate ES module syntax** - use `import`/`export`, not `require()`
+6. **Check CI compatibility** - ensure changes work with Node.js 20
+7. **Trust these instructions** - comprehensive testing validates all commands work correctly
+
+This language server is production-ready with extensive testing. Focus on understanding the domain-specific language patterns and lexer/parser architecture when making changes.

package/.github/workflows/ci.yml

@@ -0,0 +1,31 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+
+jobs:
+  xanoscript-language:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+      - name: Use Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: "npm"
+
+      - name: Install language dependencies
+        run: |
+          npm install
+
+      - name: Lint language server
+        run: |
+          npm run lint
+
+      - name: Test language server
+        run: |
+          npm test

package/.husky/pre-commit

@@ -0,0 +1 @@
+npm run lint && npm test

package/CLAUDE.md

@@ -0,0 +1,121 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Commands
+
+```bash
+# Install dependencies (always run first, takes ~2s)
+npm install
+
+# Run tests (1041 tests, ~45s - required for CI)
+npm test
+
+# Run specific test
+npm test -- -g "test name"
+
+# Lint code (required for CI, ~1s)
+npm run lint
+
+# Generate TextMate language definition (optional)
+npm run tm
+```
+
+**Important:** Tests take ~45 seconds. Set adequate timeouts (60+ seconds) for test commands.
+
+## Architecture Overview
+
+This is a Language Server Protocol (LSP) implementation for XanoScript, built on Chevrotain parser generator. The architecture follows: **Lexer → Parser → Language Server Features**.
+
+### Core Components
+
+**Lexer (`lexer/`)**: Token definitions and lexical analysis
+- `tokens.js` - Main token registry
+- `lexer.js` - Chevrotain lexer implementation
+- Domain tokens: `api.js`, `db.js`, `cloud.js`, `function.js`, etc.
+- `utils.js` - Token creation utilities (`createToken`, `createTokenByName`)
+
+**Parser (`parser/`)**: Grammar rules and parsing logic
+- `base_parser.js` - Core XanoBaseParser extending Chevrotain
+- Main parsers: `query_parser.js`, `function_parser.js`, `task_parser.js`, `api_group_parser.js`, `table_parser.js`, `workflow_test_parser.js`, `table_trigger_parser.js`
+- `attributes/` - Field attributes (description, disabled, sensitive)
+- `clauses/` - Language blocks (stack, input, response, security, auth, cache, history, index, schema, test)
+- `definitions/` - Type and column definitions
+- `functions/` - Built-in functions organized by domain (api, array, cloud, controls, db, debug, expect, math, object, redis, time, util, variable)
+- `generic/` - Reusable parsing components
+
+**Language Server (`server.js` + feature directories)**:
+- `onCompletion/` - Auto-completion logic
+- `onDidChangeContent/` - Live diagnostics and error reporting
+- `onHover/` - Documentation and hover information
+- `onSemanticCheck/` - Syntax highlighting token generation
+
+### XanoScript Object Types
+
+Primary constructs parsed by dedicated parsers:
+- **query** - API endpoints with HTTP verbs, input validation, processing logic, responses
+- **function** - Reusable logic blocks with testing capabilities
+- **task** - Scheduled operations with cron-like triggers
+- **api_group** - Collections of related API endpoints
+- **table** - Database schema definitions with column types
+- **workflow_test** - Test definitions for workflows
+- **table_trigger** - Database table trigger definitions
+
+## Adding New Features
+
+### New Object Type
+1. Create a new parser in `parser/` (e.g., `my_object_parser.js`)
+2. Follow existing parser patterns (see `query_parser.js`, `function_parser.js`)
+3. Register it in `server.js`
+
+### New Keyword/Function
+1. Add token definition in appropriate `lexer/` file
+2. Create function implementation in `parser/functions/[domain]/`
+3. Register in parent clause or parser
+4. Add comprehensive tests in corresponding `.spec.js` file
+
+### Token Creation Pattern
+```javascript
+export const MyToken = createTokenByName("keyword", {
+  longer_alt: Identifier,
+  categories: [Identifier],
+});
+```
+
+### Parser Rule Pattern
+```javascript
+myRule = this.RULE("myRule", () => {
+  this.CONSUME(MyToken);
+  this.SUBRULE(this.otherRule);
+});
+```
+
+## Testing Guidelines
+
+- Tests use Mocha + Chai framework
+- 171 test files with `.spec.js` naming convention
+- Test structure mirrors source structure
+- Real XanoScript examples in `valid_sources/` directories
+- Tests are explicit and straightforward - avoid dynamic test generation
+- CI requires all tests to pass
+
+### Test Pattern
+```javascript
+function parse(inputText) {
+  const lexResult = lexDocument(inputText);
+  const parser = new Parser();
+  parser.input = lexResult.tokens;
+  parser.myRule();
+  return parser;
+}
+```
+
+## Development Notes
+
+- **Node.js 20+ required** for ES module support
+- **No compilation step** - pure JavaScript ES modules
+- Use `import`/`export`, not `require()`
+- Follow existing code conventions when adding features
+- Check neighboring files for patterns and conventions
+- Never assume a library is available - check `package.json` first
+- 3 low-severity npm audit warnings are known and acceptable

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Xano
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,55 @@
+[![CI](https://github.com/xano-labs/xs-language-server/actions/workflows/ci.yml/badge.svg)](https://github.com/xano-labs/xs-language-server/actions/workflows/ci.yml)
+
+# XanoScript Language Server
+
+The language server is based on [Chevrotain](https://chevrotain.io/), a powerful parsing library for JavaScript.
+
+Maintained by the [Xano](https://xano.com) team.
+
+## File structure
+
+- `lexer/`: Contains the lexer implementation, including token definitions and the lexer itself.
+- `parser/`: Contains the parser implementation, including grammar definitions and the main parser class.
+
+To integrate the language server with 3rd party tools, we also have a `server.js` file that sets up the language server and handles communication with clients.
+
+- `onCompletion/`: Contains the implementation for the completion feature, allowing the language server to provide suggestions for code completion.
+- `onDidChangeContent/`: Runs a diagnostic analysis on the content of the xanoscript (allow the editor to show errors + error message)
+- `onHover/`: Provides hover information for symbols in the xanoscript, such as type information and documentation.
+- `onSemanticCheck/`: Provides the highlight syntax for Xanoscript to the editor.
+
+## How do I add a new object type?
+
+Every new object requires a new parser in the `parser/` folder. Use one of our existing parser (`query_parser.js`, `function_parser.js`...) to create yours. Once created, you'll have to add it to `server.js`.
+
+## How do I add a new keyword/function ?
+
+We have a hierarchy for the different statements Xanoscript uses.
+
+1. Parser: this is the top level, we have a Query parser, function parser, etc.
+2. Clause: this is the main blocks in a given object type, could be stack, response, input...
+3. functions: this would be a statement, like a `debug.log` or `db.query`
+4. `attributes`, `definitions` would come next as component you can use to define your functions
+5. `generic` is used by all the other statement, like a toolset for language.
+
+## Testing
+
+The language server is heavily tested and should remain that way as it grows. Test should be easy to copy, paste, extends. Avoid dynamic test (like using a loop), your test should be straightforward, easy to read, easy to understand, trustworthy.
+
+To run the tests:
+
+```sh
+npm test
+```
+
+To run a specific test
+
+```sh
+npm test -- -g "my test name"
+```
+
+## CI-CD
+
+On commit, the CI/CD pipeline will run all tests and linting checks to ensure code quality. If any tests fail, the commit will be rejected until the issues are resolved.
+
+You'll find the configuration of the action in the `.github/workflows/ci.yml` file.

package/connection.js

@@ -0,0 +1,7 @@
+import {
+  createConnection,
+  ProposedFeatures,
+} from "vscode-languageserver/node.js";
+
+// Create a connection to the VS Code client
+export const connection = createConnection(ProposedFeatures.all);

package/documents.js

@@ -0,0 +1,5 @@
+import { TextDocuments } from "vscode-languageserver/node.js";
+import { TextDocument } from "vscode-languageserver-textdocument";
+
+// Manage open text documents
+export const documents = new TextDocuments(TextDocument);

package/embedded/README.md

@@ -0,0 +1,102 @@
+# Embedded JavaScript/TypeScript Support
+
+This folder contains the server-side (JavaScript) implementation for recognizing and handling embedded JavaScript/TypeScript code within XanoScript `api.lambda` statements.
+
+## Files
+
+### `embeddedContent.js`
+Core extraction and mapping logic:
+- `extractEmbeddedJS(text)` - Finds all `code = """..."""` blocks in XanoScript
+- `mapToVirtualJS(offset, text)` - Maps cursor position to embedded JS region
+- `mapFromVirtualJS(virtualOffset, region)` - Maps from JS position back to XanoScript
+- `isInEmbeddedRegion(offset, text)` - Quick check if position is in JS
+
+### `embeddedDocuments.js`
+Virtual document manager:
+- `EmbeddedDocumentManager` class - Tracks virtual documents per file
+- Singleton `embeddedDocuments` instance for global access
+
+### `jsLanguageService.js`
+Language service coordinator:
+- `JSLanguageService` class - Coordinates JS features
+- Helper methods for checking regions and updating documents
+- Singleton `jsLanguageService` instance
+
+## How It Works
+
+When a user types in a `.xs` file with embedded JavaScript:
+
+```xanoscript
+api.lambda {
+  code = """
+    console.log("hello");
+    const result = [1, 2, 3].map(x => x * 2);
+  """
+  timeout = 10
+}
+```
+
+1. **Detection**: The regex pattern `/code\s*=\s*"""\s*\n([\s\S]*?)\n\s*"""/g` finds the JavaScript content
+2. **Extraction**: `extractEmbeddedJS()` returns regions with `{content, offset, end}`
+3. **Delegation**: When completion/hover is requested in a JS region:
+   - `onCompletion.js` and `onHover.js` call `mapToVirtualJS()`
+   - If inside JS, they return `null`
+   - This tells VS Code to use its own JavaScript language service
+4. **Virtual Documents**: The client-side (TypeScript) creates virtual documents that VS Code's JS service can process
+
+## Usage
+
+### In Language Server Files
+
+```javascript
+import { mapToVirtualJS } from "../embedded/embeddedContent.js";
+
+export function onCompletion(params, documents) {
+  const document = documents.get(params.textDocument.uri);
+  const text = document.getText();
+  const offset = document.offsetAt(params.position);
+  
+  // Check if we're in embedded JS
+  const virtualPos = mapToVirtualJS(offset, text);
+  if (virtualPos) {
+    // Let VS Code's JS service handle it
+    return null;
+  }
+  
+  // Otherwise, handle as regular XanoScript
+  return getXanoScriptCompletions(text, offset);
+}
+```
+
+## Pattern Matching
+
+The regex pattern is intentionally simple:
+- `code\s*=\s*"""` - Matches `code = """`  with flexible whitespace
+- `\s*\n` - Optional whitespace before newline
+- `([\s\S]*?)` - **Capture group**: Any characters (including newlines), non-greedy
+- `\n\s*"""` - Newline and closing triple quotes
+
+This works in any context (not just `api.lambda`), making it flexible for future extensions.
+
+## Client-Side vs Server-Side
+
+- **Server-side** (this folder): JavaScript implementation used by language server
+- **Client-side** (`src/tooling/js_embedding.ts`): TypeScript implementation used by VS Code extension
+- Both implement the same extraction logic but in their respective environments
+
+## Testing
+
+All modules are ES6 modules and can be tested independently:
+
+```bash
+cd language-server
+node -e "import('./embedded/embeddedContent.js').then(m => console.log(m.extractEmbeddedJS('code = \"\"\"\\nconsole.log()\\n\"\"\"')))"
+```
+
+## Future Enhancements
+
+Potential additions:
+- Support for SQL in `db.query { sql = """...""" }`
+- Support for HTML/CSS in template literals
+- Multiple embedded regions per line
+- Nested language detection

package/embedded/embeddedContent.js

@@ -0,0 +1,74 @@
+/**
+ * Extract embedded JavaScript from XanoScript documents
+ * Finds api.lambda { code = """...""" } blocks
+ */
+
+/**
+ * Extract all embedded JavaScript regions from XanoScript text
+ * @param {string} text - The full XanoScript document text
+ * @returns {Array<{content: string, offset: number, end: number}>} Array of JS regions
+ */
+export function extractEmbeddedJS(text) {
+  const regions = [];
+  
+  // Pattern matches: code = """..."""
+  // We use a simpler pattern that works regardless of context (api.lambda, etc.)
+  const pattern = /code\s*=\s*"""\s*\n([\s\S]*?)\n\s*"""/g;
+  
+  let match;
+  while ((match = pattern.exec(text)) !== null) {
+    const content = match[1]; // The captured JavaScript content
+    const offset = match.index + match[0].indexOf(match[1]); // Start of JS content
+    const end = offset + content.length;
+    
+    regions.push({
+      content,
+      offset,
+      end
+    });
+  }
+  
+  return regions;
+}
+
+/**
+ * Check if a cursor position is within an embedded JavaScript region
+ * @param {number} offset - Cursor offset in the document
+ * @param {string} text - The full XanoScript document text
+ * @returns {{region: object, jsOffset: number} | null} The region and offset within JS, or null
+ */
+export function mapToVirtualJS(offset, text) {
+  const regions = extractEmbeddedJS(text);
+  
+  for (const region of regions) {
+    if (offset >= region.offset && offset <= region.end) {
+      const jsOffset = offset - region.offset;
+      return {
+        region,
+        jsOffset
+      };
+    }
+  }
+  
+  return null;
+}
+
+/**
+ * Map a position from virtual JavaScript document back to XanoScript document
+ * @param {number} virtualOffset - Offset in the virtual JS document
+ * @param {object} region - The region object from extractEmbeddedJS
+ * @returns {number} Offset in the original XanoScript document
+ */
+export function mapFromVirtualJS(virtualOffset, region) {
+  return region.offset + virtualOffset;
+}
+
+/**
+ * Check if a position is inside an embedded JavaScript region
+ * @param {number} offset - Cursor offset in the document
+ * @param {string} text - The full XanoScript document text
+ * @returns {boolean}
+ */
+export function isInEmbeddedRegion(offset, text) {
+  return mapToVirtualJS(offset, text) !== null;
+}