# VS Code

The Elements extension connects VS Code to the Elements language server, so
`.ts`, `.js`, HTML templates, `.jsoc` and `.css` in a project get diagnostics,
completion, hover, definition, references, rename and symbol search from the
checker the build uses. It also brings syntax highlighting for templates and
`.jsoc`, and two commands.

## Install

Nothing to do. Installing Elements copies the extension to
`~/.vscode/extensions/elements-vscode` and registers it in that directory's
`extensions.json`. When `~/.cursor/extensions` exists, the same extension is
installed there too. Reinstalling Elements updates it in place.

The installer also sets two keys in your user `settings.json`,
`security.promptForLocalFileProtocolHandling` and
`security.promptForRemoteFileProtocolHandling`, both to `false`, and only for an
editor whose settings directory already exists.

The extension finds `elements-lsp` in `~/elements/bin` (or
`$ELEMENTS_SYSTEM_PATH/bin`), so it works when VS Code is launched from the dock
without your shell's `PATH`. If it cannot find the CLI at all it shows
"Elements CLI not found" once.

## Inside a project

The extension attaches only to a folder holding `.elements/id`, found up to four
levels below each workspace folder, or the nearest one above a file you open.
A project created while the window is open is picked up when its marker
appears. Nested projects each get their own connection, and a file belongs to
the deepest project containing it.

Once a project is attached, the extension makes the Elements server the only
one answering in that workspace:

- `.html`, `.ts` and `.js` files are re-tagged as `Elements HTML`,
  `Elements TypeScript` and `Elements JavaScript`, so the built-in extensions
  do not return a second copy of every definition and hover.
- The built-in TypeScript, JavaScript, HTML and CSS validation and suggestions
  are turned off at workspace scope, along with HTML auto-closing tags.
- Emmet is enabled for templates, with `form` abbreviations that expand without
  an `action` attribute, since a form submits through its `onsubmit` handler
  (`html/events`).

The extension also hides `.elements/` from the explorer, the file watcher, and
search.

## Commands

- **Elements: New Project** asks for a name or a path, and optionally a scaffold
  (a GitHub repository or a `.tar.gz` url), runs `elements create`, opens the
  project as the workspace, and opens a terminal in it. A bare name is created
  under `elements.projectsDirectory`, default `~/elements/projects`.
- **Elements: Jump to Matching Tag** moves between an opening and closing tag in
  a template, bound to `cmd+shift+\` (`ctrl+shift+\` elsewhere). Outside a
  template it falls back to jump-to-bracket. With the Vim extension, `%` in
  normal mode runs it.

## Settings

- `elements.projectsDirectory`: where New Project creates a project from a bare
  name. `~` expands to your home directory.
- `elements.trace.server`: `off`, `messages` or `verbose`, to trace the traffic
  between the editor and the language server.

## Troubleshooting

- **No diagnostics or completion**: confirm the folder has `.elements/id` and
  that `~/elements/bin/elements-lsp` exists. Set `elements.trace.server` to
  `verbose` and read the output panel.
- **Logs**: server-side detail is in `.elements/logs/project.log`.