@abide/abide 0.41.1 → 0.42.0

package/AGENTS.md

@@ -143,23 +143,29 @@ import: `scope`, `props` / `prop`, `effect`, `html`, `snippet`.
 | `{...expr}`                 | Spread keys as attributes (elements) or props (components).                                  |
 | `attach={fn}`               | Build-time element attachment with optional teardown.                                        |
 
-**Control flow** — native `<template>` tags:
-
-| Form                                                                                           | Meaning                                                                                    |
-| ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
-| `<template if={c}>` / `<template elseif={c}>` / `<template else>`                              | Conditional, source-order, re-evaluated reactively.                                        |
-| `<template each={list} as="x" key="x.id" index="i">`                                           | Keyed list; reorder/re-key updates rows in place; `index` is reactive.                     |
-| `<template each await={asyncIter} as="x" key="…">`                                             | Async keyed list; rows append as the iterator yields.                                      |
-| `<template await={p}>` / `<template then="v">` / `<template catch="e">` / `<template finally>` | Promise branches; `await={p} then="v"` on one tag renders inline (blocking) on the server. |
-| `<template switch={s}>` / `<template case="v">` / `<template default>`                         | First strict (`===`) match wins.                                                           |
-| `<template try>` / `<template catch="e">` / `<template finally>`                               | Synchronous render error boundary.                                                         |
-| `<template name="row" args={item}>` … `{row(item)}`                                            | Snippet definition + call.                                                                 |
+**Control flow** — `{#…}` blocks (each head reads as the JS clause it lowers to):
+
+| Form                                                                | Meaning                                                                                               |
+| ------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
+| `{#if c}` / `{:else if c}` / `{:else}` / `{/if}`                    | Conditional, source-order, re-evaluated reactively.                                                   |
+| `{#for x of list}` / `{#for x, i of list by x.id}` / `{/for}`       | Keyed list (`for…of`); `, i` index reactive; `by` key reconciles rows in place; key defaults to item. |
+| `{#for await x of asyncIter by x.id}` … `{:catch e}` / `{/for}`     | Async keyed list (`for await…of`); rows append as the iterator yields.                                |
+| `{#await p}` / `{:then v}` / `{:catch e}` / `{:finally}` / `{/await}` | Promise branches; pending content (before `{:then}`) streams.                                         |
+| `{#await p then v}` / `{/await}`                                    | Blocking: no pending, resolved inline (SSR settles before the first flush).                           |
+| `{#switch s}` / `{:case v}` / `{:default}` / `{/switch}`            | First strict (`===`) match wins.                                                                      |
+| `{#try}` / `{:catch e}` / `{:finally}` / `{/try}`                   | Synchronous render error boundary.                                                                    |
+
+**Reusable markup** — `<template>`:
+
+| Form                                                | Meaning                                                                                                                                            |
+| --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `<template name="row" args={item}>` … `{row(item)}` | Named template (snippet) definition + call. A `<template>` with a control-flow attribute (`if`/`each`/…) is a compile error — use the `{#…}` block. |
 
 **Components & slots** — a capitalised tag (`<Card title={x}>`) mounts a child;
 attributes become props, children fill the child's `<slot>` (with fallback when
 empty). `<style>` is scoped to the component and its children. Component files
-end in `.abide`. `then`/`each` value names lexically shadow same-named
-component state inside the block.
+end in `.abide`. A block's binding names (`{:then v}`, `{#for x of …}`) lexically
+shadow same-named component state inside the block.
 
 ## Server surface — abide/server/\* (server-only)
 

package/CHANGELOG.md

@@ -1,5 +1,53 @@
 # abide
 
+## 0.42.0
+
+### Minor Changes
+
+- [`568956c`](https://github.com/briancray/abide/commit/568956c88ff1d32ca79a2aa8a1a0ffffeb25afe3) - reject stray {:…}/{/…} tokens outside a block ([`1b5d54e`](https://github.com/briancray/abide/commit/1b5d54e7798acfa7c9b15ce6b65b0c2b6a8c2c07))
+
+- [`568956c`](https://github.com/briancray/abide/commit/568956c88ff1d32ca79a2aa8a1a0ffffeb25afe3) - parse {#switch}/{:case}/{:default} blocks to the switch AST ([`448da38`](https://github.com/briancray/abide/commit/448da3840c120ac3b15d239c090f123c25527fec))
+
+- [`568956c`](https://github.com/briancray/abide/commit/568956c88ff1d32ca79a2aa8a1a0ffffeb25afe3) - parse {#for … of … by …} blocks to the each AST ([`7bb2ac8`](https://github.com/briancray/abide/commit/7bb2ac8f3012e3d40cfcbe8ddf277d6a8732ee93))
+
+- [`568956c`](https://github.com/briancray/abide/commit/568956c88ff1d32ca79a2aa8a1a0ffffeb25afe3) - LSP semantic-token encoder + extract offsetToPosition ([`7daeb92`](https://github.com/briancray/abide/commit/7daeb926f045058aa452b5f539ddd75b0d8efa67))
+
+- [`568956c`](https://github.com/briancray/abide/commit/568956c88ff1d32ca79a2aa8a1a0ffffeb25afe3) - semantic-token legend + TS-classification mapping for abide lsp ([`892f97b`](https://github.com/briancray/abide/commit/892f97bbc6dfd8af9301297276995f7060fe3f9a))
+
+- [`568956c`](https://github.com/briancray/abide/commit/568956c88ff1d32ca79a2aa8a1a0ffffeb25afe3) - type-aware semanticClassifications on the shadow language service ([`9377dd2`](https://github.com/briancray/abide/commit/9377dd24d855cde790d960fceef00255904ee926))
+
+- [`568956c`](https://github.com/briancray/abide/commit/568956c88ff1d32ca79a2aa8a1a0ffffeb25afe3) - block control-flow grammar formatting + shared helpers ([`b39c0a7`](https://github.com/briancray/abide/commit/b39c0a70696b031b63ef157c67360c2da0fd60b0))
+
+- [`568956c`](https://github.com/briancray/abide/commit/568956c88ff1d32ca79a2aa8a1a0ffffeb25afe3) - zed onboarding — auto-install extension + enable semantic tokens ([`b47acc7`](https://github.com/briancray/abide/commit/b47acc7cc106956f115c70b110c29ce017a71cd0))
+
+- [`568956c`](https://github.com/briancray/abide/commit/568956c88ff1d32ca79a2aa8a1a0ffffeb25afe3) - parse {#if}/{:else if}/{:else} blocks to the if AST ([`b662397`](https://github.com/briancray/abide/commit/b66239765bae2ec7a24d70bc7b2edbcbe400614c))
+
+- [`568956c`](https://github.com/briancray/abide/commit/568956c88ff1d32ca79a2aa8a1a0ffffeb25afe3) - parse {#try}/{:catch}/{:finally} blocks to the try AST ([`b82c3dd`](https://github.com/briancray/abide/commit/b82c3ddaaec3db3941639df952e568f017d6c767))
+
+- [`568956c`](https://github.com/briancray/abide/commit/568956c88ff1d32ca79a2aa8a1a0ffffeb25afe3) - Breaking: remove <template> control-flow directives in favor of {#…} blocks ([`bf5cf89`](https://github.com/briancray/abide/commit/bf5cf89813a8dcbc967e1303bd2509e18e701761))
+
+- [`568956c`](https://github.com/briancray/abide/commit/568956c88ff1d32ca79a2aa8a1a0ffffeb25afe3) - color of/by connectors in {#for} block heads ([`c958614`](https://github.com/briancray/abide/commit/c9586147f8196e9e6301b14cdb08986b36da2751))
+
+- [`568956c`](https://github.com/briancray/abide/commit/568956c88ff1d32ca79a2aa8a1a0ffffeb25afe3) - parse {#await} streaming + blocking blocks to the await AST ([`cfd7ff0`](https://github.com/briancray/abide/commit/cfd7ff0102b2be2ac241a6c0b1965949aa6621bf))
+
+- [`568956c`](https://github.com/briancray/abide/commit/568956c88ff1d32ca79a2aa8a1a0ffffeb25afe3) - serve textDocument/semanticTokens/full for .abide ([`e152663`](https://github.com/briancray/abide/commit/e152663dae9e60e13d16f0edf4b0a140a99b1bfb))
+
+- [`568956c`](https://github.com/briancray/abide/commit/568956c88ff1d32ca79a2aa8a1a0ffffeb25afe3) - structural {#…} block framing tokenizer ([`e1e85e8`](https://github.com/briancray/abide/commit/e1e85e847e9442f8c6140df5346b1d37f8cfad54))
+
+### Patch Changes
+
+- [`568956c`](https://github.com/briancray/abide/commit/568956c88ff1d32ca79a2aa8a1a0ffffeb25afe3) - point block-construct loc at its primary expression (shadow source-map fidelity) ([`0fb0efa`](https://github.com/briancray/abide/commit/0fb0efab43639331c856969fdb6a7b83bd7ab604))
+
+- [`568956c`](https://github.com/briancray/abide/commit/568956c88ff1d32ca79a2aa8a1a0ffffeb25afe3) - unify block/branch child-scan loops behind a shared helper ([`4683098`](https://github.com/briancray/abide/commit/4683098df96edd0321dc66d200372e0fbedce2e2))
+
+- [`568956c`](https://github.com/briancray/abide/commit/568956c88ff1d32ca79a2aa8a1a0ffffeb25afe3) - document {#…} control-flow blocks in the AGENTS surface map ([`68fe96f`](https://github.com/briancray/abide/commit/68fe96f3294a228b91eef5cde37c0300673eb88a))
+
+- [`568956c`](https://github.com/briancray/abide/commit/568956c88ff1d32ca79a2aa8a1a0ffffeb25afe3) - map {#for}/{:then}/{:catch} bindings + by-key to source so hover & semantic tokens land on them ([`e8447e8`](https://github.com/briancray/abide/commit/e8447e8d54934737b80c2f49d4f4d1b134786531))
+
+- [`568956c`](https://github.com/briancray/abide/commit/568956c88ff1d32ca79a2aa8a1a0ffffeb25afe3) - map <template args> snippet param + await/try {:catch} bindings (+ index/catch/snippet tests) ([`f724d10`](https://github.com/briancray/abide/commit/f724d101f5baed79de2d39a1ab9598eb9d1eb818))
+
+- [`568956c`](https://github.com/briancray/abide/commit/568956c88ff1d32ca79a2aa8a1a0ffffeb25afe3) - satisfy noUncheckedIndexedAccess in block-token + shadow paths ([`fbb6e44`](https://github.com/briancray/abide/commit/fbb6e4443932e92277fb332b639c746663c7759b))
+
 ## 0.41.1
 
 ### Patch Changes

package/README.md

@@ -140,29 +140,28 @@ async function send() {
     <button disabled={!text}>send</button>
 </form>
 
-<template if={latest}>
+{#if latest}
     <p>latest from {latest.from}</p>
-<template else>
+{:else}
     <p>no messages yet</p>
-</template>
+{/if}
 
-<template switch={view}>
-<template case="mine"><p>showing your messages</p></template>
-<template default><p>showing every message</p></template>
-</template>
+{#switch view}
+{:case 'mine'}<p>showing your messages</p>
+{:default}<p>showing every message</p>
+{/switch}
 
-<template await={history}>
+{#await history}
     <p>loading…</p>
-<template then="data">
+{:then data}
     <ul>
-        <template each={data} as="message" key="message.id" index="i">
+        {#for message, i of data by message.id}
             {i}. {line(message)}
-        </template>
+        {/for}
     </ul>
-<template catch="reason">
+{:catch reason}
     <p>failed: {reason.message}</p>
-</template>
-</template>
+{/await}
 
 <style>
 form { display: flex; gap: 0.5rem; }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@abide/abide",
-    "version": "0.41.1",
+    "version": "0.42.0",
     "type": "module",
     "sideEffects": false,
     "description": "Isomorphic multimodal HTTP framework built for humans and machines in a single Bun runtime",

package/src/abideLsp.ts

@@ -1,11 +1,15 @@
 import { fileURLToPath, pathToFileURL } from 'node:url'
 import ts from 'typescript'
+import { ABIDE_SEMANTIC_TOKENS_LEGEND } from './lib/ui/compile/ABIDE_SEMANTIC_TOKENS_LEGEND.ts'
 import type {
     ShadowLanguageService,
     ShadowQuickInfo,
 } from './lib/ui/compile/createShadowLanguageService.ts'
 import { createShadowLanguageService } from './lib/ui/compile/createShadowLanguageService.ts'
+import { encodeSemanticTokens } from './lib/ui/compile/encodeSemanticTokens.ts'
 import { nearestProjectRoot } from './lib/ui/compile/nearestProjectRoot.ts'
+import { offsetToPosition } from './lib/ui/compile/offsetToPosition.ts'
+import { structuralBlockTokens } from './lib/ui/compile/structuralBlockTokens.ts'
 import type { AbideDiagnostic } from './lib/ui/compile/types/AbideDiagnostic.ts'
 
 /*
@@ -19,6 +23,28 @@ unsaved text as overlays. Each document routes to a shadow service for its
 nearest tsconfig, so files in a monorepo opened at its root are checked against
 their own project — matching `abide check` run from that package.
 */
+/*
+The semantic-tokens `data` array for one component: the structural `{#…}` framing
+merged with the shadow's type-aware expression tokens, encoded to the LSP wire
+format. Never throws — on any internal failure it yields an empty stream so the
+editor falls back to tree-sitter highlighting.
+*/
+export function componentSemanticTokens(
+    service: ShadowLanguageService,
+    abidePath: string,
+    text: string,
+): number[] {
+    try {
+        const tokens = [
+            ...structuralBlockTokens(text),
+            ...service.semanticClassifications(abidePath),
+        ]
+        return encodeSemanticTokens(text, tokens)
+    } catch {
+        return []
+    }
+}
+
 export async function abideLsp({ cwd }: { cwd: string }): Promise<void> {
     const documentText = new Map<string, string>()
 
@@ -64,7 +90,14 @@ export async function abideLsp({ cwd }: { cwd: string }): Promise<void> {
                     jsonrpc: '2.0',
                     id: message.id,
                     result: {
-                        capabilities: { textDocumentSync: 1, hoverProvider: true },
+                        capabilities: {
+                            textDocumentSync: 1,
+                            hoverProvider: true,
+                            semanticTokensProvider: {
+                                legend: ABIDE_SEMANTIC_TOKENS_LEGEND,
+                                full: true,
+                            },
+                        },
                         serverInfo: { name: 'abide-lsp' },
                     },
                 })
@@ -115,6 +148,18 @@ export async function abideLsp({ cwd }: { cwd: string }): Promise<void> {
                 })
                 return
             }
+            case 'textDocument/semanticTokens/full': {
+                const { uri } = message.params.textDocument
+                const data = isAbide(uri)
+                    ? componentSemanticTokens(
+                          serviceFor(fileURLToPath(uri)),
+                          fileURLToPath(uri),
+                          documentText.get(fileURLToPath(uri)) ?? '',
+                      )
+                    : []
+                send({ jsonrpc: '2.0', id: message.id, result: { data } })
+                return
+            }
             case 'textDocument/didClose': {
                 const { uri } = message.params.textDocument
                 if (isAbide(uri)) {
@@ -194,13 +239,6 @@ function toLspHover(text: string, info: ShadowQuickInfo): object {
     }
 }
 
-/* An absolute offset → LSP `{ line, character }` (0-based, UTF-16 code units). */
-function offsetToPosition(text: string, offset: number): { line: number; character: number } {
-    const before = text.slice(0, offset)
-    const line = before.split('\n').length - 1
-    return { line, character: offset - (before.lastIndexOf('\n') + 1) }
-}
-
 /* An LSP `{ line, character }` (0-based) → absolute offset in `text`. */
 function positionToOffset(text: string, position: { line: number; character: number }): number {
     const lineStart = text

package/src/abideResolverPlugin.ts

@@ -4,6 +4,8 @@ import type { BunPlugin } from 'bun'
 import { Glob } from 'bun'
 import { abideImportName } from './lib/shared/abideImportName.ts'
 import { abideLog } from './lib/shared/abideLog.ts'
+import { escapeRegex } from './lib/shared/escapeRegex.ts'
+import { fileName } from './lib/shared/fileName.ts'
 import { fileStem } from './lib/shared/fileStem.ts'
 import { jsonSchemaForPromptArguments } from './lib/shared/jsonSchemaForPromptArguments.ts'
 import { manifestModule } from './lib/shared/manifestModule.ts'
@@ -65,10 +67,6 @@ function resolveExtensionUncached(path: string): string {
 
 const NS = 'abide-virtual'
 
-function escapeRegex(value: string): string {
-    return value.replace(/[\\^$.*+?()[\]{}|]/g, '\\$&')
-}
-
 /* Memoises a zero-arg async producer so repeat calls reuse the first in-flight promise. */
 function once<T>(produce: () => Promise<T>): () => Promise<T> {
     let promise: Promise<T> | undefined
@@ -791,7 +789,7 @@ async function scanPages(pagesDir: string): Promise<PagesScan> {
         return { pageFiles: [], layoutFiles: [] }
     }
     const allFiles = await Array.fromAsync(new Glob('**/*.abide').scan({ cwd: pagesDir }))
-    const leafIs = (name: string) => (file: string) => (file.split('/').pop() ?? '') === name
+    const leafIs = (name: string) => (file: string) => fileName(file) === name
     return {
         pageFiles: allFiles.filter(leafIs('page.abide')),
         layoutFiles: allFiles.filter(leafIs('layout.abide')),

package/src/lib/server/runtime/devClientFingerprint.ts

@@ -1,4 +1,5 @@
 import { relative } from 'node:path'
+import { fileName } from '../../shared/fileName.ts'
 import { analyzeComponent } from '../../ui/compile/analyzeComponent.ts'
 import { compileComponent } from '../../ui/compile/compileComponent.ts'
 import { nearestProjectRoot } from '../../ui/compile/nearestProjectRoot.ts'
@@ -19,7 +20,7 @@ const GENERATED = /(^|\/)\.abide\//
 // page.abide / layout.abide are router-mounted, not `mountChild`-tracked, so they
 // can't hot-swap — they fold into `structure` (a reload) instead.
 function isPageOrLayout(moduleId: string): boolean {
-    const file = moduleId.split('/').pop() ?? ''
+    const file = fileName(moduleId)
     return file === 'page.abide' || file === 'layout.abide'
 }
 

package/src/lib/shared/escapeRegex.ts

@@ -0,0 +1,9 @@
+/*
+Escapes the regex metacharacters in `value` so it can be embedded literally
+inside a `new RegExp(...)` pattern. Shared by the $rpc/$sockets import stripper,
+the resolver plugin's virtual-namespace matcher, and the SSR snippet-call
+rewriter so the same escaping is applied one way everywhere.
+*/
+export function escapeRegex(value: string): string {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+}

package/src/lib/shared/fileName.ts

@@ -0,0 +1,9 @@
+/*
+The bare leaf filename of a path — directory stripped, extension kept —
+e.g. `users/list.ts` → `list.ts`. The extension-stripping `fileStem` builds on
+this; call sites that match a full filename (`layout.abide`, `page.abide`) use
+it directly so the leaf-grab is written one way.
+*/
+export function fileName(path: string): string {
+    return path.split('/').pop() ?? ''
+}

package/src/lib/shared/fileStem.ts

@@ -1,3 +1,5 @@
+import { fileName } from './fileName.ts'
+
 /*
 The bare filename of a path, with directory and trailing extension stripped —
 e.g. `users/list.ts` → `list`, `/_virtual/mcp-resources.ts` → `mcp-resources`.
@@ -5,5 +7,5 @@ Used to derive a virtual-module name from its path and to check an $rpc /
 $sockets module's single export name against its file stem.
 */
 export function fileStem(path: string): string {
-    return (path.split('/').pop() ?? '').replace(/\.[^.]+$/, '')
+    return fileName(path).replace(/\.[^.]+$/, '')
 }

package/src/lib/shared/programNameForPackage.ts

@@ -1,3 +1,5 @@
+import { fileName } from './fileName.ts'
+
 /*
 Derives the CLI program/binary name from a package.json `name` field.
 Scoped names (`@scope/tool`) keep only the final segment so the value is
@@ -10,5 +12,5 @@ export function programNameForPackage(name: string | undefined): string {
     if (name === undefined || name === '') {
         return 'app'
     }
-    return name.split('/').pop() || 'app'
+    return fileName(name) || 'app'
 }

package/src/lib/shared/stripImport.ts

@@ -1,3 +1,5 @@
+import { escapeRegex } from './escapeRegex.ts'
+
 /*
 Strips the user's `import { … } from '<moduleName>'` declaration from a
 module source. Used by the $rpc / $sockets rewriters to remove the
@@ -18,7 +20,7 @@ includes newlines, so multi-line braced imports like
 still match — the body just can't contain another `}` to bound it.
 */
 export function stripImport(source: string, moduleName: string): string {
-    const escaped = moduleName.replace(/[\\^$.*+?()[\]{}|]/g, '\\$&')
+    const escaped = escapeRegex(moduleName)
     const pattern = new RegExp(
         `^\\s*import\\s*\\{[^}]*\\}\\s*from\\s*['"]${escaped}['"]\\s*;?\\s*$`,
         'gm',

package/src/lib/ui/compile/ABIDE_SEMANTIC_TOKENS_LEGEND.ts

@@ -0,0 +1,45 @@
+/*
+The LSP semantic-tokens legend abide lsp advertises, and the decoder from
+TypeScript's encoded classifications to legend names. TypeScript encodes a
+classification as `((tokenType + 1) << 8) + modifierBitset`; its TokenType and
+TokenModifier enums fix the orders below. `keyword`/`operator` carry the `{#…}`
+block framing the structural tokenizer emits.
+*/
+
+/* TS TokenType order (class=0 … member=11) → LSP token-type name. */
+const TS_TYPE_TO_LSP = [
+    'class',
+    'enum',
+    'interface',
+    'namespace',
+    'typeParameter',
+    'type',
+    'parameter',
+    'variable',
+    'enumMember',
+    'property',
+    'function',
+    'method',
+]
+
+/* TS TokenModifier order (declaration=bit 0 … local=bit 5). */
+const TS_MODIFIERS = ['declaration', 'static', 'async', 'readonly', 'defaultLibrary', 'local']
+
+export const ABIDE_SEMANTIC_TOKENS_LEGEND = {
+    tokenTypes: [...TS_TYPE_TO_LSP, 'keyword', 'operator'],
+    tokenModifiers: TS_MODIFIERS,
+}
+
+/* Decodes one TypeScript encoded classification into legend names. */
+export function mapTsClassification(
+    classification: number,
+): { type: string; modifiers: string[] } | undefined {
+    const tokenType = (classification >> 8) - 1
+    const type = TS_TYPE_TO_LSP[tokenType]
+    if (type === undefined) {
+        return undefined
+    }
+    const modifierSet = classification & 255
+    const modifiers = TS_MODIFIERS.filter((_, bit) => (modifierSet & (1 << bit)) !== 0)
+    return { type, modifiers }
+}

package/src/lib/ui/compile/abideUiPlugin.ts

@@ -1,5 +1,6 @@
 import { relative } from 'node:path'
 import type { BunPlugin } from 'bun'
+import { fileName } from '../../shared/fileName.ts'
 import { messageFromError } from '../../shared/messageFromError.ts'
 import { AbideCompileError } from './AbideCompileError.ts'
 import { analyzeComponent } from './analyzeComponent.ts'
@@ -42,7 +43,7 @@ export const abideUiPlugin: BunPlugin = {
         build.onLoad({ filter: /\.abide$/ }, async (args) => {
             const source = await Bun.file(args.path).text()
             const moduleId = relative(nearestProjectRoot(args.path, process.cwd()), args.path)
-            const isLayout = (args.path.split('/').pop() ?? '') === 'layout.abide'
+            const isLayout = fileName(args.path) === 'layout.abide'
             /* Bun frames a plugin throw at `<file>:0` regardless of the real spot, so
                carry the component path + resolved line:col in the message — otherwise a
                control-flow / compile error reads as `:0` and (in deep imports) can look

package/src/lib/ui/compile/compileShadow.ts

@@ -91,6 +91,10 @@ export function compileShadow(source: string): CompiledShadow {
    pre-assembled scope line carrying its own embedded segments. */
 type Builder = {
     raw: (text: string) => void
+    /* Appends `text` verbatim and maps it back to source, WITHOUT the `expr`
+       parens — for binding names and other spans that must stay bare TS syntax
+       (`for (const NAME of …)`). `text` must equal the source at `sourceLoc`. */
+    mapped: (text: string, sourceLoc: number | undefined) => void
     expr: (code: string, sourceLoc: number | undefined) => void
     stmt: (code: string, sourceLoc: number | undefined) => void
     flush: (line: ScopeLine) => void
@@ -115,6 +119,16 @@ function createBuilder(): Builder {
         raw(text) {
             code += text
         },
+        mapped(text, sourceLoc) {
+            if (sourceLoc !== undefined) {
+                mappings.push({
+                    shadowStart: code.length,
+                    sourceStart: sourceLoc,
+                    length: text.length,
+                })
+            }
+            code += text
+        },
         expr(exprCode, sourceLoc) {
             code += '('
             if (sourceLoc !== undefined) {
@@ -408,19 +422,24 @@ function emitNode(node: TemplateNode, builder: Builder): void {
         }
         case 'each':
             /* `for await` over an async each's AsyncIterable, plain `for…of` otherwise —
-               so the item binds to the element type under either iteration protocol. */
-            builder.raw(
-                node.async ? `for await (const ${node.as} of ` : `for (const ${node.as} of `,
-            )
+               so the item binds to the element type under either iteration protocol. The
+               binding name is `mapped` (not `raw`) so hover/highlighting land on it. */
+            builder.raw(node.async ? 'for await (const ' : 'for (const ')
+            builder.mapped(node.as, node.asLoc)
+            builder.raw(' of ')
             builder.expr(node.items, node.loc)
             builder.raw(') {\n')
             if (node.key !== undefined) {
-                builder.raw(`void (${node.key});\n`)
+                builder.raw('void ')
+                builder.expr(node.key, node.keyLoc)
+                builder.raw(';\n')
             }
             /* `index="i"` binds the row's position — always a number (the row ordinal,
                or an async stream's arrival count). Declare it so body references check. */
             if (node.index !== undefined) {
-                builder.raw(`const ${node.index}: number = 0;\n`)
+                builder.raw('const ')
+                builder.mapped(node.index, node.indexLoc)
+                builder.raw(': number = 0;\n')
             }
             emitNodes(node.children, builder)
             builder.raw('}\n')
@@ -439,7 +458,9 @@ function emitNode(node: TemplateNode, builder: Builder): void {
             const pending = node.children.filter((child) => child.kind !== 'branch')
             const branches = node.children.filter((child) => child.kind === 'branch')
             if (node.blocking && node.as !== undefined) {
-                builder.raw(`{\nconst ${node.as} = ${resolved};\n`)
+                builder.raw('{\nconst ')
+                builder.mapped(node.as, node.asLoc)
+                builder.raw(` = ${resolved};\n`)
                 emitNodes(pending, builder)
                 builder.raw('}\n')
             } else {
@@ -451,9 +472,13 @@ function emitNode(node: TemplateNode, builder: Builder): void {
                 }
                 builder.raw('{\n')
                 if (branch.branch === 'then' && branch.as !== undefined) {
-                    builder.raw(`const ${branch.as} = ${resolved};\n`)
+                    builder.raw('const ')
+                    builder.mapped(branch.as, branch.asLoc)
+                    builder.raw(` = ${resolved};\n`)
                 } else if (branch.branch === 'catch' && branch.as !== undefined) {
-                    builder.raw(`const ${branch.as} = undefined as any;\n`)
+                    builder.raw('const ')
+                    builder.mapped(branch.as, branch.asLoc)
+                    builder.raw(' = undefined as any;\n')
                 }
                 emitNodes(branch.children, builder)
                 builder.raw('}\n')
@@ -508,7 +533,14 @@ function emitNode(node: TemplateNode, builder: Builder): void {
             builder.raw('}\n')
             return
         case 'snippet':
-            builder.raw(`const ${node.name} = (${node.params ?? ''}) => {\n`)
+            /* `args={…}` is the parameter list; `mapped` (not `raw`) so hover/highlighting
+               land on the binding. `loc` is the `args` expression's offset (see
+               toSnippetOrTemplate). The name is a static attribute with no tracked offset. */
+            builder.raw(`const ${node.name} = (`)
+            if (node.params !== undefined) {
+                builder.mapped(node.params, node.loc)
+            }
+            builder.raw(') => {\n')
             emitNodes(node.children, builder)
             builder.raw('};\n')
             return

package/src/lib/ui/compile/createShadowLanguageService.ts

@@ -1,6 +1,7 @@
 import { resolve } from 'node:path'
 import ts from 'typescript'
 import { messageFromError } from '../../shared/messageFromError.ts'
+import { mapTsClassification } from './ABIDE_SEMANTIC_TOKENS_LEGEND.ts'
 import { assetModulesFile } from './assetModulesFile.ts'
 import { compileShadow } from './compileShadow.ts'
 import { loadShadowTsConfig } from './loadShadowTsConfig.ts'
@@ -10,6 +11,7 @@ import { shadowNaming } from './shadowNaming.ts'
 import { sourceToShadowOffset } from './sourceToShadowOffset.ts'
 import type { AbideDiagnostic } from './types/AbideDiagnostic.ts'
 import type { CompiledShadow } from './types/CompiledShadow.ts'
+import type { SemanticToken } from './types/SemanticToken.ts'
 
 const { suffixed, isShadow, sourceOf } = shadowNaming
 
@@ -27,6 +29,8 @@ export type ShadowLanguageService = {
     /* Hover info at a source offset, or undefined if the offset isn't a checked
        expression (markup, whitespace) or TypeScript has nothing to report. */
     quickInfo: (abidePath: string, sourceOffset: number) => ShadowQuickInfo | undefined
+    /* Type-aware semantic tokens for every checked expression, in source coords. */
+    semanticClassifications: (abidePath: string) => SemanticToken[]
 }
 
 /*
@@ -194,5 +198,49 @@ export function createShadowLanguageService(cwd: string): ShadowLanguageService
                 length: span?.length ?? 1,
             }
         },
+        semanticClassifications(abidePath) {
+            const fileName = suffixed(abidePath)
+            /* Compile first so the mappings cache is current. */
+            shadowText(abidePath)
+            const shadow = shadows.get(abidePath)
+            if (shadow === undefined) {
+                return []
+            }
+            const { spans } = service.getEncodedSemanticClassifications(
+                fileName,
+                { start: 0, length: shadow.code.length },
+                ts.SemanticClassificationFormat.TwentyTwenty,
+            )
+            /* `spans` is flat triples [start, length, classification, …] in shadow
+               coords; keep only those overlapping a mapped expression segment. */
+            const tokens: SemanticToken[] = []
+            for (let index = 0; index + 2 < spans.length; index += 3) {
+                const spanStart = spans[index]
+                const spanLength = spans[index + 1]
+                const classification = spans[index + 2]
+                if (
+                    spanStart === undefined ||
+                    spanLength === undefined ||
+                    classification === undefined
+                ) {
+                    continue
+                }
+                const mapped = mapTsClassification(classification)
+                if (mapped === undefined) {
+                    continue
+                }
+                const located = remapShadowDiagnostic(shadow.mappings, spanStart, spanLength)
+                if (located === undefined) {
+                    continue
+                }
+                tokens.push({
+                    start: located.start,
+                    length: located.length,
+                    type: mapped.type,
+                    modifiers: mapped.modifiers,
+                })
+            }
+            return tokens
+        },
     }
 }

package/src/lib/ui/compile/encodeSemanticTokens.ts

@@ -0,0 +1,37 @@
+import { ABIDE_SEMANTIC_TOKENS_LEGEND } from './ABIDE_SEMANTIC_TOKENS_LEGEND.ts'
+import { offsetToPosition } from './offsetToPosition.ts'
+import type { SemanticToken } from './types/SemanticToken.ts'
+
+/*
+Encodes source-coordinate tokens into the LSP semantic-tokens `data` array: five
+integers per token (deltaLine, deltaStartChar, length, tokenTypeIndex,
+modifierBitset), each position relative to the previous token. Tokens are sorted
+by start; tokens with an unknown legend type, and any token overlapping the one
+before it, are dropped — the protocol requires a strictly non-overlapping,
+positionally-ordered stream.
+*/
+export function encodeSemanticTokens(text: string, tokens: SemanticToken[]): number[] {
+    const sorted = [...tokens].sort((a, b) => a.start - b.start || a.length - b.length)
+    const data: number[] = []
+    let previousLine = 0
+    let previousCharacter = 0
+    let previousEnd = -1
+    for (const token of sorted) {
+        const typeIndex = ABIDE_SEMANTIC_TOKENS_LEGEND.tokenTypes.indexOf(token.type)
+        if (typeIndex < 0 || token.start < previousEnd) {
+            continue
+        }
+        const modifierBitset = token.modifiers.reduce((bits, name) => {
+            const bit = ABIDE_SEMANTIC_TOKENS_LEGEND.tokenModifiers.indexOf(name)
+            return bit < 0 ? bits : bits | (1 << bit)
+        }, 0)
+        const { line, character } = offsetToPosition(text, token.start)
+        const deltaLine = line - previousLine
+        const deltaCharacter = deltaLine === 0 ? character - previousCharacter : character
+        data.push(deltaLine, deltaCharacter, token.length, typeIndex, modifierBitset)
+        previousLine = line
+        previousCharacter = character
+        previousEnd = token.start + token.length
+    }
+    return data
+}