# Understanding the NodeTree Primitive and Tree-Agnostic Mutations in Instatic > Explore Instatic's NodeTree primitive. Discover how its flat map architecture and tree-agnostic mutations offer O(1) lookups and uniform manipulation across all hierarchical structures. - Repository: [CoreBunch/Instatic](https://github.com/CoreBunch/Instatic) - Tags: architecture - Published: 2026-07-29 --- **Instatic's `NodeTree` primitive represents every hierarchical structure as a flat map of nodes, enabling O(1) lookups and tree-agnostic mutations that work uniformly across pages, visual components, and slot-fill fragments.** In the Instatic visual editor, all tree-based data—from page hierarchies to visual component instances—flows through a single architecture defined in [`src/core/page-tree/treeSchema.ts`](https://github.com/CoreBunch/Instatic/blob/main/src/core/page-tree/treeSchema.ts). This design eliminates the need for recursive tree traversals by flattening the hierarchy into a map-based structure, while the mutation API in [`src/core/page-tree/mutations.ts`](https://github.com/CoreBunch/Instatic/blob/main/src/core/page-tree/mutations.ts) provides generic operations that remain agnostic to the specific content type being edited. ## The NodeTree Primitive Architecture The `NodeTree` interface serves as the universal container for hierarchical data throughout the Instatic codebase. Unlike traditional nested tree structures, this primitive uses a **flat-map pattern** that stores every node in a flat dictionary keyed by UUID. ### Flat-Map Storage Design According to the source code in [`src/core/page-tree/treeSchema.ts`](https://github.com/CoreBunch/Instatic/blob/main/src/core/page-tree/treeSchema.ts), the `NodeTree` interface consists of two essential properties: ```ts export interface NodeTree { nodes: Record rootNodeId: string } ``` - **`nodes`**: A `Record` providing **O(1) lookup** for any node by its unique identifier. This eliminates recursive traversal when accessing specific items. - **`rootNodeId`**: A string indicating the entry point for tree traversals, defining where the hierarchy begins. This flat structure persists through `NodeTreeSchema`, which validates data at the persistence boundary to ensure all stored trees conform to the `BaseNode` schema requirements. ### Generic Type Safety The `NodeTree` interface accepts a generic type parameter `TNode extends BaseNode`, allowing callers to work with specialized node types while maintaining runtime compatibility. For example, `PageNode` extends `BaseNode` with additional properties like `dynamicBindings`, yet stores within the same `NodeTree` container. ### Schema Validation The `NodeTreeSchema` (also defined in [`treeSchema.ts`](https://github.com/CoreBunch/Instatic/blob/main/treeSchema.ts)) guarantees that any loaded tree conforms to the expected shape. Because concrete node types extend `BaseNode`, they automatically satisfy the schema validator without requiring custom validation logic for each node variant. ## Tree-Agnostic Mutation API All mutation helpers reside in [`src/core/page-tree/mutations.ts`](https://github.com/CoreBunch/Instatic/blob/main/src/core/page-tree/mutations.ts) and operate on `NodeTree` regardless of whether the tree represents a page, a visual component, or a slot-fill fragment. This architecture ensures that **create**, **insert**, **move**, and **delete** operations work identically across the React-based editor and the plugin VM sandbox. ### Core Mutation Functions The mutation library exposes pure functions that receive a draft `NodeTree` (typically from Zustand's Mutative middleware) and mutate it in-place. These include: - **`createNode(moduleId, defaults?)`**: Generates a fresh node with a nano-ID, empty children array, and `parentId: null`. - **`insertNode(tree, node, parentId, index?)`**: Adds a node under the specified parent, updating the child array and parent references. - **`deleteNode(tree, nodeId)`**: Removes a node and all descendants via `deleteSubtree`. - **`updateNodeProps(tree, nodeId, patch)`**: Shallow-merges property changes into `node.props`. - **`moveNode(tree, nodeId, newParentId, newIndex)`**: Re-parents nodes while preventing cyclic dependencies. - **`duplicateNode(tree, nodeId, options?)`**: Deep-clones subtrees with fresh UUIDs and inserts them adjacent to the original. - **`pasteSubtree(tree, payload, parentId, index?, options?)`**: Inserts foreign tree structures (e.g., clipboard data) with regenerated identifiers. - **`wrapNode` and `wrapNodes`**: Enclose existing nodes within new container modules. - **`setBreakpointOverride` / `clearBreakpointOverride`**: Manage responsive style overrides per viewport. - **`renameNode`**, **`toggleNodeLocked`**, **`toggleNodeHidden`**: Metadata mutations for editor state. ### The Dispatcher Pattern The `applyTreeOperation(tree, op)` function serves as the single entry point used by both the editor store and plugin VM. It accepts a tagged union defined in [`src/core/page-tree/operationSchema.ts`](https://github.com/CoreBunch/Instatic/blob/main/src/core/page-tree/operationSchema.ts) and dispatches to the appropriate mutation handler. This dispatcher ensures that all tree modifications flow through a consistent validation and execution path. ### Performance and Safety Guarantees Because mutations operate on the flat map rather than recursive tree structures, they touch only the relevant subtree during operations. The `linkChildrenParents` helper (utilizing selectors from [`src/core/page-tree/selectors.ts`](https://github.com/CoreBunch/Instatic/blob/main/src/core/page-tree/selectors.ts)) re-links cloned subtrees in O(subtree) time rather than O(tree). Safety validations include parent existence checks, cycle detection in `moveNode`, and prevention of root node deletion. ## Practical Implementation Examples Below are typical patterns for manipulating node trees in Instatic, applicable both in the visual editor and plugin code: ```ts import { createNode, insertNode, moveNode, wrapNode } from '@core/page-tree'; import type { NodeTree, PageNode } from '@core/page-tree'; // Create a new paragraph node const paragraph = createNode('core.paragraph', { text: 'Hello world' }); // Insert as the last child of the root node insertNode(pageTree as NodeTree, paragraph, pageTree.rootNodeId); // Move the paragraph under a different container moveNode(pageTree as NodeTree, paragraph.id, columnNodeId, 0); // Wrap the paragraph in a new section container const wrapperId = wrapNode(pageTree as NodeTree, paragraph.id, 'core.section'); ``` These functions import from [`src/core/page-tree/mutations.ts`](https://github.com/CoreBunch/Instatic/blob/main/src/core/page-tree/mutations.ts) and can be invoked directly or through the `applyTreeOperation` dispatcher when crossing the plugin boundary. ## Summary - **NodeTree** stores hierarchical data as a flat `Record` with O(1) lookup, defined in [`src/core/page-tree/treeSchema.ts`](https://github.com/CoreBunch/Instatic/blob/main/src/core/page-tree/treeSchema.ts). - The **tree-agnostic mutation API** in [`src/core/page-tree/mutations.ts`](https://github.com/CoreBunch/Instatic/blob/main/src/core/page-tree/mutations.ts) provides 11+ operations (create, insert, move, duplicate, wrap) that work uniformly across pages, visual components, and slots. - **Generic type safety** via `TNode extends BaseNode` allows specialized node types while maintaining a unified storage format. - **Performance optimizations** include draft-based mutations, subtree-only updates, and lazy parent-linking via helper functions. - **Safety mechanisms** prevent cyclic moves, validate parent existence, and protect root nodes from deletion. ## Frequently Asked Questions ### How does the flat-map structure improve performance over nested trees? The flat-map design stores every node in a `Record` object keyed by UUID, enabling O(1) direct access without recursive traversal. When mutations occur, the system updates only the affected nodes and their immediate children rather than walking the entire tree structure, resulting in constant-time lookups and linear-time subtree operations. ### Can tree-agnostic mutations handle different node types like pages and visual components? Yes. The `NodeTree` generic accepts any type extending `BaseNode`, meaning the same `insertNode`, `moveNode`, and `duplicateNode` functions work for `PageNode` instances, visual component nodes, and slot-fill fragments without modification. The runtime storage remains a plain `BaseNode` map while TypeScript provides compile-time type safety. ### What prevents invalid tree operations like creating cycles or deleting the root? The mutation functions in [`src/core/page-tree/mutations.ts`](https://github.com/CoreBunch/Instatic/blob/main/src/core/page-tree/mutations.ts) include validation logic that checks for parent existence before insertion and validates ancestry relationships during move operations to prevent cycles. The `deleteNode` function explicitly guards against root node deletion, and `moveNode` uses selectors from [`src/core/page-tree/selectors.ts`](https://github.com/CoreBunch/Instatic/blob/main/src/core/page-tree/selectors.ts) to verify that the new parent is not a descendant of the moved node. ### How do plugins access the tree mutation API safely? Plugins interact with the tree through the `applyTreeOperation` dispatcher, which accepts a serialized `TreeOperation` defined in [`src/core/page-tree/operationSchema.ts`](https://github.com/CoreBunch/Instatic/blob/main/src/core/page-tree/operationSchema.ts). This single entry point validates operations before execution, ensuring that plugin code running in the sandboxed VM can mutate the tree using the same safe, tree-agnostic API available to the core editor.