Add tree state functionality

README.md

@@ -2,7 +2,8 @@
 
 A dependency-free, instance-based checkbox tree for browser ES modules. It
 supports cascading selection, indeterminate parent states, expandable branches,
-multiple independent instances, and optional local-storage persistence.
+multiple independent instances, optional local-storage persistence, and compact
+shareable URL state backed by an append-only node manifest.
 
 ## Install
 
@@ -65,6 +66,9 @@ flags.
 - `setSelectedIds(ids, { notify })` replaces the selection.
 - `restoreState()` restores selection and expansion state.
 - `destroy()` removes listeners, markup, and the root CSS class.
+- `serializeStateToFragment(manifest)` returns `#v=1&c=...&x=...` state.
+- `restoreStateFromLocation(manifest, location)` safely applies URL state.
+- `validateManifest(manifest)` reports unregistered and missing paths.
 
 Options:
 
@@ -72,6 +76,32 @@ Options:
 - `initiallySelected` defaults to `false`.
 - `storageKey` defaults to `null`, which disables persistence.
 - `onSelectionChange` receives `{ selectedIds, selectedNodes }`.
+- `manifest` optionally supplies a parsed manifest and automatically restores
+  state from `window.location.hash` after `setData()`.
+
+## Shareable URL state
+
+Create a JSON manifest whose array positions are permanent slots. Canonical node
+paths join ancestor IDs with `>`:
+
+```json
+{ "schema": 1, "nodes": ["fruit", "fruit>apple", "fruit>pear", null] }
+```
+
+Import `loadManifest`, pass its result as the `manifest` option, and call
+`tree.serializeStateToFragment()` when creating a share link. Existing entries
+must never be reordered. Append new paths, replace removed paths with `null`, and
+edit a path in place for a logical rename or move. Node IDs therefore cannot
+contain `>`.
+
+The fragment contains independently trimmed checked (`c`) and expanded (`x`)
+bitsets. Bits are least-significant-bit first within each byte. Missing bits
+default to unchecked and collapsed; malformed or unsupported state is ignored.
+The helpers `encodeTreeState`, `decodeTreeState`, `applyTreeState`, and
+`restoreStateFromLocation` are also exported for custom integrations.
+Use `validateManifestEvolution(previous, next)` in a build check to reject
+removed slots and tombstone reuse; path changes are reported for deliberate
+rename/move review.
 
 Styling is namespaced under `.checkbox-tree`. Override the custom properties
 `--checkbox-tree-indent`, `--checkbox-tree-toggle-size`, and