@macroforge/mcp-server 0.1.42 → 0.1.50

package/docs/integration/mcp-server.md

@@ -1,45 +1,86 @@
 # MCP Server
- *The MCP (Model Context Protocol) server enables AI assistants to understand and work with Macroforge macros, providing documentation lookup, code validation, and macro expansion.*
- The local (stdio) version of the MCP server is available via the [<code class="shiki-inline"><span class="line"><span style="--shiki-dark:#E1E4E8;--shiki-light:#24292E">@macroforge<span style="--shiki-dark:#F97583;--shiki-light:#D73A49">/<span style="--shiki-dark:#E1E4E8;--shiki-light:#24292E">mcp<span style="--shiki-dark:#F97583;--shiki-light:#D73A49">-<span style="--shiki-dark:#E1E4E8;--shiki-light:#24292E">server</code>](https://www.npmjs.com/package/@macroforge/mcp-server) npm package. You can either install it globally and then reference it in your configuration or run it with <code class="shiki-inline"><span class="line"><span style="--shiki-dark:#E1E4E8;--shiki-light:#24292E">npx</code>:
- ```
-npx&nbsp;-y&nbsp;@macroforge/mcp-server
-``` Here's how to set it up in some common MCP clients:
- ## Claude Code
- To include the local MCP version in Claude Code, simply run the following command:
- ```
-claude&nbsp;mcp&nbsp;add&nbsp;-t&nbsp;stdio&nbsp;-s&nbsp;[scope]&nbsp;macroforge&nbsp;--&nbsp;npx&nbsp;-y&nbsp;@macroforge/mcp-server
-``` The <code class="shiki-inline"><span class="line"><span style="--shiki-dark:#E1E4E8;--shiki-light:#24292E">[scope]</code> must be <code class="shiki-inline"><span class="line"><span style="--shiki-dark:#E1E4E8;--shiki-light:#24292E">user</code>, <code class="shiki-inline"><span class="line"><span style="--shiki-dark:#E1E4E8;--shiki-light:#24292E">project</code> or <code class="shiki-inline"><span class="line"><span style="--shiki-dark:#E1E4E8;--shiki-light:#24292E">local</code>.
- ## Claude Desktop
- In the Settings > Developer section, click on Edit Config. It will open the folder with a <code class="shiki-inline"><span class="line"><span style="--shiki-dark:#E1E4E8;--shiki-light:#24292E">claude_desktop_config.json</code> file in it. Edit the file to include the following configuration:
- ```
-&#123;
-&nbsp;&nbsp;&nbsp;&nbsp;"mcpServers":&nbsp;&#123;
-&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"macroforge":&nbsp;&#123;
-&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"command":&nbsp;"npx",
-&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"args":&nbsp;["-y",&nbsp;"@macroforge/mcp-server"]
-&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&#125;
-&nbsp;&nbsp;&nbsp;&nbsp;&#125;
-&#125;
-``` ## Codex CLI
- Add the following to your <code class="shiki-inline"><span class="line"><span style="--shiki-dark:#FDAEB7;--shiki-dark-font-style:italic;--shiki-light:#B31D28;--shiki-light-font-style:italic">config.toml</code> (which defaults to <code class="shiki-inline"><span class="line"><span style="--shiki-dark:#FDAEB7;--shiki-dark-font-style:italic;--shiki-light:#B31D28;--shiki-light-font-style:italic">~/.codex/config.toml</code>, but refer to [the configuration documentation](https://github.com/openai/codex/blob/main/docs/config.md) for more advanced setups):
- ```
+
+The MCP (Model Context Protocol) server enables AI assistants to understand and work with Macroforge macros, providing documentation lookup, code validation, and macro expansion.
+
+The local (stdio) version of the MCP server is available via the [`@macroforge/mcp-server`](https://www.npmjs.com/package/@macroforge/mcp-server) npm package. You can either install it globally and then reference it in your configuration or run it with `npx`:
+
+Bash
+
+```
+npx -y @macroforge/mcp-server
+```
+
+Here's how to set it up in some common MCP clients:
+
+## Claude Code
+
+To include the local MCP version in Claude Code, simply run the following command:
+
+Bash
+
+```
+claude mcp add -t stdio -s [scope] macroforge -- npx -y @macroforge/mcp-server
+```
+
+The `[scope]` must be `user`, `project` or `local`.
+
+## Claude Desktop
+
+In the Settings > Developer section, click on Edit Config. It will open the folder with a `claude_desktop_config.json` file in it. Edit the file to include the following configuration:
+
+claude\_desktop\_config.json 
+
+```
+{
+    "mcpServers": {
+        "macroforge": {
+            "command": "npx",
+            "args": ["-y", "@macroforge/mcp-server"]
+        }
+    }
+}
+```
+
+## Codex CLI
+
+Add the following to your `config.toml` (which defaults to `~/.codex/config.toml`, but refer to [the configuration documentation](https://github.com/openai/codex/blob/main/docs/config.md) for more advanced setups):
+
+config.toml 
+
+```
 [mcp_servers.macroforge]
-command&nbsp;=&nbsp;"npx"
-args&nbsp;=&nbsp;["-y",&nbsp;"@macroforge/mcp-server"]
-``` ## Gemini CLI
- To include the local MCP version in Gemini CLI, simply run the following command:
- ```
-gemini&nbsp;mcp&nbsp;add&nbsp;-t&nbsp;stdio&nbsp;-s&nbsp;[scope]&nbsp;macroforge&nbsp;npx&nbsp;-y&nbsp;@macroforge/mcp-server
-``` The <code class="shiki-inline"><span class="line"><span style="--shiki-dark:#E1E4E8;--shiki-light:#24292E">[scope]</code> must be <code class="shiki-inline"><span class="line"><span style="--shiki-dark:#E1E4E8;--shiki-light:#24292E">user</code>, <code class="shiki-inline"><span class="line"><span style="--shiki-dark:#E1E4E8;--shiki-light:#24292E">project</code> or <code class="shiki-inline"><span class="line"><span style="--shiki-dark:#E1E4E8;--shiki-light:#24292E">local</code>.
- ## Other Clients
- If we didn't include the MCP client you are using, refer to their documentation for <code class="shiki-inline"><span class="line"><span style="--shiki-dark:#E1E4E8;--shiki-light:#24292E">stdio</code> servers and use <code class="shiki-inline"><span class="line"><span style="--shiki-dark:#E1E4E8;--shiki-light:#24292E">npx</code> as the command and <code class="shiki-inline"><span class="line"><span style="--shiki-dark:#F97583;--shiki-light:#D73A49">-<span style="--shiki-dark:#E1E4E8;--shiki-light:#24292E">y @macroforge<span style="--shiki-dark:#F97583;--shiki-light:#D73A49">/<span style="--shiki-dark:#E1E4E8;--shiki-light:#24292E">mcp<span style="--shiki-dark:#F97583;--shiki-light:#D73A49">-<span style="--shiki-dark:#E1E4E8;--shiki-light:#24292E">server</code> as the arguments.
- ## Available Tools
- The MCP server provides five tools for AI assistants:
- | Tool | Description |
-| --- | --- |
-| list-sections | Lists all available Macroforge documentation sections |
-| get-documentation | Retrieves full documentation for one or more sections |
-| macroforge-autofixer | Validates code with @derive decorators and returns diagnostics |
-| expand-code | Expands macros and returns the transformed TypeScript code |
-| get-macro-info | Retrieves documentation for macros and field decorators |
- > **Note:** For code validation and expansion features (macroforge-autofixer, expand-code, get-macro-info), the MCP server requires macroforge as a peer dependency. Install it in your project with npm install macroforge.
+command = "npx"
+args = ["-y", "@macroforge/mcp-server"]
+```
+
+## Gemini CLI
+
+To include the local MCP version in Gemini CLI, simply run the following command:
+
+Bash
+
+```
+gemini mcp add -t stdio -s [scope] macroforge npx -y @macroforge/mcp-server
+```
+
+The `[scope]` must be `user`, `project` or `local`.
+
+## Other Clients
+
+If we didn't include the MCP client you are using, refer to their documentation for `stdio` servers and use `npx` as the command and `-y @macroforge/mcp-server` as the arguments.
+
+## Available Tools
+
+The MCP server provides five tools for AI assistants:
+
+| Tool                   | Description                                                      |
+| ---------------------- | ---------------------------------------------------------------- |
+| `list-sections`        | Lists all available Macroforge documentation sections            |
+| `get-documentation`    | Retrieves full documentation for one or more sections            |
+| `macroforge-autofixer` | Validates code with `@derive` decorators and returns diagnostics |
+| `expand-code`          | Expands macros and returns the transformed TypeScript code       |
+| `get-macro-info`       | Retrieves documentation for macros and field decorators          |
+
+Note
+
+For code validation and expansion features (`macroforge-autofixer`, `expand-code`, `get-macro-info`), the MCP server requires `macroforge` as a peer dependency. Install it in your project with `npm install macroforge`.

package/docs/integration/svelte-preprocessor.md

@@ -1,128 +1,185 @@
 # Svelte Preprocessor
- *The Svelte preprocessor expands Macroforge macros in <code class="shiki-inline"><span class="line"><span style="--shiki-dark:#E1E4E8;--shiki-light:#24292E"><<span style="--shiki-dark:#B392F0;--shiki-light:#6F42C1">script<span style="--shiki-dark:#E1E4E8;--shiki-light:#24292E">></code> blocks before Svelte compilation, enabling seamless macro usage in Svelte components.*
- ## Installation
- ```
-npm&nbsp;install&nbsp;-D&nbsp;@macroforge/svelte-preprocessor
-``` ## Configuration
- Add the preprocessor to your <code class="shiki-inline"><span class="line"><span style="--shiki-dark:#E1E4E8;--shiki-light:#24292E">svelte.config.js</code>:
- ```
-import&nbsp;adapter&nbsp;from&nbsp;'@sveltejs/adapter-auto';
-import&nbsp;&#123;&nbsp;vitePreprocess&nbsp;&#125;&nbsp;from&nbsp;'@sveltejs/vite-plugin-svelte';
-import&nbsp;&#123;&nbsp;macroforgePreprocess&nbsp;&#125;&nbsp;from&nbsp;'@macroforge/svelte-preprocessor';
-
-/**&nbsp;@type&nbsp;&#123;import('@sveltejs/kit').Config&#125;&nbsp;*/
-const&nbsp;config&nbsp;=&nbsp;&#123;
-&nbsp;&nbsp;preprocess:&nbsp;[
-&nbsp;&nbsp;&nbsp;&nbsp;macroforgePreprocess(),&nbsp;&nbsp;//&nbsp;Expand&nbsp;macros&nbsp;FIRST
-&nbsp;&nbsp;&nbsp;&nbsp;vitePreprocess()&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;//&nbsp;Then&nbsp;handle&nbsp;TypeScript/CSS
-&nbsp;&nbsp;],
-
-&nbsp;&nbsp;kit:&nbsp;&#123;
-&nbsp;&nbsp;&nbsp;&nbsp;adapter:&nbsp;adapter()
-&nbsp;&nbsp;&#125;
-&#125;;
-
-export&nbsp;default&nbsp;config;
-```  **Warning Always place **<code class="shiki-inline"><span class="line"><span style="--shiki-dark:#B392F0;--shiki-light:#6F42C1">macroforgePreprocess<span style="--shiki-dark:#E1E4E8;--shiki-light:#24292E">()</code> **before** other preprocessors like <code class="shiki-inline"><span class="line"><span style="--shiki-dark:#B392F0;--shiki-light:#6F42C1">vitePreprocess<span style="--shiki-dark:#E1E4E8;--shiki-light:#24292E">()</code>. This ensures macros are expanded before TypeScript compilation. ## Usage
- Use <code class="shiki-inline"><span class="line"><span style="--shiki-dark:#E1E4E8;--shiki-light:#24292E">@derive</code> decorators directly in your Svelte component scripts:
- ```
-&#x3C;script&nbsp;lang="ts">
-&nbsp;&nbsp;/**&nbsp;@derive(Debug,&nbsp;Clone)&nbsp;*/
-&nbsp;&nbsp;class&nbsp;User&nbsp;&#123;
-&nbsp;&nbsp;&nbsp;&nbsp;name:&nbsp;string;
-&nbsp;&nbsp;&nbsp;&nbsp;email:&nbsp;string;
-
-&nbsp;&nbsp;&nbsp;&nbsp;constructor(name:&nbsp;string,&nbsp;email:&nbsp;string)&nbsp;&#123;
-&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;this.name&nbsp;=&nbsp;name;
-&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;this.email&nbsp;=&nbsp;email;
-&nbsp;&nbsp;&nbsp;&nbsp;&#125;
-&nbsp;&nbsp;&#125;
-
-&nbsp;&nbsp;let&nbsp;user&nbsp;=&nbsp;new&nbsp;User("Alice",&nbsp;"alice@example.com");
-&nbsp;&nbsp;console.log(user.toString());&nbsp;&nbsp;//&nbsp;Generated&nbsp;by&nbsp;Debug&nbsp;macro
-&#x3C;/script>
-
-&#x3C;p>User:&nbsp;&#123;user.name&#125;&#x3C;/p>
-``` ## Options
- ```
-macroforgePreprocess(&#123;
-&nbsp;&nbsp;//&nbsp;Keep&nbsp;@derive&nbsp;decorators&nbsp;in&nbsp;output&nbsp;(for&nbsp;debugging)
-&nbsp;&nbsp;keepDecorators:&nbsp;false,
-
-&nbsp;&nbsp;//&nbsp;Process&nbsp;JavaScript&nbsp;files&nbsp;(not&nbsp;just&nbsp;TypeScript)
-&nbsp;&nbsp;processJavaScript:&nbsp;false
-&#125;)
-``` ### Option Reference
- | Option | Type | Default | Description |
-| --- | --- | --- | --- |
-| keepDecorators | boolean | false | Keep decorators in output |
-| processJavaScript | boolean | false | Process <script> blocks without lang="ts" |
- ## How It Works
- The preprocessor:
- 1. Intercepts <code class="shiki-inline"><span class="line"><span style="--shiki-dark:#F97583;--shiki-light:#D73A49"><<span style="--shiki-dark:#E1E4E8;--shiki-light:#24292E">script lang<span style="--shiki-dark:#F97583;--shiki-light:#D73A49">=<span style="--shiki-dark:#9ECBFF;--shiki-light:#032F62">"ts"<span style="--shiki-dark:#F97583;--shiki-light:#D73A49">></code> blocks in <code class="shiki-inline"><span class="line"><span style="--shiki-dark:#E1E4E8;--shiki-light:#24292E">.svelte</code> files
- 2. Checks for <code class="shiki-inline"><span class="line"><span style="--shiki-dark:#E1E4E8;--shiki-light:#24292E">@derive</code> decorators (skips files without them)
- 3. Expands macros using the native Macroforge binary
- 4. Returns the transformed code for Svelte compilation
-  **Tip Files without **<code class="shiki-inline"><span class="line"><span style="--shiki-dark:#E1E4E8;--shiki-light:#24292E">@derive</code> decorators are passed through unchanged with zero overhead. ## SvelteKit Integration
- For SvelteKit projects, you can use both the preprocessor (for <code class="shiki-inline"><span class="line"><span style="--shiki-dark:#E1E4E8;--shiki-light:#24292E">.svelte</code> files) and the Vite plugin (for standalone <code class="shiki-inline"><span class="line"><span style="--shiki-dark:#E1E4E8;--shiki-light:#24292E">.ts</code> files):
- ```
-//&nbsp;svelte.config.js
-import&nbsp;&#123;&nbsp;macroforgePreprocess&nbsp;&#125;&nbsp;from&nbsp;'@macroforge/svelte-preprocessor';
-import&nbsp;&#123;&nbsp;vitePreprocess&nbsp;&#125;&nbsp;from&nbsp;'@sveltejs/vite-plugin-svelte';
-
-export&nbsp;default&nbsp;&#123;
-&nbsp;&nbsp;preprocess:&nbsp;[
-&nbsp;&nbsp;&nbsp;&nbsp;macroforgePreprocess(),
-&nbsp;&nbsp;&nbsp;&nbsp;vitePreprocess()
-&nbsp;&nbsp;]
-&#125;;
-``` ```
-//&nbsp;vite.config.ts
-import&nbsp;macroforge&nbsp;from&nbsp;'@macroforge/vite-plugin';
-import&nbsp;&#123;&nbsp;sveltekit&nbsp;&#125;&nbsp;from&nbsp;'@sveltejs/kit/vite';
-import&nbsp;&#123;&nbsp;defineConfig&nbsp;&#125;&nbsp;from&nbsp;'vite';
-
-export&nbsp;default&nbsp;defineConfig(&#123;
-&nbsp;&nbsp;plugins:&nbsp;[
-&nbsp;&nbsp;&nbsp;&nbsp;macroforge(),&nbsp;&nbsp;//&nbsp;For&nbsp;.ts&nbsp;files
-&nbsp;&nbsp;&nbsp;&nbsp;sveltekit()
-&nbsp;&nbsp;]
-&#125;);
-``` ## Using with Vitest
- The preprocessor works seamlessly with Vitest for testing Svelte components:
- ```
-//&nbsp;vitest.config.ts
-import&nbsp;&#123;&nbsp;defineConfig&nbsp;&#125;&nbsp;from&nbsp;'vitest/config';
-import&nbsp;&#123;&nbsp;sveltekit&nbsp;&#125;&nbsp;from&nbsp;'@sveltejs/kit/vite';
-import&nbsp;&#123;&nbsp;svelteTesting&nbsp;&#125;&nbsp;from&nbsp;'@testing-library/svelte/vite';
-import&nbsp;macroforge&nbsp;from&nbsp;'@macroforge/vite-plugin';
-
-export&nbsp;default&nbsp;defineConfig(&#123;
-&nbsp;&nbsp;plugins:&nbsp;[
-&nbsp;&nbsp;&nbsp;&nbsp;macroforge(),
-&nbsp;&nbsp;&nbsp;&nbsp;sveltekit(),
-&nbsp;&nbsp;&nbsp;&nbsp;svelteTesting()
-&nbsp;&nbsp;],
-&nbsp;&nbsp;test:&nbsp;&#123;
-&nbsp;&nbsp;&nbsp;&nbsp;environment:&nbsp;'jsdom',
-&nbsp;&nbsp;&nbsp;&nbsp;include:&nbsp;['src/**/*.&#123;test,spec&#125;.&#123;js,ts&#125;']
-&nbsp;&nbsp;&#125;
-&#125;);
-``` ## Svelte 5 Runes Compatibility
- The preprocessor is fully compatible with Svelte 5 runes (<code class="shiki-inline"><span class="line"><span style="--shiki-dark:#E1E4E8;--shiki-light:#24292E">$state</code>, <code class="shiki-inline"><span class="line"><span style="--shiki-dark:#E1E4E8;--shiki-light:#24292E">$derived</code>, <code class="shiki-inline"><span class="line"><span style="--shiki-dark:#E1E4E8;--shiki-light:#24292E">$props</code>, etc.). Files using runes but without <code class="shiki-inline"><span class="line"><span style="--shiki-dark:#E1E4E8;--shiki-light:#24292E">@derive</code> decorators are skipped entirely.
- ```
-&#x3C;script&nbsp;lang="ts">
-&nbsp;&nbsp;//&nbsp;Runes&nbsp;work&nbsp;normally
-&nbsp;&nbsp;let&nbsp;count&nbsp;=&nbsp;$state(0);
-&nbsp;&nbsp;let&nbsp;doubled&nbsp;=&nbsp;$derived(count&nbsp;*&nbsp;2);
-
-&nbsp;&nbsp;//&nbsp;Macros&nbsp;expand&nbsp;correctly
-&nbsp;&nbsp;/**&nbsp;@derive(Debug)&nbsp;*/
-&nbsp;&nbsp;class&nbsp;Counter&nbsp;&#123;
-&nbsp;&nbsp;&nbsp;&nbsp;value:&nbsp;number;
-&nbsp;&nbsp;&nbsp;&nbsp;constructor(value:&nbsp;number)&nbsp;&#123;
-&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;this.value&nbsp;=&nbsp;value;
-&nbsp;&nbsp;&nbsp;&nbsp;&#125;
-&nbsp;&nbsp;&#125;
-&#x3C;/script>
+
+The Svelte preprocessor expands Macroforge macros in `<script>` blocks before Svelte compilation, enabling seamless macro usage in Svelte components.
+
+## Installation
+
+Bash
+
+```
+npm install -D @macroforge/svelte-preprocessor
+```
+
+## Configuration
+
+Add the preprocessor to your `svelte.config.js`:
+
+svelte.config.js 
+
+```
+import adapter from '@sveltejs/adapter-auto';
+import { vitePreprocess } from '@sveltejs/vite-plugin-svelte';
+import { macroforgePreprocess } from '@macroforge/svelte-preprocessor';
+
+/** @type {import('@sveltejs/kit').Config} */
+const config = {
+  preprocess: [
+    macroforgePreprocess(),  // Expand macros FIRST
+    vitePreprocess()          // Then handle TypeScript/CSS
+  ],
+
+  kit: {
+    adapter: adapter()
+  }
+};
+
+export default config;
+```
+
+Warning
+
+Always place `macroforgePreprocess()` **before** other preprocessors like `vitePreprocess()`. This ensures macros are expanded before TypeScript compilation.
+
+## Usage
+
+Use `@derive` decorators directly in your Svelte component scripts:
+
+UserCard.svelte 
+
+```
+<script lang="ts">
+  /** @derive(Debug, Clone) */
+  class User {
+    name: string;
+    email: string;
+
+    constructor(name: string, email: string) {
+      this.name = name;
+      this.email = email;
+    }
+  }
+
+  let user = new User("Alice", "alice@example.com");
+  console.log(user.toString());  // Generated by Debug macro
+</script>
+
+<p>User: {user.name}</p>
+```
+
+## Options
+
+TypeScript
+
+```
+macroforgePreprocess({
+  // Keep @derive decorators in output (for debugging)
+  keepDecorators: false,
+
+  // Process JavaScript files (not just TypeScript)
+  processJavaScript: false
+})
+```
+
+### Option Reference
+
+| Option              | Type      | Default | Description                                   |
+| ------------------- | --------- | ------- | --------------------------------------------- |
+| `keepDecorators`    | `boolean` | `false` | Keep decorators in output                     |
+| `processJavaScript` | `boolean` | `false` | Process `<script>` blocks without `lang="ts"` |
+
+## How It Works
+
+The preprocessor:
+
+1.  Intercepts `<script lang="ts">` blocks in `.svelte` files
+2.  Checks for `@derive` decorators (skips files without them)
+3.  Expands macros using the native Macroforge binary
+4.  Returns the transformed code for Svelte compilation
+
+Tip
+
+Files without `@derive` decorators are passed through unchanged with zero overhead.
+
+## SvelteKit Integration
+
+For SvelteKit projects, you can use both the preprocessor (for `.svelte` files) and the Vite plugin (for standalone `.ts` files):
+
+svelte.config.js 
+
+```
+// svelte.config.js
+import { macroforgePreprocess } from '@macroforge/svelte-preprocessor';
+import { vitePreprocess } from '@sveltejs/vite-plugin-svelte';
+
+export default {
+  preprocess: [
+    macroforgePreprocess(),
+    vitePreprocess()
+  ]
+};
+```
+
+vite.config.ts 
+
+```
+// vite.config.ts
+import macroforge from '@macroforge/vite-plugin';
+import { sveltekit } from '@sveltejs/kit/vite';
+import { defineConfig } from 'vite';
+
+export default defineConfig({
+  plugins: [
+    macroforge(),  // For .ts files
+    sveltekit()
+  ]
+});
+```
+
+## Using with Vitest
+
+The preprocessor works seamlessly with Vitest for testing Svelte components:
+
+vitest.config.ts 
+
+```
+// vitest.config.ts
+import { defineConfig } from 'vitest/config';
+import { sveltekit } from '@sveltejs/kit/vite';
+import { svelteTesting } from '@testing-library/svelte/vite';
+import macroforge from '@macroforge/vite-plugin';
+
+export default defineConfig({
+  plugins: [
+    macroforge(),
+    sveltekit(),
+    svelteTesting()
+  ],
+  test: {
+    environment: 'jsdom',
+    include: ['src/**/*.{test,spec}.{js,ts}']
+  }
+});
+```
+
+## Svelte 5 Runes Compatibility
+
+The preprocessor is fully compatible with Svelte 5 runes (`$state`, `$derived`, `$props`, etc.). Files using runes but without `@derive` decorators are skipped entirely.
+
+Svelte
+
+```
+<script lang="ts">
+  // Runes work normally
+  let count = $state(0);
+  let doubled = $derived(count * 2);
+
+  // Macros expand correctly
+  /** @derive(Debug) */
+  class Counter {
+    value: number;
+    constructor(value: number) {
+      this.value = value;
+    }
+  }
+</script>
 ```

package/docs/integration/typescript-plugin.md

@@ -1,54 +1,102 @@
 # TypeScript Plugin
- *The TypeScript plugin provides IDE integration for Macroforge, including error reporting, completions, and type checking for generated code.*
- ## Installation
- ```
-npm install -D @macroforge/typescript-plugin
-``` ## Configuration
- Add the plugin to your <code class="shiki-inline"><span class="line"><span style="--shiki-dark:#E1E4E8;--shiki-light:#24292E">tsconfig.json</code>:
- ```
-&#123;
-&nbsp;&nbsp;"compilerOptions":&nbsp;&#123;
-&nbsp;&nbsp;&nbsp;&nbsp;"plugins":&nbsp;[
-&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&#123;
-&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"name":&nbsp;"@macroforge/typescript-plugin"
-&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&#125;
-&nbsp;&nbsp;&nbsp;&nbsp;]
-&nbsp;&nbsp;&#125;
-&#125;
-``` ## VS Code Setup
- VS Code uses its own TypeScript version by default. To use the workspace version (which includes plugins):
- 1. Open the Command Palette (<code class="shiki-inline"><span class="line"><span style="--shiki-dark:#E1E4E8;--shiki-light:#24292E">Cmd<span style="--shiki-dark:#F97583;--shiki-light:#D73A49">/<span style="--shiki-dark:#E1E4E8;--shiki-light:#24292E">Ctrl <span style="--shiki-dark:#F97583;--shiki-light:#D73A49">+<span style="--shiki-dark:#E1E4E8;--shiki-light:#24292E"> Shift <span style="--shiki-dark:#F97583;--shiki-light:#D73A49">+<span style="--shiki-dark:#79B8FF;--shiki-light:#005CC5"> P</code>)
- 2. Search for "TypeScript: Select TypeScript Version"
- 3. Choose "Use Workspace Version"
-  **Tip Add this setting to your **<code class="shiki-inline"><span class="line"><span style="--shiki-dark:#E1E4E8;--shiki-light:#24292E">.vscode/settings.json</code> to make it permanent: ```
-&#123;
-&nbsp;&nbsp;"typescript.tsdk":&nbsp;"node_modules/typescript/lib"
-&#125;
-``` ## Features
- ### Error Reporting
- Errors in macro-generated code are reported at the <code class="shiki-inline"><span class="line"><span style="--shiki-dark:#E1E4E8;--shiki-light:#24292E">@derive</code> decorator position:
- ```
-/**&nbsp;@derive(Debug)&nbsp;*/&nbsp;&nbsp;//&nbsp;&#x3C;-&nbsp;Errors&nbsp;appear&nbsp;here
-class&nbsp;User&nbsp;&#123;
-&nbsp;&nbsp;name:&nbsp;string;
-&#125;
-``` ### Completions
- The plugin provides completions for generated methods:
- ```
-const&nbsp;user&nbsp;=&nbsp;new&nbsp;User("Alice");
-user.to&nbsp;&nbsp;//&nbsp;Suggests:&nbsp;toString(),&nbsp;toJSON(),&nbsp;etc.
-``` ### Type Information
- Hover over generated methods to see their types:
- ```
-//&nbsp;Hover&nbsp;over&nbsp;'clone'&nbsp;shows:
-//&nbsp;(method)&nbsp;User.clone():&nbsp;User
-const&nbsp;copy&nbsp;=&nbsp;user.clone();
-``` ## Troubleshooting
- ### Plugin Not Loading
- 1. Ensure you're using the workspace TypeScript version
- 2. Restart the TypeScript server (Command Palette → "TypeScript: Restart TS Server")
- 3. Check that the plugin is listed in <code class="shiki-inline"><span class="line"><span style="--shiki-dark:#E1E4E8;--shiki-light:#24292E">tsconfig.json</code>
- ### Errors Not Showing
- If errors from macros aren't appearing:
- 1. Make sure the Vite plugin is also installed (for source file watching)
- 2. Check that your file is saved (plugins process on save)
+
+The TypeScript plugin provides IDE integration for Macroforge, including error reporting, completions, and type checking for generated code.
+
+## Installation
+
+Bash
+
+```
+npm install -D @macroforge/typescript-plugin
+```
+
+## Configuration
+
+Add the plugin to your `tsconfig.json`:
+
+tsconfig.json 
+
+```
+{
+  "compilerOptions": {
+    "plugins": [
+      {
+        "name": "@macroforge/typescript-plugin"
+      }
+    ]
+  }
+}
+```
+
+## VS Code Setup
+
+VS Code uses its own TypeScript version by default. To use the workspace version (which includes plugins):
+
+1.  Open the Command Palette (`Cmd/Ctrl + Shift + P`)
+2.  Search for "TypeScript: Select TypeScript Version"
+3.  Choose "Use Workspace Version"
+
+Tip
+
+Add this setting to your `.vscode/settings.json` to make it permanent:
+
+.vscode/settings.json 
+
+```
+{
+  "typescript.tsdk": "node_modules/typescript/lib"
+}
+```
+
+## Features
+
+### Error Reporting
+
+Errors in macro-generated code are reported at the `@derive` decorator position:
+
+TypeScript
+
+```
+/** @derive(Debug) */  // <- Errors appear here
+class User {
+  name: string;
+}
+```
+
+### Completions
+
+The plugin provides completions for generated methods:
+
+TypeScript
+
+```
+const user = new User("Alice");
+user.to  // Suggests: toString(), toJSON(), etc.
+```
+
+### Type Information
+
+Hover over generated methods to see their types:
+
+TypeScript
+
+```
+// Hover over 'clone' shows:
+// (method) User.clone(): User
+const copy = user.clone();
+```
+
+## Troubleshooting
+
+### Plugin Not Loading
+
+1.  Ensure you're using the workspace TypeScript version
+2.  Restart the TypeScript server (Command Palette → "TypeScript: Restart TS Server")
+3.  Check that the plugin is listed in `tsconfig.json`
+
+### Errors Not Showing
+
+If errors from macros aren't appearing:
+
+1.  Make sure the Vite plugin is also installed (for source file watching)
+2.  Check that your file is saved (plugins process on save)