perf: reduce per-character overhead in hot parsing paths

.gitignore

@@ -6,3 +6,4 @@ composer.lock
 .phpstan-cache
 coverage
 .idea
+.claude

composer.json

@@ -45,7 +45,7 @@
         }
     },
     "scripts": {
-        "test": "pest",
+        "test": "pest --parallel",
         "benchmark": "phpbench run",
         "ecs": "ecs check --fix",
         "rector": "rector process",

docs/json-repair/configuration.mdx

@@ -12,12 +12,12 @@ When `true` (default), non-ASCII characters are escaped. When `false`, Unicode i
 use function Cortex\JsonRepair\json_repair;
 
 // ensureAscii: true (default) - escapes Unicode
-json_repair("{'test_中国人_ascii':'统一码'}", ensureAscii: true);
-// {"test_中国人_ascii":"\u7edf\u4e00\u7801"}
+json_repair("{'city':'上海'}", ensureAscii: true);
+// {"city":"\u4e0a\u6d77"}
 
 // ensureAscii: false - preserves Unicode
-json_repair("{'test_中国人_ascii':'统一码'}", ensureAscii: false);
-// {"test_中国人_ascii":"统一码"}
+json_repair("{'city':'上海'}", ensureAscii: false);
+// {"city":"上海"}
 ```
 
 ## omitEmptyValues

docs/json-repair/installation.mdx

@@ -40,6 +40,7 @@ If you're contributing to the package or want to run tests:
     ```
   </Step>
   <Step title="Run Tests and Code Quality Tools">
+    Runs tests, static analysis (PHPStan), coding standards (ECS), and type coverage:
     ```bash
     composer check
     ```

docs/json-repair/logging.mdx

@@ -39,15 +39,22 @@ Valid JSON produces a single log entry:
 When repairs occur, you'll see messages such as:
 
 - `Starting JSON repair`
-- `Adding missing closing quote for unclosed string`
-- `Adding missing closing bracket/brace`
+- `Extracted JSON from markdown code block`
+- `Removed comments from JSON`
+- `Removing single-line comment`
+- `Removing multi-line comment`
 - `Converting single-quoted key to double quotes`
-- `Normalizing boolean/null value` (with context: `from: 'True', to: 'true'`)
+- `Converting smart/curly quote to standard double quote`
+- `Found doubled quote delimiter pattern, normalizing key`
 - `Adding quotes around unquoted key`
 - `Found unquoted string value, adding quotes`
-- `Inserting missing comma`
 - `Inserting missing colon after key`
-- `Extracted JSON from markdown code block`
+- `Inserting missing comma`
+- `Removing trailing comma`
+- `Normalizing boolean/null value` (with context: `from: 'True', to: 'true'`)
+- `Adding missing closing quote for unclosed string`
+- `Removing incomplete string value (omitIncompleteStrings enabled)`
+- `Adding missing closing bracket/brace`
 - `Removing key with missing value (omitEmptyValues enabled)`
 
 Log entries include `position` and `context` with `>>>` markers showing where the repair occurred.

docs/json-repair/quickstart.mdx

@@ -40,6 +40,23 @@ $data = $repairer->decode();
 // ['key' => 'value']
 ```
 
+## Error Handling
+
+`repair()` throws `JsonRepairException` if the input cannot be repaired into valid JSON:
+
+```php
+use Cortex\JsonRepair\JsonRepairer;
+use Cortex\JsonRepair\Exceptions\JsonRepairException;
+
+try {
+    $repaired = (new JsonRepairer($input))->repair();
+} catch (JsonRepairException $e) {
+    // input could not be repaired into valid JSON
+}
+```
+
+The helper functions `json_repair()` and `json_repair_decode()` propagate the same exception.
+
 ## Next Steps
 
 - See [Repair Examples](/json-repair/repair-examples) for what gets fixed

docs/json-repair/repair-examples.mdx

@@ -19,13 +19,30 @@ json_repair("{'key': 'string', \"key4\": unquoted}");
 // {"key": "string", "key4": "unquoted"}
 ```
 
+Typographic (smart/curly) quotes are normalised to standard double quotes:
+
+```php
+json_repair('{"key": "value"}');
+// {"key": "value"}
+
+json_repair("{'key': 'value'}");
+// {"key": "value"}
+```
+
 Quotes inside string values are escaped:
 
 ```php
 json_repair('{"key": "v"alu"e"}');
 // {"key": "v\"alu\"e"}
 ```
 
+Invalid escape sequences are double-escaped so the output stays valid:
+
+```php
+json_repair('{"key": "foo\qbar"}');
+// {"key": "foo\\qbar"}
+```
+
 ## Commas and Colons
 
 Trailing commas are removed; missing commas and colons are inserted.

src/Concerns/InputSanitization.php

@@ -47,6 +47,11 @@ private function extractJsonFromMarkdown(string $input): string
      */
     private function removeComments(string $input): string
     {
+        // Fast path: if no comment markers exist, return as-is without scanning
+        if (! str_contains($input, '//') && ! str_contains($input, '/*')) {
+            return $input;
+        }
+
         $length = strlen($input);
         $output = '';
         $inString = false;