JAML

Language support for JAML in VS Code and Cursor.

Features

• Context-aware element, control-key, style, plugin, and argument completion
• Diagnostics for element types, style/plugin paths, and argument values
• Hover documentation sourced from current JAM-UI language metadata
• Go to Definition for methods, props, vars, refs, shared members, aliases, and registered JAML symbols
• Cross-file discovery of custom components, usages, param suffixes, styles, and colors
• CC Definition field validation, hover information, completions, and jaml.cc.* builder completions
• Automatic JAML recognition in JSON, JavaScript, and ES module files
• Explicit .jaml.json, .jaml.js, .jaml.mjs, and .cc.mjs file naming
• A singleton live preview for JAML, plain JSON, CC Definitions, and Markdown

The extension leaves ordinary JSON and JavaScript files alone unless their content contains strong JAML signals. Project-specific settings can be placed in jaml.config.json.

Project configuration

Place jaml.config.json at the workspace root. Exact registry entries participate in completion, validation, hover, schema generation, and Go to Definition when a source or config location is available.

{
    "customComponents": ["breadcrumb", "dropdown"],
    "customUsages": ["confirmReset"],
    "customSuffixes": ["remote"],
    "customStyles": ["dashboard.card"],
    "customColors": ["grid-alert"],
    "customComponentPatterns": [
        "^dashboard-",
        "^(notify|theme).+$"
    ]
}

Pattern entries are case-sensitive JavaScript regular-expression source strings without /.../ delimiters or flags. Add ^ and $ when the expression must match the whole type name. Matching patterns only suppress the not-built-in type warning and are not offered as type completions; use customComponents for concrete completion values. The extension reloads this file automatically. Invalid patterns are disabled and surfaced as configuration warnings. Pattern evaluation is bounded, and expressions that exceed that budget are disabled. .hintrc is not read by the JAML language server.

Preview

Run JAML: Open Preview from the command palette or the editor-title button. One pinned preview follows the active supported editor while it is visible; switching between the editor and preview does not rerender unchanged content. It supports:

• Plain JSON data and JSON JAML
• JavaScript and ES-module JAML without imports
• Content-recognized CC Definitions, with .cc.mjs as the explicit convention
• Markdown, including the bundled code editor, Mermaid, KaTeX, and ZenUML renderers

The preview includes reload, theme, grid, and zoom controls plus a movable, resizable preview frame. Its initial dark mode follows the VS Code workbench, and scroll positions are retained per source document across rerenders.

Configure runtime resources in the workspace jaml.config.json:

{
    "preview": {
        "debounce": 400,
        "root": "packages/playground",
        "scripts": [
            "assets/echarts.min.js",
            "https://cdn.jsdelivr.net/npm/axios@1.12.2/dist/axios.min.js"
        ],
        "stylesheets": [
            "assets/fontawesome/css/all.min.css"
        ]
    }
}

root is project-relative and defaults to the directory containing jaml.config.json. Local script and stylesheet paths are resolved beneath that root and must remain inside it; scripts must be classic .js files and stylesheets must be .css files. Credential-free HTTPS URLs are also accepted. Resources load in configured order, and local resource changes reload the visible preview. debounce controls source rerender delay in milliseconds, defaults to 400, and is bounded to 0–5000.

The preview executes project-configured resources and JavaScript JAML only in a trusted workspace. Module imports and re-exports inside the previewed document are intentionally unsupported in this version; put required browser globals in preview.scripts instead.

Project registry discovery

The language server statically indexes high-confidence literal registrations in workspace .js, .mjs, .cjs, .ts, and .tsx files:

jaml.register('weatherCard', factory);
jaml.registerUsage('confirmReset', option);
jaml.registerSuffix('remote', processor);
Styles.registerPlugin('dashboard.card', descriptor);
jam.registerCustomColors({ 'grid-alert': '#f00' });

Computed names, locally shadowed or reassigned globals, aliases, optional calls, dynamic object keys, and spreads are ignored. Workspace and dependency code is never executed. Open unsaved registry files temporarily replace their on-disk declarations, and closing them restores the disk index.

When an exact name has multiple declarations, Go to Definition returns all locations in this order: workspace source, workspace config, dependency source, dependency config, then built-in JAM-UI metadata. A regex-only component match has no definition target.

Dependency registry discovery

Only declared direct dependencies can opt in. A package can expose an additive config:

{
    "jaml": "./jaml.config.json"
}

Or it can additionally declare bounded source globs for static discovery:

{
    "jaml": {
        "config": "./jaml.config.json",
        "sources": ["./dist/**/*.js"]
    }
}

Paths are resolved inside that dependency package. Dependency configs may contribute only customComponents, customComponentPatterns, customUsages, customSuffixes, customStyles, and customColors; they cannot change the consumer's include/exclude, strictness, or validation settings. Transitive dependencies and unrelated node_modules packages are not scanned.

Commands

• JAML: Open Preview
• JAML: Validate File
• JAML: Doctor
• JAML: Reload Metadata

Settings

• jaml.enableForJson: choose auto, always, or never
• jaml.include: additional file patterns to inspect
• jaml.exclude: file patterns to ignore

Runtime metadata is loaded from a packaged, generated cache. In the JAM-UI development repository, trusted source changes invalidate that cache and trigger bounded extraction in an isolated child process. Opened workspace source is never executed for metadata discovery.

License

ISC