treeloom 0.0.0-stage → 2.1.0

package/dist/domItem/traits/getNonSerializableKeys.js

@@ -0,0 +1,25 @@
+"use strict";
+
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/. */
+var __importDefault = void 0 && (void 0).__importDefault || function (mod) {
+  return mod && mod.__esModule ? mod : {
+    "default": mod
+  };
+};
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+const definitions_1 = __importDefault(require("./definitions"));
+/**
+ * The properties an item has only because of its traits, and which do not belong in json (the element of the render
+ * trait, for one).
+ * @param item - The item to look at.
+ * @private
+ */
+const getNonSerializableKeys = item => Object.keys(item.has ?? {}).flatMap(trait => {
+  const definition = definitions_1.default.get(trait);
+  return definition && definition.serializable === false ? definition.keys : [];
+});
+exports.default = getNonSerializableKeys;

package/dist/domItem/traits/getNonSerializableKeys.min.js

@@ -0,0 +1 @@
+"use strict";var __importDefault=function(e){return e&&e.__esModule?e:{default:e}};Object.defineProperty(exports,"__esModule",{value:!0});const definitions_1=__importDefault(require("./definitions")),getNonSerializableKeys=e=>Object.keys(e.has??{}).flatMap(e=>{const t=definitions_1.default.get(e);return t&&!1===t.serializable?t.keys:[]});exports.default=getNonSerializableKeys;

package/dist/domItem/traits/getTraitDefinition.d.ts

@@ -0,0 +1,7 @@
+import type { TraitDefinition } from '../types';
+/**
+ * The runtime definition of a trait, if it was defined.
+ * @param name - The name of the trait.
+ */
+declare const getTraitDefinition: (name: string) => TraitDefinition | undefined;
+export default getTraitDefinition;

package/dist/domItem/traits/getTraitDefinition.js

@@ -0,0 +1,20 @@
+"use strict";
+
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/. */
+var __importDefault = void 0 && (void 0).__importDefault || function (mod) {
+  return mod && mod.__esModule ? mod : {
+    "default": mod
+  };
+};
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+const definitions_1 = __importDefault(require("./definitions"));
+/**
+ * The runtime definition of a trait, if it was defined.
+ * @param name - The name of the trait.
+ */
+const getTraitDefinition = name => definitions_1.default.get(name);
+exports.default = getTraitDefinition;

package/dist/domItem/traits/getTraitDefinition.min.js

@@ -0,0 +1 @@
+"use strict";var __importDefault=function(e){return e&&e.__esModule?e:{default:e}};Object.defineProperty(exports,"__esModule",{value:!0});const definitions_1=__importDefault(require("./definitions")),getTraitDefinition=e=>definitions_1.default.get(e);exports.default=getTraitDefinition;

package/dist/domItem/traits/hasTrait.d.ts

@@ -0,0 +1,8 @@
+import type { CoreItem, TraitName, WithTraits } from '../types';
+/**
+ * Whether an item has a trait. It is also a type guard: after the check the trait's data is typed on the item.
+ * @param item - The item to check.
+ * @param trait - The name of the trait.
+ */
+declare const hasTrait: <Trait extends TraitName>(item: CoreItem, trait: Trait) => item is CoreItem & WithTraits<Trait>;
+export default hasTrait;

package/dist/domItem/traits/hasTrait.js

@@ -0,0 +1,15 @@
+"use strict";
+
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/. */
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+/**
+ * Whether an item has a trait. It is also a type guard: after the check the trait's data is typed on the item.
+ * @param item - The item to check.
+ * @param trait - The name of the trait.
+ */
+const hasTrait = (item, trait) => (item.has ?? {})[trait] === true;
+exports.default = hasTrait;

package/dist/domItem/traits/hasTrait.min.js

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,"__esModule",{value:!0});const hasTrait=(e,t)=>!0===(e.has??{})[t];exports.default=hasTrait;

package/dist/domItem/traits/hasTraits.d.ts

@@ -0,0 +1,9 @@
+import type { CoreItem, TraitName, WithTraits } from '../types';
+/**
+ * Whether an item has all of these traits. It is also a type guard: after the check the data of every one of the traits
+ * is typed on the item.
+ * @param item - The item to check.
+ * @param traits - The names of the traits.
+ */
+declare const hasTraits: <Trait extends TraitName>(item: CoreItem, ...traits: Trait[]) => item is CoreItem & WithTraits<Trait>;
+export default hasTraits;

package/dist/domItem/traits/hasTraits.js

@@ -0,0 +1,16 @@
+"use strict";
+
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/. */
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+/**
+ * Whether an item has all of these traits. It is also a type guard: after the check the data of every one of the traits
+ * is typed on the item.
+ * @param item - The item to check.
+ * @param traits - The names of the traits.
+ */
+const hasTraits = (item, ...traits) => traits.every(trait => (item.has ?? {})[trait] === true);
+exports.default = hasTraits;

package/dist/domItem/traits/hasTraits.min.js

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,"__esModule",{value:!0});const hasTraits=(e,...s)=>s.every(s=>!0===(e.has??{})[s]);exports.default=hasTraits;

package/dist/domItem/traits/isDomItem.d.ts

@@ -0,0 +1,8 @@
+import type { CoreItem, DomItem } from '../types';
+/**
+ * Whether an item, and every item below it, has the render trait: the tree treeloom's render and sync functions work
+ * on. hasTrait only checks the one item, so use this where a tree comes from somewhere else. It is also a type guard.
+ * @param item - The item at the top of the tree to check.
+ */
+declare const isDomItem: (item: CoreItem) => item is DomItem;
+export default isDomItem;

package/dist/domItem/traits/isDomItem.js

@@ -0,0 +1,21 @@
+"use strict";
+
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/. */
+var __importDefault = void 0 && (void 0).__importDefault || function (mod) {
+  return mod && mod.__esModule ? mod : {
+    "default": mod
+  };
+};
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+const hasTrait_1 = __importDefault(require("./hasTrait"));
+/**
+ * Whether an item, and every item below it, has the render trait: the tree treeloom's render and sync functions work
+ * on. hasTrait only checks the one item, so use this where a tree comes from somewhere else. It is also a type guard.
+ * @param item - The item at the top of the tree to check.
+ */
+const isDomItem = item => (0, hasTrait_1.default)(item, 'render') && item.children.every(isDomItem);
+exports.default = isDomItem;

package/dist/domItem/traits/isDomItem.min.js

@@ -0,0 +1 @@
+"use strict";var __importDefault=function(e){return e&&e.__esModule?e:{default:e}};Object.defineProperty(exports,"__esModule",{value:!0});const hasTrait_1=__importDefault(require("./hasTrait")),isDomItem=e=>(0,hasTrait_1.default)(e,"render")&&e.children.every(isDomItem);exports.default=isDomItem;

package/dist/domItem/traits/withTrait.d.ts

@@ -0,0 +1,11 @@
+import type { CoreItem, TraitName, TraitRegistry, WithTraits } from '../types';
+/**
+ * Give an item a trait: the trait's defaults and the given data are put on the item (the same object, not a copy), and
+ * it is added to the item's has map.
+ * @param item - The item which gains the trait.
+ * @param trait - The name of the trait.
+ * @param data - The data the trait puts on the item.
+ * @returns The same item, now with the trait.
+ */
+declare const withTrait: <Item extends CoreItem, Trait extends TraitName>(item: Item, trait: Trait, data: TraitRegistry[Trait]) => Item & WithTraits<Trait>;
+export default withTrait;

package/dist/domItem/traits/withTrait.js

@@ -0,0 +1,30 @@
+"use strict";
+
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/. */
+var __importDefault = void 0 && (void 0).__importDefault || function (mod) {
+  return mod && mod.__esModule ? mod : {
+    "default": mod
+  };
+};
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+const definitions_1 = __importDefault(require("./definitions"));
+/**
+ * Give an item a trait: the trait's defaults and the given data are put on the item (the same object, not a copy), and
+ * it is added to the item's has map.
+ * @param item - The item which gains the trait.
+ * @param trait - The name of the trait.
+ * @param data - The data the trait puts on the item.
+ * @returns The same item, now with the trait.
+ */
+const withTrait = (item, trait, data) => {
+  Object.assign(item, definitions_1.default.get(trait)?.defaults?.(), data);
+  item.has = Object.assign(item.has ?? {}, {
+    [trait]: true
+  });
+  return item;
+};
+exports.default = withTrait;

package/dist/domItem/traits/withTrait.min.js

@@ -0,0 +1 @@
+"use strict";var __importDefault=function(e){return e&&e.__esModule?e:{default:e}};Object.defineProperty(exports,"__esModule",{value:!0});const definitions_1=__importDefault(require("./definitions")),withTrait=(e,t,i)=>(Object.assign(e,definitions_1.default.get(t)?.defaults?.(),i),e.has=Object.assign(e.has??{},{[t]:!0}),e);exports.default=withTrait;

package/dist/domItem/tree/appendChild.d.ts

@@ -0,0 +1,8 @@
+import type { DomItem } from '../types';
+/**
+ * Append a child to the end of given parent's children list.
+ * @param parent - The parent that will receive the child.
+ * @param child - The new child to attach to the parent.
+ */
+declare const appendChild: (parent: DomItem, child: DomItem) => DomItem;
+export default appendChild;

package/dist/domItem/tree/appendChild.js

@@ -0,0 +1,19 @@
+"use strict";
+
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/. */
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+/**
+ * Append a child to the end of given parent's children list.
+ * @param parent - The parent that will receive the child.
+ * @param child - The new child to attach to the parent.
+ */
+const appendChild = (parent, child) => {
+  parent.children.push(child);
+  child.parentItem = parent;
+  return parent;
+};
+exports.default = appendChild;

package/dist/domItem/tree/appendChild.min.js

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,"__esModule",{value:!0});const appendChild=(e,t)=>(e.children.push(t),t.parentItem=e,e);exports.default=appendChild;

package/dist/domItem/tree/getItemByPath.d.ts

@@ -0,0 +1,10 @@
+import type { DomItem, ItemPath } from '../types';
+/**
+ * Resolve a path (as built by getItemPath) back to the item it points at, starting from the root. Throws when the
+ * path no longer matches the tree's current shape - exactly like a stale reference to a real DOM element would, a
+ * path is only valid for as long as the tree it was built from keeps the same shape.
+ * @param root - The item the path is relative to (usually documentItem).
+ * @param path - The path to resolve, as returned by getItemPath.
+ */
+declare const getItemByPath: (root: DomItem, path: ItemPath) => DomItem;
+export default getItemByPath;

package/dist/domItem/tree/getItemByPath.js

@@ -0,0 +1,23 @@
+"use strict";
+
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/. */
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+/**
+ * Resolve a path (as built by getItemPath) back to the item it points at, starting from the root. Throws when the
+ * path no longer matches the tree's current shape - exactly like a stale reference to a real DOM element would, a
+ * path is only valid for as long as the tree it was built from keeps the same shape.
+ * @param root - The item the path is relative to (usually documentItem).
+ * @param path - The path to resolve, as returned by getItemPath.
+ */
+const getItemByPath = (root, path) => path.reduce((item, index) => {
+  const child = item.children[index];
+  if (!child) {
+    throw new Error(`No item at index ${index} of path [${path.join(', ')}] - the tree may have changed shape since this path was built.`);
+  }
+  return child;
+}, root);
+exports.default = getItemByPath;

package/dist/domItem/tree/getItemByPath.min.js

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,"__esModule",{value:!0});const getItemByPath=(e,t)=>t.reduce((e,r)=>{const a=e.children[r];if(!a)throw new Error(`No item at index ${r} of path [${t.join(", ")}] - the tree may have changed shape since this path was built.`);return a},e);exports.default=getItemByPath;

package/dist/domItem/tree/getItemPath.d.ts

@@ -0,0 +1,9 @@
+import type { DomItem, ItemPath } from '../types';
+/**
+ * The path from the root to an item: the index of the item among its parent's children, at each level from the top
+ * down. An empty array means the item is the root itself.
+ * WARNING: This is a recursive function.
+ * @param item - The DomItem to find the path of.
+ */
+declare const getItemPath: (item: DomItem) => ItemPath;
+export default getItemPath;

package/dist/domItem/tree/getItemPath.js

@@ -0,0 +1,31 @@
+"use strict";
+
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/. */
+var __importDefault = void 0 && (void 0).__importDefault || function (mod) {
+  return mod && mod.__esModule ? mod : {
+    "default": mod
+  };
+};
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+const si_funciona_1 = __importDefault(require("si-funciona"));
+/**
+ * The path from the root to an item: the index of the item among its parent's children, at each level from the top
+ * down. An empty array means the item is the root itself.
+ * WARNING: This is a recursive function.
+ * @param item - The DomItem to find the path of.
+ */
+const getItemPath = item => {
+  if (item.parentItem === null) {
+    throw new Error('Detached child, missing parentItem reference. Use empty object if this is the root item.');
+  }
+  if (si_funciona_1.default.emptyObject(item.parentItem)) {
+    return [];
+  }
+  const parent = item.parentItem;
+  return [...getItemPath(parent), parent.children.indexOf(item)];
+};
+exports.default = getItemPath;

package/dist/domItem/tree/getItemPath.min.js

@@ -0,0 +1 @@
+"use strict";var __importDefault=function(e){return e&&e.__esModule?e:{default:e}};Object.defineProperty(exports,"__esModule",{value:!0});const si_funciona_1=__importDefault(require("si-funciona")),getItemPath=e=>{if(null===e.parentItem)throw new Error("Detached child, missing parentItem reference. Use empty object if this is the root item.");if(si_funciona_1.default.emptyObject(e.parentItem))return[];const t=e.parentItem;return[...getItemPath(t),t.children.indexOf(e)]};exports.default=getItemPath;

package/dist/domItem/tree/getTopParentItem.d.ts

@@ -0,0 +1,8 @@
+import type { DomItem, DomItemRoot } from '../types';
+/**
+ * Get the upper parentItem for the provided child. (usually this is a documentItem reference)
+ * WARNING: This is a recursive function.
+ * @param item - The DomItem which we want the highest parent item of
+ */
+declare const getTopParentItem: (item: DomItem) => DomItemRoot;
+export default getTopParentItem;

package/dist/domItem/tree/getTopParentItem.js

@@ -0,0 +1,29 @@
+"use strict";
+
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/. */
+var __importDefault = void 0 && (void 0).__importDefault || function (mod) {
+  return mod && mod.__esModule ? mod : {
+    "default": mod
+  };
+};
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+const si_funciona_1 = __importDefault(require("si-funciona"));
+/**
+ * Get the upper parentItem for the provided child. (usually this is a documentItem reference)
+ * WARNING: This is a recursive function.
+ * @param item - The DomItem which we want the highest parent item of
+ */
+const getTopParentItem = item => {
+  if (item.parentItem === null) {
+    if (item.nodeName === '#document') {
+      throw new Error('Root parent item must be an empty object, null reference found.');
+    }
+    throw new Error('Detached child, missing parentItem reference. Use empty object if this is the root item.');
+  }
+  return si_funciona_1.default.emptyObject(item.parentItem) ? item : getTopParentItem(item.parentItem);
+};
+exports.default = getTopParentItem;

package/dist/domItem/tree/getTopParentItem.min.js

@@ -0,0 +1 @@
+"use strict";var __importDefault=function(e){return e&&e.__esModule?e:{default:e}};Object.defineProperty(exports,"__esModule",{value:!0});const si_funciona_1=__importDefault(require("si-funciona")),getTopParentItem=e=>{if(null===e.parentItem){if("#document"===e.nodeName)throw new Error("Root parent item must be an empty object, null reference found.");throw new Error("Detached child, missing parentItem reference. Use empty object if this is the root item.")}return si_funciona_1.default.emptyObject(e.parentItem)?e:getTopParentItem(e.parentItem)};exports.default=getTopParentItem;

package/dist/domItem/tree/insertChild.d.ts

@@ -0,0 +1,11 @@
+import type { DomItem } from '../types';
+/**
+ * Insert a child into a parent's children list at a given position (like appendChild, but positioned). Appending is
+ * insertChild at the end: `appendChild(parent, child)` is `insertChild(parent, child, parent.children.length)`.
+ * @param parent - The parent that will receive the child.
+ * @param child - The new child to attach to the parent.
+ * @param index - Where in parent's children the child goes; out of range clamps to the nearest end, so 0 is always
+ * the front and a large index is always the back (matching Array.prototype.splice).
+ */
+declare const insertChild: (parent: DomItem, child: DomItem, index: number) => DomItem;
+export default insertChild;

package/dist/domItem/tree/insertChild.js

@@ -0,0 +1,22 @@
+"use strict";
+
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/. */
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+/**
+ * Insert a child into a parent's children list at a given position (like appendChild, but positioned). Appending is
+ * insertChild at the end: `appendChild(parent, child)` is `insertChild(parent, child, parent.children.length)`.
+ * @param parent - The parent that will receive the child.
+ * @param child - The new child to attach to the parent.
+ * @param index - Where in parent's children the child goes; out of range clamps to the nearest end, so 0 is always
+ * the front and a large index is always the back (matching Array.prototype.splice).
+ */
+const insertChild = (parent, child, index) => {
+  parent.children.splice(index, 0, child);
+  child.parentItem = parent;
+  return parent;
+};
+exports.default = insertChild;

package/dist/domItem/tree/insertChild.min.js

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,"__esModule",{value:!0});const insertChild=(e,t,r)=>(e.children.splice(r,0,t),t.parentItem=e,e);exports.default=insertChild;

package/dist/domItem/tree/itemIdIndex.d.ts

@@ -0,0 +1,43 @@
+import type { DomItem, DomItemRoot } from '../types';
+export declare const generateItemId: () => number;
+/**
+ * Register an item (and, recursively, its whole subtree) in its own root's id index, so getItemById can find
+ * it. Call once a subtree's relationship to its parent is settled - see renderHtml, which is the one place
+ * that happens for a freshly-attached subtree. Does nothing when item is not under a real root yet (or ever).
+ *
+ * Repairs two ways an item can reach this point without the id createCoreItem is supposed to have already
+ * stamped on it, rather than requiring every consumer to avoid either:
+ * - No id at all (`typeof item.id !== 'number'`): a raw plain config object merged directly onto an
+ *   already-rendered tree (si-funciona's mergeObjectsMutable, by reference, "as is", when the two sides'
+ *   shapes do not line up index-for-index - see updatePlayerStats.ts) never passed through createCoreItem at
+ *   all, so it has no id (or parentItem, or has map) whatsoever.
+ * - A collision (the id is already registered to a *different* item within this same root): a generic "build
+ *   one item, then replicate it N times" helper (si-funciona's buildArray, cloning rather than constructing
+ *   fresh - the shape matrix-dom's own buildMatrix uses for a grid's rows/columns/tiles) copies whatever id
+ *   the one template already carries into every copy right along with everything else, with no way for
+ *   treeloom to know that happened before registration.
+ *
+ * Catching both here, at the one real choke point every attached item passes through, protects against these
+ * patterns (and any other generic cloning or raw merging this codebase does not yet know about) without
+ * needing every consumer to avoid them. A real reuse of someone else's id (rather than two different items
+ * both starting unassigned) is not realistically distinguishable from the collision case, so the same repair
+ * applies regardless of cause - the alternative (leaving it in place) silently breaks resolution for one of
+ * the two items, which is worse than quietly handing the second one a fresh id.
+ * @param item - The subtree to register, root item included.
+ */
+export declare const registerItemIds: (item: DomItem) => void;
+/**
+ * Remove an item (and, recursively, its whole subtree) from its own root's id index - the reverse of
+ * registerItemIds. Call before the item is actually detached, while its parentItem chain still resolves and
+ * its own subtree is still intact to walk.
+ * @param item - The subtree to unregister, root item included.
+ */
+export declare const unregisterItemIds: (item: DomItem) => void;
+/**
+ * Resolve an id (as captured off a DomItem's own id) back to the item it refers to, within root's own tree.
+ * Throws when the id isn't registered against this root - the same "stale reference" contract getItemByPath
+ * already has: a silent wrong-answer resolution is worse than a loud failure.
+ * @param root - The tree to resolve the id against.
+ * @param id - The id to resolve, as read directly off a DomItem's own id property.
+ */
+export declare const getItemById: (root: DomItemRoot, id: number) => DomItem;

package/dist/domItem/tree/itemIdIndex.js

@@ -0,0 +1,118 @@
+"use strict";
+
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/. */
+var __importDefault = void 0 && (void 0).__importDefault || function (mod) {
+  return mod && mod.__esModule ? mod : {
+    "default": mod
+  };
+};
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.getItemById = exports.unregisterItemIds = exports.registerItemIds = exports.generateItemId = void 0;
+const si_funciona_1 = __importDefault(require("si-funciona"));
+const collect_your_stuff_1 = require("collect-your-stuff");
+/** One lookup index per treeloom process: every root's own ids live in their own scope, so two unrelated trees
+ * (the server's real tree and a client's independently-built one) never collide even though both number their
+ * items starting from the same small integers. */
+const itemsById = new collect_your_stuff_1.ScopedCollection();
+/** The next id to assign - a plain, process-local monotonic counter (not a UUID: cheaper to generate/compare/
+ * serialize, and uniqueness only ever needs to hold within one process, since nothing resolves an id against a
+ * different root than the one it came from). Exported for createCoreItem's own first stamp and for this
+ * module's own collision repair below - kept here, not there, since this module must never import back from
+ * createCoreItem (which already imports this one, via removeChild - see unregisterItemIds's own caller). */
+let nextItemId = 0;
+const generateItemId = () => nextItemId++;
+exports.generateItemId = generateItemId;
+/**
+ * The real root above item, or null when item's own parentItem chain never reaches one. That covers two
+ * different, both legitimate cases: an item rendered into some arbitrary, never-rooted container (see
+ * renderHtml's own tests - not one forwarding could ever target, so it is not an error for it to have no
+ * id-index entry), and an item that was never completed as a real DomItem at all - a raw plain config object
+ * merged directly onto an already-rendered tree (si-funciona's mergeObjectsMutable, by reference, "as is",
+ * when the two sides' shapes do not line up index-for-index - see updatePlayerStats.ts) carries no parentItem
+ * property whatsoever, `undefined` rather than this codebase's own usual `null` for "detached". Unlike
+ * getTopParentItem, this never throws: it is used purely to decide whether registration applies, not to
+ * assert that a real root exists.
+ * @param item
+ */
+const tryGetRoot = item => {
+  let current = item;
+  while (current.parentItem != null) {
+    if (si_funciona_1.default.emptyObject(current.parentItem)) {
+      return current;
+    }
+    current = current.parentItem;
+  }
+  return null;
+};
+/**
+ * Register an item (and, recursively, its whole subtree) in its own root's id index, so getItemById can find
+ * it. Call once a subtree's relationship to its parent is settled - see renderHtml, which is the one place
+ * that happens for a freshly-attached subtree. Does nothing when item is not under a real root yet (or ever).
+ *
+ * Repairs two ways an item can reach this point without the id createCoreItem is supposed to have already
+ * stamped on it, rather than requiring every consumer to avoid either:
+ * - No id at all (`typeof item.id !== 'number'`): a raw plain config object merged directly onto an
+ *   already-rendered tree (si-funciona's mergeObjectsMutable, by reference, "as is", when the two sides'
+ *   shapes do not line up index-for-index - see updatePlayerStats.ts) never passed through createCoreItem at
+ *   all, so it has no id (or parentItem, or has map) whatsoever.
+ * - A collision (the id is already registered to a *different* item within this same root): a generic "build
+ *   one item, then replicate it N times" helper (si-funciona's buildArray, cloning rather than constructing
+ *   fresh - the shape matrix-dom's own buildMatrix uses for a grid's rows/columns/tiles) copies whatever id
+ *   the one template already carries into every copy right along with everything else, with no way for
+ *   treeloom to know that happened before registration.
+ *
+ * Catching both here, at the one real choke point every attached item passes through, protects against these
+ * patterns (and any other generic cloning or raw merging this codebase does not yet know about) without
+ * needing every consumer to avoid them. A real reuse of someone else's id (rather than two different items
+ * both starting unassigned) is not realistically distinguishable from the collision case, so the same repair
+ * applies regardless of cause - the alternative (leaving it in place) silently breaks resolution for one of
+ * the two items, which is worse than quietly handing the second one a fresh id.
+ * @param item - The subtree to register, root item included.
+ */
+const registerItemIds = item => {
+  const root = tryGetRoot(item);
+  if (!root) {
+    return;
+  }
+  const alreadyThere = typeof item.id === 'number' ? itemsById.get(root, item.id) : undefined;
+  if (typeof item.id !== 'number' || alreadyThere && alreadyThere !== item) {
+    item.id = (0, exports.generateItemId)();
+  }
+  itemsById.set(root, item.id, item);
+  (item.children || []).forEach(exports.registerItemIds);
+};
+exports.registerItemIds = registerItemIds;
+/**
+ * Remove an item (and, recursively, its whole subtree) from its own root's id index - the reverse of
+ * registerItemIds. Call before the item is actually detached, while its parentItem chain still resolves and
+ * its own subtree is still intact to walk.
+ * @param item - The subtree to unregister, root item included.
+ */
+const unregisterItemIds = item => {
+  const root = tryGetRoot(item);
+  if (!root) {
+    return;
+  }
+  itemsById.delete(root, item.id);
+  (item.children || []).forEach(exports.unregisterItemIds);
+};
+exports.unregisterItemIds = unregisterItemIds;
+/**
+ * Resolve an id (as captured off a DomItem's own id) back to the item it refers to, within root's own tree.
+ * Throws when the id isn't registered against this root - the same "stale reference" contract getItemByPath
+ * already has: a silent wrong-answer resolution is worse than a loud failure.
+ * @param root - The tree to resolve the id against.
+ * @param id - The id to resolve, as read directly off a DomItem's own id property.
+ */
+const getItemById = (root, id) => {
+  const item = itemsById.get(root, id);
+  if (!item) {
+    throw new Error(`No item with id ${id} in this tree - it may have been removed, or never belonged to it.`);
+  }
+  return item;
+};
+exports.getItemById = getItemById;

package/dist/domItem/tree/itemIdIndex.min.js

@@ -0,0 +1 @@
+"use strict";var __importDefault=function(e){return e&&e.__esModule?e:{default:e}};Object.defineProperty(exports,"__esModule",{value:!0}),exports.getItemById=exports.unregisterItemIds=exports.registerItemIds=exports.generateItemId=void 0;const si_funciona_1=__importDefault(require("si-funciona")),collect_your_stuff_1=require("collect-your-stuff"),itemsById=new collect_your_stuff_1.ScopedCollection;let nextItemId=0;const generateItemId=()=>nextItemId++;exports.generateItemId=generateItemId;const tryGetRoot=e=>{let t=e;for(;null!=t.parentItem;){if(si_funciona_1.default.emptyObject(t.parentItem))return t;t=t.parentItem}return null},registerItemIds=e=>{const t=tryGetRoot(e);if(!t)return;const r="number"==typeof e.id?itemsById.get(t,e.id):void 0;("number"!=typeof e.id||r&&r!==e)&&(e.id=(0,exports.generateItemId)()),itemsById.set(t,e.id,e),(e.children||[]).forEach(exports.registerItemIds)};exports.registerItemIds=registerItemIds;const unregisterItemIds=e=>{const t=tryGetRoot(e);t&&(itemsById.delete(t,e.id),(e.children||[]).forEach(exports.unregisterItemIds))};exports.unregisterItemIds=unregisterItemIds;const getItemById=(e,t)=>{const r=itemsById.get(e,t);if(!r)throw new Error(`No item with id ${t} in this tree - it may have been removed, or never belonged to it.`);return r};exports.getItemById=getItemById;

package/dist/domItem/tree/removeChild.d.ts

@@ -0,0 +1,8 @@
+import type { DomItem } from '../types';
+/**
+ * Reverse of appendHtml, remove a DomItem and have the associated element removed.
+ * @param parent - The parent of the items
+ * @param child - The DomItem with HTMLElement to be removed
+ */
+declare const removeChild: (parent: DomItem, child: DomItem) => DomItem[];
+export default removeChild;

package/dist/domItem/tree/removeChild.js

@@ -0,0 +1,21 @@
+"use strict";
+
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/. */
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+const itemIdIndex_1 = require("./itemIdIndex");
+/**
+ * Reverse of appendHtml, remove a DomItem and have the associated element removed.
+ * @param parent - The parent of the items
+ * @param child - The DomItem with HTMLElement to be removed
+ */
+const removeChild = (parent, child) => {
+  // Before detaching: child's own parentItem chain (still pointing at parent) is what resolves its root.
+  (0, itemIdIndex_1.unregisterItemIds)(child);
+  parent.element.removeChild(child.element);
+  return parent.children.splice(parent.children.indexOf(child), 1);
+};
+exports.default = removeChild;

package/dist/domItem/tree/removeChild.min.js

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,"__esModule",{value:!0});const itemIdIndex_1=require("./itemIdIndex"),removeChild=(e,d)=>((0,itemIdIndex_1.unregisterItemIds)(d),e.element.removeChild(d.element),e.children.splice(e.children.indexOf(d),1));exports.default=removeChild;

package/dist/domItem/tree/setParentItemReferences.d.ts

@@ -0,0 +1,7 @@
+import type { DomItem } from '../types';
+/**
+ * For each child of this item, set the parentItem references.
+ * @param item - The DomItem to have parent references applied.
+ */
+declare const setParentItemReferences: (item: DomItem) => DomItem;
+export default setParentItemReferences;