Nomad changes

docs/snippets/php/async/async_amp_bridge.md

@@ -0,0 +1,27 @@
+```php title="PHP (Amp v3+)"
+<?php
+
+declare(strict_types=1);
+
+// Requires: composer require amphp/amp ^3.0
+use Kreuzberg\Kreuzberg;
+use Kreuzberg\Async\AmpBridge;
+
+$kreuzberg = new Kreuzberg();
+
+// Single file extraction with Amp Future
+$deferred = $kreuzberg->extractFileAsync('document.pdf');
+$future = AmpBridge::toFuture($deferred);
+$result = $future->await();
+echo $result->content;
+
+// Batch extraction with Amp Future
+$files = ['doc1.pdf', 'doc2.docx', 'doc3.xlsx'];
+$batchDeferred = $kreuzberg->batchExtractFilesAsync($files);
+$batchFuture = AmpBridge::toBatchFuture($batchDeferred);
+$results = $batchFuture->await();
+
+foreach ($results as $i => $result) {
+    echo "{$files[$i]}: {$result->content}\n";
+}
+```

docs/snippets/php/async/async_batch.md

@@ -0,0 +1,40 @@
+```php title="PHP"
+<?php
+
+declare(strict_types=1);
+
+use Kreuzberg\Kreuzberg;
+use function Kreuzberg\batch_extract_files_async;
+
+$kreuzberg = new Kreuzberg();
+
+// Async batch file extraction
+$files = ['doc1.pdf', 'doc2.docx', 'doc3.xlsx'];
+$deferred = $kreuzberg->batchExtractFilesAsync($files);
+
+// Do other work while extraction runs...
+processOtherTasks();
+
+// Block until all results are ready
+$results = $deferred->getResults();
+
+foreach ($results as $i => $result) {
+    echo "{$files[$i]}: " . strlen($result->content) . " chars\n";
+}
+
+// With timeout
+$deferred = $kreuzberg->batchExtractFilesAsync($files);
+$results = $deferred->waitBatch(10000); // 10 second timeout
+
+if ($results !== null) {
+    foreach ($results as $result) {
+        echo $result->content . "\n";
+    }
+} else {
+    echo "Batch extraction timed out\n";
+}
+
+// Procedural API
+$deferred = batch_extract_files_async($files);
+$results = $deferred->getResults();
+```

docs/snippets/php/async/async_extract_file.md

@@ -0,0 +1,47 @@
+```php title="PHP"
+<?php
+
+declare(strict_types=1);
+
+use Kreuzberg\Kreuzberg;
+use Kreuzberg\Exceptions\KreuzbergException;
+use function Kreuzberg\extract_file_async;
+
+// OOP API: async file extraction
+$kreuzberg = new Kreuzberg();
+$deferred = $kreuzberg->extractFileAsync('document.pdf');
+
+// Non-blocking: check if ready
+if ($deferred->isReady()) {
+    $result = $deferred->getResult();
+    echo $result->content;
+}
+
+// Non-blocking: try to get result (returns null if pending)
+$result = $deferred->tryGetResult();
+if ($result !== null) {
+    echo $result->content;
+}
+
+// Blocking: wait until ready
+$result = $deferred->getResult();
+echo $result->content;
+
+// Blocking with timeout (5 seconds)
+$result = $deferred->wait(5000);
+if ($result !== null) {
+    echo $result->content;
+} else {
+    echo "Extraction timed out\n";
+}
+
+// Procedural API
+$deferred = extract_file_async('document.pdf');
+$result = $deferred->getResult();
+echo $result->content;
+
+// Static API
+$deferred = Kreuzberg::extractFileAsyncStatic('document.pdf');
+$result = $deferred->getResult();
+echo $result->content;
+```

docs/snippets/php/async/async_react_bridge.md

@@ -0,0 +1,25 @@
+```php title="PHP (ReactPHP)"
+<?php
+
+declare(strict_types=1);
+
+// Requires: composer require react/promise ^3.0 react/event-loop ^1.0
+use Kreuzberg\Kreuzberg;
+use Kreuzberg\Async\ReactBridge;
+
+$kreuzberg = new Kreuzberg();
+
+// Single file extraction with ReactPHP Promise
+$deferred = $kreuzberg->extractFileAsync('document.pdf');
+$promise = ReactBridge::toPromise($deferred);
+
+$promise->then(
+    function ($result) {
+        echo "Content: {$result->content}\n";
+        echo "MIME type: {$result->mimeType}\n";
+    },
+    function (\Throwable $error) {
+        echo "Extraction failed: {$error->getMessage()}\n";
+    }
+);
+```