From 085547bc8ee42e6976aa6d9ba02644bc00f5a7e3 Mon Sep 17 00:00:00 2001
From: Caleb Porzio <calebporzio@gmail.com>
Date: Thu, 23 Oct 2025 14:58:08 -0400
Subject: [PATCH 1/5] wip

---
 src/BladeService.php         |  13 +++-
 src/BlazeServiceProvider.php |  24 +++++--
 src/Unblaze.php              | 121 +++++++++++++++++++++++++++++++++++
 3 files changed, 151 insertions(+), 7 deletions(-)
 create mode 100644 src/Unblaze.php

diff --git a/src/BladeService.php b/src/BladeService.php
index 7edd0c91..a07708b9 100644
--- a/src/BladeService.php
+++ b/src/BladeService.php
@@ -3,6 +3,7 @@
 namespace Livewire\Blaze;
 
 use Illuminate\Support\Facades\Event;
+use Livewire\Blaze\Unblaze;
 use ReflectionClass;
 
 class BladeService
@@ -24,12 +25,22 @@ public function isolatedRender(string $template): string
 
         [$compiler, $restore] = $this->freezeObjectProperties($compiler, [
             'rawBlocks',
-            'prepareStringsForCompilationUsing' => [],
+            'prepareStringsForCompilationUsing' => [
+                function ($input) {
+                    if (Unblaze::hasUnblaze($input)) {
+                        $input = Unblaze::processUnblazeDirectives($input);
+                    }
+
+                    return $input;
+                }
+            ],
             'path' => null,
         ]);
 
         try {
             $result = $compiler->render($template);
+
+            $result = Unblaze::replaceUnblazePrecompiledDirectives($result);
         } finally {
             $restore();
             $restoreFactory();
diff --git a/src/BlazeServiceProvider.php b/src/BlazeServiceProvider.php
index 98b97761..b0a36b5f 100644
--- a/src/BlazeServiceProvider.php
+++ b/src/BlazeServiceProvider.php
@@ -2,20 +2,21 @@
 
 namespace Livewire\Blaze;
 
-use Livewire\Blaze\Directive\BlazeDirective;
-use Livewire\Blaze\Tokenizer\Tokenizer;
-use Illuminate\Support\ServiceProvider;
-use Livewire\Blaze\Memoizer\Memoizer;
 use Livewire\Blaze\Walker\Walker;
+use Livewire\Blaze\Tokenizer\Tokenizer;
 use Livewire\Blaze\Parser\Parser;
+use Livewire\Blaze\Memoizer\Memoizer;
 use Livewire\Blaze\Folder\Folder;
+use Livewire\Blaze\Directive\BlazeDirective;
+use Illuminate\Support\ServiceProvider;
+use Illuminate\Support\Facades\Blade;
 
 class BlazeServiceProvider extends ServiceProvider
 {
     public function register(): void
     {
         $this->registerBlazeManager();
-        $this->registerBlazeDirectiveFallback();
+        $this->registerBlazeDirectiveFallbacks();
         $this->registerBladeMacros();
         $this->interceptBladeCompilation();
         $this->interceptViewCacheInvalidation();
@@ -44,8 +45,19 @@ protected function registerBlazeManager(): void
         $this->app->bind('blaze', fn ($app) => $app->make(BlazeManager::class));
     }
 
-    protected function registerBlazeDirectiveFallback(): void
+    protected function registerBlazeDirectiveFallbacks(): void
     {
+        Blade::directive('unblaze', function ($expression) {
+            return ''
+                . '<'.'?php $__getScope = fn($scope = []) => $scope; ?>'
+                . '<'.'?php if (isset($scope)) $__scope = $scope; ?>'
+                . '<'.'?php $scope = $__getScope('.$expression.'); ?>';
+        });
+
+        Blade::directive('endunblaze', function () {
+            return '<'.'?php if (isset($__scope)) { $scope = $__scope; unset($__scope); } ?>';
+        });
+
         BlazeDirective::registerFallback();
     }
 
diff --git a/src/Unblaze.php b/src/Unblaze.php
new file mode 100644
index 00000000..5477edcf
--- /dev/null
+++ b/src/Unblaze.php
@@ -0,0 +1,121 @@
+<?php
+
+namespace Livewire\Blaze;
+
+use Illuminate\Support\Arr;
+
+class Unblaze
+{
+    static $unblazeScopes = [];
+    static $unblazeReplacements = [];
+
+    public static function storeScope($token, $scope = [])
+    {
+        static::$unblazeScopes[$token] = $scope;
+    }
+
+    public static function hasUnblaze(string $template): bool
+    {
+        return str_contains($template, '@unblaze');
+    }
+
+    public static function processUnblazeDirectives(string $template)
+    {
+        $compiler = static::getHackedBladeCompiler();
+
+        $expressionsByToken = [];
+
+        $compiler->directive('unblaze', function ($expression) use (&$expressionsByToken) {
+            $token = str()->random(10);
+
+            $expressionsByToken[$token] = $expression;
+
+            return '[STARTUNBLAZE:'.$token.']';
+        });
+
+        $compiler->directive('endunblaze', function () {
+            return '[ENDUNBLAZE]';
+        });
+
+        $result = $compiler->compileStatementsMadePublic($template);
+
+        $result = preg_replace_callback('/(\[STARTUNBLAZE:([0-9a-zA-Z]+)\])(.*?)(\[ENDUNBLAZE\])/s', function ($matches) use (&$expressionsByToken) {
+            $token = $matches[2];
+            $expression = $expressionsByToken[$token];
+            $innerContent = $matches[3];
+
+            static::$unblazeReplacements[$token] = $innerContent;
+
+            return ''
+                . '[STARTCOMPILEDUNBLAZE:'.$token.']'
+                . '<'.'?php \Livewire\Blaze\Unblaze::storeScope("'.$token.'", '.$expression.') ?>'
+                . '[ENDCOMPILEDUNBLAZE]';
+        }, $result);
+
+        return $result;
+    }
+
+    public static function replaceUnblazePrecompiledDirectives(string $template)
+    {
+        if (str_contains($template, '[STARTCOMPILEDUNBLAZE')) {
+            $template = preg_replace_callback('/(\[STARTCOMPILEDUNBLAZE:([0-9a-zA-Z]+)\])(.*?)(\[ENDCOMPILEDUNBLAZE\])/s', function ($matches) use (&$expressionsByToken) {
+                $token = $matches[2];
+
+                $innerContent = static::$unblazeReplacements[$token];
+
+                $scope = static::$unblazeScopes[$token];
+
+                $runtimeScopeString = var_export($scope, true);
+
+                return ''
+                    . '<'.'?php if (isset($scope)) $__scope = $scope; ?>'
+                    . '<'.'?php $scope = '.$runtimeScopeString.'; ?>'
+                    . $innerContent
+                    . '<'.'?php if (isset($__scope)) { $scope = $__scope; unset($__scope); } ?>';
+            }, $template);
+        }
+
+        return $template;
+    }
+
+    public static function getHackedBladeCompiler()
+    {
+        $instance = new class (
+            app('files'),
+            storage_path('framework/views'),
+        ) extends \Illuminate\View\Compilers\BladeCompiler {
+            /**
+             * Make this method public...
+             */
+            public function compileStatementsMadePublic($template)
+            {
+                return $this->compileStatements($template);
+            }
+
+            /**
+             * Tweak this method to only process custom directives so we
+             * can restrict rendering solely to @island related directives...
+             */
+            protected function compileStatement($match)
+            {
+                if (str_contains($match[1], '@')) {
+                    $match[0] = isset($match[3]) ? $match[1].$match[3] : $match[1];
+                } elseif (isset($this->customDirectives[$match[1]])) {
+                    $match[0] = $this->callCustomDirective($match[1], Arr::get($match, 3));
+                } elseif (method_exists($this, $method = 'compile'.ucfirst($match[1]))) {
+                    // Don't process through built-in directive methods...
+                    // $match[0] = $this->$method(Arr::get($match, 3));
+
+                    // Just return the original match...
+                    return $match[0];
+                } else {
+                    return $match[0];
+                }
+
+                return isset($match[3]) ? $match[0] : $match[0].$match[2];
+            }
+        };
+
+        return $instance;
+    }
+}
\ No newline at end of file

From 56170a0a23f03c57d3a3035bd95221b7b9fd30ef Mon Sep 17 00:00:00 2001
From: Josh Hanley <josh@hitsystems.com.au>
Date: Fri, 24 Oct 2025 19:07:59 +1000
Subject: [PATCH 2/5] Fix failed render unblaze issue

---
 src/BladeService.php | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/src/BladeService.php b/src/BladeService.php
index a07708b9..753e9b4f 100644
--- a/src/BladeService.php
+++ b/src/BladeService.php
@@ -3,6 +3,7 @@
 namespace Livewire\Blaze;
 
 use Illuminate\Support\Facades\Event;
+use Illuminate\Support\Facades\File;
 use Livewire\Blaze\Unblaze;
 use ReflectionClass;
 
@@ -12,6 +13,10 @@ public function isolatedRender(string $template): string
     {
         $compiler = app('blade.compiler');
 
+        $temporaryCachePath = storage_path('framework/views/blaze/isolated-render/');
+
+        File::ensureDirectoryExists($temporaryCachePath);
+
         $factory = app('view');
 
         [$factory, $restoreFactory] = $this->freezeObjectProperties($factory, [
@@ -24,6 +29,7 @@ public function isolatedRender(string $template): string
         ]);
 
         [$compiler, $restore] = $this->freezeObjectProperties($compiler, [
+            'cachePath' => $temporaryCachePath,
             'rawBlocks',
             'prepareStringsForCompilationUsing' => [
                 function ($input) {
@@ -44,6 +50,8 @@ function ($input) {
         } finally {
             $restore();
             $restoreFactory();
+
+            File::deleteDirectory($temporaryCachePath);
         }
 
         return $result;

From 52ac5a75ed0f4378aaaba400bfd9129f30fe88e7 Mon Sep 17 00:00:00 2001
From: Caleb Porzio <calebporzio@gmail.com>
Date: Fri, 24 Oct 2025 09:41:27 -0400
Subject: [PATCH 3/5] wip

---
 tests/BenchmarkTest.php | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/tests/BenchmarkTest.php b/tests/BenchmarkTest.php
index e52eec36..4712baf6 100644
--- a/tests/BenchmarkTest.php
+++ b/tests/BenchmarkTest.php
@@ -31,7 +31,11 @@ function clearCache() {
     $files = glob(__DIR__ . '/../vendor/orchestra/testbench-core/laravel/storage/framework/views/*');
     foreach ($files as $file) {
         if (!str_ends_with($file, '.gitignore')) {
-            unlink($file);
+           if (is_dir($file)) {
+                rmdir($file);
+           } else {
+                unlink($file);
+            }
         }
     }
 }

From 0ebb5882c89c525c3bce52b05ca93cfd8a5c0b66 Mon Sep 17 00:00:00 2001
From: Caleb Porzio <calebporzio@gmail.com>
Date: Fri, 24 Oct 2025 09:53:28 -0400
Subject: [PATCH 4/5] add tests

---
 tests/UnblazeTest.php                         | 221 ++++++++++++++++++
 .../components/mixed-random.blade.php         |   8 +
 .../components/random-static.blade.php        |   5 +
 .../components/scoped-dynamic.blade.php       |   8 +
 .../components/with-unblaze-scope.blade.php   |   8 +
 .../components/with-unblaze.blade.php         |   8 +
 6 files changed, 258 insertions(+)
 create mode 100644 tests/UnblazeTest.php
 create mode 100644 tests/fixtures/components/mixed-random.blade.php
 create mode 100644 tests/fixtures/components/random-static.blade.php
 create mode 100644 tests/fixtures/components/scoped-dynamic.blade.php
 create mode 100644 tests/fixtures/components/with-unblaze-scope.blade.php
 create mode 100644 tests/fixtures/components/with-unblaze.blade.php

diff --git a/tests/UnblazeTest.php b/tests/UnblazeTest.php
new file mode 100644
index 00000000..572b5370
--- /dev/null
+++ b/tests/UnblazeTest.php
@@ -0,0 +1,221 @@
+<?php
+
+use Illuminate\Support\Facades\View;
+
+describe('unblaze directive', function () {
+    beforeEach(function () {
+        // Configure Blade to find our test components
+        app('blade.compiler')->anonymousComponentNamespace('', 'x');
+        app('blade.compiler')->anonymousComponentPath(__DIR__ . '/fixtures/components');
+
+        // Add view path for our test pages
+        View::addLocation(__DIR__ . '/fixtures/pages');
+    });
+
+    it('folds component but preserves unblaze block', function () {
+        $input = '<x-with-unblaze />';
+
+        $compiled = app('blaze')->compile($input);
+
+        // The component should be folded
+        expect($compiled)->toContain('<div class="container">');
+        expect($compiled)->toContain('<h1>Static Header</h1>');
+        expect($compiled)->toContain('<footer>Static Footer</footer>');
+
+        // The unblaze block should be preserved as dynamic content
+        expect($compiled)->toContain('{{ $dynamicValue }}');
+        expect($compiled)->not->toContain('<x-with-unblaze');
+    });
+
+    it('preserves unblaze content without folding the dynamic parts', function () {
+        $input = '<x-with-unblaze />';
+
+        $compiled = app('blaze')->compile($input);
+
+        // Static parts should be folded
+        expect($compiled)->toContain('Static Header');
+        expect($compiled)->toContain('Static Footer');
+
+        // Dynamic parts inside @unblaze should remain dynamic
+        expect($compiled)->toContain('$dynamicValue');
+    });
+
+    it('handles unblaze with scope parameter', function () {
+        $input = '<?php $message = "Hello World"; ?> <x-with-unblaze-scope :message="$message" />';
+
+        $compiled = app('blaze')->compile($input);
+
+        // The component should be folded
+        expect($compiled)->toContain('<div class="wrapper">');
+        expect($compiled)->toContain('<h2>Title</h2>');
+        expect($compiled)->toContain('<p>Static paragraph</p>');
+
+        // The scope should be captured and made available
+        expect($compiled)->toContain('$scope');
+    });
+
+    it('encodes scope into compiled view for runtime access', function () {
+        $input = '<?php $message = "Test Message"; ?> <x-with-unblaze-scope :message="$message" />';
+
+        $compiled = app('blaze')->compile($input);
+
+        // Should contain PHP code to set up the scope
+        expect($compiled)->toMatch('/\$scope\s*=\s*array\s*\(/');
+
+        // The dynamic content should reference $scope
+        expect($compiled)->toContain('$scope[\'message\']');
+    });
+
+    it('renders unblaze component correctly at runtime', function () {
+        $template = '<?php $message = "Runtime Test"; ?> <x-with-unblaze-scope :message="$message" />';
+
+        $rendered = \Illuminate\Support\Facades\Blade::render($template);
+
+        // Static content should be present
+        expect($rendered)->toContain('<div class="wrapper">');
+        expect($rendered)->toContain('<h2>Title</h2>');
+        expect($rendered)->toContain('<p>Static paragraph</p>');
+
+        // Dynamic content should be rendered with the scope value
+        // Note: The actual rendering of scope variables happens at runtime
+        expect($rendered)->toContain('class="dynamic"');
+    });
+
+    it('allows punching a hole in static component for dynamic section', function () {
+        $input = <<<'BLADE'
+<x-card>
+    Static content here
+    @unblaze
+        <span>{{ $dynamicValue }}</span>
+    @endunblaze
+    More static content
+</x-card>
+BLADE;
+
+        $compiled = app('blaze')->compile($input);
+
+        // Card should be folded
+        expect($compiled)->toContain('<div class="card">');
+        expect($compiled)->toContain('Static content here');
+        expect($compiled)->toContain('More static content');
+
+        // But dynamic part should be preserved
+        expect($compiled)->toContain('{{ $dynamicValue }}');
+        expect($compiled)->not->toContain('<x-card>');
+    });
+
+    it('supports multiple unblaze blocks in same component', function () {
+        $template = <<<'BLADE'
+@blaze
+<div>
+    <p>Static 1</p>
+    @unblaze
+        <span>{{ $dynamic1 }}</span>
+    @endunblaze
+    <p>Static 2</p>
+    @unblaze
+        <span>{{ $dynamic2 }}</span>
+    @endunblaze
+    <p>Static 3</p>
+</div>
+BLADE;
+
+        $compiled = app('blaze')->compile($template);
+
+        // All static parts should be folded
+        expect($compiled)->toContain('<p>Static 1</p>');
+        expect($compiled)->toContain('<p>Static 2</p>');
+        expect($compiled)->toContain('<p>Static 3</p>');
+
+        // Both dynamic parts should be preserved
+        expect($compiled)->toContain('{{ $dynamic1 }}');
+        expect($compiled)->toContain('{{ $dynamic2 }}');
+    });
+
+    it('handles nested components with unblaze', function () {
+        $input = <<<'BLADE'
+<x-card>
+    <x-button>Static Button</x-button>
+    @unblaze
+        <x-button>{{ $dynamicLabel }}</x-button>
+    @endunblaze
+</x-card>
+BLADE;
+
+        $compiled = app('blaze')->compile($input);
+
+        // Outer card and static button should be folded
+        expect($compiled)->toContain('<div class="card">');
+        expect($compiled)->toContain('Static Button');
+
+        // Dynamic button inside unblaze should be preserved
+        expect($compiled)->toContain('{{ $dynamicLabel }}');
+    });
+
+    it('static folded content with random strings stays the same between renders', function () {
+        // First render
+        $render1 = \Illuminate\Support\Facades\Blade::render('<x-random-static />');
+
+        // Second render
+        $render2 = \Illuminate\Support\Facades\Blade::render('<x-random-static />');
+
+        // The random string should be the same because it was folded at compile time
+        expect($render1)->toBe($render2);
+
+        // Verify it contains the static structure
+        expect($render1)->toContain('class="static-component"');
+        expect($render1)->toContain('This should be folded and not change between renders');
+    });
+
+    it('unblazed dynamic content changes between renders while static parts stay the same', function () {
+        // First render with a value
+        $render1 = \Illuminate\Support\Facades\Blade::render('<x-mixed-random />', ['dynamicValue' => 'first-value']);
+
+        // Second render with a different value
+        $render2 = \Illuminate\Support\Facades\Blade::render('<x-mixed-random />', ['dynamicValue' => 'second-value']);
+
+        // Extract the static parts (header and footer with random strings)
+        preg_match('/<h1>Static Random: (.+?)<\/h1>/', $render1, $matches1);
+        preg_match('/<h1>Static Random: (.+?)<\/h1>/', $render2, $matches2);
+        $staticRandom1 = $matches1[1] ?? '';
+        $staticRandom2 = $matches2[1] ?? '';
+
+        // The static random strings should be IDENTICAL (folded at compile time)
+        expect($staticRandom1)->toBe($staticRandom2);
+        expect($staticRandom1)->not->toBeEmpty();
+
+        // But the dynamic parts should be DIFFERENT
+        expect($render1)->toContain('Dynamic value: first-value');
+        expect($render2)->toContain('Dynamic value: second-value');
+        expect($render1)->not->toContain('second-value');
+        expect($render2)->not->toContain('first-value');
+    });
+
+    it('multiple renders of unblaze component proves folding optimization', function () {
+        // Render the same template multiple times with different dynamic values
+        $renders = [];
+        foreach (['one', 'two', 'three'] as $value) {
+            $renders[] = \Illuminate\Support\Facades\Blade::render(
+                '<x-mixed-random />',
+                ['dynamicValue' => $value]
+            );
+        }
+
+        // Extract the static footer random string from each render
+        $staticFooters = [];
+        foreach ($renders as $render) {
+            preg_match('/<footer>Static Footer: (.+?)<\/footer>/', $render, $matches);
+            $staticFooters[] = $matches[1] ?? '';
+        }
+
+        // All static random strings should be IDENTICAL (proving they were folded)
+        expect($staticFooters[0])->toBe($staticFooters[1]);
+        expect($staticFooters[1])->toBe($staticFooters[2]);
+        expect($staticFooters[0])->not->toBeEmpty();
+
+        // But each render should have its unique dynamic value
+        expect($renders[0])->toContain('Dynamic value: one');
+        expect($renders[1])->toContain('Dynamic value: two');
+        expect($renders[2])->toContain('Dynamic value: three');
+    });
+});
diff --git a/tests/fixtures/components/mixed-random.blade.php b/tests/fixtures/components/mixed-random.blade.php
new file mode 100644
index 00000000..861183c8
--- /dev/null
+++ b/tests/fixtures/components/mixed-random.blade.php
@@ -0,0 +1,8 @@
+@blaze
+<div class="mixed-component">
+    <h1>Static Random: {{ \Illuminate\Support\Str::random(20) }}</h1>
+    @unblaze
+        <p class="dynamic">Dynamic value: {{ $dynamicValue ?? 'none' }}</p>
+    @endunblaze
+    <footer>Static Footer: {{ \Illuminate\Support\Str::random(10) }}</footer>
+</div>
diff --git a/tests/fixtures/components/random-static.blade.php b/tests/fixtures/components/random-static.blade.php
new file mode 100644
index 00000000..635ae031
--- /dev/null
+++ b/tests/fixtures/components/random-static.blade.php
@@ -0,0 +1,5 @@
+@blaze
+<div class="static-component">
+    <h1>Random: {{ \Illuminate\Support\Str::random(20) }}</h1>
+    <p>This should be folded and not change between renders</p>
+</div>
diff --git a/tests/fixtures/components/scoped-dynamic.blade.php b/tests/fixtures/components/scoped-dynamic.blade.php
new file mode 100644
index 00000000..afe6405f
--- /dev/null
+++ b/tests/fixtures/components/scoped-dynamic.blade.php
@@ -0,0 +1,8 @@
+@blaze
+<div class="scoped-component">
+    <h1>Static: {{ \Illuminate\Support\Str::random(15) }}</h1>
+    @unblaze(scope: ['value' => $value])
+        <div class="dynamic-section">Value: {{ $scope['value'] }}</div>
+    @endunblaze
+    <p>Static paragraph: {{ \Illuminate\Support\Str::random(10) }}</p>
+</div>
diff --git a/tests/fixtures/components/with-unblaze-scope.blade.php b/tests/fixtures/components/with-unblaze-scope.blade.php
new file mode 100644
index 00000000..d818e5d9
--- /dev/null
+++ b/tests/fixtures/components/with-unblaze-scope.blade.php
@@ -0,0 +1,8 @@
+@blaze
+<div class="wrapper">
+    <h2>Title</h2>
+    @unblaze(scope: ['message' => $message])
+        <div class="dynamic">{{ $scope['message'] }}</div>
+    @endunblaze
+    <p>Static paragraph</p>
+</div>
diff --git a/tests/fixtures/components/with-unblaze.blade.php b/tests/fixtures/components/with-unblaze.blade.php
new file mode 100644
index 00000000..a24bb4b7
--- /dev/null
+++ b/tests/fixtures/components/with-unblaze.blade.php
@@ -0,0 +1,8 @@
+@blaze
+<div class="container">
+    <h1>Static Header</h1>
+    @unblaze
+        <p>Dynamic content: {{ $dynamicValue }}</p>
+    @endunblaze
+    <footer>Static Footer</footer>
+</div>

From b533e4a904ed5058b3ce3855821171f602d37a87 Mon Sep 17 00:00:00 2001
From: Caleb Porzio <calebporzio@gmail.com>
Date: Fri, 24 Oct 2025 10:00:15 -0400
Subject: [PATCH 5/5] add docs

---
 README.md | 136 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 136 insertions(+)

diff --git a/README.md b/README.md
index a7e686fe..8348110a 100644
--- a/README.md
+++ b/README.md
@@ -85,6 +85,7 @@ Blaze will automatically optimize it during compilation, pre-rendering the stati
 ## Table of contents
 
 - [When to use @blaze](#when-to-use-blaze)
+- [Making impure components Blaze-eligible with @unblaze](#making-impure-components-blaze-eligible-with-unblaze)
 - [Performance expectations](#performance-expectations)
 - [Debugging](#debugging)
 - [AI assistant integration](#ai-assistant-integration)
@@ -284,6 +285,141 @@ When a component can't be folded due to dynamic content, Blaze automatically fal
 - **Test thoroughly**: After adding `@blaze`, verify the component still works correctly across different requests
 - **Blaze is forgiving**: If a component can't be optimized, Blaze will automatically fall back to normal rendering
 
+## Making impure components Blaze-eligible with @unblaze
+
+Sometimes you have a component that's *mostly* static, but contains a small dynamic section that would normally prevent it from being folded (like `$errors`, `request()`, or `session()`). The `@unblaze` directive lets you "punch a hole" in an otherwise static component, keeping the static parts optimized while allowing specific sections to remain dynamic.
+
+### The problem
+
+Imagine a form input component that's perfect for `@blaze` - except it needs to show validation errors:
+
+```blade
+{{-- ❌ Can't use @blaze - $errors prevents optimization --}}
+
+<div>
+    <label>{{ $label }}</label>
+    <input type="text" name="{{ $name }}">
+
+    @if($errors->has($name))
+        <span>{{ $errors->first($name) }}</span>
+    @endif
+</div>
+```
+
+Without `@unblaze`, you have to choose: either skip `@blaze` entirely (losing all optimization), or remove the error handling (losing functionality).
+
+### The solution: @unblaze
+
+The `@unblaze` directive creates a dynamic section within a folded component:
+
+```blade
+{{-- ✅ Now we can use @blaze! --}}
+
+@blaze
+
+@props(['name', 'label'])
+
+<div>
+    <label>{{ $label }}</label>
+    <input type="text" name="{{ $name }}">
+
+    @unblaze
+        @if($errors->has($name))
+            <span>{{ $errors->first($name) }}</span>
+        @endif
+    @endunblaze
+</div>
+```
+
+**What happens:**
+- The `<div>`, `<label>`, and `<input>` are folded (pre-rendered at compile time)
+- The error handling inside `@unblaze` remains dynamic (evaluated at runtime)
+- You get the best of both worlds: optimization + dynamic functionality
+
+### Using scope to pass data into @unblaze
+
+Sometimes you need to pass component props into the `@unblaze` block. Use the `scope` parameter:
+
+```blade
+@blaze
+
+@props(['userId', 'showStatus' => true])
+
+<div>
+    <h2>User Profile</h2>
+    {{-- Lots of static markup here --}}
+
+    @unblaze(scope: ['userId' => $userId, 'showStatus' => $showStatus])
+        @if($scope['showStatus'])
+            <div>User #{{ $scope['userId'] }} - Last seen: {{ session('last_seen') }}</div>
+        @endif
+    @endunblaze
+</div>
+```
+
+**How scope works:**
+- Variables captured in `scope:` are encoded into the compiled view
+- Inside the `@unblaze` block, access them via `$scope['key']`
+- This allows the unblaze section to use component props while keeping the rest folded
+
+### Nested components inside @unblaze
+
+You can render other components inside `@unblaze` blocks, which is useful for extracting reusable dynamic sections:
+
+```blade
+@blaze
+
+@props(['name', 'label'])
+
+<div>
+    <label>{{ $label }}</label>
+    <input type="text" name="{{ $name }}">
+
+    @unblaze(scope: ['name' => $name])
+        <x-form.errors :name="$scope['name']" />
+    @endunblaze
+</div>
+```
+
+```blade
+{{-- components/form/errors.blade.php --}}
+
+@props(['name'])
+
+@error($name)
+    <p>{{ $message }}</p>
+@enderror
+```
+
+This allows you to keep your error display logic in a separate component while still using it within the unblaze section. The form input remains folded, and only the error component is evaluated at runtime.
+
+### Multiple @unblaze blocks
+
+You can use multiple `@unblaze` blocks in a single component:
+
+```blade
+@blaze
+
+<div>
+    <header>Static Header</header>
+
+    @unblaze
+        <div>Hello, {{ auth()->user()->name }}</div>
+    @endunblaze
+
+    <main>
+        {{-- Lots of static content --}}
+    </main>
+
+    @unblaze
+        <input type="hidden" value="{{ csrf_token() }}">
+    @endunblaze
+
+    <footer>Static Footer</footer>
+</div>
+```
+
+Each `@unblaze` block creates an independent dynamic section, while everything else remains folded.
 
 ## Performance expectations