Revised checkbox-tree functions and related

src/main.js

@@ -139,6 +139,7 @@ async function initializeVisibilityTree() {
     initiallySelected: true,
     storageKey: "a-plot-of-plants:visibility:v1",
     manifest,
+    stateEncoding: "tiered",
     onSelectionChange: ({ selectedNodes }) => {
       selectedFeatureIndexes = getSelectedFeatureIndexes(selectedNodes);
       renderYardForDate(selectedTimelineDate);

vendor/checkbox-tree/README.md

@@ -43,8 +43,8 @@ tree.setData([
 ]);
 ```
 
-For applications without a bundler, serve or copy the two files in `src/` and
+For applications without a bundler, serve or copy the `src/` directory and use
-use relative URLs:
+relative URLs. The main module imports its state-codec modules alongside it:
 
 ```html
 <link rel="stylesheet" href="./checkbox-tree.css">
@@ -78,6 +78,9 @@ Options:
 - `onSelectionChange` receives `{ selectedIds, selectedNodes }`.
 - `manifest` optionally supplies a parsed manifest and automatically restores
   state from `window.location.hash` after `setData()`.
+- `stateEncoding` selects `"adaptive"` (the default), `"dense"`, or `"tiered"`.
+  The website's configured value is the URL-format contract and is not embedded
+  in the fragment.
 
 ## Shareable URL state
 
@@ -105,6 +108,15 @@ Use `validateManifestEvolution(previous, next)` in a build check to reject
 removed slots and tombstone reuse; path changes are reported for deliberate
 rename/move review.
 
+With `stateEncoding: "tiered"`, `c1` stores root checked state and each deeper
+`cN` field stores nodes whose checked state differs from their parent. Expansion
+does not inherit: every `xN` stores the actual expanded branches at that depth,
+with collapsed as the baseline. Each tier field uses the adaptive codec. The
+`n` field records manifest coverage so nodes appended later still default to
+false. A non-selectable parent supplies a false checked baseline. With
+`stateEncoding: "dense"`, `c` and `x` contain trimmed
+least-significant-bit-first bitsets.
+
 Styling is namespaced under `.checkbox-tree`. Override the custom properties
 `--checkbox-tree-indent`, `--checkbox-tree-toggle-size`, and
 `--checkbox-tree-hover-color` in the consuming application.

vendor/checkbox-tree/checkbox-tree.js

@@ -1,311 +1,44 @@
+// Dependency-free checkbox tree widget. State serialization lives in focused sibling modules.
+import {
+    PATH_DELIMITER,
+    assertStateEncoding
+} from './state-codec.js';
+import {
+    restoreStateFromLocation,
+    serializeStateToFragment,
+    validateManifest
+} from './tree-state.js';
+
+export {
+    PATH_DELIMITER,
+    SERIALIZATION_VERSION,
+    base64UrlToBytes,
+    bytesToBase64Url,
+    decodeAdaptiveBitset,
+    encodeAdaptiveBitset,
+    getBit,
+    loadManifest,
+    setBit
+} from './state-codec.js';
+export {
+    applyTreeState,
+    decodeTreeState,
+    encodeTreeState,
+    restoreStateFromLocation,
+    serializeStateToFragment,
+    validateManifest,
+    validateManifestEvolution
+} from './tree-state.js';
+
 const DEFAULT_OPTIONS = {
     initiallyCollapsed: true,
     initiallySelected: false,
     storageKey: null,
     onSelectionChange: null,
-    manifest: null
+    manifest: null,
+    stateEncoding: 'adaptive'
 };
 
-const SERIALIZATION_VERSION = 1;
-const PATH_DELIMITER = '>';
-
-export function loadManifest(source) {
-    let records;
-    let schema = 1;
-
-    if (typeof source === 'string') {
-        records = source.split(/\r?\n/)
-            .map(line => line.trim())
-            .filter(line => line && !line.startsWith('#'))
-            .map(line => line === '!deleted' ? null : line);
-    } else if (source && typeof source === 'object' && Array.isArray(source.nodes)) {
-        schema = source.schema;
-        records = source.nodes;
-    } else if (source && Array.isArray(source.slots)) {
-        return normalizeManifest(source.schema, source.slots.map(slot => slot?.deleted ? null : slot?.path));
-    } else {
-        throw new TypeError('CheckboxTree manifest must be text or an object with a nodes array.');
-    }
-
-    return normalizeManifest(schema, records);
-}
-
-function normalizeManifest(schema, records) {
-    if (schema !== 1) {
-        throw new Error(`Unsupported CheckboxTree manifest schema: ${schema}`);
-    }
-
-    const pathToSlot = new Map();
-    const slots = records.map((record, index) => {
-        if (record === null || record === '!deleted') {
-            return { path: null, deleted: true };
-        }
-        if (typeof record !== 'string' || !record || record.trim() !== record) {
-            throw new TypeError(`Invalid CheckboxTree manifest entry at slot ${index}.`);
-        }
-        if (pathToSlot.has(record)) {
-            throw new Error(`Duplicate CheckboxTree manifest path: ${record}`);
-        }
-        pathToSlot.set(record, index);
-        return { path: record, deleted: false };
-    });
-
-    return { schema: 1, slots, pathToSlot };
-}
-
-export function setBit(bytes, bitIndex, value) {
-    const byteIndex = Math.floor(bitIndex / 8);
-    const mask = 1 << (bitIndex % 8);
-    if (value) bytes[byteIndex] |= mask;
-    else bytes[byteIndex] &= ~mask;
-}
-
-export function getBit(bytes, bitIndex) {
-    const byteIndex = Math.floor(bitIndex / 8);
-    return byteIndex < bytes.length && (bytes[byteIndex] & (1 << (bitIndex % 8))) !== 0;
-}
-
-export function bytesToBase64Url(bytes) {
-    let binary = '';
-    for (const byte of bytes) binary += String.fromCharCode(byte);
-    return btoa(binary).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/g, '');
-}
-
-export function base64UrlToBytes(value, maximumLength = Infinity) {
-    if (typeof value !== 'string' || !/^[A-Za-z0-9_-]*$/.test(value) || value.length % 4 === 1) {
-        throw new Error('Invalid Base64URL value.');
-    }
-    if (Number.isFinite(maximumLength) && value.length > Math.ceil(maximumLength * 4 / 3) + 2) {
-        throw new Error('Encoded tree state exceeds the manifest size.');
-    }
-    const base64 = value.replace(/-/g, '+').replace(/_/g, '/');
-    const binary = atob(base64 + '='.repeat((4 - base64.length % 4) % 4));
-    if (binary.length > maximumLength) throw new Error('Encoded tree state exceeds the manifest size.');
-    return Uint8Array.from(binary, character => character.charCodeAt(0));
-}
-
-function trimTrailingZeroBytes(bytes) {
-    let end = bytes.length;
-    while (end && bytes[end - 1] === 0) end--;
-    return bytes.slice(0, end);
-}
-
-function encodeUnsignedVarint(value) {
-    const bytes = [];
-    do {
-        let byte = value & 0x7f;
-        value = Math.floor(value / 128);
-        if (value) byte |= 0x80;
-        bytes.push(byte);
-    } while (value);
-    return bytes;
-}
-
-function decodeUnsignedVarint(bytes, offset) {
-    let value = 0;
-    let multiplier = 1;
-    for (let index = offset; index < bytes.length && index < offset + 8; index++) {
-        const byte = bytes[index];
-        value += (byte & 0x7f) * multiplier;
-        if ((byte & 0x80) === 0) return { value, offset: index + 1 };
-        multiplier *= 128;
-        if (!Number.isSafeInteger(value) || !Number.isSafeInteger(multiplier)) break;
-    }
-    throw new Error('Invalid adaptive tree-state integer.');
-}
-
-function encodeSparseIndexes(indexes) {
-    const bytes = [];
-    let previous = -1;
-    for (const index of indexes) {
-        bytes.push(...encodeUnsignedVarint(index - previous - 1));
-        previous = index;
-    }
-    return bytes;
-}
-
-function decodeSparseIndexes(bytes, offset, limit) {
-    const indexes = new Set();
-    let previous = -1;
-    while (offset < bytes.length) {
-        const decoded = decodeUnsignedVarint(bytes, offset);
-        const index = previous + decoded.value + 1;
-        if (index >= limit) throw new Error('Sparse tree state contains an out-of-range slot.');
-        indexes.add(index);
-        previous = index;
-        offset = decoded.offset;
-    }
-    return indexes;
-}
-
-export function encodeAdaptiveBitset(values, slotCount) {
-    const enabled = [];
-    const disabled = [];
-    const denseBytes = new Uint8Array(Math.ceil(slotCount / 8));
-    for (const [slot, value] of values) {
-        (value ? enabled : disabled).push(slot);
-        setBit(denseBytes, slot, value);
-    }
-    enabled.sort((left, right) => left - right);
-    disabled.sort((left, right) => left - right);
-    if (enabled.length === 0) return new Uint8Array();
-
-    const candidates = [
-        Uint8Array.from([0, ...trimTrailingZeroBytes(denseBytes)]),
-        Uint8Array.from([1, ...encodeSparseIndexes(enabled)]),
-        Uint8Array.from([2, ...encodeUnsignedVarint(slotCount), ...encodeSparseIndexes(disabled)])
-    ];
-    return candidates.reduce((shortest, candidate) =>
-        candidate.length < shortest.length ? candidate : shortest
-    );
-}
-
-export function decodeAdaptiveBitset(bytes, slotCount) {
-    if (bytes.length === 0) return () => false;
-    const mode = bytes[0];
-    if (mode === 0) {
-        const dense = bytes.slice(1);
-        if (dense.length > Math.ceil(slotCount / 8)) {
-            throw new Error('Dense tree state exceeds the manifest size.');
-        }
-        return slot => getBit(dense, slot);
-    }
-    if (mode === 1) {
-        const enabled = decodeSparseIndexes(bytes, 1, slotCount);
-        return slot => enabled.has(slot);
-    }
-    if (mode === 2) {
-        const coverage = decodeUnsignedVarint(bytes, 1);
-        if (coverage.value > slotCount) throw new Error('Tree-state coverage exceeds the manifest size.');
-        const disabled = decodeSparseIndexes(bytes, coverage.offset, coverage.value);
-        return slot => slot < coverage.value && !disabled.has(slot);
-    }
-    throw new Error('Unknown adaptive tree-state mode.');
-}
-
-function asManifest(manifest) {
-    return manifest?.pathToSlot instanceof Map ? manifest : loadManifest(manifest);
-}
-
-export function validateManifest(manifest, tree) {
-    const normalized = asManifest(manifest);
-    const treePaths = new Set(tree.nodesByPath.keys());
-    return {
-        valid: Array.from(treePaths).every(path => normalized.pathToSlot.has(path)),
-        unregisteredPaths: Array.from(treePaths).filter(path => !normalized.pathToSlot.has(path)),
-        missingPaths: normalized.slots
-            .filter(slot => !slot.deleted && !treePaths.has(slot.path))
-            .map(slot => slot.path)
-    };
-}
-
-export function validateManifestEvolution(previous, next) {
-    const oldManifest = asManifest(previous);
-    const newManifest = asManifest(next);
-    const errors = [];
-
-    if (newManifest.slots.length < oldManifest.slots.length) {
-        errors.push('Manifest slots cannot be removed; use tombstones.');
-    }
-    oldManifest.slots.forEach((oldSlot, index) => {
-        const newSlot = newManifest.slots[index];
-        if (!newSlot) return;
-        if (oldSlot.deleted && !newSlot.deleted) {
-            errors.push(`Tombstoned slot ${index} cannot be reused.`);
-        }
-        if (!oldSlot.deleted && !newSlot.deleted && oldSlot.path !== newSlot.path) {
-            errors.push(`Slot ${index} changed path; confirm this is a logical rename or move.`);
-        }
-    });
-
-    return { valid: errors.length === 0, errors };
-}
-
-export function encodeTreeState(tree, manifest) {
-    const normalized = asManifest(manifest);
-    const checkedValues = new Map();
-    const expandedValues = new Map();
-
-    for (const [path, node] of tree.nodesByPath) {
-        const slot = normalized.pathToSlot.get(path);
-        if (slot === undefined) continue;
-        const item = tree.itemForNode(node.id);
-        const checkbox = item && tree.directCheckbox(item);
-        const toggle = item?.querySelector(':scope > .checkbox-tree__row > .checkbox-tree__toggle');
-        checkedValues.set(slot, Boolean(checkbox?.checked));
-        expandedValues.set(slot, toggle?.getAttribute('aria-expanded') === 'true');
-    }
-
-    const checkedValue = bytesToBase64Url(encodeAdaptiveBitset(checkedValues, normalized.slots.length));
-    const expandedValue = bytesToBase64Url(encodeAdaptiveBitset(expandedValues, normalized.slots.length));
-    return { version: SERIALIZATION_VERSION, checked: checkedValue || null, expanded: expandedValue || null };
-}
-
-export function decodeTreeState(fragment, manifest) {
-    const normalized = asManifest(manifest);
-    const value = fragment.startsWith('#') ? fragment.slice(1) : fragment;
-    const params = new URLSearchParams(value);
-    if (params.get('v') !== String(SERIALIZATION_VERSION)) {
-        return { applied: false, version: params.get('v'), warnings: ['Missing or unsupported serialization version.'] };
-    }
-    const maximumLength = Math.max(
-        Math.ceil(normalized.slots.length / 8) + 1,
-        normalized.slots.length * 2 + 10
-    );
-    try {
-        const checked = base64UrlToBytes(params.get('c') ?? '', maximumLength);
-        const expanded = base64UrlToBytes(params.get('x') ?? '', maximumLength);
-        decodeAdaptiveBitset(checked, normalized.slots.length);
-        decodeAdaptiveBitset(expanded, normalized.slots.length);
-        return {
-            applied: true,
-            version: SERIALIZATION_VERSION,
-            checked,
-            expanded,
-            warnings: []
-        };
-    } catch (error) {
-        return { applied: false, version: SERIALIZATION_VERSION, warnings: [error.message] };
-    }
-}
-
-export function applyTreeState(tree, manifest, state) {
-    if (!state?.applied) return false;
-    const normalized = asManifest(manifest);
-    let isChecked;
-    let isExpanded;
-    try {
-        isChecked = decodeAdaptiveBitset(state.checked, normalized.slots.length);
-        isExpanded = decodeAdaptiveBitset(state.expanded, normalized.slots.length);
-    } catch {
-        return false;
-    }
-    for (const [path, node] of tree.nodesByPath) {
-        const slot = normalized.pathToSlot.get(path);
-        if (slot === undefined) continue;
-        const item = tree.itemForNode(node.id);
-        const checkbox = item && tree.directCheckbox(item);
-        if (checkbox && !checkbox.disabled) checkbox.checked = isChecked(slot);
-        tree.setExpanded(item, isExpanded(slot));
-    }
-    tree.updateAllParentCheckboxes();
-    return true;
-}
-
-export function serializeStateToFragment(tree, manifest) {
-    const state = encodeTreeState(tree, manifest);
-    const params = new URLSearchParams({ v: String(state.version) });
-    if (state.checked) params.set('c', state.checked);
-    if (state.expanded) params.set('x', state.expanded);
-    return `#${params}`;
-}
-
-export function restoreStateFromLocation(tree, manifest, location = window.location) {
-    const state = decodeTreeState(location.hash ?? '', manifest);
-    if (state.applied) applyTreeState(tree, manifest, state);
-    return state;
-}
-
 export class CheckboxTree {
     constructor(container, options = {}) {
         if (!(container instanceof Element)) {
@@ -314,8 +47,10 @@ export class CheckboxTree {
 
         this.container = container;
         this.options = { ...DEFAULT_OPTIONS, ...options };
+        assertStateEncoding(this.options.stateEncoding);
         this.nodesById = new Map();
         this.nodesByPath = new Map();
+        this.itemsById = new Map();
         this.rootNodes = [];
         this.handleChange = this.handleChange.bind(this);
         this.handleClick = this.handleClick.bind(this);
@@ -332,6 +67,7 @@ export class CheckboxTree {
 
         this.nodesById.clear();
         this.nodesByPath.clear();
+        this.itemsById.clear();
         this.rootNodes = nodes;
         this.indexNodes(nodes);
         this.render();
@@ -371,6 +107,7 @@ export class CheckboxTree {
         this.container.replaceChildren();
         this.nodesById.clear();
         this.nodesByPath.clear();
+        this.itemsById.clear();
     }
 
     indexNodes(nodes, parentPath = '') {
@@ -408,6 +145,7 @@ export class CheckboxTree {
         const item = document.createElement('div');
         item.className = 'checkbox-tree__item';
         item.dataset.nodeId = node.id;
+        this.itemsById.set(node.id, item);
 
         const row = document.createElement('div');
         row.className = 'checkbox-tree__row';
@@ -524,8 +262,7 @@ export class CheckboxTree {
     }
 
     itemForNode(id) {
-        return Array.from(this.container.querySelectorAll('.checkbox-tree__item'))
+        return this.itemsById.get(id) ?? null;
-            .find(item => item.dataset.nodeId === id) ?? null;
     }
 
     updateAncestorCheckboxes(item) {

vendor/checkbox-tree/state-codec.js

@@ -0,0 +1,206 @@
+// Manifest parsing and binary codecs. This module has no DOM dependencies.
+export const SERIALIZATION_VERSION = 1;
+export const PATH_DELIMITER = '>';
+const STATE_ENCODINGS = new Set(['adaptive', 'dense', 'tiered']);
+
+export function loadManifest(source) {
+    let records;
+    let schema = 1;
+
+    if (typeof source === 'string') {
+        records = source.split(/\r?\n/)
+            .map(line => line.trim())
+            .filter(line => line && !line.startsWith('#'))
+            .map(line => line === '!deleted' ? null : line);
+    } else if (source && typeof source === 'object' && Array.isArray(source.nodes)) {
+        schema = source.schema;
+        records = source.nodes;
+    } else if (source && Array.isArray(source.slots)) {
+        return normalizeManifest(source.schema, source.slots.map(slot => slot?.deleted ? null : slot?.path));
+    } else {
+        throw new TypeError('CheckboxTree manifest must be text or an object with a nodes array.');
+    }
+
+    return normalizeManifest(schema, records);
+}
+
+function normalizeManifest(schema, records) {
+    if (schema !== 1) {
+        throw new Error(`Unsupported CheckboxTree manifest schema: ${schema}`);
+    }
+
+    const pathToSlot = new Map();
+    const slots = records.map((record, index) => {
+        if (record === null || record === '!deleted') {
+            return { path: null, deleted: true };
+        }
+        if (typeof record !== 'string' || !record || record.trim() !== record) {
+            throw new TypeError(`Invalid CheckboxTree manifest entry at slot ${index}.`);
+        }
+        if (pathToSlot.has(record)) {
+            throw new Error(`Duplicate CheckboxTree manifest path: ${record}`);
+        }
+        pathToSlot.set(record, index);
+        return { path: record, deleted: false };
+    });
+
+    return { schema: 1, slots, pathToSlot };
+}
+
+export function setBit(bytes, bitIndex, value) {
+    const byteIndex = Math.floor(bitIndex / 8);
+    const mask = 1 << (bitIndex % 8);
+    if (value) bytes[byteIndex] |= mask;
+    else bytes[byteIndex] &= ~mask;
+}
+
+export function getBit(bytes, bitIndex) {
+    const byteIndex = Math.floor(bitIndex / 8);
+    return byteIndex < bytes.length && (bytes[byteIndex] & (1 << (bitIndex % 8))) !== 0;
+}
+
+export function bytesToBase64Url(bytes) {
+    let binary = '';
+    for (const byte of bytes) binary += String.fromCharCode(byte);
+    return btoa(binary).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/g, '');
+}
+
+export function base64UrlToBytes(value, maximumLength = Infinity) {
+    if (typeof value !== 'string' || !/^[A-Za-z0-9_-]*$/.test(value) || value.length % 4 === 1) {
+        throw new Error('Invalid Base64URL value.');
+    }
+    if (Number.isFinite(maximumLength) && value.length > Math.ceil(maximumLength * 4 / 3) + 2) {
+        throw new Error('Encoded tree state exceeds the manifest size.');
+    }
+    const base64 = value.replace(/-/g, '+').replace(/_/g, '/');
+    const binary = atob(base64 + '='.repeat((4 - base64.length % 4) % 4));
+    if (binary.length > maximumLength) throw new Error('Encoded tree state exceeds the manifest size.');
+    return Uint8Array.from(binary, character => character.charCodeAt(0));
+}
+
+function trimTrailingZeroBytes(bytes) {
+    let end = bytes.length;
+    while (end && bytes[end - 1] === 0) end--;
+    return bytes.slice(0, end);
+}
+
+function encodeUnsignedVarint(value) {
+    const bytes = [];
+    do {
+        let byte = value & 0x7f;
+        value = Math.floor(value / 128);
+        if (value) byte |= 0x80;
+        bytes.push(byte);
+    } while (value);
+    return bytes;
+}
+
+function decodeUnsignedVarint(bytes, offset) {
+    let value = 0;
+    let multiplier = 1;
+    for (let index = offset; index < bytes.length && index < offset + 8; index++) {
+        const byte = bytes[index];
+        value += (byte & 0x7f) * multiplier;
+        if ((byte & 0x80) === 0) return { value, offset: index + 1 };
+        multiplier *= 128;
+        if (!Number.isSafeInteger(value) || !Number.isSafeInteger(multiplier)) break;
+    }
+    throw new Error('Invalid adaptive tree-state integer.');
+}
+
+function encodeSparseIndexes(indexes) {
+    const bytes = [];
+    let previous = -1;
+    for (const index of indexes) {
+        bytes.push(...encodeUnsignedVarint(index - previous - 1));
+        previous = index;
+    }
+    return bytes;
+}
+
+function decodeSparseIndexes(bytes, offset, limit) {
+    const indexes = new Set();
+    let previous = -1;
+    while (offset < bytes.length) {
+        const decoded = decodeUnsignedVarint(bytes, offset);
+        const index = previous + decoded.value + 1;
+        if (index >= limit) throw new Error('Sparse tree state contains an out-of-range slot.');
+        indexes.add(index);
+        previous = index;
+        offset = decoded.offset;
+    }
+    return indexes;
+}
+
+export function encodeAdaptiveBitset(values, slotCount) {
+    const enabled = [];
+    const disabled = [];
+    const denseBytes = new Uint8Array(Math.ceil(slotCount / 8));
+    for (const [slot, value] of values) {
+        (value ? enabled : disabled).push(slot);
+        setBit(denseBytes, slot, value);
+    }
+    enabled.sort((left, right) => left - right);
+    disabled.sort((left, right) => left - right);
+    if (enabled.length === 0) return new Uint8Array();
+
+    const candidates = [
+        Uint8Array.from([0, ...trimTrailingZeroBytes(denseBytes)]),
+        Uint8Array.from([1, ...encodeSparseIndexes(enabled)]),
+        Uint8Array.from([2, ...encodeUnsignedVarint(slotCount), ...encodeSparseIndexes(disabled)])
+    ];
+    return candidates.reduce((shortest, candidate) =>
+        candidate.length < shortest.length ? candidate : shortest
+    );
+}
+
+export function decodeAdaptiveBitset(bytes, slotCount) {
+    if (bytes.length === 0) return () => false;
+    const mode = bytes[0];
+    if (mode === 0) {
+        const dense = bytes.slice(1);
+        if (dense.length > Math.ceil(slotCount / 8)) {
+            throw new Error('Dense tree state exceeds the manifest size.');
+        }
+        return slot => getBit(dense, slot);
+    }
+    if (mode === 1) {
+        const enabled = decodeSparseIndexes(bytes, 1, slotCount);
+        return slot => enabled.has(slot);
+    }
+    if (mode === 2) {
+        const coverage = decodeUnsignedVarint(bytes, 1);
+        if (coverage.value > slotCount) throw new Error('Tree-state coverage exceeds the manifest size.');
+        const disabled = decodeSparseIndexes(bytes, coverage.offset, coverage.value);
+        return slot => slot < coverage.value && !disabled.has(slot);
+    }
+    throw new Error('Unknown adaptive tree-state mode.');
+}
+
+
+export function encodeDenseBitset(values, slotCount) {
+    const bytes = new Uint8Array(Math.ceil(slotCount / 8));
+    for (const [slot, value] of values) setBit(bytes, slot, value);
+    return trimTrailingZeroBytes(bytes);
+}
+
+export function decodeDenseBitset(bytes, slotCount) {
+    if (bytes.length > Math.ceil(slotCount / 8)) {
+        throw new Error('Dense tree state exceeds the manifest size.');
+    }
+    return slot => getBit(bytes, slot);
+}
+
+export function maximumEncodedLength(slotCount) {
+    return Math.max(Math.ceil(slotCount / 8) + 1, slotCount * 2 + 10);
+}
+
+export function assertStateEncoding(encoding) {
+    if (!STATE_ENCODINGS.has(encoding)) {
+        throw new Error(`Unsupported CheckboxTree state encoding: ${encoding}`);
+    }
+}
+
+export function asManifestSource(manifest) {
+    return manifest?.pathToSlot instanceof Map ? manifest : loadManifest(manifest);
+}

vendor/checkbox-tree/tree-state.js

@@ -0,0 +1,310 @@
+// Adapts pure state codecs to CheckboxTree's rendered node model and URL format.
+import {
+    PATH_DELIMITER,
+    SERIALIZATION_VERSION,
+    asManifestSource as asManifest,
+    assertStateEncoding,
+    base64UrlToBytes,
+    bytesToBase64Url,
+    decodeAdaptiveBitset,
+    decodeDenseBitset,
+    encodeAdaptiveBitset,
+    encodeDenseBitset,
+    maximumEncodedLength
+} from './state-codec.js';
+
+export function validateManifest(manifest, tree) {
+    const normalized = asManifest(manifest);
+    const treePaths = new Set(tree.nodesByPath.keys());
+    return {
+        valid: Array.from(treePaths).every(path => normalized.pathToSlot.has(path)),
+        unregisteredPaths: Array.from(treePaths).filter(path => !normalized.pathToSlot.has(path)),
+        missingPaths: normalized.slots
+            .filter(slot => !slot.deleted && !treePaths.has(slot.path))
+            .map(slot => slot.path)
+    };
+}
+
+export function validateManifestEvolution(previous, next) {
+    const oldManifest = asManifest(previous);
+    const newManifest = asManifest(next);
+    const errors = [];
+
+    if (newManifest.slots.length < oldManifest.slots.length) {
+        errors.push('Manifest slots cannot be removed; use tombstones.');
+    }
+    oldManifest.slots.forEach((oldSlot, index) => {
+        const newSlot = newManifest.slots[index];
+        if (!newSlot) return;
+        if (oldSlot.deleted && !newSlot.deleted) {
+            errors.push(`Tombstoned slot ${index} cannot be reused.`);
+        }
+        if (!oldSlot.deleted && !newSlot.deleted && oldSlot.path !== newSlot.path) {
+            errors.push(`Slot ${index} changed path; confirm this is a logical rename or move.`);
+        }
+    });
+
+    return { valid: errors.length === 0, errors };
+}
+
+function collectTreeValues(tree, manifest) {
+    const normalized = asManifest(manifest);
+    const checkedValues = new Map();
+    const expandedValues = new Map();
+
+    for (const [path, node] of tree.nodesByPath) {
+        const slot = normalized.pathToSlot.get(path);
+        if (slot === undefined) continue;
+        const item = tree.itemForNode(node.id);
+        const checkbox = item && tree.directCheckbox(item);
+        const toggle = item?.querySelector(':scope > .checkbox-tree__row > .checkbox-tree__toggle');
+        checkedValues.set(slot, Boolean(checkbox?.checked));
+        expandedValues.set(slot, toggle?.getAttribute('aria-expanded') === 'true');
+    }
+
+    return { normalized, checkedValues, expandedValues };
+}
+
+function nodeState(tree, node) {
+    const item = tree.itemForNode(node.id);
+    const checkbox = item && tree.directCheckbox(item);
+    const toggle = item?.querySelector(':scope > .checkbox-tree__row > .checkbox-tree__toggle');
+    return {
+        checked: Boolean(checkbox?.checked),
+        hasChecked: Boolean(checkbox),
+        expanded: toggle?.getAttribute('aria-expanded') === 'true',
+        hasExpanded: Boolean(toggle)
+    };
+}
+
+function encodeTieredState(tree, normalized) {
+    const checkedByDepth = new Map();
+    const expandedByDepth = new Map();
+    const statesByPath = new Map();
+
+    for (const [path, node] of tree.nodesByPath) {
+        const slot = normalized.pathToSlot.get(path);
+        if (slot === undefined) continue;
+        const depth = path.split(PATH_DELIMITER).length;
+        const parentPath = path.includes(PATH_DELIMITER)
+            ? path.slice(0, path.lastIndexOf(PATH_DELIMITER))
+            : null;
+        const parent = statesByPath.get(parentPath) ?? {
+            checked: false,
+            hasChecked: false,
+            expanded: false,
+            hasExpanded: false
+        };
+        const current = nodeState(tree, node);
+        if (current.hasChecked) {
+            checkedByDepth.set(depth, checkedByDepth.get(depth) ?? new Map());
+            checkedByDepth.get(depth).set(slot, current.checked !== (parent.hasChecked ? parent.checked : false));
+        }
+        if (current.hasExpanded) {
+            expandedByDepth.set(depth, expandedByDepth.get(depth) ?? new Map());
+            expandedByDepth.get(depth).set(slot, current.expanded);
+        }
+        statesByPath.set(path, current);
+    }
+
+    const fields = new Map([['n', String(normalized.slots.length)]]);
+    for (const [depth, values] of checkedByDepth) {
+        const encoded = bytesToBase64Url(encodeAdaptiveBitset(values, normalized.slots.length));
+        if (encoded) fields.set(`c${depth}`, encoded);
+    }
+    for (const [depth, values] of expandedByDepth) {
+        const encoded = bytesToBase64Url(encodeAdaptiveBitset(values, normalized.slots.length));
+        if (encoded) fields.set(`x${depth}`, encoded);
+    }
+    return fields;
+}
+
+export function encodeTreeState(tree, manifest, encoding = tree.options?.stateEncoding ?? 'adaptive') {
+    assertStateEncoding(encoding);
+    const { normalized, checkedValues, expandedValues } = collectTreeValues(tree, manifest);
+
+    if (encoding === 'tiered') {
+        return { version: SERIALIZATION_VERSION, encoding, fields: encodeTieredState(tree, normalized) };
+    }
+
+    const encode = encoding === 'dense' ? encodeDenseBitset : encodeAdaptiveBitset;
+    const checkedValue = bytesToBase64Url(encode(checkedValues, normalized.slots.length));
+    const expandedValue = bytesToBase64Url(encode(expandedValues, normalized.slots.length));
+    return {
+        version: SERIALIZATION_VERSION,
+        encoding,
+        checked: checkedValue || null,
+        expanded: expandedValue || null
+    };
+}
+
+function decodeField(params, name, normalized, encoding) {
+    const maximumLength = encoding === 'dense'
+        ? Math.ceil(normalized.slots.length / 8)
+        : maximumEncodedLength(normalized.slots.length);
+    const bytes = base64UrlToBytes(params.get(name) ?? '', maximumLength);
+    const decode = encoding === 'dense' ? decodeDenseBitset : decodeAdaptiveBitset;
+    decode(bytes, normalized.slots.length);
+    return bytes;
+}
+
+export function decodeTreeState(fragment, manifest, encoding = 'adaptive') {
+    assertStateEncoding(encoding);
+    const normalized = asManifest(manifest);
+    const value = fragment.startsWith('#') ? fragment.slice(1) : fragment;
+    const params = new URLSearchParams(value);
+    if (params.get('v') !== String(SERIALIZATION_VERSION)) {
+        return { applied: false, version: params.get('v'), encoding, warnings: ['Missing or unsupported serialization version.'] };
+    }
+    try {
+        if (encoding === 'tiered') {
+            if (params.has('c') || params.has('x')) {
+                throw new Error('Tiered tree state contains non-tiered fields.');
+            }
+            const maximumDepth = normalized.slots.reduce((depth, slot) =>
+                slot.deleted ? depth : Math.max(depth, slot.path.split(PATH_DELIMITER).length)
+            , 0);
+            for (const key of params.keys()) {
+                const match = /^([cx])(\d+)$/.exec(key);
+                if (match && (Number(match[2]) < 1 || Number(match[2]) > maximumDepth)) {
+                    throw new Error(`Tree state contains an invalid tier: ${key}`);
+                }
+            }
+            const coverage = Number(params.get('n'));
+            if (!Number.isSafeInteger(coverage) || coverage < 0 || coverage > normalized.slots.length) {
+                throw new Error('Tiered tree state has invalid manifest coverage.');
+            }
+            const checkedTiers = new Map();
+            const expandedTiers = new Map();
+            for (let depth = 1; depth <= maximumDepth; depth++) {
+                checkedTiers.set(depth, decodeField(params, `c${depth}`, normalized, 'adaptive'));
+                expandedTiers.set(depth, decodeField(params, `x${depth}`, normalized, 'adaptive'));
+            }
+            return {
+                applied: true,
+                version: SERIALIZATION_VERSION,
+                encoding,
+                coverage,
+                checkedTiers,
+                expandedTiers,
+                warnings: []
+            };
+        }
+
+        for (const key of params.keys()) {
+            if (key === 'n' || /^[cx]\d+$/.test(key)) {
+                throw new Error('Tree state contains tiered fields for a non-tiered encoding.');
+            }
+        }
+
+        const checked = decodeField(params, 'c', normalized, encoding);
+        const expanded = decodeField(params, 'x', normalized, encoding);
+        return {
+            applied: true,
+            version: SERIALIZATION_VERSION,
+            encoding,
+            checked,
+            expanded,
+            warnings: []
+        };
+    } catch (error) {
+        return { applied: false, version: SERIALIZATION_VERSION, encoding, warnings: [error.message] };
+    }
+}
+
+export function applyTreeState(tree, manifest, state) {
+    if (!state?.applied) return false;
+    const normalized = asManifest(manifest);
+    if (state.encoding === 'tiered') return applyTieredTreeState(tree, normalized, state);
+    let isChecked;
+    let isExpanded;
+    try {
+        const decode = state.encoding === 'dense' ? decodeDenseBitset : decodeAdaptiveBitset;
+        isChecked = decode(state.checked, normalized.slots.length);
+        isExpanded = decode(state.expanded, normalized.slots.length);
+    } catch {
+        return false;
+    }
+    for (const [path, node] of tree.nodesByPath) {
+        const slot = normalized.pathToSlot.get(path);
+        if (slot === undefined) continue;
+        const item = tree.itemForNode(node.id);
+        const checkbox = item && tree.directCheckbox(item);
+        if (checkbox && !checkbox.disabled) checkbox.checked = isChecked(slot);
+        tree.setExpanded(item, isExpanded(slot));
+    }
+    tree.updateAllParentCheckboxes();
+    return true;
+}
+
+function applyTieredTreeState(tree, normalized, state) {
+    const resolvedByPath = new Map();
+    const checkedDecoders = new Map();
+    const expandedDecoders = new Map();
+    try {
+        for (const [depth, bytes] of state.checkedTiers) {
+            checkedDecoders.set(depth, decodeAdaptiveBitset(bytes, normalized.slots.length));
+        }
+        for (const [depth, bytes] of state.expandedTiers) {
+            expandedDecoders.set(depth, decodeAdaptiveBitset(bytes, normalized.slots.length));
+        }
+    } catch {
+        return false;
+    }
+
+    for (const [path, node] of tree.nodesByPath) {
+        const slot = normalized.pathToSlot.get(path);
+        if (slot === undefined) continue;
+        const depth = path.split(PATH_DELIMITER).length;
+        const parentPath = path.includes(PATH_DELIMITER)
+            ? path.slice(0, path.lastIndexOf(PATH_DELIMITER))
+            : null;
+        const parent = resolvedByPath.get(parentPath) ?? {
+            checked: false,
+            hasChecked: false,
+            expanded: false,
+            hasExpanded: false
+        };
+        const item = tree.itemForNode(node.id);
+        const checkbox = item && tree.directCheckbox(item);
+        const toggle = item?.querySelector(':scope > .checkbox-tree__row > .checkbox-tree__toggle');
+        const isCovered = slot < state.coverage;
+        const checked = checkbox && isCovered
+            ? (parent.hasChecked ? parent.checked : false) !== checkedDecoders.get(depth)(slot)
+            : false;
+        const expanded = Boolean(toggle && isCovered && expandedDecoders.get(depth)(slot));
+        if (checkbox && !checkbox.disabled) checkbox.checked = checked;
+        tree.setExpanded(item, expanded);
+        resolvedByPath.set(path, {
+            checked,
+            hasChecked: Boolean(checkbox),
+            expanded,
+            hasExpanded: Boolean(toggle)
+        });
+    }
+    tree.updateAllParentCheckboxes();
+    return true;
+}
+
+export function serializeStateToFragment(tree, manifest, encoding = tree.options?.stateEncoding ?? 'adaptive') {
+    const state = encodeTreeState(tree, manifest, encoding);
+    const params = new URLSearchParams({ v: String(state.version) });
+    if (state.encoding === 'tiered') {
+        for (const [name, value] of state.fields) params.set(name, value);
+    } else {
+        if (state.checked) params.set('c', state.checked);
+        if (state.expanded) params.set('x', state.expanded);
+    }
+    return `#${params}`;
+}
+
+export function restoreStateFromLocation(
+    tree,
+    manifest,
+    location = window.location,
+    encoding = tree.options?.stateEncoding ?? 'adaptive'
+) {
+    const state = decodeTreeState(location.hash ?? '', manifest, encoding);
+    if (state.applied) applyTreeState(tree, manifest, state);
+    return state;
+}