Merge remote-tracking branch 'origin/develop' into claude/fix-issue-3989-db7e45

Signed-off-by: Niels Lohmann <mail@nlohmann.me>

docs/mkdocs/docs/features/parsing/sax_interface.md

@@ -29,6 +29,8 @@ class sax_t ["json::sax_t"] {
 }
 ```
 
+<p class="nj-caption" markdown>The interface `json::sax_t`: one function per event, each returning `bool`; the functions marked with `*` are pure virtual.</p>
+
 ```cpp
 // called when null is parsed
 bool null();
@@ -63,6 +65,37 @@ bool parse_error(std::size_t position, const std::string& last_token, const json
 The return value of each function determines whether parsing should proceed. For `parse_error`, returning
 `#!cpp true` [recovers from the error](error_recovery.md).
 
+Object keys are passed to `key` decoded and validated: escape sequences are already resolved, so different spellings of
+the same name yield the same string. See [`key`](../../api/json_sax/key.md#notes) for the exact guarantees.
+
+## Stepping through the events
+
+The events for a small input, step by step, and what two different handlers do with them. Press *Play* or step with *Next*:
+
+<div class="nj-sax nj-fig" id="sax-event-stepper" data-nj-sax role="group" aria-label="SAX events for the input {&quot;a&quot;:[1,true],&quot;b&quot;:&quot;x&quot;}, and the state of a handler after each event">
+<div class="nj-sax__lane nj-sax__lane--text"><p class="nj-sax__h">input</p><p class="nj-sax__text"><code class="nj-sax__src">{"a":[1,true],"b":"x"}</code></p></div>
+<div class="nj-sax__lane nj-sax__lane--events"><p class="nj-sax__h">events, in the order the parser calls them</p><ol class="nj-sax__events">
+<li class="nj-sax-ev nj-sax-ev--os"><code>start_object(-1)</code></li>
+<li class="nj-sax-ev nj-sax-ev--k"><code>key("a")</code></li>
+<li class="nj-sax-ev nj-sax-ev--as"><code>start_array(-1)</code></li>
+<li class="nj-sax-ev nj-sax-ev--v"><code>number_unsigned(1)</code></li>
+<li class="nj-sax-ev nj-sax-ev--v"><code>boolean(true)</code></li>
+<li class="nj-sax-ev nj-sax-ev--ae"><code>end_array()</code></li>
+<li class="nj-sax-ev nj-sax-ev--k"><code>key("b")</code></li>
+<li class="nj-sax-ev nj-sax-ev--v"><code>string("x")</code></li>
+<li class="nj-sax-ev nj-sax-ev--oe"><code>end_object()</code></li>
+</ol></div>
+<div class="nj-sax__lane nj-sax__lane--state"><p class="nj-sax__h">handler: build a value tree, as <code>parse</code> does</p><div class="nj-sax__state"><pre class="nj-sax__tree"><code>{
+  "a": [
+    1,
+    true
+  ],
+  "b": "x"
+}</code></pre><p class="nj-sax__note">After <code>end_object()</code> the tree is complete and no container is open. The number of elements is passed as -1: the parser does not know it in advance.</p></div></div>
+</div>
+
+<p class="nj-caption" markdown>The three lanes show the input consumed so far, the events called so far, and the state of the selected handler (*build a tree* or *keep only /b*). Check *return false at this event* to stop the parse at the current event and see which events are no longer called.</p>
+
 To implement your own SAX handler, proceed as follows:
 
 1. Implement the SAX interface in a class. You can use class `nlohmann::json_sax<json>` as base class, but you can also use any class where the functions described above are implemented and public.
@@ -73,5 +106,9 @@ Note the `sax_parse` function only returns a `#!cpp bool` indicating whether the
 
 ## See also
 
-- [json_sax](../../api/json_sax/index.md) - documentation of the SAX interface
-- [sax_parse](../../api/basic_json/sax_parse.md) - SAX parser
+- [`json_sax`](../../api/json_sax/index.md) - documentation of the SAX interface
+- [`sax_parse`](../../api/basic_json/sax_parse.md) - SAX parser
+- [Parsing](index.md) - overview of the parsing functions
+- [Parsing and Exceptions](parse_exceptions.md) - handling parse errors and locating them in the input
+- [`parse`](../../api/basic_json/parse.md) - deserialize from a compatible input
+- [Binary Formats](../binary_formats/index.md) - CBOR, MessagePack, BSON, and other formats