# VS Code

The Elements extension connects VS Code to the Elements language server, so
`.ts`, `.js`, `.ehtml`, `.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 Elements HTML
(`.ehtml`) and `.jsoc` files anywhere, in a project or not, 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 keys in your user `settings.json`, only for an editor
whose settings directory already exists:
`security.promptForLocalFileProtocolHandling` and
`security.promptForRemoteFileProtocolHandling`, both to `false`, and
`elements.elements-vscode` added to `extensions.confirmedUriHandlerExtensionIds`,
so `elements start` can show the app in the editor's browser without asking.
It also sets `security.workspace.trust.startupPrompt` to `once`, so VS Code
asks whether to trust a new project when it opens it. That dialog offers to
trust the parent folder, `projects`, and ticking it trusts every app you create
after. Each key is added only when it is absent; a value you set is kept.

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:

- `.ts` and `.js` files are re-tagged as `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 and CSS validation and suggestions are
  turned off at workspace scope.
- New chat sessions start in Bypass Approvals (`chat.permissions.default` at
  workspace scope), and the agent's edits are kept a second after they land
  (`chat.editing.autoAcceptDelay`), so the agent edits files and runs builds
  without asking and without a Keep or Undo to click. The workspace also stays
  on the local chat harness (`chat.defaultToCopilotHarness` and
  `chat.editor.preferCopilotHarness` false): the Agent Host Copilot harness
  VS Code is trying out ignores `chat.permissions.default` and asks before
  every command. A workspace that already sets any of these keeps its own
  value.
- Plain `.html` files are left to the built-in HTML support. They are real
  HTML, not Elements HTML.
- Emmet is enabled for `.ehtml` files, 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.

In the editor's terminal, the database in `elements start`'s startup line,
`→ postgres://...`, is a link: click it and `elements db` opens in a terminal
named `elements db` in the panel, in that project. Clicking again while that
session is open shows it. The link opens only a project open in the window, a
workspace folder or a folder holding `.elements/id` inside one; any other is
ignored and noted in the Elements output channel.

## Commands

- **Elements: New App**, also under File > New File, asks for a name or a path,
  runs `elements create`, and opens the project as the workspace with the chat
  in the side bar and a terminal in the panel. `elements start` in that
  terminal opens the app in the editor's browser, with no prompt, and a later
  start reloads that tab rather than opening another. The chat agent opens its
  own page of the app when it needs to look at or click through it. A bare name is created under
  `elements.projectsDirectory`, default `~/elements/projects`. An empty name
  creates `myapp`, or the next free `myapp2`, `myapp3`.
- **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 App 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 -service project`.