@@ -14,7 +14,8 @@
  *
  * To refresh docs/performance.md: dispatch the workflow
  * (`gh workflow run speed-page-table.yml`), paste the linux-x64 table into the
- * page verbatim, and update the run link below the table.
+ * page verbatim, update the run link below the table, and refresh the
+ * worked-example numbers from the raw timings block.
  *
  * Harness rules (same as speed-probe.php): runtime-built pools of 64 distinct
  * strings, interleaved A/B in one process, best-of-7, results consumed. Before any
@@ -70,7 +71,8 @@ function pool(string $unit, int $bytes): array
 // Category units. Rotation keeps every character in every entry, so each specials
 // entry keeps its & and ' and each accented entry keeps its multibyte characters.
 // Densities are corpus-measured (Gutenberg EN/FR + published letter-frequency
-// tables): the apostrophe is the dominant special in real text (~0.1-0.5% of
+// tables; modern Wikipedia articles in both languages measure the same rates):
+// the apostrophe is the dominant special in real text (~0.1-0.5% of
 // typed-English characters, ~1% of typed French); & < > are essentially absent
 // from prose (they live in names and titles); French accented characters are
 // ~2.5% of all characters. Short units are denser than prose because a short
@@ -156,7 +158,7 @@ function ratioLabel(float $ratio): string
 $scale = max(0.01, (float)($opts['scale'] ?? 1.0));
 
 // [category, bytes label, example, pool, iterations]
-$mixLabel = '70% 16B (two of 45 are names with specials), 15% 200B, 10% 1KB, 5% 1KB with quotes';
+$mixLabel = '55% short 16 B, 10% numbers, 5% empty, 15% 200 B, 15% 1 KB; a few fields have quotes or apostrophes';
 $rows     = [];
 
 // Numbers first: ints and floats skip the scan entirely
@@ -209,16 +211,22 @@ function ratioLabel(float $ratio): string
 // Page mixes: proportions of a 64-entry pool; every iteration cycles the pool so
 // the measured cost is the weighted average of one field output
 $standardMix = array_merge(
-    array_slice(pool(UNIT_CLEAN, 16), 0, 43),
+    array_slice(pool(UNIT_CLEAN, 16), 0, 34),
     array_slice(pool(UNIT_SPECIALS, 16), 0, 2),   // a couple of short fields are names with specials
+    array_slice($numbers, 0, 6),                  // ids, counts, prices
+    array_slice($empties, 0, 3),                  // blank optional fields
     array_slice(pool(UNIT_CLEAN, 200), 0, 10),
     array_slice(pool(UNIT_CLEAN, 1024), 0, 6),
     array_slice(pool(UNIT_PROSE, 1024), 0, 3),
 );
-$rows[] = ['Realistic page mix', 'mixed', $mixLabel, $standardMix, 60000];
+// Measured for the bottom line's per-platform numbers; kept out of the docs
+// table - the worked example on the page is the page-level illustration
+$rows[] = ['Realistic page mix', 'mixed', $mixLabel, $standardMix, 60000, false];
 
+// Measured for the record but kept out of the docs table: a second weighted-average
+// mix number reads as contradicting the first (the article's higher ratio pulls it up)
 $articleMix = array_merge(array_slice($standardMix, 0, 63), array_slice(pool(UNIT_PROSE, 10240), 0, 1));
-$rows[] = ['Page mix + one 10 KB article', 'mixed', 'the mix above plus an article with quotes', $articleMix, 60000];
+$rows[] = ['Page mix + one 10 KB article', 'mixed', 'the mix above plus an article with quotes', $articleMix, 60000, false];
 
 #endregion
 #region Run and report
@@ -233,7 +241,7 @@ function ratioLabel(float $ratio): string
     $opcache ? '' : ' - NOT CITABLE, short-string rows dominated by unoptimized call overhead'
 );
 
-$table   = "| Content | Size | Example | SmartString speed |\n|---|---|---|---|\n";
+$table   = "| Content | Size | Example | Speed vs `htmlspecialchars()` |\n|---|---|---|---|\n";
 $rawLines = [];
 foreach ($rows as $row) {
     [$label, $sizeLabel, $example, $values, $iterations] = $row;
@@ -250,7 +258,7 @@ function ratioLabel(float $ratio): string
 }
 
 echo $table;
-echo "\n2x = SmartString outputs the value in half the time `htmlspecialchars()` takes; 1.0x = same speed; below 1x = slower.\n";
+echo "\n2x = twice as fast as calling `htmlspecialchars()` yourself; 1.0x = same speed; below 1x = slower.\n";
 echo "Measured on " . PHP_OS_FAMILY . ' ' . php_uname('m') . ", PHP " . PHP_VERSION . ".\n";
 echo "\nRaw timings (per call, best of 7):\n" . implode("\n", $rawLines) . "\n";
 
 
@@ -546,7 +546,8 @@ public function getIterator(): Iterator
 
 // Specials and accent densities are corpus-measured (six Project Gutenberg
 // texts, ~5.5M chars: EN 1342/3300/84, FR 17489/4650/5097, plus published
-// letter-frequency tables): the apostrophe is the dominant special (~0.1-0.5%
+// letter-frequency tables; modern Wikipedia articles in both languages measure
+// the same rates): the apostrophe is the dominant special (~0.1-0.5%
 // of typed-English characters, ~1% of typed French - elision); & < > are
 // essentially absent from prose (they live in names and titles); French
 // accented characters are ~2.5% of all characters (é alone ~2%). Typeset
 
@@ -17,8 +17,9 @@
 
 ### Performance
 
-- HTML-encoded output (echo and `htmlEncode()`) is 2-4x faster across a typical
-  page: values are scanned first and only encoded when something needs encoding.
+- HTML-encoded output (echo and `htmlEncode()`) is about 4x faster across a
+  typical page (up to 43x on Windows): values are scanned first and only
+  encoded when something needs encoding.
   Output stays byte-identical to `htmlspecialchars()`, verified against every
   possible string up to 4 bytes (4.3 billion inputs) on PHP 8.1-8.5. Benchmarks
   and details: [docs/performance.md](docs/performance.md)
 
@@ -47,7 +47,7 @@ Full guides and references ([browse on GitHub](https://github.com/interactivetoo
 - **Lookup**
     - [Method Reference](docs/method-reference.md) - every method, grouped by what it returns
     - [Troubleshooting](docs/troubleshooting.md) - common error messages and gotchas, with fixes
-    - [Performance](docs/performance.md) - how SmartString is 2-4x faster than calling `htmlspecialchars()` yourself
+    - [Performance](docs/performance.md) - how our automatic encoding is 4x faster than calling `htmlspecialchars()` yourself
     - [AI Reference](docs/ai-reference.md) - the complete API in one dense file, written for AI coding assistants
 
 ## You're Never Locked In
 
@@ -21,7 +21,7 @@ one before. The rest are standalone: open whichever matches your task.
 
 - [Method Reference](method-reference.md) - Every method in one place, grouped by what it returns.
 - [Troubleshooting](troubleshooting.md) - Common error messages and behavior gotchas, with fixes.
-- [Performance](performance.md) - How SmartString is 2-4x faster than calling `htmlspecialchars()` yourself.
+- [Performance](performance.md) - How our automatic encoding is 4x faster than calling `htmlspecialchars()` yourself.
 - [AI Reference](ai-reference.md) - The complete API in one dense file, written for AI coding assistants.
 
 ---
 
@@ -1,11 +1,20 @@
-# Performance: As Fast as `htmlspecialchars()`, Often 2-4x Faster
+# Performance: 4x Faster Than Calling `htmlspecialchars()` Yourself
 
-SmartString's auto-encoding produces byte-identical output to `htmlspecialchars()`
-and is usually faster: on a real-world mix of database fields, 2-4x faster. Most
+Our automatic encoding produces byte-identical output to `htmlspecialchars()`
+and is faster: about 4x on a real-world page. Most
 values don't need encoding, and proving that with a scan costs less than encoding
 them anyway. This page shows how that works, the
 measurements, and the tests that keep the shortcut honest.
 
+The exact multiplier depends on the platform: our scans cost about the same
+everywhere, so the win tracks how slowly each platform's `htmlspecialchars()`
+runs. On a realistic page mix:
+
+- **Linux x64** - the most common web platform: **4.1x**
+- **Linux ARM** - Graviton-class hosts: **2.9x**
+- **Windows** - its PHP builds encode slowest: **11x**, and long clean fields
+  reach 43x
+
 ## How It Works
 
 Every `<?= $row->title ?>` runs the cheapest check that can settle the value.
@@ -47,39 +56,51 @@ echo $title;                    // SmartString: scans first, encodes only if nee
 
 Measured on Linux x64, PHP 8.5 with opcache, on GitHub Actions' standard cloud
 servers; output was verified byte-identical before every timing run. Timings are identical
-whether you write `<?= $title ?>` or `echo $title;`.
-
-| Content                        | Size  | Example                                                                            | SmartString speed |
-|--------------------------------|-------|------------------------------------------------------------------------------------|-------------------|
-| Clean text - no `& < > " '`    | 16 B  | `Annual Report 2026`                                                               | 1.0x              |
-| Clean text - no `& < > " '`    | 1 KB  | a plain-text paragraph                                                             | 9.4x              |
-| Clean text - no `& < > " '`    | 10 KB | a long field, nothing to encode                                                    | 13x               |
-| Has `& < > " '`                | 16 B  | `O'Brien & Co Ltd`                                                                 | 0.5x              |
-| Has `& < > " '`                | 1 KB  | a paragraph with quotes                                                            | 3.6x              |
-| Has `& < > " '`                | 10 KB | a 1,500-word article                                                               | 4.4x              |
-| Accented text - no `& < > " '` | 16 B  | `Café Montréal QC`                                                                 | 0.4x              |
-| Accented text - no `& < > " '` | 1 KB  | a French paragraph                                                                 | 3.8x              |
-| Accented text - no `& < > " '` | 10 KB | a French article                                                                   | 4.8x              |
-| Realistic page mix             | mixed | 70% 16B (two of 45 are names with specials), 15% 200B, 10% 1KB, 5% 1KB with quotes | 4.1x              |
-| Page mix + one 10 KB article   | mixed | the mix above plus an article with quotes                                          | 4.3x              |
-
-2x = SmartString outputs the value in half the time `htmlspecialchars()` takes;
-1.0x = same speed; below 1x = slower.
-
-**The bottom line: a realistic page encodes 2-4x faster on Linux (2.9x on ARM,
-4.1x on x64) and 11x on Windows, whose PHP builds encode slowly (long clean
-fields reach 43x there).** The content mix matches measured corpus rates: the
-apostrophe is the only special that commonly appears in real text, `& < >`
-live in names rather than prose, and the French rows carry accents at true
-French density (~3% of characters). SmartString is slower in one case: short
-fields with quotes or accents, where the quick scan finds something and full
-encoding has to run anyway. That wastes about 0.2 microseconds per field -
-you'd need 5,000 of them on one page to lose a millisecond - and the wins
-everywhere else pay it back many times over; even a long article in the mix
-barely moves the page total. This table comes from the repo's Speed Page Table
-workflow
+whether you write `<?= $title ?>` or `echo $title;`. The test content matches
+the character mix of real English and French writing, measured on both classic
+and current text.
+
+| Content                        | Size  | Example                         | Speed vs `htmlspecialchars()` |
+|--------------------------------|-------|---------------------------------|-------------------------------|
+| Clean text - no `& < > " '`    | 16 B  | `Annual Report 2026`            | 1.0x                          |
+| Clean text - no `& < > " '`    | 1 KB  | a plain-text paragraph          | 9.4x                          |
+| Clean text - no `& < > " '`    | 10 KB | a long field, nothing to encode | 13x                           |
+| Has `& < > " '`                | 16 B  | `O'Brien & Co Ltd`              | 0.5x                          |
+| Has `& < > " '`                | 1 KB  | a paragraph with quotes         | 3.6x                          |
+| Has `& < > " '`                | 10 KB | a 1,500-word article            | 4.4x                          |
+| Accented text - no `& < > " '` | 16 B  | `Café Montréal QC`              | 0.4x                          |
+| Accented text - no `& < > " '` | 1 KB  | a French paragraph              | 3.8x                          |
+| Accented text - no `& < > " '` | 10 KB | a French article                | 4.8x                          |
+
+Real pages combine those rows. Here is a news-article page priced field by
+field (the ~200 B caption sits between the measured sizes, so its numbers are
+interpolated):
+
+| Field                        | Table row              | `htmlspecialchars()` | SmartString  | Speed vs `htmlspecialchars()` |
+|------------------------------|------------------------|----------------------|--------------|-------------------------------|
+| Headline - `Mayor Says 'No'` | Has `& < > " '`, 16 B  | 0.12 µs              | 0.26 µs      | 0.5x                          |
+| Author                       | Clean text, 16 B       | 0.11 µs              | 0.12 µs      | 1.0x                          |
+| Category                     | Clean text, 16 B       | 0.11 µs              | 0.12 µs      | 1.0x                          |
+| Date                         | Clean text, 16 B       | 0.11 µs              | 0.12 µs      | 1.0x                          |
+| Photo caption                | Clean text, ~200 B     | ~1 µs                | ~0.2 µs      | ~5x                           |
+| Article body with quotes     | Has `& < > " '`, 10 KB | 52.1 µs              | 11.9 µs      | 4.4x                          |
+| **Whole page**               |                        | **~53.6 µs**         | **~12.7 µs** | **4.2x**                      |
+
+The body settles the outcome: the five short fields together cost under two
+microseconds on either side, the quoted headline is the one field SmartString
+loses (by 0.14 µs), and the body alone saves 40 µs. A body pasted with smart
+quotes would contain none of `& < > " '`, land on the clean 10 KB row, and
+save even more. The measured page mix behind the bullets at the top prices
+out the same way.
+
+The one case where SmartString is slower: short fields with quotes or accents,
+where the scan finds something and full encoding has to run anyway. That costs
+about 0.2 microseconds per field - you'd need 5,000 of them on one page to
+lose a millisecond - and the wins everywhere else repay it many times over.
+
+These numbers come from the repo's Speed Page Table workflow
 ([this run](https://github.com/interactivetools-com/SmartString/actions/runs/29868668475));
-run it yourself any time for fresh numbers.
+you can run it yourself any time to confirm the numbers.
 
 ## How We Know It's Safe
 
@@ -114,6 +135,15 @@ Reading is cheaper than transforming, and most values only need to be read. Ever
 scan threshold comes from A/B benchmarks across PHP 8.1-8.5 on five OS and CPU
 combinations, recorded in the repo at `.github/scripts/speed-results.md`.
 
+Three notes for careful readers. The baseline helper runs the common faster
+flags while SmartString always produces the stronger full-flag output; full
+flags would slow the baseline about 50% on long strings, so the multipliers
+above understate the win. Timings cover output, not construction - values
+from SmartArray or ZenDB arrive already wrapped, and constructing one
+yourself adds about 60ns per field. And a full pass of the benchmark matrix
+with opcache's tracing JIT enabled produced the same verdicts as the JIT-off
+runs shown here.
+
 Most libraries and frameworks run the full encoder on every value, every time.
 Checking first and skipping the work when there is nothing to do is, as far as
 we know, unique to SmartString - the kind of care we try to put into everything