fix: hoisted tag vars no longer collapse to never

.changeset/hoisted-tag-var-never.md

@@ -0,0 +1,9 @@
+---
+"@marko/language-server": patch
+"@marko/language-tools": patch
+"@marko/ts-plugin": patch
+"@marko/type-check": patch
+"marko-vscode": patch
+---
+
+Fix tag variables being typed `never` when referenced before their declaration or hoisted out of control flow, since `Marko._.hoist` only preserved function-typed values. Most visibly, `<style/styles>` used above the style tag errored with "Property does not exist on type 'never'".

agent-feedback/cleanup.md

@@ -1,3 +1,9 @@
 # Cleanup
 
 Duplication, dead code, inconsistencies, refactor opportunities. Format and rules: [README.md](README.md).
+
+## Plumb the source node (or tag kind) through `getProgramBindings`
+
+`packages/language-tools/src/extractors/script/util/attach-scopes.ts` › `getProgramBindings` | 2026-07-30 | impact:low | effort:med
+
+`ProgramBinding` exposes only `{ name, sources }` (plus mutation info), dropping the declaring node/tag. This makes it impossible for the script extractor's program-level hoist emission (`packages/language-tools/src/extractors/script/index.ts` › `#writeProgram`) to treat any tag kind specially — e.g. declaring a `<style/styles>` CSS-module var with its statically known selector type at program scope instead of routing it through `Marko._.hoist`. If per-tag-kind program-level typing is ever wanted, the binding needs to carry its `Node.Tag` (or at least the tag name). Re-verify: inspect the `ProgramBinding` interface in attach-scopes.ts and confirm it has no node reference.

agent-feedback/perf.md

@@ -1,3 +1,9 @@
 # Performance
 
 Runtime speed and bundle size opportunities. Format and rules: [README.md](README.md).
+
+## Tag-var hoisting is unconditional — no reference analysis
+
+`packages/language-tools/src/extractors/script/util/attach-scopes.ts` › `attachScopes` | 2026-07-30 | impact:low | effort:high
+
+Every tag-var binding is pushed to `potentialHoists` unconditionally, and every nested tag var whose walk reaches program scope becomes a `HoistedBinding` — whether or not anything outside its section references it. Each such binding costs a program-level `Marko._.hoist(...)` const plus `readScope`/`readScopes` machinery in the extracted TS, which the TypeScript checker must then evaluate per template. A reference-aware pass (only hoist names actually referenced outside their declaring scope) would shrink extracted output and checker work on templates with many tag vars. Re-verify: extract any template with a tag var inside an `<if>` that is never referenced elsewhere and observe the emitted `hoist`/`readScope` code.

packages/language-server/src/__tests__/fixtures/script/style-tag-var/__snapshots__/style-tag-var.expected/index.html

@@ -1 +1 @@
-<main data-marko-node-id="0" id="dynamic" class="dynamic"></main><div data-marko-node-id="1" class="dynamic"></div>
+<section data-marko-node-id="0" class="dynamic"></section><main data-marko-node-id="1" id="dynamic" class="dynamic"></main><div data-marko-node-id="2" class="dynamic"></div>

packages/language-server/src/__tests__/fixtures/script/style-tag-var/__snapshots__/style-tag-var.expected/index.md

@@ -1,22 +1,31 @@
 ## Hovers
-### Ln 13, Col 35
+### Ln 1, Col 23
 ```marko
-  11 | </style>
-  12 |
-> 13 | <main id=styles.main class=styles.button/>
+> 1 | <section class=styles.button/>
+    |                       ^ (property) "button": string
+  2 | //                    ^?
+  3 | <style/styles>
+  4 |   .button {
+```
+
+### Ln 15, Col 35
+```marko
+  13 | </style>
+  14 |
+> 15 | <main id=styles.main class=styles.button/>
      |                                   ^ (property) "button": string
-  14 | //                                ^?
-  15 | <div class=styles.missing/>
-  16 |
+  16 | //                                ^?
+  17 | <div class=styles.missing/>
+  18 |
 ```
 
 ## Diagnostics
-### Ln 15, Col 19
+### Ln 17, Col 19
 ```marko
-  13 | <main id=styles.main class=styles.button/>
-  14 | //                                ^?
-> 15 | <div class=styles.missing/>
+  15 | <main id=styles.main class=styles.button/>
+  16 | //                                ^?
+> 17 | <div class=styles.missing/>
      |                   ^^^^^^^ Property 'missing' does not exist on type '{ button: string; main: string; }'.
-  16 |
+  18 |
 ```
 

packages/language-server/src/__tests__/fixtures/script/style-tag-var/__snapshots__/style-tag-var.expected/index.ts

@@ -7,15 +7,21 @@ export interface Input {}
     (Marko._.error, Marko._.any as MarkoRun.Context),
   );
   const styles = Marko._.hoist(() => __marko_internal_hoist__styles);
+  Marko._.renderNativeTag("section")()()({
+    class: styles.button,
+  });
   {
     const styles = Marko._.any as { button: string; main: string };
-    Marko._.renderNativeTag("style")()()({
-      [Marko._.content]: (() => {
-        return () => {
-          return Marko._.voidReturn;
-        };
-      })(),
-    });
+    Marko._.renderNativeTag("style")()()(
+      //                    ^?
+      {
+        [Marko._.content]: (() => {
+          return () => {
+            return Marko._.voidReturn;
+          };
+        })(),
+      },
+    );
     Marko._.renderNativeTag("main")()()({
       id: styles.main,
       class: styles.button,

packages/language-server/src/__tests__/fixtures/script/style-tag-var/index.marko

@@ -1,3 +1,5 @@
+<section class=styles.button/>
+//                    ^?
 <style/styles>
   .button {
     color: blue;

packages/language-server/src/__tests__/fixtures/script/tag-var-hoisting-from-control-flow/__snapshots__/tag-var-hoisting-from-control-flow.expected/index.md

@@ -36,7 +36,7 @@
   20 |
   21 | -- ${() => {
 > 22 |   a;
-     |   ^ const a: never
+     |   ^ const a: readonly ["apples", "oranges"]
   23 | //^?
   24 |   b;
   25 | //^?
@@ -47,7 +47,7 @@
   22 |   a;
   23 | //^?
 > 24 |   b;
-     |   ^ const b: never
+     |   ^ const b: readonly ["slice", "dice"]
   25 | //^?
   26 |   c;
   27 | //^?

packages/language-tools/marko.internal.d.ts

@@ -33,7 +33,7 @@ declare global {
 
       export function hoist<T>(
         value: () => T,
-      ): T extends () => infer R ? T & Iterable<R> : never;
+      ): T extends () => infer R ? T & Iterable<R> : Exclude<T, undefined>;
       // TODO: hoist should really be the below implementation which accounts for hoisting from unknown
       // sections causing the getter to return undefined. Right now the type says it always has a value.
       // export function hoist<T, U = T>(