Kielan · February 14, 2026 21:02 · Feb 14, 2026 · Feb 14, 2026 · Feb 14, 2026
diff --git a/README.md b/README.md
@@ -278,15 +278,17 @@ provideCompletionItems
 Set breakpoint in:
 suggestModel.ts
 Run VS Code in dev mode:
+```
 yarn watch
+```
 ./scripts/code.sh
 
 14. If You're Studying Architecture
 The most educational files:
 Those define the whole contract.
+```
 languages.ts
 suggestModel.ts
 extHostLanguageFeatures.ts
 languageFeatureRegistry.ts
-
-https://chatgpt.com/?utm_source=google&utm_medium=paid_search&utm_campaign=GOOG_C_SEM_GBR_Core_CHT_BAU_ACQ_PER_MIX_ALL_NAMER_US_EN_091724&c_id=21714513245&c_agid=169187630042&c_crid=713941893298&c_kwid={keywordid}&c_ims=&c_pms=9032905&c_nw=g&c_dvc=c&gad_source=1&gad_campaignid=21714513245&gbraid=0AAAAA-I0E5euvThCYMMNZyWABQrAgx4b_&gclid=Cj0KCQiA18DMBhDeARIsABtYwT05M-ZK_ujpLpBERuz0tpXGVGnTujCKvyIjGbJVJp1-CLth1c79IFsaAhhZEALw_wcB
+```
diff --git a/README.md b/README.md
@@ -289,3 +289,4 @@ suggestModel.ts
 extHostLanguageFeatures.ts
 languageFeatureRegistry.ts
 
+https://chatgpt.com/?utm_source=google&utm_medium=paid_search&utm_campaign=GOOG_C_SEM_GBR_Core_CHT_BAU_ACQ_PER_MIX_ALL_NAMER_US_EN_091724&c_id=21714513245&c_agid=169187630042&c_crid=713941893298&c_kwid={keywordid}&c_ims=&c_pms=9032905&c_nw=g&c_dvc=c&gad_source=1&gad_campaignid=21714513245&gbraid=0AAAAA-I0E5euvThCYMMNZyWABQrAgx4b_&gclid=Cj0KCQiA18DMBhDeARIsABtYwT05M-ZK_ujpLpBERuz0tpXGVGnTujCKvyIjGbJVJp1-CLth1c79IFsaAhhZEALw_wcB
diff --git a/README.md b/README.md
@@ -0,0 +1,291 @@
+VS Code’s core architecture:
+VS Code splits into three major layers:
+UI (Workbench)
+    ↓
+Editor (Monaco)
+    ↓
+Language Features (Providers / LSP)
+
+VS Code itself does NOT parse most languages.
+It delegates to:
+- Built-in language services (TS/JS, JSON, HTML, CSS)
+- Extensions
+- LSP servers
+
+Autocomplete (Suggest) data flow/architecture:
+When you press:
+Ctrl + Space
+
+Here’s what happens:
+SuggestController
+    ↓
+SuggestModel
+    ↓
+CompletionItemProvider (1..N)
+    ↓
+Language Feature Registry
+    ↓
+Extension Host or Built-in Provider
+    ↓
+(Optional) LSP Server
+
+🔹 UI Layer (Popup Menu)
+src/vs/editor/contrib/suggest/
+
+Key Files
+1️⃣ suggestController.ts
+
+Main entry point for triggering suggest.
+Class:
+SuggestController
+Key methods:
+triggerSuggest()
+_cancelSuggestWidget()
+
+2️⃣ suggestModel.ts
+Handles provider orchestration and merging results.
+This is where all providers are queried.
+Class:
+SuggestModel
+Important methods:
+trigger(context: SuggestTriggerContext)
+_provideCompletionItems()
+
+3️⃣ suggestWidget.ts
+The actual popup UI list.
+Class:
+SuggestWidget
+Handles:
+Rendering
+Selection
+Filtering
+Focus
+
+3. Completion Providers (Language Side)
+This is the core autocomplete interface.
+Provider Interface
+Defined in:
+src/vs/editor/common/languages.ts
+Interface:
+export interface CompletionItemProvider {
+    provideCompletionItems(
+        model: ITextModel,
+        position: Position,
+        context: CompletionContext,
+        token: CancellationToken
+    ): ProviderResult<CompletionList>;
+}
+
+Registry
+In:
+src/vs/editor/common/languageFeatureRegistry.ts
+Class:
+LanguageFeatureRegistry<T>
+Used for:
+-CompletionItemProvider
+-HoverProvider
+-DefinitionProvider
+-etc.
+
+4. Hover / “Lookup Window” (Tooltip)
+When you hover over a symbol:
+HoverController
+    ↓
+HoverOperation
+    ↓
+HoverProvider (1..N)
+    ↓
+Language Service / LSP
+
+🔹 UI Files
+Folder:
+src/vs/editor/contrib/hover/
+Important files:
+hoverController.ts
+Entry point.
+contentHoverController.ts
+Coordinates content hover behavior.
+hoverWidget.ts
+The actual tooltip UI.
+
+Hover Provider Interface
+In:
+src/vs/editor/common/languages.ts
+Interface:
+export interface HoverProvider {
+    provideHover(
+        model: ITextModel,
+        position: Position,
+        token: CancellationToken
+    ): ProviderResult<Hover>;
+}
+
+5. Syntax Tree — Where It Actually Comes From
+VS Code editor itself does NOT build an AST for most languages.
+Instead:
+| Language              | Who owns AST                |
+| --------------------- | --------------------------- |
+| TypeScript/JavaScript | TypeScript Server           |
+| JSON                  | vscode-json-languageservice |
+| HTML                  | vscode-html-languageservice |
+| CSS                   | vscode-css-languageservice  |
+| Python                | Pylance extension           |
+| Rust                  | rust-analyzer extension     |
+
+TypeScript Example (Built-in)
+Extension folder:
+extensions/typescript-language-features/
+Important file:
+src/tsServer/tsServerService.ts
+This launches:
+tsserver.js
+
+The AST lives inside TypeScript's compiler services.
+Autocomplete ultimately comes from:
+
+languageService.getCompletionsAtPosition()
+
+Defined in the TypeScript repo, not VS Code.
+
+6. LSP Data Flow (Most Languages)
+For extension-based languages:
+Editor (Monaco)
+    ↓
+Extension Host
+    ↓
+vscode-languageclient
+    ↓
+JSON-RPC
+    ↓
+Language Server (separate process)
+
+LSP Interface (Extension API)
+Registers providers from extensions.
+In:
+src/vs/workbench/api/common/extHostLanguageFeatures.ts
+Key class:
+ExtHostLanguageFeatures
+
+Completion LSP Spec
+Protocol definition lives in:
+Language Server Protocol repo:
+Completion request:
+textDocument/completion
+Spec:
+CompletionParams
+CompletionItem
+CompletionList
+
+7. Full Autocomplete Flow (Step-by-Step)
+Let’s trace Ctrl+Space fully:
+1️⃣ User triggers suggest
+SuggestController.triggerSuggest()
+↓
+2️⃣ SuggestModel gathers providers
+LanguageFeatureRegistry<CompletionItemProvider>
+↓
+3️⃣ Each provider called
+provideCompletionItems()
+↓
+4️⃣ If LSP-backed:
+Extension Host →
+JSON RPC →
+Language Server →
+returns CompletionItems
+↓
+5️⃣ SuggestModel merges & ranks
+↓
+6️⃣ SuggestWidget renders popup
+
+8. Core Language Interfaces
+src/vs/editor/common/languages.ts
+Defines:
+CompletionItem
+Hover
+Definition
+DocumentSymbol
+2️⃣ Provider Registry
+src/vs/editor/common/languageFeatureRegistry.ts
+3️⃣ Suggest Engine
+src/vs/editor/contrib/suggest/
+4️⃣ Hover Engine
+src/vs/editor/contrib/hover/
+5️⃣ Extension Host Bridge
+src/vs/workbench/api/common/extHostLanguageFeatures.ts
+
+9. Monaco vs VS Code
+Important distinction:
+VS Code embeds Monaco Editor.
+Monaco repo:
+https://github.com/microsoft/monaco-editor
+Many editor-side files originate from Monaco.
+If you're exploring autocomplete internals, also read:
+monaco-editor/src/vs/editor/contrib/suggest/
+They are extremely similar.
+
+10. Architectural Layers (Mental Model)
+Think of VS Code like this:
+[Workbench UI]
+    panels, tabs, layout
+[Editor (Monaco)]
+    text model
+    cursor
+    decorations
+    suggest
+    hover
+[Language Feature Registry]
+    provider orchestration
+[Extension Host]
+    sandbox for extensions
+[Language Server / Built-in Service]
+    AST
+    type checking
+    semantic model
+
+11. If You Want to Modify Behavior
+Modify popup UI?
+Look in:
+suggestWidget.ts
+Modify ranking?
+completionModel.ts
+Modify trigger logic?
+suggestController.ts
+Modify hover appearance?
+hoverWidget.ts
+
+12. Where Lookup Tables Live
+There are 2 types:
+1️⃣ Keyword-based completion
+Hardcoded arrays inside language services.
+Example:
+JSON schema keywords
+HTML tags list
+These live in:
+vscode-html-languageservice
+vscode-json-languageservice
+
+2️⃣ AST-based lookup
+Generated from:
+TypeScript compiler API
+LSP server symbol tables
+VS Code itself does not maintain symbol tables.
+
+13. Best Way to Learn the Flow
+I recommend:
+Open VS Code repo
+Search:
+provideCompletionItems
+Set breakpoint in:
+suggestModel.ts
+Run VS Code in dev mode:
+yarn watch
+./scripts/code.sh
+
+14. If You're Studying Architecture
+The most educational files:
+Those define the whole contract.
+languages.ts
+suggestModel.ts
+extHostLanguageFeatures.ts
+languageFeatureRegistry.ts
+
No results found