feat: Stac VS Code Plugin

.gitignore

@@ -1,5 +1,6 @@
 # Miscellaneous
 *.class
+**/node_modules/
 *.log
 *.pyc
 *.swp
@@ -45,3 +46,10 @@ mason-lock.json
 
 # FVM Version Cache
 .fvm/
+
+# VS Code extension (stac-vscode)
+tools/stac-vscode/out/
+tools/stac-vscode/build/
+*.vsix
+.eslintcache
+.vscode-test/

examples/counter_example/pubspec.lock

@@ -452,10 +452,10 @@ packages:
     dependency: transitive
     description:
       name: matcher
-      sha256: "12956d0ad8390bbcc63ca2e1469c0619946ccb52809807067a7020d57e647aa6"
+      sha256: dc0b7dc7651697ea4ff3e69ef44b0407ea32c487a39fff6a4004fa585e901861
       url: "https://pub.dev"
     source: hosted
-    version: "0.12.18"
+    version: "0.12.19"
   material_color_utilities:
     dependency: transitive
     description:
@@ -861,10 +861,10 @@ packages:
     dependency: transitive
     description:
       name: test_api
-      sha256: "93167629bfc610f71560ab9312acdda4959de4df6fac7492c89ff0d3886f6636"
+      sha256: "8161c84903fd860b26bfdefb7963b3f0b68fee7adea0f59ef805ecca346f0c7a"
       url: "https://pub.dev"
     source: hosted
-    version: "0.7.9"
+    version: "0.7.10"
   timing:
     dependency: transitive
     description:

examples/movie_app/pubspec.lock

@@ -388,10 +388,10 @@ packages:
     dependency: transitive
     description:
       name: matcher
-      sha256: "12956d0ad8390bbcc63ca2e1469c0619946ccb52809807067a7020d57e647aa6"
+      sha256: dc0b7dc7651697ea4ff3e69ef44b0407ea32c487a39fff6a4004fa585e901861
       url: "https://pub.dev"
     source: hosted
-    version: "0.12.18"
+    version: "0.12.19"
   material_color_utilities:
     dependency: transitive
     description:
@@ -789,10 +789,10 @@ packages:
     dependency: transitive
     description:
       name: test_api
-      sha256: "93167629bfc610f71560ab9312acdda4959de4df6fac7492c89ff0d3886f6636"
+      sha256: "8161c84903fd860b26bfdefb7963b3f0b68fee7adea0f59ef805ecca346f0c7a"
       url: "https://pub.dev"
     source: hosted
-    version: "0.7.9"
+    version: "0.7.10"
   typed_data:
     dependency: transitive
     description:

examples/stac_gallery/pubspec.lock

@@ -428,10 +428,10 @@ packages:
     dependency: transitive
     description:
       name: matcher
-      sha256: "12956d0ad8390bbcc63ca2e1469c0619946ccb52809807067a7020d57e647aa6"
+      sha256: dc0b7dc7651697ea4ff3e69ef44b0407ea32c487a39fff6a4004fa585e901861
       url: "https://pub.dev"
     source: hosted
-    version: "0.12.18"
+    version: "0.12.19"
   material_color_utilities:
     dependency: transitive
     description:
@@ -860,10 +860,10 @@ packages:
     dependency: transitive
     description:
       name: test_api
-      sha256: "93167629bfc610f71560ab9312acdda4959de4df6fac7492c89ff0d3886f6636"
+      sha256: "8161c84903fd860b26bfdefb7963b3f0b68fee7adea0f59ef805ecca346f0c7a"
       url: "https://pub.dev"
     source: hosted
-    version: "0.7.9"
+    version: "0.7.10"
   typed_data:
     dependency: transitive
     description:

tools/stac-vscode/.vscode-test.mjs

@@ -0,0 +1,5 @@
+import { defineConfig } from '@vscode/test-cli';
+
+export default defineConfig({
+	files: 'out/test/**/*.test.js',
+});

tools/stac-vscode/.vscode/extensions.json

@@ -0,0 +1,8 @@
+{
+	// See http://go.microsoft.com/fwlink/?LinkId=827846
+	// for the documentation about the extensions.json format
+	"recommendations": [
+		"dbaeumer.vscode-eslint",
+		"ms-vscode.extension-test-runner"
+	]
+}

tools/stac-vscode/.vscode/launch.json

@@ -0,0 +1,21 @@
+// A launch configuration that compiles the extension and then opens it inside a new window
+// Use IntelliSense to learn about possible attributes.
+// Hover to view descriptions of existing attributes.
+// For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
+{
+	"version": "0.2.0",
+	"configurations": [
+		{
+			"name": "Run Extension",
+			"type": "extensionHost",
+			"request": "launch",
+			"args": [
+				"--extensionDevelopmentPath=${workspaceFolder}"
+			],
+			"outFiles": [
+				"${workspaceFolder}/out/**/*.js"
+			],
+			"preLaunchTask": "${defaultBuildTask}"
+		}
+	]
+}

tools/stac-vscode/.vscode/settings.json

@@ -0,0 +1,11 @@
+// Place your settings in this file to overwrite default and user settings.
+{
+	"files.exclude": {
+		"out": false // set this to true to hide the "out" folder with the compiled JS files
+	},
+	"search.exclude": {
+		"out": true // set this to false to include "out" folder in search results
+	},
+	// Turn off tsc task auto detection since we have the necessary tasks as npm scripts
+	"typescript.tsc.autoDetect": "off"
+}

tools/stac-vscode/.vscode/tasks.json

@@ -0,0 +1,20 @@
+// See https://go.microsoft.com/fwlink/?LinkId=733558
+// for the documentation about the tasks.json format
+{
+	"version": "2.0.0",
+	"tasks": [
+		{
+			"type": "npm",
+			"script": "watch",
+			"problemMatcher": "$tsc-watch",
+			"isBackground": true,
+			"presentation": {
+				"reveal": "never"
+			},
+			"group": {
+				"kind": "build",
+				"isDefault": true
+			}
+		}
+	]
+}

tools/stac-vscode/.vscodeignore

@@ -0,0 +1,15 @@
+.vscode/**
+.vscode-test/**
+src/**
+.gitignore
+.yarnrc
+vsc-extension-quickstart.md
+**/tsconfig.json
+**/eslint.config.mjs
+**/*.map
+**/*.ts
+**/.vscode-test.*
+preview_host/.dart_tool/**
+preview_host/build/**
+preview_host/.flutter-plugins
+preview_host/.flutter-plugins-dependencies

tools/stac-vscode/CHANGELOG.md

@@ -0,0 +1,25 @@
+# Change Log
+
+All notable changes to the "stac-vscode" extension will be documented in this file.
+
+## [0.1.0]
+
+### Live Preview
+- Side-by-side preview panel for any `@StacScreen` — updates on save.
+- Android / iOS / Web device toggles with `TargetPlatform` simulation (scroll physics, page transitions, AppBar behavior).
+- Theme discovery from `@StacThemeRef` annotations with live theme selection dropdown.
+- Multi-screen support with automatic cursor-based screen switching.
+- Runner fast-path JSON generation (`screen().toJson()`) with build fallback.
+- Automatic port recovery when the preview host port is in use.
+- Mobile viewport frame with rounded border styling.
+
+### Wrap Quick Fixes
+- Cmd+. quick-fix wrapping for Stac widgets in Dart files.
+- Presets: `StacContainer`, `StacPadding`, `StacCenter`, `StacAlign`, `StacSizedBox`, `StacExpanded`.
+- "Wrap with Stac widget…" for any Stac widget class.
+- Auto-generated widget catalog from `packages/stac_core`.
+
+### Snippets
+- `stac screen` — new screen template.
+- `stac theme` — new theme template.
+- Context-aware: only shown in Stac DSL files.

tools/stac-vscode/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Stac
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

tools/stac-vscode/README.md

@@ -0,0 +1,67 @@
+# Stac — Server-Driven UI for Flutter
+
+Build and preview Server-Driven UI screens with the **Stac** framework — directly inside VS Code.
+
+## ✨ Features
+
+### 🔴 Live Preview
+Open a side-by-side preview of any `@StacScreen` — updates on save, supports theme selection, and renders with Android/iOS/Web platform simulation.
+
+![Stac Live Preview](media/stac_preview.png)
+
+- **`Stac: Open Preview`** — launch the preview panel for the active screen
+- **Device toggles** — switch between Android, iOS, and Web viewports
+- **Theme picker** — select any `@StacThemeRef` theme to preview with
+
+### 🔧 Wrap Quick Fixes
+Place your cursor on any Stac widget expression and press **Cmd+.** to wrap it:
+
+- `StacContainer`, `StacPadding`, `StacCenter`, `StacAlign`, `StacSizedBox`, `StacExpanded`
+- **Wrap with Stac widget…** — type any Stac widget class name
+
+### 📝 Snippets
+Type in a Stac DSL context (files containing `@StacScreen`, `@StacThemeRef`, or `package:stac_core`):
+
+- `stac screen` — new screen template
+- `stac theme` — new theme template
+
+## ⚙️ Extension Settings
+
+| Setting | Default | Description |
+|---|---|---|
+| `stacVscode.enableWrapQuickFix` | `true` | Enable wrap quick-fix actions |
+| `stacVscode.wrapPresets` | All presets | Preset wrappers in quick-fix menu |
+| `stacVscode.enableSnippets` | `true` | Enable `stac screen`/`stac theme` snippets |
+| `stacVscode.preview.enable` | `true` | Enable preview commands |
+| `stacVscode.preview.autoRefreshOnSave` | `true` | Refresh preview on save |
+| `stacVscode.preview.jsonStrategy` | `runnerThenBuild` | JSON generation strategy |
+| `stacVscode.preview.hostPort` | `47841` | Local preview host port |
+| `stacVscode.preview.startupTimeoutMs` | `120000` | Host startup timeout |
+
+## Requirements
+
+- **Flutter SDK** with Dart `3.9.2+`
+- A Flutter project using the [Stac](https://stac.dev) framework
+
+## Commands
+
+| Command | Description |
+|---|---|
+| `Stac: Open Preview` | Open live preview panel |
+| `Stac: Select Preview Screen` | Switch to a different screen in the current file |
+| `Stac: Stop Preview` | Stop the preview host |
+| `Stac: Regenerate Catalog` | Rebuild widget catalog from `stac_core` |
+
+## Troubleshooting
+
+If the preview doesn't start, open **Output → Stac Preview** for detailed logs.
+
+## Links
+
+- [Stac Documentation](https://stac.dev)
+- [GitHub Repository](https://github.com/StacDev/stac)
+- [Report Issues](https://github.com/StacDev/stac/issues)
+
+## License
+
+[MIT](LICENSE)

tools/stac-vscode/eslint.config.mjs

@@ -0,0 +1,28 @@
+import typescriptEslint from "typescript-eslint";
+
+export default [{
+    files: ["**/*.ts"],
+}, {
+    files: ["**/*.ts"],
+    plugins: {
+        "@typescript-eslint": typescriptEslint.plugin,
+    },
+
+    languageOptions: {
+        parser: typescriptEslint.parser,
+        ecmaVersion: 2022,
+        sourceType: "module",
+    },
+
+    rules: {
+        "@typescript-eslint/naming-convention": ["warn", {
+            selector: "import",
+            format: ["camelCase", "PascalCase"],
+        }],
+
+        curly: "warn",
+        eqeqeq: "warn",
+        "no-throw-literal": "warn",
+        semi: "warn",
+    },
+}];