[nstarman]

JAX 0.11.2 (2026-09-17) registers the built-in frozendict (PEP 814) as a PyTree node, which makes the README's "Relationship to frozendict" section out of date: it says JAX treats the built-in as an opaque leaf and that this package can retire once JAX registers it upstream.

This PR:

• Recommends the built-in frozendict on Python 3.15+ with jax>=0.11.2, and keeps ImmutableMap as the option for Python < 3.15.
• Adds a leaf-order caveat. JAX flattens frozendict the way it flattens dict: leaves come out in sorted-key order, unflattening rebuilds the map in sorted order, and keys that can't be sorted raise an error. ImmutableMap flattens in insertion order, so for ImmutableMap(b=1, a=2) the leaves are [1, 2], while for frozendict(b=1, a=2) they are [2, 1].
• Updates the intro to point to that section.

Verified on CPython 3.15.0 with jax 0.11.2 (treedef PyTreeDef(frozendict({'a': *, 'b': *})), round-tripping through jit returns a frozendict). On 3.13, pytest passes (113 tests, including the README blocks via Sybil) and the pre-commit hooks pass.

A follow-up PR will make ImmutableMap flatten in sorted-key order as well, so that switching types doesn't change leaf order.

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
⚠️ Please upload report for BASE (main@ae3b488). Learn more about missing BASE report.

Additional details and impacted files

@@           Coverage Diff            @@
##             main       #79   +/-   ##
========================================
  Coverage        ?   100.00%           
========================================
  Files           ?         3           
  Lines           ?        75           
  Branches        ?         0           
========================================
  Hits            ?        75           
  Misses          ?         0           
  Partials        ?         0           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.