dirvi-lib 0.11.0-beta.6 → 0.11.0-beta.7

package/dist/state-and-nav/tree/tree-node.model.d.ts

@@ -0,0 +1,193 @@
+import { z } from 'zod';
+/**
+ * A serializable primitive suitable for use as a stable tree-node ID.
+ *
+ * @remarks
+ *
+ * A node ID identifies a node among its direct siblings. It is not required
+ * to be globally unique across the whole tree: two nodes in different
+ * branches may have the same ID.
+ *
+ * Numeric IDs must be finite. TypeScript cannot represent the exclusion of
+ * `NaN`, `Infinity`, and `-Infinity` from `number`, so values received from
+ * an untrusted source should be validated at an application boundary, for
+ * example with `serializableKeySchema`.
+ *
+ * Applications should normally define a narrower domain-specific ID type.
+ * Branded ID types prevent IDs from unrelated domains from being mixed
+ * accidentally, even when both use strings at runtime.
+ *
+ * @example
+ *
+ * ```ts
+ * const myIdSchema = z
+ *   .string()
+ *   .min(1)
+ *   .brand<'MyId'>();
+ *
+ * type MyId = z.output<typeof myIdSchema>;
+ *
+ * type MyItem = Readonly<{
+ *   label: string;
+ *   href?: string;
+ * }>;
+ *
+ * type MyTreeModel = TreeNodeModel<MyId, MyItem>;
+ * ```
+ */
+export type SerializableKey = string | number;
+/**
+ * Validates a serializable primitive suitable for use as a tree-node ID.
+ *
+ * Strings are accepted without additional restrictions. Numbers must be
+ * finite: `NaN`, `Infinity`, and `-Infinity` are rejected.
+ *
+ * Applications can derive narrower schemas to impose domain-specific
+ * restrictions or produce branded ID types.
+ *
+ * @remarks
+ *
+ * Requires Zod v4, where `z.number()` rejects non-finite values.
+ */
+export declare const serializableKeySchema: z.ZodType<SerializableKey>;
+/**
+ * A structural model for persisting or exchanging a tree node.
+ *
+ * @remarks
+ *
+ * This model is independent of the opaque runtime tree representation.
+ * It consists of ordinary objects and ordered child arrays.
+ *
+ * The presence and value of `children` distinguish three node states:
+ *
+ * - Absent: a leaf, which cannot contain children.
+ * - `null`: a branch whose children have not been loaded.
+ * - An array: a branch whose children are loaded, possibly with no children.
+ *
+ * Loaded children form an ordered sequence. Their array positions describe
+ * child order, while their IDs identify them independently of those positions.
+ * Direct siblings must have unique IDs.
+ *
+ * The model is suitable for JSON serialization when `Id` and `Value` are
+ * JSON-serializable. The generic `Value` type does not itself guarantee this.
+ *
+ * `Readonly` prevents structural mutation through these types at compile time.
+ * It does not freeze objects at runtime or make application-owned values
+ * deeply immutable.
+ *
+ * Models represent finite trees, not cyclic object graphs.
+ *
+ * @typeParam Id - The type identifying each node among its direct siblings.
+ * @typeParam Value - Application-owned data associated with each node.
+ */
+export type TreeNodeModel<Id extends SerializableKey, Value> = LeafTreeNodeModel<Id, Value> | UnloadedBranchTreeNodeModel<Id, Value> | LoadedBranchTreeNodeModel<Id, Value>;
+/**
+ * A structural model of a leaf node.
+ *
+ * A leaf cannot contain children. This is distinct from a loaded branch
+ * whose child array is currently empty.
+ *
+ * @typeParam Id - The type identifying this node among its direct siblings.
+ * @typeParam Value - Application-owned data associated with this node.
+ */
+export type LeafTreeNodeModel<Id extends SerializableKey, Value> = Readonly<{
+    id: Id;
+    value: Value;
+    children?: never;
+}>;
+/**
+ * A structural model of a branch whose children have not been loaded.
+ *
+ * The branch may contain children, but their identities, order, and values
+ * are unavailable in this model. `null` does not mean the branch is empty.
+ *
+ * @typeParam Id - The type identifying this node among its direct siblings.
+ * @typeParam Value - Application-owned data associated with this node.
+ */
+export type UnloadedBranchTreeNodeModel<Id extends SerializableKey, Value> = Readonly<{
+    id: Id;
+    value: Value;
+    children: null;
+}>;
+/**
+ * A structural model of a branch with loaded children.
+ *
+ * An empty child array represents a loaded branch with no current children,
+ * not a leaf. The branch can still contain children.
+ *
+ * @typeParam Id - The type identifying this node among its direct siblings.
+ * @typeParam Value - Application-owned data associated with this node.
+ */
+export type LoadedBranchTreeNodeModel<Id extends SerializableKey, Value> = Readonly<{
+    id: Id;
+    value: Value;
+    children: readonly TreeNodeModel<Id, Value>[];
+}>;
+/**
+ * Creates a recursive schema for validating structural tree-node models.
+ *
+ * @remarks
+ *
+ * The supplied schemas validate every node's ID and application-owned value.
+ * The returned schema validates the three node shapes recursively:
+ *
+ * - Leaves omit `children`.
+ * - Unloaded branches have `children: null`.
+ * - Loaded branches have an ordered array of valid child models.
+ *
+ * Node objects are strict: properties other than `id`, `value`, and the
+ * appropriate `children` property are rejected. Validation of properties
+ * inside `value` is controlled by `valueSchema`.
+ *
+ * Child arrays are parsed in their existing order; this schema does not sort
+ * or reorder children.
+ *
+ * This schema validates shape and field values, but does not enforce
+ * sibling-ID uniqueness. That invariant must be checked when constructing
+ * runtime tree nodes or by an additional validation step.
+ *
+ * The supplied ID schema is responsible for enforcing the runtime ID
+ * constraints, including finite numeric IDs. The generic constraint alone
+ * cannot enforce those restrictions.
+ *
+ * Inputs must describe finite trees. Cyclic object graphs are not supported.
+ *
+ * @typeParam Id - The validated node-ID type.
+ * @typeParam Value - The validated application-value type.
+ * @param idSchema - Schema used to validate every node's ID.
+ * @param valueSchema - Schema used to validate every node's application data.
+ * @returns A recursive schema for the application's tree-node models.
+ *
+ * @example
+ *
+ * ```ts
+ * const myIdSchema = serializableKeySchema
+ *   .pipe(z.string().min(1))
+ *   .brand<'MyId'>();
+ *
+ * type MyId = z.output<typeof myIdSchema>;
+ *
+ * const modelSchema = createTreeNodeModelSchema(
+ *   myIdSchema,
+ *   z.object({ label: z.string() }).strict(),
+ * );
+ *
+ * const model = modelSchema.parse({
+ *   id: 'root',
+ *   value: { label: 'My' },
+ *   children: [
+ *     {
+ *       id: 'home',
+ *       value: { label: 'Home' },
+ *     },
+ *     {
+ *       id: 'settings',
+ *       value: { label: 'Settings' },
+ *       children: null,
+ *     },
+ *   ],
+ * });
+ * ```
+ */
+export declare function createTreeNodeModelSchema<Id extends SerializableKey, Value>(idSchema: z.ZodType<Id>, valueSchema: z.ZodType<Value>): z.ZodType<TreeNodeModel<Id, Value>>;
+//# sourceMappingURL=tree-node.model.d.ts.map

package/dist/state-and-nav/tree/tree-node.model.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tree-node.model.d.ts","sourceRoot":"","sources":["../../../src/state-and-nav/tree/tree-node.model.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,MAAM,CAAC;AAE9C;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,qBAAqB,EAAE,CAAC,CAAC,OAAO,CAAC,eAAe,CAG3D,CAAC;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,MAAM,aAAa,CAAC,EAAE,SAAS,eAAe,EAAE,KAAK,IACvD,iBAAiB,CAAC,EAAE,EAAE,KAAK,CAAC,GAC5B,2BAA2B,CAAC,EAAE,EAAE,KAAK,CAAC,GACtC,yBAAyB,CAAC,EAAE,EAAE,KAAK,CAAC,CAAC;AAEzC;;;;;;;;GAQG;AACH,MAAM,MAAM,iBAAiB,CAAC,EAAE,SAAS,eAAe,EAAE,KAAK,IAAI,QAAQ,CAAC;IAC1E,EAAE,EAAE,EAAE,CAAC;IACP,KAAK,EAAE,KAAK,CAAC;IACb,QAAQ,CAAC,EAAE,KAAK,CAAC;CAClB,CAAC,CAAC;AAEH;;;;;;;;GAQG;AACH,MAAM,MAAM,2BAA2B,CACrC,EAAE,SAAS,eAAe,EAC1B,KAAK,IACH,QAAQ,CAAC;IACX,EAAE,EAAE,EAAE,CAAC;IACP,KAAK,EAAE,KAAK,CAAC;IACb,QAAQ,EAAE,IAAI,CAAC;CAChB,CAAC,CAAC;AAEH;;;;;;;;GAQG;AACH,MAAM,MAAM,yBAAyB,CACnC,EAAE,SAAS,eAAe,EAC1B,KAAK,IACH,QAAQ,CAAC;IACX,EAAE,EAAE,EAAE,CAAC;IACP,KAAK,EAAE,KAAK,CAAC;IACb,QAAQ,EAAE,SAAS,aAAa,CAAC,EAAE,EAAE,KAAK,CAAC,EAAE,CAAC;CAC/C,CAAC,CAAC;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiEG;AACH,wBAAgB,yBAAyB,CAAC,EAAE,SAAS,eAAe,EAAE,KAAK,EACzE,QAAQ,EAAE,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,EACvB,WAAW,EAAE,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,GAC5B,CAAC,CAAC,OAAO,CAAC,aAAa,CAAC,EAAE,EAAE,KAAK,CAAC,CAAC,CA+BrC"}

package/dist/state-and-nav/tree/tree-node.model.js

@@ -0,0 +1,110 @@
+import { z } from 'zod';
+/**
+ * Validates a serializable primitive suitable for use as a tree-node ID.
+ *
+ * Strings are accepted without additional restrictions. Numbers must be
+ * finite: `NaN`, `Infinity`, and `-Infinity` are rejected.
+ *
+ * Applications can derive narrower schemas to impose domain-specific
+ * restrictions or produce branded ID types.
+ *
+ * @remarks
+ *
+ * Requires Zod v4, where `z.number()` rejects non-finite values.
+ */
+export const serializableKeySchema = z.union([
+    z.string(),
+    z.number(),
+]);
+/**
+ * Creates a recursive schema for validating structural tree-node models.
+ *
+ * @remarks
+ *
+ * The supplied schemas validate every node's ID and application-owned value.
+ * The returned schema validates the three node shapes recursively:
+ *
+ * - Leaves omit `children`.
+ * - Unloaded branches have `children: null`.
+ * - Loaded branches have an ordered array of valid child models.
+ *
+ * Node objects are strict: properties other than `id`, `value`, and the
+ * appropriate `children` property are rejected. Validation of properties
+ * inside `value` is controlled by `valueSchema`.
+ *
+ * Child arrays are parsed in their existing order; this schema does not sort
+ * or reorder children.
+ *
+ * This schema validates shape and field values, but does not enforce
+ * sibling-ID uniqueness. That invariant must be checked when constructing
+ * runtime tree nodes or by an additional validation step.
+ *
+ * The supplied ID schema is responsible for enforcing the runtime ID
+ * constraints, including finite numeric IDs. The generic constraint alone
+ * cannot enforce those restrictions.
+ *
+ * Inputs must describe finite trees. Cyclic object graphs are not supported.
+ *
+ * @typeParam Id - The validated node-ID type.
+ * @typeParam Value - The validated application-value type.
+ * @param idSchema - Schema used to validate every node's ID.
+ * @param valueSchema - Schema used to validate every node's application data.
+ * @returns A recursive schema for the application's tree-node models.
+ *
+ * @example
+ *
+ * ```ts
+ * const myIdSchema = serializableKeySchema
+ *   .pipe(z.string().min(1))
+ *   .brand<'MyId'>();
+ *
+ * type MyId = z.output<typeof myIdSchema>;
+ *
+ * const modelSchema = createTreeNodeModelSchema(
+ *   myIdSchema,
+ *   z.object({ label: z.string() }).strict(),
+ * );
+ *
+ * const model = modelSchema.parse({
+ *   id: 'root',
+ *   value: { label: 'My' },
+ *   children: [
+ *     {
+ *       id: 'home',
+ *       value: { label: 'Home' },
+ *     },
+ *     {
+ *       id: 'settings',
+ *       value: { label: 'Settings' },
+ *       children: null,
+ *     },
+ *   ],
+ * });
+ * ```
+ */
+export function createTreeNodeModelSchema(idSchema, valueSchema) {
+    let nodeSchema;
+    nodeSchema = z.lazy(() => z.union([
+        z
+            .object({
+            id: idSchema,
+            value: valueSchema,
+        })
+            .strict(),
+        z
+            .object({
+            id: idSchema,
+            value: valueSchema,
+            children: z.null(),
+        })
+            .strict(),
+        z
+            .object({
+            id: idSchema,
+            value: valueSchema,
+            children: z.array(nodeSchema),
+        })
+            .strict(),
+    ]));
+    return nodeSchema;
+}

package/dist/state-and-nav/tree/tree-node.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=tree-node.test.d.ts.map

package/dist/state-and-nav/tree/tree-node.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tree-node.test.d.ts","sourceRoot":"","sources":["../../../src/state-and-nav/tree/tree-node.test.ts"],"names":[],"mappings":""}

package/dist/state-and-nav/tree/tree-node.test.js

@@ -0,0 +1,234 @@
+import { describe, expect, it, vi } from 'vitest';
+import * as fc from 'fast-check';
+import { createTreeMethods } from './tree.impl.js';
+import { childrenStateModelArb, modelAndBranchPathArb, modelAndReachablePathArb, } from './tree-node.arb.js';
+const api = createTreeMethods();
+/**
+ * Fail rather than silently skipping assertions when an operation that should
+ * succeed returns undefined.
+ */
+function requireDefined(value) {
+    if (value === undefined) {
+        throw new Error('Expected a defined result');
+    }
+    return value;
+}
+function fromModel(model) {
+    return requireDefined(api.fromModel(model));
+}
+function loadedBranch(id, children) {
+    return requireDefined(api.createLoadedBranch(id, 0, children));
+}
+describe('findChildById', () => {
+    it('returns the existing matching direct child', () => {
+        const child = api.createLeaf('child', 1);
+        const root = loadedBranch('root', [child]);
+        expect(api.findChildById(root, 'child')).toBe(child);
+    });
+    it('does not search descendants', () => {
+        const descendant = api.createLeaf('descendant', 1);
+        const child = loadedBranch('child', [descendant]);
+        const root = loadedBranch('root', [child]);
+        expect(api.findChildById(root, 'descendant')).toBeUndefined();
+    });
+    it.each([
+        {
+            name: 'an empty loaded branch',
+            root: loadedBranch('root', []),
+        },
+        {
+            name: 'a leaf',
+            root: api.createLeaf('root', 0),
+        },
+        {
+            name: 'an unloaded branch',
+            root: api.createUnloadedBranch('root', 0),
+        },
+    ])('returns undefined for a missing child in $name', ({ root }) => {
+        expect(api.findChildById(root, 'missing')).toBeUndefined();
+    });
+});
+describe('findAtPath and selectAtPath', () => {
+    it('resolves generated reachable paths', () => {
+        fc.assert(fc.property(modelAndReachablePathArb, ({ root: rootModel, path, expected }) => {
+            const root = fromModel(rootModel);
+            const selected = requireDefined(api.findAtPath(root, path));
+            expect(api.toModel(selected)).toStrictEqual(expected);
+            expect(api.selectAtPath(root, path, (node) => node)).toBe(selected);
+            expect(api.selectAtPath(root, path, (node) => api.id(node))).toBe(expected.id);
+        }));
+    });
+    it('calls the selector once with the existing resolved node', () => {
+        const child = api.createLeaf('child', 1);
+        const root = loadedBranch('root', [child]);
+        const selector = vi.fn((node) => api.id(node));
+        expect(api.selectAtPath(root, ['child'], selector)).toBe('child');
+        expect(selector).toHaveBeenCalledOnce();
+        expect(selector).toHaveBeenCalledWith(child);
+    });
+    it('resolves the root for an empty path', () => {
+        const root = api.createLeaf('root', 0);
+        const selector = vi.fn((node) => node);
+        expect(api.findAtPath(root, [])).toBe(root);
+        expect(api.selectAtPath(root, [], selector)).toBe(root);
+        expect(selector).toHaveBeenCalledOnce();
+        expect(selector).toHaveBeenCalledWith(root);
+    });
+    it.each([
+        {
+            name: 'a missing child',
+            root: loadedBranch('root', []),
+            path: ['missing'],
+        },
+        {
+            name: 'a missing descendant',
+            root: loadedBranch('root', [loadedBranch('child', [])]),
+            path: ['child', 'missing'],
+        },
+        {
+            name: 'a path through a leaf',
+            root: loadedBranch('root', [api.createLeaf('child', 1)]),
+            path: ['child', 'descendant'],
+        },
+        {
+            name: 'a path through an unloaded branch',
+            root: loadedBranch('root', [api.createUnloadedBranch('child', 1)]),
+            path: ['child', 'descendant'],
+        },
+    ])('returns undefined for $name without calling the selector', ({ root, path }) => {
+        const selector = vi.fn((node) => node);
+        expect(api.findAtPath(root, path)).toBeUndefined();
+        expect(api.selectAtPath(root, path, selector)).toBeUndefined();
+        expect(selector).not.toHaveBeenCalled();
+    });
+    it('returns undefined when the selector returns undefined', () => {
+        const root = api.createLeaf('root', 0);
+        const selector = vi.fn((_node) => undefined);
+        expect(api.selectAtPath(root, [], selector)).toBeUndefined();
+        expect(selector).toHaveBeenCalledOnce();
+        expect(selector).toHaveBeenCalledWith(root);
+    });
+});
+describe('updateAtPath', () => {
+    it('replaces a generated node without changing the original tree', () => {
+        fc.assert(fc.property(modelAndReachablePathArb, ({ root: rootModel, path, expected }) => {
+            const root = fromModel(rootModel);
+            const originalNode = requireDefined(api.findAtPath(root, path));
+            const replacement = api.createLeaf(expected.id, expected.value);
+            const updatedRoot = requireDefined(api.updateAtPath(root, path, () => replacement));
+            expect(api.findAtPath(updatedRoot, path)).toBe(replacement);
+            expect(api.findAtPath(root, path)).toBe(originalNode);
+            expect(api.toModel(root)).toStrictEqual(rootModel);
+        }));
+    });
+    it('replaces child loading state at a generated branch path', () => {
+        fc.assert(fc.property(modelAndBranchPathArb, childrenStateModelArb, ({ root: rootModel, path, expected }, newChildren) => {
+            const root = fromModel(rootModel);
+            const originalNode = requireDefined(api.findAtPath(root, path));
+            const updatedRoot = requireDefined(api.updateAtPath(root, path, (node) => newChildren === null
+                ? api.toUnloadedBranch(node)
+                : api.withLoadedChildren(node, newChildren.map(fromModel))));
+            const updatedNode = requireDefined(api.findAtPath(updatedRoot, path));
+            expect(updatedNode).not.toBe(originalNode);
+            expect(api.toModel(updatedNode)).toStrictEqual({
+                id: expected.id,
+                value: expected.value,
+                children: newChildren,
+            });
+            expect(api.findAtPath(root, path)).toBe(originalNode);
+            expect(api.toModel(root)).toStrictEqual(rootModel);
+        }));
+    });
+    it('calls the updater once and preserves position when the ID changes', () => {
+        const before = api.createLeaf('before', 1);
+        const child = api.createLeaf('child', 2);
+        const after = api.createLeaf('after', 3);
+        const root = loadedBranch('root', [before, child, after]);
+        const replacement = api.createLeaf('replacement', 4);
+        const update = vi.fn(() => replacement);
+        const updatedRoot = requireDefined(api.updateAtPath(root, ['child'], update));
+        expect(update).toHaveBeenCalledOnce();
+        expect(update).toHaveBeenCalledWith(child);
+        expect(api.findAtPath(updatedRoot, ['replacement'])).toBe(replacement);
+        expect(api.findAtPath(updatedRoot, ['child'])).toBeUndefined();
+        const children = [...requireDefined(api.getLoadedChildren(updatedRoot))];
+        expect(children.map((node) => api.id(node))).toStrictEqual([
+            'before',
+            'replacement',
+            'after',
+        ]);
+        expect(children[0]).toBe(before);
+        expect(children[1]).toBe(replacement);
+        expect(children[2]).toBe(after);
+        expect(api.findAtPath(root, ['child'])).toBe(child);
+    });
+    it('rejects a replacement ID that duplicates a sibling ID', () => {
+        const child = api.createLeaf('child', 1);
+        const sibling = api.createLeaf('sibling', 2);
+        const root = loadedBranch('root', [child, sibling]);
+        const replacement = api.createLeaf('sibling', 3);
+        const update = vi.fn(() => replacement);
+        expect(api.updateAtPath(root, ['child'], update)).toBeUndefined();
+        expect(update).toHaveBeenCalledOnce();
+        expect(update).toHaveBeenCalledWith(child);
+        expect(api.findAtPath(root, ['child'])).toBe(child);
+        expect(api.findAtPath(root, ['sibling'])).toBe(sibling);
+    });
+    it('rebuilds ancestors while preserving unrelated node identities', () => {
+        const target = api.createLeaf('target', 1);
+        const sibling = api.createLeaf('sibling', 2);
+        const branch = loadedBranch('branch', [target, sibling]);
+        const otherBranch = loadedBranch('other', []);
+        const root = loadedBranch('root', [branch, otherBranch]);
+        const replacement = api.createLeaf('target', 3);
+        const updatedRoot = requireDefined(api.updateAtPath(root, ['branch', 'target'], () => replacement));
+        expect(updatedRoot).not.toBe(root);
+        expect(api.findAtPath(updatedRoot, ['branch'])).not.toBe(branch);
+        expect(api.findAtPath(updatedRoot, ['branch', 'target'])).toBe(replacement);
+        expect(api.findAtPath(updatedRoot, ['branch', 'sibling'])).toBe(sibling);
+        expect(api.findAtPath(updatedRoot, ['other'])).toBe(otherBranch);
+        expect(api.findAtPath(root, ['branch', 'target'])).toBe(target);
+    });
+    it('replaces the root for an empty path', () => {
+        const root = api.createLeaf('root', 0);
+        const replacement = api.createLeaf('replacement', 1);
+        const update = vi.fn(() => replacement);
+        expect(api.updateAtPath(root, [], update)).toBe(replacement);
+        expect(update).toHaveBeenCalledOnce();
+        expect(update).toHaveBeenCalledWith(root);
+    });
+    it.each([
+        {
+            name: 'a missing child',
+            root: loadedBranch('root', []),
+            path: ['missing'],
+        },
+        {
+            name: 'a path through a leaf',
+            root: api.createLeaf('root', 0),
+            path: ['child'],
+        },
+        {
+            name: 'a path through an unloaded branch',
+            root: api.createUnloadedBranch('root', 0),
+            path: ['child'],
+        },
+    ])('returns undefined for $name without calling the updater', ({ root, path }) => {
+        const update = vi.fn((node) => node);
+        expect(api.updateAtPath(root, path, update)).toBeUndefined();
+        expect(update).not.toHaveBeenCalled();
+    });
+    it.each([
+        { name: 'the root', path: [] },
+        { name: 'a descendant', path: ['child'] },
+    ])('returns undefined when updating $name is aborted', ({ path }) => {
+        const child = api.createLeaf('child', 1);
+        const root = loadedBranch('root', [child]);
+        const selected = requireDefined(api.findAtPath(root, path));
+        const update = vi.fn(() => undefined);
+        expect(api.updateAtPath(root, path, update)).toBeUndefined();
+        expect(update).toHaveBeenCalledOnce();
+        expect(update).toHaveBeenCalledWith(selected);
+        expect(api.findAtPath(root, ['child'])).toBe(child);
+    });
+});

package/dist/{trees/tree-node/tree-node.impl.d.ts → state-and-nav/tree/tree.impl.d.ts}

@@ -1,4 +1,4 @@
-import type { TreeNodeApi } from './tree-node.types.js';
+import type { TreeMethods } from './tree.types.js';
 import type { SerializableKey } from './tree-node.model.js';
 /**
  * Creates an API for constructing, inspecting, and immutably updating opaque
@@ -11,5 +11,5 @@ import type { SerializableKey } from './tree-node.model.js';
  * Tree updates preserve object identity for unrelated nodes. New ancestor
  * nodes and child collections are created only along an updated path.
  */
-export declare function createTreeNodeApi<Id extends SerializableKey, Value>(): TreeNodeApi<Id, Value>;
-//# sourceMappingURL=tree-node.impl.d.ts.map
+export declare function createTreeMethods<Id extends SerializableKey, Value>(): TreeMethods<Id, Value>;
+//# sourceMappingURL=tree.impl.d.ts.map

package/dist/state-and-nav/tree/tree.impl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tree.impl.d.ts","sourceRoot":"","sources":["../../../src/state-and-nav/tree/tree.impl.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAEV,WAAW,EAGZ,MAAM,iBAAiB,CAAC;AACzB,OAAO,KAAK,EAAE,eAAe,EAAiB,MAAM,sBAAsB,CAAC;AA2J3E;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAC/B,EAAE,SAAS,eAAe,EAC1B,KAAK,KACF,WAAW,CAAC,EAAE,EAAE,KAAK,CAAC,CAgR1B"}

package/dist/{trees/tree-node/tree-node.impl.js → state-and-nav/tree/tree.impl.js}

@@ -13,6 +13,9 @@ function toData(node) {
 function fromData(data) {
     return data;
 }
+// =============================================================================
+// Helpers
+// =============================================================================
 function isLeafData(node) {
     return !('children' in node);
 }
@@ -23,11 +26,8 @@ function isLoadedBranchData(node) {
     return 'children' in node && node.children !== null;
 }
 /**
- * Returns a reusable iterable over child nodes without exposing the internal
- * child-array representation.
- *
- * The implementation currently stores children in an array, but callers only
- * receive an `Iterable` and must not rely on iteration order.
+ * Returns a reusable iterable over child nodes in their stored order without
+ * exposing the internal child array.
  */
 function asChildrenIterable(children) {
     return Object.freeze({
@@ -45,14 +45,15 @@ function asChildrenIterable(children) {
  * for `createLoadedBranch` and `withLoadedChildren`.
  */
 function copyUniqueChildren(children, getId) {
-    const copiedChildren = [...children];
+    const copiedChildren = [];
     const seenIds = new Set();
-    for (const child of copiedChildren) {
+    for (const child of children) {
         const id = getId(child);
         if (seenIds.has(id)) {
             return undefined;
         }
         seenIds.add(id);
+        copiedChildren.push(child);
     }
     return Object.freeze(copiedChildren);
 }
@@ -76,6 +77,9 @@ function createLoadedBranchData(id, value, children) {
         children,
     });
 }
+// =============================================================================
+// Generic Tree Methods Init
+// =============================================================================
 /**
  * Creates an API for constructing, inspecting, and immutably updating opaque
  * tree nodes.
@@ -87,8 +91,8 @@ function createLoadedBranchData(id, value, children) {
  * Tree updates preserve object identity for unrelated nodes. New ancestor
  * nodes and child collections are created only along an updated path.
  */
-export function createTreeNodeApi() {
-    function getOpenChildren(node) {
+export function createTreeMethods() {
+    function getLoadedChildrenData(node) {
         const data = toData(node);
         return isLoadedBranchData(data) ? data.children : undefined;
     }
@@ -143,11 +147,11 @@ export function createTreeNodeApi() {
             });
         },
         getLoadedChildren(node) {
-            const children = getOpenChildren(node);
+            const children = getLoadedChildrenData(node);
             return children === undefined ? undefined : asChildrenIterable(children);
         },
         findChildById(node, id) {
-            const children = getOpenChildren(node);
+            const children = getLoadedChildrenData(node);
             if (children === undefined) {
                 return undefined;
             }
@@ -245,7 +249,7 @@ export function createTreeNodeApi() {
     };
     function modifyChildAtPath(node, path, modifier) {
         const childId = path[0];
-        const children = getOpenChildren(node);
+        const children = getLoadedChildrenData(node);
         if (childId === undefined || children === undefined) {
             return undefined;
         }
@@ -270,14 +274,13 @@ export function createTreeNodeApi() {
             return undefined;
         }
         /*
-         * The current representation happens to use an array, so replacing one
-         * child is efficient internally. The public API makes no ordering promise:
-         * this is solely an implementation detail.
+         * Replace the child at its existing position, preserving sibling order even
+         * when the replacement has a different ID.
          */
         const updatedChildren = [...children];
         updatedChildren[childIndex] = updatedChild;
         /*
-         * `withChildren` revalidates sibling-ID uniqueness. This matters when
+         * `withLoadedChildren` revalidates sibling-ID uniqueness. This matters when
          * `modifier` replaces a node with another node having a different ID.
          */
         return api.withLoadedChildren(node, updatedChildren);