Alter URL encoding

docs/tree-state-serialization.md

@@ -1,5 +1,29 @@
 # Tree UI State Serialization Design
 
+## Implementation amendment: adaptive fields
+
+The implemented version 1 format retains the manifest, URL parameters, stable
+slots, and default-state behavior described below, but adaptively encodes each
+`c` and `x` field. This amendment supersedes the document's later recommendation
+that fields always use dense bitsets.
+
+Each decoded field still represents one Boolean per manifest slot. Before
+Base64URL encoding, its first byte selects the shortest representation:
+
+* `0`: dense, least-significant-bit-first bitset
+* `1`: delta-encoded variable-length indexes of enabled slots
+* `2`: manifest coverage followed by delta-encoded indexes of disabled slots
+
+Mode 2's coverage value preserves forward compatibility: slots appended beyond
+the encoded coverage remain false rather than inheriting the enabled state.
+Empty all-false fields remain omitted. The encoder compares all three valid
+representations independently for checked and expanded state and emits the
+shortest. Sparse indexes are ascending, delta encoded, and stored as unsigned
+base-128 variable-length integers.
+
+This adaptive layout was adopted before deployment, so it uses serialization
+version `1`; no dense-only version 1 URLs need backward compatibility.
+
 ## 1. Purpose
 
 Implement a compact, shareable, client-side serialization format for storing tree widget state in a URL.