Documentation site and editorial pass

[Astn]

Documentation site and editorial pass

Two things, both documentation only; no code under Json-Rpc/ or the packages changes.

Site

site/ builds https://astn.github.io/JSON-RPC.NET/ from the Markdown files already in the repository, so GitHub, NuGet and the site never drift apart. Typst 0.14 renders each page through the cmarker package inside site/page.typ (the page shell: top bar, grouped page list, article, table of contents, footer); site/build.py adds GitHub-compatible heading ids, a per-page table of contents, link resolution (pages become site links, other files link to GitHub or are copied under their repository path), Pygments highlighting in light and dark, and copies the benchmark charts and the explorer. .github/workflows/pages.yml runs the same build on every push to master that touches a documentation file and fails the deploy if a page does not compile or a chart is stale. site/README.md says how to build locally and add a page.

The landing page at https://astn.github.io/ (repository Astn/astn.github.io) links here.

Editorial pass

Two independent reviews of the README, docs/serializers.md, the three package READMEs, the WebAssembly sample page and the micro-benchmark page, each with mirrored lenses (flow and human against structure and enterprise), a second round where each answered the other, and one merged list applied here. Every factual claim in the reviews was checked against the source before the docs were changed, and the Getting started sample was compiled and run on net8.0 and net10.0.

Factual corrections worth knowing about:

• Conversion failures are -32602 with structured data, not -32603 (both serializer READMEs said the latter).
• NaN and the infinities are written as quoted strings, not bare symbols (System.Text.Json README).
• Config.SetErrorHandler(handler) and the other session-less setters set the default session's handler only; the Configuration section now has a scope table.
• Process(json, null) does not compile (CS0121, ambiguous with the JsonRpcStateAsync overload) and ProcessAsync(json, null) binds json as the session id and throws ArgumentNullException; the upgrade notes now say so and show Process(json) / Process(json, context: null).
• The StreamJsonRpc comparison ran JSON-RPC.Net's built-in serializer, not "the same JSON library underneath".
• Exception disclosure: the CLR type name and message are sent by default; "redacted" was overstating it.
• AddJsonRpcService<T>() is a singleton resolved once at startup; scoped dependencies and per-request services are explained, and the raw-connection samples now listen on loopback.
• An unknown session id creates a session that persists; SessionSelector must map to a fixed set of ids.
• AustinHarris.JsonRpc.AspNet targets .NET Framework 4.0 and cannot be combined with the 2.0 core; it is documented as 1.x only.
• A bare byte[] is ambiguous between the memory and span overloads on C# 12; samples use AsSpan().
• The WebAssembly page's "bytes beat strings" holds under the interpreter only, and it now derives its ratios from the README's 217 ns figure.

Structure: the README is ordered around the reader's path (Getting started keeps the class example only; Defining methods, Hosting, Errors, Asynchronous methods and cancellation, Sessions and context, Configuration, a new Security section, Benchmarks with a summary table first, Upgrading grouped by impact, Versioning and support, Building, License). render.py --check passes; no published benchmark figure changed.

Open decisions for the maintainer

These came out of the reviews and are not changed here:

1. Should an unhandled exception's Message be sent to clients by default, or only with IncludeExceptionDetails?
2. Should the request path stop creating sessions for unknown ids (answer -32601 without a registry entry)?
3. Should the session-less handler setters become truly process-wide, and should SetBeforeProcessHandler(sessionId, …) get a SetPreProcessHandler alias and a per-session post-process setter on Config?
4. A JsonRpcService subclass bound through DI to another session is still exposed on the default session (its base constructor binds it there). Document only, or add a non-binding base constructor?
5. Versioning commitments (SemVer, 1.x maintenance), SECURITY.md with a private reporting route, CHANGELOG.md: the docs state only what the repository establishes today.
6. The core package's NuGet description says "no dependencies"; it depends on NonBlocking. "No JSON library dependency" would be accurate.