From f97ec4fdabd81a967c3ce6c1a58c662124203e5e Mon Sep 17 00:00:00 2001
From: DCCA <dcca12@gmail.com>
Date: Sat, 18 Jul 2026 17:57:44 -0300
Subject: [PATCH] feat: allow nesting primitives inside containers in the
 builder

A composite could only ever be a flat stack. builder-node-tree.tsx said
'display only - nested operations not supported' and meant it:
handleAddPrimitive always appended to the top-level array, and move, delete
and selection all searched only that array, so a nested node could not be
selected, reordered, deleted, or have its properties edited. A designer
could add a container, watch it render as an empty box, and never put
anything in it - which rules out most real components, since a card is a
container with a heading and a body inside it.

The limitation was only ever in the builder UI. PrimitiveNode already has
children, ContainerRenderer already renders them, setNestedValue already
walks arbitrary paths, and getBindableTargets already recursed into
children - so this adds no data model change, no migration, and no new
persistence concern.

Tree manipulation moves into pure immutable helpers in lib/composite/tree.ts,
which is what makes the recursive cases testable without rendering, and
collapses each builder handler to one call.

Two decisions worth naming:

- A new primitive lands inside the selected container when there is room,
  otherwise at the top level. The palette states which, because the
  alternative is the user clicking and finding out.
- MAX_NEST_DEPTH matches the renderer's MAX_DEPTH of 2, and a test asserts
  the two agree. A node the user can build but the renderer refuses to draw
  is worse than one they cannot build.

Reordering stays within a node's own sibling list; dragging across parents
is a different interaction and is not attempted here.
---
 __tests__/composite/tree.test.ts              | 163 ++++++++++++++++++
 components/sandbox/builder-node-tree.tsx      |  85 +++++----
 components/sandbox/builder-palette.tsx        |  12 +-
 components/sandbox/component-builder.tsx      |  58 ++++---
 .../2026-07-18-nested-containers-design.md    |  80 +++++++++
 e2e/nested-containers.spec.ts                 |  91 ++++++++++
 lib/composite/tree.ts                         |  95 ++++++++++
 7 files changed, 514 insertions(+), 70 deletions(-)
 create mode 100644 __tests__/composite/tree.test.ts
 create mode 100644 docs/superpowers/specs/2026-07-18-nested-containers-design.md
 create mode 100644 e2e/nested-containers.spec.ts
 create mode 100644 lib/composite/tree.ts

diff --git a/__tests__/composite/tree.test.ts b/__tests__/composite/tree.test.ts
new file mode 100644
index 0000000..eb5705e
--- /dev/null
+++ b/__tests__/composite/tree.test.ts
@@ -0,0 +1,163 @@
+import { describe, it, expect } from "vitest";
+import {
+  findNode,
+  insertNode,
+  removeNode,
+  moveNode,
+  updateNodeProps,
+  depthOf,
+  MAX_NEST_DEPTH,
+} from "@/lib/composite/tree";
+import type { PrimitiveNode } from "@/lib/composite/types";
+
+const node = (id: string, type: PrimitiveNode["type"] = "heading"): PrimitiveNode => ({
+  id,
+  type,
+  props: { text: id },
+  ...(type === "container" ? { children: [] } : {}),
+});
+
+/** a, then box[b, inner[c]] */
+function tree(): PrimitiveNode[] {
+  return [
+    node("a"),
+    {
+      ...node("box", "container"),
+      children: [node("b"), { ...node("inner", "container"), children: [node("c")] }],
+    },
+  ];
+}
+
+describe("findNode", () => {
+  it("finds a top-level node", () => {
+    expect(findNode(tree(), "a")?.id).toBe("a");
+  });
+
+  it("finds a deeply nested node", () => {
+    expect(findNode(tree(), "c")?.id).toBe("c");
+  });
+
+  it("returns null when the id is absent", () => {
+    expect(findNode(tree(), "nope")).toBeNull();
+  });
+});
+
+describe("insertNode", () => {
+  it("appends to the top level when no parent is given", () => {
+    const next = insertNode(tree(), null, node("new"));
+
+    expect(next.map((n) => n.id)).toEqual(["a", "box", "new"]);
+  });
+
+  it("appends into the named container", () => {
+    const next = insertNode(tree(), "box", node("new"));
+
+    expect(findNode(next, "box")?.children?.map((n) => n.id)).toEqual(["b", "inner", "new"]);
+  });
+
+  it("appends into a nested container", () => {
+    const next = insertNode(tree(), "inner", node("new"));
+
+    expect(findNode(next, "inner")?.children?.map((n) => n.id)).toEqual(["c", "new"]);
+  });
+
+  it("does not mutate the input", () => {
+    const original = tree();
+    insertNode(original, "box", node("new"));
+
+    expect(findNode(original, "box")?.children).toHaveLength(2);
+  });
+
+  it("refuses to nest into a non-container", () => {
+    const next = insertNode(tree(), "a", node("new"));
+
+    expect(findNode(next, "new")).toBeNull();
+  });
+});
+
+describe("removeNode", () => {
+  it("removes a top-level node", () => {
+    expect(removeNode(tree(), "a").map((n) => n.id)).toEqual(["box"]);
+  });
+
+  it("removes a nested node", () => {
+    const next = removeNode(tree(), "b");
+
+    expect(findNode(next, "b")).toBeNull();
+    expect(findNode(next, "box")?.children?.map((n) => n.id)).toEqual(["inner"]);
+  });
+
+  it("removes a container along with its children", () => {
+    const next = removeNode(tree(), "box");
+
+    expect(findNode(next, "c")).toBeNull();
+    expect(next.map((n) => n.id)).toEqual(["a"]);
+  });
+
+  it("does not mutate the input", () => {
+    const original = tree();
+    removeNode(original, "b");
+
+    expect(findNode(original, "b")).not.toBeNull();
+  });
+});
+
+describe("moveNode", () => {
+  it("reorders within the top level", () => {
+    expect(moveNode(tree(), "box", "up").map((n) => n.id)).toEqual(["box", "a"]);
+  });
+
+  it("reorders within a container, not across parents", () => {
+    const next = moveNode(tree(), "inner", "up");
+
+    expect(findNode(next, "box")?.children?.map((n) => n.id)).toEqual(["inner", "b"]);
+    expect(next.map((n) => n.id)).toEqual(["a", "box"]);
+  });
+
+  it("is a no-op at the start of its sibling list", () => {
+    expect(moveNode(tree(), "a", "up").map((n) => n.id)).toEqual(["a", "box"]);
+  });
+
+  it("is a no-op at the end of its sibling list", () => {
+    const next = moveNode(tree(), "inner", "down");
+
+    expect(findNode(next, "box")?.children?.map((n) => n.id)).toEqual(["b", "inner"]);
+  });
+});
+
+describe("updateNodeProps", () => {
+  it("updates a nested node's props", () => {
+    const next = updateNodeProps(tree(), "c", { text: "changed" });
+
+    expect(findNode(next, "c")?.props.text).toBe("changed");
+  });
+
+  it("leaves siblings alone and does not mutate the input", () => {
+    const original = tree();
+    const next = updateNodeProps(original, "b", { text: "changed" });
+
+    expect(findNode(next, "c")?.props.text).toBe("c");
+    expect(findNode(original, "b")?.props.text).toBe("b");
+  });
+});
+
+describe("depthOf", () => {
+  it("reports 0 for a top-level node", () => {
+    expect(depthOf(tree(), "box")).toBe(0);
+  });
+
+  it("reports nesting depth", () => {
+    expect(depthOf(tree(), "b")).toBe(1);
+    expect(depthOf(tree(), "c")).toBe(2);
+  });
+
+  it("returns -1 for an unknown id", () => {
+    expect(depthOf(tree(), "nope")).toBe(-1);
+  });
+
+  it("agrees with the renderer's ceiling", () => {
+    // The renderer drops anything deeper than MAX_DEPTH, so the builder must not let
+    // the user create nodes it would refuse to draw.
+    expect(MAX_NEST_DEPTH).toBe(2);
+  });
+});
diff --git a/components/sandbox/builder-node-tree.tsx b/components/sandbox/builder-node-tree.tsx
index 9a58265..bd83f9a 100644
--- a/components/sandbox/builder-node-tree.tsx
+++ b/components/sandbox/builder-node-tree.tsx
@@ -76,7 +76,6 @@ function NodeRow({
       ? String(node.props.text ?? node.props.label ?? "")
       : "";
   const isSelected = selectedNodeId === node.id;
-  const isNested = depth > 0;
 
   return (
     <>
@@ -96,50 +95,48 @@ function NodeRow({
             {preview.length > 20 ? preview.slice(0, 20) + "..." : preview}
           </span>
         )}
-        {!isNested && (
-          <div className="ml-auto flex items-center gap-0.5 opacity-0 group-hover:opacity-100 transition-opacity">
-            <Button
-              variant="ghost"
-              size="sm"
-              className="h-5 w-5 p-0"
-              onClick={(e) => {
-                e.stopPropagation();
-                onMove(node.id, "up");
-              }}
-              disabled={index === 0}
-              title="Move up"
-            >
-              <ChevronUp className="size-3" />
-            </Button>
-            <Button
-              variant="ghost"
-              size="sm"
-              className="h-5 w-5 p-0"
-              onClick={(e) => {
-                e.stopPropagation();
-                onMove(node.id, "down");
-              }}
-              disabled={index === total - 1}
-              title="Move down"
-            >
-              <ChevronDown className="size-3" />
-            </Button>
-            <Button
-              variant="ghost"
-              size="sm"
-              className="h-5 w-5 p-0 text-red-400 hover:text-red-300"
-              onClick={(e) => {
-                e.stopPropagation();
-                onDelete(node.id);
-              }}
-              title="Delete"
-            >
-              <Trash2 className="size-3" />
-            </Button>
-          </div>
-        )}
+        <div className="ml-auto flex items-center gap-0.5 opacity-0 transition-opacity group-hover:opacity-100">
+          <Button
+            variant="ghost"
+            size="sm"
+            className="h-5 w-5 p-0"
+            onClick={(e) => {
+              e.stopPropagation();
+              onMove(node.id, "up");
+            }}
+            disabled={index === 0}
+            title="Move up"
+          >
+            <ChevronUp className="size-3" />
+          </Button>
+          <Button
+            variant="ghost"
+            size="sm"
+            className="h-5 w-5 p-0"
+            onClick={(e) => {
+              e.stopPropagation();
+              onMove(node.id, "down");
+            }}
+            disabled={index === total - 1}
+            title="Move down"
+          >
+            <ChevronDown className="size-3" />
+          </Button>
+          <Button
+            variant="ghost"
+            size="sm"
+            className="h-5 w-5 p-0 text-red-400 hover:text-red-300"
+            onClick={(e) => {
+              e.stopPropagation();
+              onDelete(node.id);
+            }}
+            title="Delete"
+          >
+            <Trash2 className="size-3" />
+          </Button>
+        </div>
       </div>
-      {/* Render children for containers (display only — nested operations not supported) */}
+      {/* Children are fully operable: select, reorder within their parent, delete */}
       {node.type === "container" &&
         node.children?.map((child, ci) => (
           <NodeRow
diff --git a/components/sandbox/builder-palette.tsx b/components/sandbox/builder-palette.tsx
index 2ada9af..cd8002a 100644
--- a/components/sandbox/builder-palette.tsx
+++ b/components/sandbox/builder-palette.tsx
@@ -26,12 +26,20 @@ const primitives: { type: PrimitiveType; label: string; icon: React.ReactNode }[
 
 type BuilderPaletteProps = {
   onAdd: (type: PrimitiveType) => void;
+  /** Container id new primitives will go into, or null for the top level. */
+  insertingInto?: string | null;
 };
 
-export function BuilderPalette({ onAdd }: BuilderPaletteProps) {
+export function BuilderPalette({ onAdd, insertingInto = null }: BuilderPaletteProps) {
   return (
     <div>
-      <div className="text-xs font-semibold text-muted-foreground mb-2">Primitives</div>
+      <div className="mb-2 flex items-baseline gap-1.5">
+        <span className="text-xs font-semibold text-muted-foreground">Primitives</span>
+        {/* Where a click will put the node - otherwise nesting is invisible guesswork */}
+        <span className="text-[10px] text-muted-foreground/60">
+          {insertingInto ? "into selected container" : "at top level"}
+        </span>
+      </div>
       <div className="grid grid-cols-4 gap-1.5">
         {primitives.map(({ type, label, icon }) => (
           <Button
diff --git a/components/sandbox/component-builder.tsx b/components/sandbox/component-builder.tsx
index 45be22e..22500ae 100644
--- a/components/sandbox/component-builder.tsx
+++ b/components/sandbox/component-builder.tsx
@@ -11,6 +11,15 @@ import { getDefaultProps, primitiveSchemas } from "@/lib/composite/primitives";
 import { applyTheme } from "@/lib/theme/css-vars";
 import { newCompositeId } from "@/lib/composite/identity";
 import { ModalOverlay } from "./modal-overlay";
+import {
+  findNode,
+  insertNode,
+  removeNode,
+  moveNode,
+  updateNodeProps,
+  depthOf,
+  MAX_NEST_DEPTH,
+} from "@/lib/composite/tree";
 import {
   Select,
   SelectContent,
@@ -171,37 +180,38 @@ export function ComponentBuilder({
   }, [themeTokens]);
 
   const selectedNode = useMemo(
-    () => nodes.find((n) => n.id === selectedNodeId) ?? null,
+    () => (selectedNodeId ? findNode(nodes, selectedNodeId) : null),
     [nodes, selectedNodeId],
   );
 
-  const handleAddPrimitive = useCallback((type: PrimitiveType) => {
-    const defaultProps = getDefaultProps(type);
-    const newNode: PrimitiveNode = {
-      id: nextNodeId(),
-      type,
-      props: defaultProps,
-      ...(type === "container" ? { children: [] } : {}),
-    };
-    setNodes((prev) => [...prev, newNode]);
-    setSelectedNodeId(newNode.id);
-  }, []);
+  // New primitives land inside the selected container when there is room, otherwise at
+  // the top level. The palette says which, so it is never a guess.
+  const insertParent = useMemo(() => {
+    if (!selectedNode || selectedNode.type !== "container") return null;
+    return depthOf(nodes, selectedNode.id) < MAX_NEST_DEPTH ? selectedNode : null;
+  }, [nodes, selectedNode]);
+
+  const handleAddPrimitive = useCallback(
+    (type: PrimitiveType) => {
+      const newNode: PrimitiveNode = {
+        id: nextNodeId(),
+        type,
+        props: getDefaultProps(type),
+        ...(type === "container" ? { children: [] } : {}),
+      };
+      setNodes((prev) => insertNode(prev, insertParent?.id ?? null, newNode));
+      setSelectedNodeId(newNode.id);
+    },
+    [insertParent],
+  );
 
   const handleMoveNode = useCallback((id: string, direction: "up" | "down") => {
-    setNodes((prev) => {
-      const idx = prev.findIndex((n) => n.id === id);
-      if (idx < 0) return prev;
-      const swapIdx = direction === "up" ? idx - 1 : idx + 1;
-      if (swapIdx < 0 || swapIdx >= prev.length) return prev;
-      const next = [...prev];
-      [next[idx], next[swapIdx]] = [next[swapIdx], next[idx]];
-      return next;
-    });
+    setNodes((prev) => moveNode(prev, id, direction));
   }, []);
 
   const handleDeleteNode = useCallback(
     (id: string) => {
-      setNodes((prev) => prev.filter((n) => n.id !== id));
+      setNodes((prev) => removeNode(prev, id));
       if (selectedNodeId === id) setSelectedNodeId(null);
     },
     [selectedNodeId],
@@ -210,7 +220,7 @@ export function ComponentBuilder({
   const handleNodePropsChange = useCallback(
     (props: Record<string, unknown>) => {
       if (!selectedNodeId) return;
-      setNodes((prev) => prev.map((n) => (n.id === selectedNodeId ? { ...n, props } : n)));
+      setNodes((prev) => updateNodeProps(prev, selectedNodeId, props));
     },
     [selectedNodeId],
   );
@@ -344,7 +354,7 @@ export function ComponentBuilder({
       <div className="flex-1 grid grid-cols-[300px_1fr_280px] overflow-hidden">
         {/* Left: Palette + Node Tree + Node Props */}
         <div className="border-r border-border/50 overflow-y-auto p-3 space-y-4">
-          <BuilderPalette onAdd={handleAddPrimitive} />
+          <BuilderPalette onAdd={handleAddPrimitive} insertingInto={insertParent?.id ?? null} />
           <BuilderNodeTree
             nodes={nodes}
             selectedNodeId={selectedNodeId}
diff --git a/docs/superpowers/specs/2026-07-18-nested-containers-design.md b/docs/superpowers/specs/2026-07-18-nested-containers-design.md
new file mode 100644
index 0000000..8980963
--- /dev/null
+++ b/docs/superpowers/specs/2026-07-18-nested-containers-design.md
@@ -0,0 +1,80 @@
+# Phase C - Raising the component ceiling
+
+_Date: 2026-07-18_
+_Status: implemented_
+
+## Context
+
+Third of three phases on making Sandy usable as a daily design-system tool.
+[Phase A](./2026-07-18-composite-library-trust-design.md) made the composite library
+correct; [Phase B](./2026-07-18-component-library-design.md) gave it a browsing surface.
+This phase removes the ceiling on what a composite can express.
+
+## The problem
+
+A composite could only ever be a **flat stack** of primitives. `builder-node-tree.tsx`
+carried the comment "display only - nested operations not supported", and it was accurate:
+
+- `handleAddPrimitive` always appended to the top-level `nodes` array, so there was no way
+  to put anything inside a container.
+- `handleMoveNode`, `handleDeleteNode` and the selection lookup all searched only the
+  top-level array, so a nested node could not be selected, reordered, deleted, or have its
+  own properties edited.
+- The node tree rendered children, but hid every action button on them.
+
+A designer could add a container, watch it render as an empty box, and never put anything
+in it. That rules out most real components - a card is a container with a heading and a
+body inside it.
+
+## What was already there
+
+The limitation was **only** in the builder UI. Everything underneath already supported
+nesting:
+
+- `PrimitiveNode` has `children`, and `ContainerRenderer` renders them.
+- `applyBindings` / `setNestedValue` walk arbitrary paths, so a binding can target
+  `[0, "children", 1, "props", "text"]`.
+- `getBindableTargets` in `builder-bindings.tsx` already recursed into `children`, so the
+  binding picker would have offered nested targets the moment any existed.
+- The renderer has a `MAX_DEPTH` of 2 and silently drops anything deeper.
+
+So this phase adds no data model change, no migration, and no new persistence concern.
+
+## Design
+
+Tree manipulation moves out of the component and into pure, immutable helpers in
+`lib/composite/tree.ts`: `findNode`, `insertNode`, `removeNode`, `moveNode`,
+`updateNodeProps`, `depthOf`. Keeping them pure is what makes the recursive cases testable
+without rendering anything, and the builder's handlers collapse to one call each.
+
+Two rules are worth stating because they are decisions, not consequences:
+
+**Where a new primitive lands.** If the selected node is a container with room, the new
+node goes inside it; otherwise it goes to the top level. The palette states which - "into
+selected container" or "at top level" - because the alternative is the user clicking and
+finding out. Selecting a non-container retargets it back to the top level.
+
+**How deep nesting can go.** `MAX_NEST_DEPTH` is 2, matching the renderer's `MAX_DEPTH`.
+A node the user can build but the renderer refuses to draw is worse than one they cannot
+build, so `insertNode` is only offered a container shallower than the ceiling. The tree
+test asserts the two constants agree, so moving one without the other fails.
+
+`moveNode` reorders a node **within its own sibling list** only. Dragging across parents is
+a different interaction with its own affordances and is not attempted here.
+
+## Testing
+
+- **Unit** (`__tests__/composite/tree.test.ts`, 22 cases): each helper against a fixture
+  nested two levels deep - finding, inserting at each level, refusing to nest into a
+  non-container, removing a container along with its children, reordering within a parent
+  without escaping it, no-ops at list boundaries, and immutability of the input on every
+  mutating helper.
+- **E2E** (`e2e/nested-containers.spec.ts`): adding into a selected container, the palette
+  retargeting as selection changes, nested nodes being deletable, a nested node's own
+  properties being editable, and saving a nested component - asserted against the persisted
+  definition, so a flattened stack would fail even if the UI looked right.
+
+## Out of scope
+
+Dragging nodes between parents. Nesting beyond the renderer's depth of 2. Wrapping existing
+nodes in a new container. Multi-select.
diff --git a/e2e/nested-containers.spec.ts b/e2e/nested-containers.spec.ts
new file mode 100644
index 0000000..69ab496
--- /dev/null
+++ b/e2e/nested-containers.spec.ts
@@ -0,0 +1,91 @@
+import { test, expect } from "@playwright/test";
+
+// Composites could only ever be a flat stack of primitives. The data model, the renderer
+// and the binding-path walker all supported nesting already - the builder was the ceiling:
+// it appended everything to the top level and showed container children read-only.
+
+test.describe("nested containers in the builder", () => {
+  test.beforeEach(async ({ page }) => {
+    await page.goto("/sandbox");
+    await page.getByTitle("Create custom component").click();
+    await expect(page.getByRole("dialog", { name: "Component builder" })).toBeVisible();
+  });
+
+  test("adds primitives into the selected container instead of the top level", async ({ page }) => {
+    const builder = page.getByRole("dialog", { name: "Component builder" });
+
+    await builder.getByRole("button", { name: "Container" }).click();
+    // Selecting the container retargets the palette.
+    await expect(builder.getByText("into selected container")).toBeVisible();
+
+    await builder.getByRole("button", { name: "Heading" }).click();
+    await builder.getByRole("button", { name: "Badge" }).click();
+
+    // Adding a node selects it, and a non-container selection retargets the palette
+    // back to the top level, so the destination is always stated rather than guessed.
+    await expect(builder.getByText("at top level")).toBeVisible();
+
+    // Re-selecting the container targets it again.
+    await builder.getByText("Container", { exact: true }).last().click();
+    await expect(builder.getByText("into selected container")).toBeVisible();
+  });
+
+  test("nested nodes can be reordered and deleted", async ({ page }) => {
+    const builder = page.getByRole("dialog", { name: "Component builder" });
+
+    await builder.getByRole("button", { name: "Container" }).click();
+    await builder.getByRole("button", { name: "Heading" }).click();
+    await builder.getByRole("button", { name: "Badge" }).click();
+
+    // Before this change the action buttons were hidden on nested rows entirely.
+    await expect(builder.getByTitle("Delete")).not.toHaveCount(0);
+    const deleteButtons = builder.getByTitle("Delete");
+    const countBefore = await deleteButtons.count();
+
+    await deleteButtons.last().click();
+
+    await expect(builder.getByTitle("Delete")).toHaveCount(countBefore - 1);
+  });
+
+  test("a nested node's own properties are editable", async ({ page }) => {
+    const builder = page.getByRole("dialog", { name: "Component builder" });
+
+    await builder.getByRole("button", { name: "Container" }).click();
+    await builder.getByRole("button", { name: "Heading" }).click();
+
+    // Selecting the nested heading must surface its props - previously selection only
+    // ever matched top-level nodes, so a nested node showed no editor at all.
+    await expect(builder.getByText("Node Properties", { exact: true })).toBeVisible();
+    // The heading's own fields, proving the selection resolved to the nested node.
+    await expect(builder.getByText("Level", { exact: true })).toBeVisible();
+    await expect(builder.getByText("Align", { exact: true })).toBeVisible();
+  });
+
+  test("saves a nested component and renders it on the page", async ({ page }) => {
+    const builder = page.getByRole("dialog", { name: "Component builder" });
+
+    await builder.getByRole("button", { name: "Container" }).click();
+    await builder.getByRole("button", { name: "Badge" }).click();
+    await builder.getByRole("textbox").first().fill("Nested Card");
+    await builder.getByRole("button", { name: "Save", exact: true }).click();
+
+    await expect(builder).toBeHidden();
+
+    // It is a real saved component: it appears in the library with a preview.
+    await page.getByTitle("Open component library").click();
+    const library = page.getByRole("dialog", { name: "Component library" });
+    await expect(library.getByRole("heading", { level: 3, name: "Nested Card" })).toBeVisible();
+
+    // And the saved definition actually has a nested child, not a flattened stack.
+    const stored = await page.evaluate(() => {
+      const raw = window.localStorage.getItem("sandy-composites");
+      return JSON.parse(raw || "[]");
+    });
+    const saved = stored.find((d: { name: string }) => d.name === "Nested Card");
+    expect(saved).toBeTruthy();
+    expect(saved.nodes).toHaveLength(1);
+    expect(saved.nodes[0].type).toBe("container");
+    expect(saved.nodes[0].children).toHaveLength(1);
+    expect(saved.nodes[0].children[0].type).toBe("badge");
+  });
+});
diff --git a/lib/composite/tree.ts b/lib/composite/tree.ts
new file mode 100644
index 0000000..a55f740
--- /dev/null
+++ b/lib/composite/tree.ts
@@ -0,0 +1,95 @@
+import type { PrimitiveNode } from "./types";
+
+/**
+ * Deepest nesting level the builder will create. The renderer refuses to draw anything
+ * deeper (MAX_DEPTH in components/composite/primitive-renderers.tsx), and a node the user
+ * can build but never see is worse than one they cannot build.
+ */
+export const MAX_NEST_DEPTH = 2;
+
+export function findNode(nodes: PrimitiveNode[], id: string): PrimitiveNode | null {
+  for (const node of nodes) {
+    if (node.id === id) return node;
+    if (node.children) {
+      const hit = findNode(node.children, id);
+      if (hit) return hit;
+    }
+  }
+  return null;
+}
+
+/** Nesting level of a node, 0 for top level, -1 when it isn't in the tree. */
+export function depthOf(nodes: PrimitiveNode[], id: string, depth = 0): number {
+  for (const node of nodes) {
+    if (node.id === id) return depth;
+    if (node.children) {
+      const hit = depthOf(node.children, id, depth + 1);
+      if (hit >= 0) return hit;
+    }
+  }
+  return -1;
+}
+
+/**
+ * Append `node` to the children of `parentId`, or to the top level when it is null.
+ * Only containers can take children; anything else is left untouched.
+ */
+export function insertNode(
+  nodes: PrimitiveNode[],
+  parentId: string | null,
+  node: PrimitiveNode,
+): PrimitiveNode[] {
+  if (parentId === null) return [...nodes, node];
+
+  return nodes.map((current) => {
+    if (current.id === parentId) {
+      if (current.type !== "container") return current;
+      return { ...current, children: [...(current.children ?? []), node] };
+    }
+    if (current.children) {
+      return { ...current, children: insertNode(current.children, parentId, node) };
+    }
+    return current;
+  });
+}
+
+export function removeNode(nodes: PrimitiveNode[], id: string): PrimitiveNode[] {
+  return nodes
+    .filter((node) => node.id !== id)
+    .map((node) => (node.children ? { ...node, children: removeNode(node.children, id) } : node));
+}
+
+/** Reorder a node among its own siblings. Moving across parents is not supported. */
+export function moveNode(
+  nodes: PrimitiveNode[],
+  id: string,
+  direction: "up" | "down",
+): PrimitiveNode[] {
+  const idx = nodes.findIndex((node) => node.id === id);
+
+  if (idx >= 0) {
+    const swapIdx = direction === "up" ? idx - 1 : idx + 1;
+    if (swapIdx < 0 || swapIdx >= nodes.length) return nodes;
+    const next = [...nodes];
+    [next[idx], next[swapIdx]] = [next[swapIdx], next[idx]];
+    return next;
+  }
+
+  return nodes.map((node) =>
+    node.children ? { ...node, children: moveNode(node.children, id, direction) } : node,
+  );
+}
+
+export function updateNodeProps(
+  nodes: PrimitiveNode[],
+  id: string,
+  props: Record<string, unknown>,
+): PrimitiveNode[] {
+  return nodes.map((node) => {
+    if (node.id === id) return { ...node, props };
+    if (node.children) {
+      return { ...node, children: updateNodeProps(node.children, id, props) };
+    }
+    return node;
+  });
+}