Group scene objects in the hierarchy, for the editor only (#241)

A scene with a hundred crates fills the hierarchy with a hundred rows.
Groups bundle top-level objects under one folder row that folds away.
They exist for the editor only. Parenting, positions and the game do
not see them.

- Model: a scene or container template holds a list of groups, an
  object may carry a groupId. Old projects load unchanged. Loading
  drops empty groups and members that are no longer top level.
- Only top-level objects can join a group. Parenting a member takes it
  out of the group, and Undo puts it back. There are no groups in
  groups.
- Order: treeOrder lists the members together, where the first one
  stands. The same order decides drawing at equal z, in the editor and
  in the game, so the hierarchy and the picture cannot disagree. The
  stored object list stays untouched when grouping.
- Hierarchy: a group row shows a folder icon, the name and the member
  count. Clicking it selects all members and keeps it folded. Selecting
  a single member elsewhere unfolds it. Folding lasts for the session.
- Create with "Group..." in the object menu. A name dialog asks first,
  so creating is one Undo step and Cancel creates nothing.
- The group menu has Select members, Rename... and Ungroup. The object
  menu adds "Remove from group".
- Drag and drop: onto the group row appends, into a gap between members
  inserts there, next to a row outside leaves the group. Dragging the
  group row moves all members as a block. The drop rules live in
  hierarchyDrop.ts as a pure function.
- Copy and paste keeps a top-level copy in the group of its original.
  A container built from group members takes their place in the group.
- Clicking an object that is already selected together with others now
  keeps only that object selected. ListView narrows the selection on
  release, so a drag starting on such a row keeps the selection.

Not checked in the browser: groups in the container tab, "Remove from
group", Ctrl-click on a group row and a drag out of a multi-selection.
The code path covers them.

Tests:
- check.sh: 177 files, 2552 tests, CHECK EXIT 0
- e2e 1, 51, 52: ALL PASSED, 31 checks (new module 52)
- 19 new unit tests in object-groups.test.ts and hierarchy-drop.test.ts
- 9 counter-probes, all fail as expected (7 unit, 2 in the browser)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

src/core/model/Asset.ts

@@ -3,7 +3,7 @@ import type { PropertyDef } from '../properties/PropertySchema';
 import type { AssetType } from './AssetTypes';
 import type { PropertyBag, PropertyValue, Vec2 } from './Properties';
 import type { Scope } from './Scope';
-import type { SceneObject } from './SceneObject';
+import type { ObjectGroup, SceneObject } from './SceneObject';
 
 export interface AssetBase {
   id: string;
@@ -27,6 +27,8 @@ export interface TextAsset extends AssetBase {
 export interface SceneAsset extends AssetBase {
   type: 'scene';
   objects: SceneObject[];
+  /** Hierarchy folders (#241); absent when there are none. */
+  groups?: ObjectGroup[];
 }
 
 /**
@@ -96,6 +98,8 @@ export interface RigidbodyAsset extends AssetBase {
 export interface ContainerAsset extends AssetBase {
   type: 'container';
   objects: SceneObject[];
+  /** Hierarchy folders of the template's top level (#241); absent when there are none. */
+  groups?: ObjectGroup[];
 }
 
 /** How the parts between the corners of a nine-slice frame fill the space they are given (#41). */

src/core/model/SceneObject.ts

@@ -29,6 +29,17 @@ export interface SceneObject {
    * stored – it follows the template.
    */
   instanceEdits: Record<string, InstanceEdit>;
+  /**
+   * Folder of the hierarchy this object is listed in (#241) – top-level objects only. It changes
+   * nothing about the tree: the game sees it only as the order equal `z` is drawn in.
+   */
+  groupId?: string;
+}
+
+/** A folder in the hierarchy for top-level objects – editor looks only, never part of the tree. */
+export interface ObjectGroup {
+  id: string;
+  name: string;
 }
 
 export function createSceneObject(

src/core/model/hierarchy.ts

@@ -1,5 +1,5 @@
 import { type Removed, removeWhere } from '../util/list';
-import type { SceneObject } from './SceneObject';
+import type { ObjectGroup, SceneObject } from './SceneObject';
 import { descendantsBelow, parentChain } from './walk';
 
 /**
@@ -8,6 +8,8 @@ import { descendantsBelow, parentChain } from './walk';
  */
 export interface ObjectTree {
   objects: SceneObject[];
+  /** Hierarchy folders for top-level objects (#241) – they order the tree but never shape it. */
+  groups?: ObjectGroup[];
 }
 
 export function findObject(tree: ObjectTree, id: string): SceneObject | undefined {
@@ -83,14 +85,37 @@ export interface TreeEntry {
 }
 
 /**
- * Top-level objects in storage order, each followed by its subtree – the order the hierarchy panel
- * shows and the tie-break order for equal `z`.
+ * The stored list with the members of each group moved up behind the first of them: a group is
+ * listed – and drawn at equal `z` – as one block wherever its first member stands (#241).
+ */
+export function groupedOrder(objects: readonly SceneObject[]): readonly SceneObject[] {
+  const blocks = new Map<string, SceneObject[]>();
+  for (const object of objects) {
+    if (object.parentId || !object.groupId) continue;
+    const block = blocks.get(object.groupId);
+    if (block) block.push(object);
+    else blocks.set(object.groupId, [object]);
+  }
+  if (blocks.size === 0) return objects;
+  const result: SceneObject[] = [];
+  for (const object of objects) {
+    const block = object.parentId || !object.groupId ? undefined : blocks.get(object.groupId);
+    if (!block) result.push(object);
+    else if (block[0] === object) result.push(...block);
+  }
+  return result;
+}
+
+/**
+ * Top-level objects in storage order, groups kept together, each followed by its subtree – the
+ * order the hierarchy panel shows and the tie-break order for equal `z`.
  */
 export function treeOrder(tree: ObjectTree): TreeEntry[] {
   const result: TreeEntry[] = [];
+  const ordered = groupedOrder(tree.objects);
   const ids = new Set(tree.objects.map((o) => o.id));
   const visit = (parentId: string, depth: number) => {
-    for (const object of tree.objects) {
+    for (const object of ordered) {
       if (object.parentId !== parentId) continue;
       result.push({ object, depth });
       visit(object.id, depth + 1);
@@ -98,34 +123,74 @@ export function treeOrder(tree: ObjectTree): TreeEntry[] {
   };
   visit('', 0);
   // Objects whose parent is missing are listed at the top level rather than dropped.
-  for (const object of tree.objects) {
+  for (const object of ordered) {
     if (object.parentId && !ids.has(object.parentId) && !result.some((e) => e.object === object))
       result.push({ object, depth: 0 });
   }
   return result;
 }
 
-export interface VisibleEntry extends TreeEntry {
-  hasChildren: boolean;
+export function findGroup(tree: ObjectTree, groupId: string): ObjectGroup | undefined {
+  return tree.groups?.find((g) => g.id === groupId);
 }
 
+/** The top-level objects listed in the group, in tree order. */
+export function groupMemberIds(tree: ObjectTree, groupId: string): string[] {
+  return groupedOrder(tree.objects)
+    .filter((o) => !o.parentId && o.groupId === groupId)
+    .map((o) => o.id);
+}
+
+/** Only top-level objects go into a group – a child is listed under its parent. */
+export function canGroup(tree: ObjectTree, ids: readonly string[]): boolean {
+  return ids.length > 0 && ids.every((id) => findObject(tree, id)?.parentId === '');
+}
+
+/** The list id of a group's row: never an object id, which has no colon. */
+export function groupRowId(groupId: string): string {
+  return `group:${groupId}`;
+}
+
+export function groupIdOfRow(rowId: string): string | null {
+  return rowId.startsWith('group:') ? rowId.slice('group:'.length) : null;
+}
+
+export type HierarchyRow =
+  | { kind: 'object'; object: SceneObject; depth: number; hasChildren: boolean }
+  | { kind: 'group'; group: ObjectGroup; memberIds: string[]; depth: number };
+
 /**
- * Tree order with the subtrees of collapsed objects left out. Anything not in `expanded` counts as
- * collapsed, so a freshly loaded scene shows only its top level.
+ * Tree order with a row in front of each group and the subtrees of collapsed objects and groups
+ * left out. `expanded` holds object ids and group row ids; anything not in it counts as collapsed,
+ * so a freshly loaded scene shows only its top level.
  */
-export function visibleTreeOrder(tree: ObjectTree, expanded: ReadonlySet<string>): VisibleEntry[] {
+export function hierarchyRows(tree: ObjectTree, expanded: ReadonlySet<string>): HierarchyRow[] {
   const parents = new Set(tree.objects.map((o) => o.parentId).filter(Boolean));
-  const result: VisibleEntry[] = [];
+  const groups = new Map((tree.groups ?? []).map((g) => [g.id, g]));
+  const result: HierarchyRow[] = [];
   // Depth of the collapsed row whose subtree is being skipped (-1 = showing rows).
   let collapsedAt = -1;
-  for (const entry of treeOrder(tree)) {
+  // The group of the top-level object the current entries belong to, and whether it is folded.
+  let group: ObjectGroup | undefined;
+  let groupFolded = false;
+  for (const { object, depth } of treeOrder(tree)) {
+    if (depth === 0) {
+      const next = object.parentId ? undefined : groups.get(object.groupId ?? '');
+      if (next && next !== group) {
+        const rowId = groupRowId(next.id);
+        result.push({ kind: 'group', group: next, memberIds: groupMemberIds(tree, next.id), depth: 0 });
+        groupFolded = !expanded.has(rowId);
+      }
+      group = next;
+    }
+    if (group && groupFolded) continue;
     if (collapsedAt >= 0) {
-      if (entry.depth > collapsedAt) continue;
+      if (depth > collapsedAt) continue;
       collapsedAt = -1;
     }
-    const hasChildren = parents.has(entry.object.id);
-    result.push({ ...entry, hasChildren });
-    if (hasChildren && !expanded.has(entry.object.id)) collapsedAt = entry.depth;
+    const hasChildren = parents.has(object.id);
+    result.push({ kind: 'object', object, depth: depth + (group ? 1 : 0), hasChildren });
+    if (hasChildren && !expanded.has(object.id)) collapsedAt = depth;
   }
   return result;
 }

src/core/model/instance.ts

@@ -3,7 +3,7 @@
  * in sparse `instanceEdits` keyed by template-id path; derived ids `<instance>~<path>` are never stored.
  */
 import type { ContainerAsset } from './Asset';
-import type { ObjectTree } from './hierarchy';
+import { groupedOrder, type ObjectTree } from './hierarchy';
 import {
   type Axis,
   type Position,
@@ -147,7 +147,8 @@ function expand(
   depth: number,
   out: SceneObject[],
 ): void {
-  for (const template of asset.objects) {
+  // In the order the template lists its top level, groups together, so equal `z` ties the same way.
+  for (const template of groupedOrder(asset.objects)) {
     const path = prefix ? `${prefix}${PATH_SEP}${template.id}` : template.id;
     const id = instanceChildId(instanceId, path);
     const parentId = template.parentId