@macroforge/mcp-server 0.1.33 → 0.1.35

package/docs/custom-macros/ts-quote.md

@@ -1,156 +1,36 @@
 # Template Syntax
-
-*The `macroforge_ts_quote` crate provides template-based code generation for TypeScript. The `ts_template!` macro uses Rust-inspired syntax for control flow and interpolation, making it easy to generate complex TypeScript code.*
-
-## Available Macros
-
-| `ts_template!` 
-            | Any TypeScript code 
-            | General code generation 
-        
-
-        
-            | `body!` 
-            | Class body members 
-            | Methods and properties
-
-## Quick Reference
-
-| `@{expr}` 
-            | Interpolate a Rust expression (adds space after) 
-        
-
-        
-            | `{| content |}` 
-            | Ident block: concatenates without spaces (e.g., <code
-                    >&#123;|get@&#123;name&#125;|&#125;</code
-                >
-                → `getUser`)</td
-            >
-        
-
-        
-            <td>`&#123;> "comment" <&#125;` 
-            | Block comment: outputs `/* comment */` (string preserves
-                whitespace)</td
-            >
-        
-
-        
-            <td>`&#123;>> "doc" <<&#125;` 
-            | Doc comment: outputs `/** doc */` (string preserves whitespace)</td
-            >
-        
-
-        
-            <td>`@@&#123;` 
-            | Escape for literal `@&#123;` (e.g.,
-                `"@@&#123;foo&#125;"`
-                → `@&#123;foo&#125;`)</td
-            >
-        
-
-        
-            <td>`"text @&#123;expr&#125;"` 
-            | String interpolation (auto-detected) 
-        
-
-        
-            | `"'^template $&#123;js&#125;^'"` 
-            | JS backtick template literal (outputs <code
-                    >`template $&#123;js&#125;`</code
-                >)</td
-            >
-        
-
-        
-            <td>`&#123;#if cond&#125;...&#123;/if&#125;` 
-            | Conditional block 
-        
-
-        
-            | <code
-                    >&#123;#if cond&#125;...&#123;:else&#125;...&#123;/if&#125;</code
-                ></td
-            >
-            <td>Conditional with else 
-        
-
-        
-            | <code
-                    >&#123;#if a&#125;...&#123;:else if
-                    b&#125;...&#123;:else&#125;...&#123;/if&#125;</code
-                ></td
-            >
-            <td>Full if/else-if/else chain 
-        
-
-        
-            | <code
-                    >&#123;#if let pattern = expr&#125;...&#123;/if&#125;</code
-                ></td
-            >
-            <td>Pattern matching if-let 
-        
-
-        
-            | <code
-                    >&#123;#match expr&#125;&#123;:case
-                    pattern&#125;...&#123;/match&#125;</code
-                ></td
-            >
-            <td>Match expression with case arms 
-        
-
-        
-            | <code>&#123;#for item in list&#125;...&#123;/for&#125;</code
-                ></td
-            >
-            <td>Iterate over a collection 
-        
-
-        
-            | `&#123;#while cond&#125;...&#123;/while&#125;` 
-            | While loop 
-        
-
-        
-            | <code
-                    >&#123;#while let pattern = expr&#125;...&#123;/while&#125;</code
-                ></td
-            >
-            <td>While-let pattern matching loop 
-        
-
-        
-            | `&#123;$let name = expr&#125;` 
-            | Define a local constant 
-        
-
-        
-            | `&#123;$let mut name = expr&#125;` 
-            | Define a mutable local variable 
-        
-
-        
-            | `&#123;$do expr&#125;` 
-            | Execute a side-effectful expression 
-        
-
-        
-            | `&#123;$typescript stream&#125;` 
-            <td
-                >Inject a TsStream, preserving its source and runtime_patches
-                (imports)</td
-            >
-
-**Note:** A single `@` not followed by `&#123;` passes through unchanged (e.g., `email@domain.com` works as expected).
-
-## Interpolation: `@&#123;expr&#125;`
-
-Insert Rust expressions into the generated TypeScript:
-
-```rust
+ *The `macroforge_ts_quote` crate provides template-based code generation for TypeScript. The `ts_template!` macro uses Rust-inspired syntax for control flow and interpolation, making it easy to generate complex TypeScript code.*
+ ## Available Macros
+ | Macro | Output | Use Case |
+| --- | --- | --- |
+| `ts_template!` | Any TypeScript code | General code generation |
+| `body!` | Class body members | Methods and properties |
+ ## Quick Reference
+ | Syntax | Description |
+| --- | --- |
+| `@{expr}` | Interpolate a Rust expression (adds space after) |
+| `{| content |}` | Ident block: concatenates without spaces (e.g., `{|get@{name}|}` → `getUser`) |
+| `{> "comment" <}` | Block comment: outputs `/* comment */` (string preserves whitespace) |
+| `{>> "doc" <<}` | Doc comment: outputs `/** doc */` (string preserves whitespace) |
+| `@@{` | Escape for literal `@{` (e.g., `"@@{foo}"` → `@{foo}`) |
+| `"text @{expr}"` | String interpolation (auto-detected) |
+| `"'^template ${js}^'"` | JS backtick template literal (outputs ``template ${js}``) |
+| `{#if cond}...{/if}` | Conditional block |
+| `{#if cond}...{:else}...{/if}` | Conditional with else |
+| {#if a}...{:else if b}...{:else}...{/if} | Full if/else-if/else chain |
+| `{#if let pattern = expr}...{/if}` | Pattern matching if-let |
+| {#match expr}{:case pattern}...{/match} | Match expression with case arms |
+| `{#for item in list}...{/for}` | Iterate over a collection |
+| `{#while cond}...{/while}` | While loop |
+| `{#while let pattern = expr}...{/while}` | While-let pattern matching loop |
+| `{$let name = expr}` | Define a local constant |
+| `{$let mut name = expr}` | Define a mutable local variable |
+| `{$do expr}` | Execute a side-effectful expression |
+| `{$typescript stream}` | Inject a TsStream, preserving its source and runtime_patches (imports) |
+ **Note:** A single `@` not followed by `{` passes through unchanged (e.g., `email@domain.com` works as expected).
+ ## Interpolation: `@{expr}`
+ Insert Rust expressions into the generated TypeScript:
+ ```
 let class_name = "User";
 let method = "toString";
 
@@ -159,23 +39,14 @@ let code = ts_template! {
         return "User instance";
     };
 };
-```
-
-**Generates:**
-
-```typescript
+``` **Generates:**
+ ```
 User.prototype.toString = function () {
   return "User instance";
 };
-```
-
-<h2 id="ident-blocks">
-    Identifier Concatenation: `&#123;| content |&#125;`
-</h2>
-
-When you need to build identifiers dynamically (like `getUser`, `setName`), use the ident block syntax. Everything inside `&#123;| |&#125;` is concatenated without spaces:
-
-```rust
+``` ## Identifier Concatenation: `{| content |}`
+ When you need to build identifiers dynamically (like `getUser`, `setName`), use the ident block syntax. Everything inside `{| |}` is concatenated without spaces:
+ ```
 let field_name = "User";
 
 let code = ts_template! {
@@ -183,19 +54,13 @@ let code = ts_template! {
         return this.@{field_name.to_lowercase()};
     }
 };
-```
-
-**Generates:**
-
-```typescript
+``` **Generates:**
+ ```
 function getUser() {
   return this.user;
 }
-```
-
-Without ident blocks, `@&#123;&#125;` always adds a space after for readability. Use `&#123;| |&#125;` when you explicitly want concatenation:
-
-```rust
+``` Without ident blocks, `@{}` always adds a space after for readability. Use `{| |}` when you explicitly want concatenation:
+ ```
 let name = "Status";
 
 // With space (default behavior)
@@ -203,47 +68,28 @@ ts_template! { namespace @{name} }  // → "namespace Status"
 
 // Without space (ident block)
 ts_template! { {|namespace@{name}|} }  // → "namespaceStatus"
-```
-
-Multiple interpolations can be combined:
-
-```rust
+``` Multiple interpolations can be combined:
+ ```
 let entity = "user";
 let action = "create";
 
 ts_template! { {|@{entity}_@{action}|} }  // → "user_create"
-```
-
-<h2 id="comments">
-    Comments: `&#123;> "..." <&#125;` and
-    `&#123;>> "..." <<&#125;`
-</h2>
-
-Since Rust's tokenizer strips whitespace before macros see them, use string literals to preserve exact spacing in comments:
-
-### Block Comments
-
-Use `&#123;> "comment" <&#125;` for block comments:
-
-```rust
+``` ## Comments: `{> "..." <}` and `{>> "..." <<}`
+ Since Rust's tokenizer strips whitespace before macros see them, use string literals to preserve exact spacing in comments:
+ ### Block Comments
+ Use `{> "comment" <}` for block comments:
+ ```
 let code = ts_template! {
     {> "This is a block comment" <}
     const x = 42;
 };
-```
-
-**Generates:**
-
-```typescript
+``` **Generates:**
+ ```
 /* This is a block comment */
 const x = 42;
-```
-
-### Doc Comments (JSDoc)
-
-Use `&#123;>> "doc" <<&#125;` for JSDoc comments:
-
-```rust
+``` ### Doc Comments (JSDoc)
+ Use `{>> "doc" <<}` for JSDoc comments:
+ ```
 let code = ts_template! {
     {>> "@param {string} name - The user's name" <<}
     {>> "@returns {string} A greeting message" <<}
@@ -251,23 +97,16 @@ let code = ts_template! {
         return "Hello, " + name;
     }
 };
-```
-
-**Generates:**
-
-```typescript
+``` **Generates:**
+ ```
 /** @param {string} name - The user's name */
 /** @returns {string} A greeting message */
 function greet(name: string): string {
     return "Hello, " + name;
 }
-```
-
-### Comments with Interpolation
-
-Use `format!()` or similar to build dynamic comment strings:
-
-```rust
+``` ### Comments with Interpolation
+ Use `format!()` or similar to build dynamic comment strings:
+ ```
 let param_name = "userId";
 let param_type = "number";
 let comment = format!("@param {{{}}} {} - The user ID", param_type, param_name);
@@ -276,22 +115,13 @@ let code = ts_template! {
     {>> @{comment} <<}
     function getUser(userId: number) {}
 };
-```
-
-**Generates:**
-
-```typescript
+``` **Generates:**
+ ```
 /** @param {number} userId - The user ID */
 function getUser(userId: number) {}
-```
-
-<h2 id="string-interpolation">
-    String Interpolation: `"text @&#123;expr&#125;"`
-</h2>
-
-Interpolation works automatically inside string literals - no <code >format!()</code > needed:
-
-```rust
+``` ## String Interpolation: `"text @{expr}"`
+ Interpolation works automatically inside string literals - no `format!()` needed:
+ ```
 let name = "World";
 let count = 42;
 
@@ -299,64 +129,41 @@ let code = ts_template! {
     console.log("Hello @{name}!");
     console.log("Count: @{count}, doubled: @{count * 2}");
 };
-```
-
-**Generates:**
-
-```typescript
+``` **Generates:**
+ ```
 console.log("Hello World!");
 console.log("Count: 42, doubled: 84");
-```
-
-This also works with method calls and complex expressions:
-
-```rust
+``` This also works with method calls and complex expressions:
+ ```
 let field = "username";
 
 let code = ts_template! {
     throw new Error("Invalid @{field.to_uppercase()}");
 };
-```
-
-<h2 id="backtick-templates">
-    Backtick Template Literals: `"'^...^'"`
-</h2>
-
-For JavaScript template literals (backtick strings), use the <code >'^...^'</code > syntax. This outputs actual backticks and passes through `${"${}"}` for JS interpolation:
-
-```rust
+``` ## Backtick Template Literals: `"'^...^'"`
+ For JavaScript template literals (backtick strings), use the `'^...^'` syntax. This outputs actual backticks and passes through `$${}` for JS interpolation:
+ ```
 let tag_name = "div";
 
 let code = ts_template! {
-    const html = "'^<@{tag_name}>\${content}</@{tag_name}>^'";
+    const html = "'^<@{tag_name}>${content}</@{tag_name}>^'";
 };
-```
-
-**Generates:**
-
-<CodeBlock code={"const html = `${content}`;"} lang="typescript" />
-
-You can mix Rust `@&#123;&#125;` interpolation (evaluated at macro expansion time) with JS `${"${}"}` interpolation (evaluated at runtime):
-
-```rust
+``` **Generates:**
+ ```
+const html = `${content}`;
+``` You can mix Rust `@{}` interpolation (evaluated at macro expansion time) with JS `$${}` interpolation (evaluated at runtime):
+ ```
 let class_name = "User";
 
 let code = ts_template! {
-    "'^Hello \${this.name}, you are a @{class_name}^'"
+    "'^Hello ${this.name}, you are a @{class_name}^'"
 };
-```
-
-**Generates:**
-
-<CodeBlock code={"`Hello ${this.name}, you are a User`"} lang="typescript" />
-
-<h2 id="conditionals">
-    Conditionals: `&#123;#if&#125;...&#123;/if&#125;`
-</h2>
-
-Basic conditional:
-
-```rust
+``` **Generates:**
+ ```
+`Hello ${this.name}, you are a User`
+``` ## Conditionals: `{#if}...{/if}`
+ Basic conditional:
+ ```
 let needs_validation = true;
 
 let code = ts_template! {
@@ -367,11 +174,8 @@ let code = ts_template! {
         return this.doSave();
     }
 };
-```
-
-### If-Else
-
-```rust
+``` ### If-Else
+ ```
 let has_default = true;
 
 let code = ts_template! {
@@ -381,11 +185,8 @@ let code = ts_template! {
         throw new Error("No default");
     {/if}
 };
-```
-
-### If-Else-If Chains
-
-```rust
+``` ### If-Else-If Chains
+ ```
 let level = 2;
 
 let code = ts_template! {
@@ -397,15 +198,9 @@ let code = ts_template! {
         console.log("Other level");
     {/if}
 };
-```
-
-<h2 id="pattern-matching">
-    Pattern Matching: `&#123;#if let&#125;`
-</h2>
-
-Use `if let` for pattern matching on `Option`, `Result`, or other Rust enums:
-
-```rust
+``` ## Pattern Matching: `{#if let}`
+ Use `if let` for pattern matching on `Option`, `Result`, or other Rust enums:
+ ```
 let maybe_name: Option<&str> = Some("Alice");
 
 let code = ts_template! {
@@ -415,17 +210,11 @@ let code = ts_template! {
         console.log("Hello, anonymous!");
     {/if}
 };
-```
-
-**Generates:**
-
-```typescript
+``` **Generates:**
+ ```
 console.log("Hello, Alice!");
-```
-
-This is useful when working with optional values from your IR:
-
-```rust
+``` This is useful when working with optional values from your IR:
+ ```
 let code = ts_template! {
     {#if let Some(default_val) = field.default_value}
         this.@{field.name} = @{default_val};
@@ -433,15 +222,9 @@ let code = ts_template! {
         this.@{field.name} = undefined;
     {/if}
 };
-```
-
-<h2 id="match-expressions">
-    Match Expressions: `&#123;#match&#125;`
-</h2>
-
-Use `match` for exhaustive pattern matching:
-
-```rust
+``` ## Match Expressions: `{#match}`
+ Use `match` for exhaustive pattern matching:
+ ```
 enum Visibility { Public, Private, Protected }
 let visibility = Visibility::Public;
 
@@ -456,17 +239,11 @@ let code = ts_template! {
     {/match}
     field: string;
 };
-```
-
-**Generates:**
-
-```typescript
+``` **Generates:**
+ ```
 public field: string;
-```
-
-### Match with Value Extraction
-
-```rust
+``` ### Match with Value Extraction
+ ```
 let result: Result<i32, &str> = Ok(42);
 
 let code = ts_template! {
@@ -477,11 +254,8 @@ let code = ts_template! {
             throw new Error("@{msg}")
     {/match};
 };
-```
-
-### Match with Wildcard
-
-```rust
+``` ### Match with Wildcard
+ ```
 let count = 5;
 
 let code = ts_template! {
@@ -494,11 +268,8 @@ let code = ts_template! {
             console.log("many");
     {/match}
 };
-```
-
-## Iteration: `&#123;#for&#125;`
-
-```rust
+``` ## Iteration: `{#for}`
+ ```
 let fields = vec!["name", "email", "age"];
 
 let code = ts_template! {
@@ -510,11 +281,8 @@ let code = ts_template! {
         return result;
     }
 };
-```
-
-**Generates:**
-
-```typescript
+``` **Generates:**
+ ```
 function toJSON() {
   const result = {};
   result.name = this.name;
@@ -522,11 +290,8 @@ function toJSON() {
   result.age = this.age;
   return result;
 }
-```
-
-### Tuple Destructuring in Loops
-
-```rust
+``` ### Tuple Destructuring in Loops
+ ```
 let items = vec![("user", "User"), ("post", "Post")];
 
 let code = ts_template! {
@@ -534,11 +299,8 @@ let code = ts_template! {
         const @{key} = new @{class_name}();
     {/for}
 };
-```
-
-### Nested Iterations
-
-```rust
+``` ### Nested Iterations
+ ```
 let classes = vec![
     ("User", vec!["name", "email"]),
     ("Post", vec!["title", "content"]),
@@ -555,13 +317,9 @@ ts_template! {
         };
     {/for}
 }
-```
-
-## While Loops: `&#123;#while&#125;`
-
-Use `while` for loops that need to continue until a condition is false:
-
-```rust
+``` ## While Loops: `{#while}`
+ Use `while` for loops that need to continue until a condition is false:
+ ```
 let items = get_items();
 let mut idx = 0;
 
@@ -572,13 +330,9 @@ let code = ts_template! {
         {$do i += 1}
     {/while}
 };
-```
-
-### While-Let Pattern Matching
-
-Use `while let` for iterating with pattern matching, similar to `if let`:
-
-```rust
+``` ### While-Let Pattern Matching
+ Use `while let` for iterating with pattern matching, similar to `if let`:
+ ```
 let mut items = vec!["a", "b", "c"].into_iter();
 
 let code = ts_template! {
@@ -586,31 +340,21 @@ let code = ts_template! {
         console.log("@{item}");
     {/while}
 };
-```
-
-**Generates:**
-
-```typescript
+``` **Generates:**
+ ```
 console.log("a");
 console.log("b");
 console.log("c");
-```
-
-This is especially useful when working with iterators or consuming optional values:
-
-```rust
+``` This is especially useful when working with iterators or consuming optional values:
+ ```
 let code = ts_template! {
     {#while let Some(next_field) = remaining_fields.pop()}
         result.@{next_field.name} = this.@{next_field.name};
     {/while}
 };
-```
-
-## Local Constants: `&#123;$let&#125;`
-
-Define local variables within the template scope:
-
-```rust
+``` ## Local Constants: `{$let}`
+ Define local variables within the template scope:
+ ```
 let items = vec![("user", "User"), ("post", "Post")];
 
 let code = ts_template! {
@@ -620,17 +364,10 @@ let code = ts_template! {
         const @{key} = new @{class_name}();
     {/for}
 };
-```
-
-This is useful for computing derived values inside loops without cluttering the Rust code.
-
-<h2 id="mutable-variables">
-    Mutable Variables: `&#123;$let mut&#125;`
-</h2>
-
-When you need to modify a variable within the template (e.g., in a <code >while</code > loop), use `&#123;$let mut&#125;`:
-
-```rust
+``` This is useful for computing derived values inside loops without cluttering the Rust code.
+ ## Mutable Variables: `{$let mut}`
+ When you need to modify a variable within the template (e.g., in a `while` loop), use `{$let mut}`:
+ ```
 let code = ts_template! {
     {$let mut count = 0}
     {#for item in items}
@@ -639,13 +376,9 @@ let code = ts_template! {
     {/for}
     console.log("Total: @{count}");
 };
-```
-
-## Side Effects: `&#123;$do&#125;`
-
-Execute an expression for its side effects without producing output. This is commonly used with mutable variables:
-
-```rust
+``` ## Side Effects: `{$do}`
+ Execute an expression for its side effects without producing output. This is commonly used with mutable variables:
+ ```
 let code = ts_template! {
     {$let mut results: Vec<String> = Vec::new()}
     {#for field in fields}
@@ -653,25 +386,14 @@ let code = ts_template! {
     {/for}
     return [@{results.join(", ")}];
 };
-```
-
-Common uses for `&#123;$do&#125;`:
-
-- Incrementing counters: `&#123;$do i += 1&#125;`
-
-    - Building collections: `&#123;$do vec.push(item)&#125;`
-
-    - Setting flags: `&#123;$do found = true&#125;`
-
-    - Any mutating operation
-
-<h2 id="typescript-injection">
-    TsStream Injection: `&#123;$typescript&#125;`
-</h2>
-
-Inject another TsStream into your template, preserving both its source code and runtime patches (like imports added via `add_import()`):
-
-```rust
+``` Common uses for `{$do}`:
+ - Incrementing counters: `{$do i += 1}`
+ - Building collections: `{$do vec.push(item)}`
+ - Setting flags: `{$do found = true}`
+ - Any mutating operation
+ ## TsStream Injection: `{$typescript}`
+ Inject another TsStream into your template, preserving both its source code and runtime patches (like imports added via `add_import()`):
+ ```
 // Create a helper method with its own import
 let mut helper = body! {
     validateEmail(email: string): boolean {
@@ -689,11 +411,8 @@ let result = body! {
     }
 };
 // result now includes helper's source AND its Result import
-```
-
-This is essential for composing multiple macro outputs while preserving imports and patches:
-
-```rust
+``` This is essential for composing multiple macro outputs while preserving imports and patches:
+ ```
 let extra_methods = if include_validation {
     Some(body! {
         validate(): boolean { return true; }
@@ -709,33 +428,21 @@ body! {
         {$typescript methods}
     {/if}
 }
-```
-
-## Escape Syntax
-
-If you need a literal `@&#123;` in your output (not interpolation), use `@@&#123;`:
-
-```rust
+``` ## Escape Syntax
+ If you need a literal `@{` in your output (not interpolation), use `@@{`:
+ ```
 ts_template! {
     // This outputs a literal @{foo}
     const example = "Use @@{foo} for templates";
 }
-```
-
-**Generates:**
-
-```typescript
+``` **Generates:**
+ ```
 // This outputs a literal @{foo}
 const example = "Use @{foo} for templates";
-```
-
-## Complete Example: JSON Derive Macro
-
-Here's a comparison showing how `ts_template!` simplifies code generation:
-
-### Before (Manual AST Building)
-
-```rust
+``` ## Complete Example: JSON Derive Macro
+ Here's a comparison showing how `ts_template!` simplifies code generation:
+ ### Before (Manual AST Building)
+ ```
 pub fn derive_json_macro(input: TsStream) -> MacroResult {
     let input = parse_ts_macro_input!(input as DeriveInput);
 
@@ -764,11 +471,8 @@ pub fn derive_json_macro(input: TsStream) -> MacroResult {
         }
     }
 }
-```
-
-### After (With ts_template!)
-
-```rust
+``` ### After (With ts_template!)
+ ```
 pub fn derive_json_macro(input: TsStream) -> MacroResult {
     let input = parse_ts_macro_input!(input as DeriveInput);
 
@@ -791,40 +495,24 @@ pub fn derive_json_macro(input: TsStream) -> MacroResult {
         }
     }
 }
-```
-
-## How It Works
-
-1. **Compile-Time:** The template is parsed during macro expansion
-
-    2. **String Building:** Generates Rust code that builds a TypeScript string at runtime
-
-    3. **SWC Parsing:** The generated string is parsed with SWC to produce a typed AST
-
-    4. **Result:** Returns `Stmt` that can be used in `MacroResult` patches
-
-## Return Type
-
-`ts_template!` returns a `Result<Stmt, TsSynError>` by default. The macro automatically unwraps and provides helpful error messages showing the generated TypeScript code if parsing fails:
-
-```text
+``` ## How It Works
+ 1. **Compile-Time:** The template is parsed during macro expansion
+ 2. **String Building:** Generates Rust code that builds a TypeScript string at runtime
+ 3. **SWC Parsing:** The generated string is parsed with SWC to produce a typed AST
+ 4. **Result:** Returns `Stmt` that can be used in `MacroResult` patches
+ ## Return Type
+ `ts_template!` returns a `Result<Stmt, TsSynError>` by default. The macro automatically unwraps and provides helpful error messages showing the generated TypeScript code if parsing fails:
+ ```
 Failed to parse generated TypeScript:
 User.prototype.toJSON = function( {
     return {};
 }
-```
-
-This shows you exactly what was generated, making debugging easy!
-
-## Nesting and Regular TypeScript
-
-You can mix template syntax with regular TypeScript. Braces <code >&#123;&#125;</code > are recognized as either:
-
-- **Template tags** if they start with `#`, `$`, `:`, or `/`
-
-    - **Regular TypeScript blocks** otherwise
-
-```rust
+``` This shows you exactly what was generated, making debugging easy!
+ ## Nesting and Regular TypeScript
+ You can mix template syntax with regular TypeScript. Braces `{}` are recognized as either:
+ - **Template tags** if they start with `#`, `$`, `:`, or `/`
+ - **Regular TypeScript blocks** otherwise
+ ```
 ts_template! {
     const config = {
         {#if use_strict}
@@ -835,32 +523,14 @@ ts_template! {
         timeout: 5000
     };
 }
-```
-
-## Comparison with Alternatives
-
-| `ts_quote!` 
-            | Compile-time validation, type-safe 
-            | Can't handle Vec<Stmt>, verbose 
-        
-
-        
-            | `parse_ts_str()` 
-            | Maximum flexibility 
-            | Runtime parsing, less readable 
-        
-
-        
-            | `ts_template!` 
-            | Readable, handles loops/conditions 
-            | Small runtime parsing overhead
-
-## Best Practices
-
-1. Use `ts_template!` for complex code generation with loops/conditions
-
-    2. Use `ts_quote!` for simple, static statements
-
-    3. Keep templates readable - extract complex logic into variables
-
-    4. Don't nest templates too deeply - split into helper functions
+``` ## Comparison with Alternatives
+ | Approach | Pros | Cons |
+| --- | --- | --- |
+| `ts_quote!` | Compile-time validation, type-safe | Can't handle Vec<Stmt>, verbose |
+| `parse_ts_str()` | Maximum flexibility | Runtime parsing, less readable |
+| `ts_template!` | Readable, handles loops/conditions | Small runtime parsing overhead |
+ ## Best Practices
+ 1. Use `ts_template!` for complex code generation with loops/conditions
+ 2. Use `ts_quote!` for simple, static statements
+ 3. Keep templates readable - extract complex logic into variables
+ 4. Don't nest templates too deeply - split into helper functions