@rasamjs/core 0.2.0 → 0.3.1

package/src/components/types.ts

@@ -0,0 +1,66 @@
+import type { EditRules } from '../types/common.js';
+import type { Component } from './component.js';
+import type { DrawingContext } from '../services/context.js';
+import type { ElementClass } from '../services/types.js';
+
+export type PropValue = string | number | boolean | null;
+export type ComponentProps = Readonly<Record<string, PropValue>>;
+
+/** Standard decorators cannot distinguish props from other fields in the TS type system. */
+export type ComponentFields<Instance extends Component> = {
+  [
+    Key in Exclude<keyof Instance, keyof Component> as Instance[Key] extends PropValue ? Key : never
+  ]?: Instance[Key];
+} & {
+  /** The saved size of a `resize: 'props'` component; other components reject it. */
+  readonly width?: number;
+  readonly height?: number;
+};
+
+export interface PropOptions {
+  readonly label?: string;
+  readonly unit?: string;
+  readonly min?: number;
+  readonly max?: number;
+  readonly step?: number;
+  readonly options?: readonly PropValue[];
+  readonly type?: 'color';
+  readonly notation?: 'si';
+}
+
+export interface ComponentOptions extends EditRules {
+  readonly type: string;
+  readonly name: string;
+  readonly category?: string;
+  readonly version?: number;
+  readonly migrate?: (props: ComponentProps, version: number) => ComponentProps;
+  /** Default size for `resize: 'props'`, in user units. Defaults to 100. */
+  readonly width?: number;
+  readonly height?: number;
+}
+
+export interface ComponentDefinition extends ComponentOptions {
+  readonly category: string;
+  readonly version: number;
+  readonly rotate: NonNullable<EditRules['rotate']>;
+  readonly flip: boolean;
+  readonly resize: NonNullable<EditRules['resize']>;
+}
+
+export interface ComponentClass<Instance extends Component = Component> extends ElementClass<
+  ComponentProps,
+  Instance
+> {
+  new (context: DrawingContext, props?: ComponentProps, existing?: SVGGElement): Instance;
+}
+
+/** An `@action` method: its name and undo label. */
+export interface ActionDefinition {
+  readonly name: string;
+  readonly label: string;
+}
+
+export interface PropDefinition extends PropOptions {
+  readonly name: string;
+  readonly initial: PropValue;
+}

package/src/components/view.ts

@@ -0,0 +1,123 @@
+import type { AnyNode } from '../core/types.js';
+import { Group } from '../elements/group.js';
+import { Renderer, type TemplateInstance } from '../template/render.js';
+import {
+  BindingPart,
+  TemplateCompiler,
+  type ContentItem,
+  type TemplateDescription,
+} from '../template/parts.js';
+import type { SvgTemplate } from '../template/svg-tag.js';
+import { Guards } from '../mixins/guards.js';
+import type { Component } from './component.js';
+import { destroySubtrees } from '../core/destruction.js';
+import { Attributes } from '../dom/attributes.js';
+
+/** Reuses saved wrappers when their structure matches the class's current template. */
+export class ComponentView {
+  #instance?: TemplateInstance;
+  #host?: AnyNode;
+  #strings?: TemplateStringsArray;
+  #parts: BindingPart[] = [];
+  readonly #owner: Component;
+  constructor(owner: Component) {
+    this.#owner = owner;
+  }
+
+  render(template: SvgTemplate): void {
+    if (
+      this.#instance &&
+      !this.#instance.isDestroyed &&
+      this.#instance.host.parent === this.#owner &&
+      this.#instance.template.strings === template.strings
+    ) {
+      this.#instance.update(template);
+      return;
+    }
+    if (
+      this.#host &&
+      !this.#host.isDestroyed &&
+      this.#host.parent === this.#owner &&
+      this.#strings === template.strings
+    ) {
+      this.#update(template);
+      return;
+    }
+    this.#parts = [];
+    // The first template-power phase owns structural holes; rebuild saved dynamic trees
+    // through its renderer instead of trying to infer their binding layout here.
+    const content = TemplateCompiler.content(this.#owner.context.dom, template.strings);
+    TemplateCompiler.validate(content, this.#owner.context.registry);
+    const descriptions = this.#hasChildHoles(content)
+      ? undefined
+      : content.filter((item): item is TemplateDescription => 'tag' in item);
+    const host = this.#owner.children.length === 1 ? this.#owner.children[0] : undefined;
+    if (
+      descriptions &&
+      host instanceof Group &&
+      this.#attributesMatch(host, {}) &&
+      this.#matches(host.children, descriptions)
+    ) {
+      this.#bind(host.children, descriptions);
+      this.#host = host;
+      this.#strings = template.strings;
+      this.#instance = undefined;
+      this.#update(template);
+      return;
+    }
+    const previous = [...this.#owner.children];
+    this.#instance = new Renderer(this.#owner).render(template);
+    if (previous.length) this.#owner[destroySubtrees](previous);
+    this.#host = undefined;
+    this.#strings = undefined;
+  }
+
+  #attributesMatch(node: AnyNode, attributes: Readonly<Record<string, unknown>>): boolean {
+    const names = node.attributes.entries().map(([name]) => name);
+    names.push(...node.el.getAttributeNames().map(Attributes.normalizeName));
+    return names.every((name) => Object.hasOwn(attributes, name));
+  }
+
+  #hasChildHoles(content: readonly ContentItem[]): boolean {
+    return content.some((item) => {
+      if (!('tag' in item)) return item.parts.some((part) => typeof part === 'number');
+      const Constructor = this.#owner.context.registry.get(item.tag);
+      return this.#hasChildHoles(Constructor?.isText ? item.children : item.content);
+    });
+  }
+
+  #matches(nodes: readonly AnyNode[], descriptions: readonly TemplateDescription[]): boolean {
+    return (
+      nodes.length === descriptions.length &&
+      nodes.every((node, index) => {
+        const description = descriptions[index];
+        return (
+          !(Guards.isTextual(node) && description.text.length && description.children.length) &&
+          node.el.localName === description.tag &&
+          this.#attributesMatch(node, description.attributes) &&
+          (Guards.isParent(node)
+            ? this.#matches(node.children, description.children)
+            : description.children.length === 0)
+        );
+      })
+    );
+  }
+
+  #bind(nodes: readonly AnyNode[], descriptions: readonly TemplateDescription[]): void {
+    nodes.forEach((node, index) => {
+      const description = descriptions[index];
+      for (const [name, parts] of Object.entries(description.attributes))
+        this.#parts.push(new BindingPart(node, name, parts));
+      if (description.text.length && Guards.isTextual(node)) {
+        this.#parts.push(new BindingPart(node, null, description.text));
+      }
+      if (Guards.isParent(node)) this.#bind(node.children, description.children);
+    });
+  }
+
+  #update(template: SvgTemplate): void {
+    const changes = this.#parts.map((part) => ({ part, value: part.evaluate(template.values) }));
+    for (const { part, value } of changes) part.validate(value);
+    for (const { part, value } of changes) part.commit(value);
+  }
+}

package/src/components.ts

@@ -0,0 +1,15 @@
+/** Opt-in class component rendering, saved props and temporary live state. */
+export { Component } from './components/component.js';
+export { component, prop, state, action } from './components/decorators.js';
+export { ComponentTypes, isComponentChild } from './components/registry.js';
+export type {
+  ActionDefinition,
+  ComponentClass,
+  ComponentDefinition,
+  ComponentFields,
+  ComponentOptions,
+  ComponentProps,
+  PropValue,
+  PropOptions,
+  PropDefinition,
+} from './components/types.js';

package/src/core/node.ts

@@ -4,7 +4,8 @@ import { Attributes } from '../dom/attributes.js';
 import { Emitter } from '../events/emitter.js';
 import { Matrix } from '../math/matrix.js';
 import type { DrawingContext } from '../services/context.js';
-import type { ElementClass } from '../services/types.js';
+import type { ElementClass, ElementVariant } from '../services/types.js';
+import { assertChildrenEditable, withOwnedChildren } from '../mixins/parent-internals.js';
 import type { ParentNode } from '../mixins/types.js';
 import type { AttributeValue, Bounds, CommonAttributes } from '../types/common.js';
 import type { AnyNode, NodeEvents } from './types.js';
@@ -28,6 +29,10 @@ export class Node<
   static readonly isText: boolean = false;
   static readonly childTags: readonly string[] | undefined = undefined;
   declare static readonly forbiddenDescendantTags: readonly string[] | undefined;
+  /** See `ElementVariant`: one `data-*` attribute value selects this class for its tag. */
+  static readonly variant: ElementVariant | undefined = undefined;
+  /** When true, only the class itself changes its children, through `withOwnChildren()`. */
+  static readonly ownsChildren: boolean = false;
 
   readonly el: Element;
   readonly attributes: Attributes;
@@ -61,6 +66,8 @@ export class Node<
     this.allowedAttributes = schema;
     for (const [name, value] of this.attributes.entries()) this.validateAttribute(name, value);
     if (!existing) {
+      const variant = Constructor.variant;
+      if (variant) this.setAttributeValue(variant.attribute, variant.value);
       this.attrs(options);
       for (const { attribute, initial } of fields)
         if (initial !== undefined && this.attributes.getNormalized(attribute) === undefined)
@@ -111,6 +118,19 @@ export class Node<
     name = Attributes.normalizeName(name);
     if (!this.allowedAttributes.has(name) && !/^(?:data|aria)-[\w-]+$/.test(name))
       throw new TypeError(`Unsupported attribute: ${name}`);
+    if (name.startsWith('data-')) {
+      // A variant's identifying attribute is fixed, and other classes can't claim its value.
+      const Constructor = this.constructor as ElementClass;
+      const variant = Constructor.variant;
+      if (
+        variant?.attribute === name
+          ? value !== variant.value
+          : value != null &&
+            (this.context.registry.variant(Constructor.tag, name, String(value)) ?? Constructor) !==
+              Constructor
+      )
+        throw new TypeError(`${name} selects the element class`);
+    }
     if (value != null) Attributes.normalize(name, value);
     if (name === 'transform' && value != null) Matrix.parse(String(value));
     if (
@@ -123,6 +143,12 @@ export class Node<
     (this.constructor as ElementClass)[validateAttributeValue]?.(name, value);
   }
 
+  /** For classes with `static ownsChildren`: change this node's own children. */
+  protected withOwnChildren<Result>(callback: () => Result): Result {
+    this.assertLive();
+    return withOwnedChildren(this, callback);
+  }
+
   getAttributeValue(name: string): string | number | undefined {
     this.assertLive();
     return this.attributes.get(name);
@@ -305,6 +331,7 @@ export class Node<
   remove(): this {
     return mutation(this, () => {
       this.assertLive();
+      assertChildrenEditable(this.parent);
       for (const node of this.descendants()) node.releaseCapturedPointers();
       this.detachNativeElement();
       this.context.bounds.invalidate();
@@ -316,6 +343,7 @@ export class Node<
   destroy(): void {
     if (this.isDestroyed) return;
     this.assertLive();
+    assertChildrenEditable(this.parent);
     this.context.defs.assertCanDestroy(
       new Set(this === this.context.root ? this.context.registry.nodes : this.descendants()),
     );
@@ -339,6 +367,9 @@ export class Node<
         disposalOrder.push(node);
       }
     }
+    // Preflight ownership before any disposal side effect; owners destroyed together pass.
+    for (const root of roots)
+      if (root.parent && !ownedNodes.has(root.parent)) assertChildrenEditable(root.parent);
     this.context.defs.assertCanDestroy(ownedNodes);
     this.context.changes.beforeDisposal([...ownedNodes]);
     for (const root of roots) this.context.changes.touchTree(root);

package/src/interchange/clone.ts

@@ -24,8 +24,9 @@ export function cloneNode<Node extends AnyNode>(source: Node, options: CloneOpti
     const originals = [source, ...dependencies];
     const copies = new Map<AnyNode, SVGElement>();
     const roots = originals.map((node) => snapshot(node, copies));
-    for (const original of copies.keys())
-      if (source.context.registry.get(original.el.localName) !== original.constructor)
+    // Copies are rebuilt by adoption, so each must resolve back to its original's class.
+    for (const [original, element] of copies)
+      if (source.context.registry.resolve(element) !== original.constructor)
         throw new TypeError('Clone requires the exact registered constructor for each managed tag');
     for (const original of copies.keys())
       if (Guards.isTransformable(original) && !original.geometryMatrix().inverse())

package/src/interchange/reconstruct.ts

@@ -8,6 +8,8 @@ import { validateNativeElement } from '../core/native-validation.js';
 import { destroySubtrees } from '../core/destruction.js';
 import { InterchangeDom } from './dom.js';
 import type { AttributeBindings } from '../catalog/namespaces.js';
+import { withInternalStructure } from '../mixins/parent-internals.js';
+import { withInitialization } from '../services/initialization.js';
 
 /** Pure validation for the complete forest, before Registry can claim a wrapper. */
 export function preflight(
@@ -16,7 +18,7 @@ export function preflight(
   schemas: ReadonlyMap<SVGElement, ReadonlySet<string>> = new Map(),
 ): void {
   function visit(element: SVGElement, forbidden: ReadonlySet<string>): void {
-    const Constructor = context.registry.get(element.localName) as ElementClass & {
+    const Constructor = context.registry.resolve(element) as ElementClass & {
       attributeBindings?: AttributeBindings;
     };
     if (
@@ -90,22 +92,24 @@ export function reconstruct<Result>(
 ): Result {
   const before = new Set(owner.context.registry.nodes);
   try {
-    const nodes = roots.map((element) => owner.context.registry.adopt(element));
-    for (const node of owner.context.registry.nodes)
-      if (!before.has(node))
-        for (const name of ['tabindex', 'role']) {
-          const value = node.el.getAttribute(name);
-          if (value !== null) {
-            node.defineAttribute(name);
-            node.setAttributeValue(name, value);
+    return withInitialization(() => {
+      const nodes = roots.map((element) => owner.context.registry.adopt(element));
+      for (const node of owner.context.registry.nodes)
+        if (!before.has(node))
+          for (const name of ['tabindex', 'role']) {
+            const value = node.el.getAttribute(name);
+            if (value !== null) {
+              node.defineAttribute(name);
+              node.setAttributeValue(name, value);
+            }
           }
-        }
-    return finish(nodes);
+      return finish(nodes);
+    });
   } catch (error) {
     const created = owner.context.registry.nodes.filter((node) => !before.has(node));
     if (created.length) {
       try {
-        owner[destroySubtrees](created);
+        withInternalStructure(() => owner[destroySubtrees](created));
       } catch (cleanupError) {
         throw new AggregateError(
           [error, cleanupError],

package/src/interchange/references.ts

@@ -1,5 +1,5 @@
 import type { AnyNode } from '../core/types.js';
-import { classifyReference, resolveReference } from '../resources/references.js';
+import { classifyReference, isLink, resolveReference } from '../resources/references.js';
 import { referenceValue } from '../services/reference-value.js';
 import { InterchangeDom } from './dom.js';
 import { XLINK_NAMESPACE } from '../catalog/namespaces.js';
@@ -10,10 +10,13 @@ export function dependencyRoots(source: AnyNode, references: 'typed' | 'local'):
   const pending = [...included];
   for (let index = 0; index < pending.length; index++) {
     const node = pending[index];
-    const targets = new Set(node.references.values());
+    // Links are not dependencies: copying a connector never copies the shapes it joins.
+    const targets = new Set(
+      [...node.references].filter(([name]) => !isLink(name)).map(([, target]) => target),
+    );
     if (references === 'local')
       for (const [name, value] of node.attributes.entries()) {
-        if (!classifyReference(name, value)) continue;
+        if (!classifyReference(name, value) || isLink(name)) continue;
         // Hyperlinks navigate; they are not rendering dependencies.
         if (name === 'href' && ['a', 'image'].includes(node.el.localName)) continue;
         const target = resolveReference(node, name);
@@ -87,10 +90,15 @@ export function restoreLocalReferences(nodes: readonly AnyNode[]): void {
       .map((node) => [String(node.getAttributeValue('id')), node]),
   );
   for (const node of all)
-    for (const [name, value] of node.attributes.entries()) {
+    for (const [name, value] of [...node.attributes.entries()]) {
       const reference = classifyReference(name, value);
       if (!reference) continue;
       const target = ids.get(reference.id);
+      // A connector pasted without its target keeps that end loose.
+      if (!target && isLink(name)) {
+        node.setAttributeValue(name, undefined);
+        continue;
+      }
       if (!target)
         throw new TypeError(`Local reference is outside the imported forest: ${reference.id}`);
       if (name === 'href' && ['a', 'image'].includes(node.el.localName)) continue;

package/src/mixins/parent-internals.ts

@@ -4,11 +4,48 @@ import { assertNotDestroying, pendingDestruction } from '../core/destruction.js'
 /** Structural preflight shared by Parent and the opt-in tree operations. */
 export const validateChild = Symbol('validateChild');
 
+let internalStructure = 0;
+const unlocked = new Set<AnyNode>();
+
+/** @internal Core's own exact-tree paths (adoption, replay, rollback) bypass child ownership. */
+export function withInternalStructure<Result>(callback: () => Result): Result {
+  internalStructure++;
+  try {
+    return callback();
+  } finally {
+    internalStructure--;
+  }
+}
+
+/** @internal Lets a node whose class owns its children change them inside the callback. */
+export function withOwnedChildren<Result>(parent: AnyNode, callback: () => Result): Result {
+  if (unlocked.has(parent)) return callback();
+  unlocked.add(parent);
+  try {
+    return callback();
+  } finally {
+    unlocked.delete(parent);
+  }
+}
+
+/** Throws for outside structural edits of a node whose class owns its children. */
+export function assertChildrenEditable(parent: AnyNode | null | undefined): void {
+  if (
+    parent &&
+    (parent.constructor as { readonly ownsChildren?: boolean }).ownsChildren &&
+    !internalStructure &&
+    !unlocked.has(parent) &&
+    !pendingDestruction.has(parent)
+  )
+    throw new Error('This node owns its children');
+}
+
 export function assertCanAddChildren(parent: AnyNode): void {
   parent.assertLive();
   // Whole-drawing teardown already cleans late subscriptions and registrations.
   const drawingCloses = parent.context.root && pendingDestruction.has(parent.context.root);
   if (!drawingCloses) assertNotDestroying(parent);
+  assertChildrenEditable(parent);
 }
 
 export function validateIndex(index: number, length: number): void {

package/src/mixins/parent.ts

@@ -1,11 +1,16 @@
 import { mutation } from '../changes/mutation.js';
 import type { Node } from '../core/node.js';
 import type { AnyNode } from '../core/types.js';
-import type { ElementClass } from '../services/types.js';
+import type { ElementClass, CreationOptions } from '../services/types.js';
 import { BBox } from '../math/bbox.js';
 import type { Bounds } from '../types/common.js';
 import type { MixinParent, NodeSelector } from './types.js';
-import { assertCanAddChildren, validateChild, validateIndex } from './parent-internals.js';
+import {
+  assertCanAddChildren,
+  assertChildrenEditable,
+  validateChild,
+  validateIndex,
+} from './parent-internals.js';
 import { assertNotDestroying } from '../core/destruction.js';
 
 export const Parent: MixinParent = (BaseClass) => {
@@ -50,6 +55,7 @@ export const Parent: MixinParent = (BaseClass) => {
     adopt(element: SVGElement): AnyNode {
       return mutation(this, () => {
         this.assertLive();
+        assertChildrenEditable(this);
         const siblings = this.context.dom.children(this.el);
         if (!siblings.includes(element))
           throw new Error('Element is not a native child of this parent');
@@ -93,6 +99,7 @@ export const Parent: MixinParent = (BaseClass) => {
     [validateChild](child: AnyNode): void {
       assertCanAddChildren(this);
       child.assertLive();
+      if (child.parent !== this) assertChildrenEditable(child.parent);
       assertNotDestroying(child);
       this.validateChildTag(this.context.dom.tag(child.el));
       if (child.context !== this.context) throw new Error('Cross-root moves are unsupported');
@@ -110,13 +117,13 @@ export const Parent: MixinParent = (BaseClass) => {
 
     create<Options, Child extends AnyNode>(
       Constructor: ElementClass<Options, Child>,
-      options: Options,
+      options: NoInfer<CreationOptions<Options, Child>>,
     ): Child {
       return mutation(this, () => {
         assertCanAddChildren(this);
         this.validateChildTag(Constructor.tag);
         this.context.registry.register(Constructor);
-        return this.add(new Constructor(this.context, options));
+        return this.add(new Constructor(this.context, options as Options));
       });
     }
 
@@ -128,6 +135,7 @@ export const Parent: MixinParent = (BaseClass) => {
 
     detachChild(child: AnyNode): void {
       return mutation(this, () => {
+        assertChildrenEditable(this);
         const index = this.#children.indexOf(child);
         if (index >= 0) {
           this.context.changes.touch(child);
@@ -139,6 +147,7 @@ export const Parent: MixinParent = (BaseClass) => {
     }
 
     private childrenChanged(): void {
+      this.context.changes.invalidateOrder(this);
       this.context.bounds.invalidate();
       this.context.defs.invalidateHost(this);
     }

package/src/mixins/types.ts

@@ -16,7 +16,7 @@ import type { Text } from '../elements/text.js';
 import type { Use } from '../elements/use.js';
 import type { Matrix } from '../math/matrix.js';
 import type { Vec2 } from '../math/vec2.js';
-import type { ElementClass } from '../services/types.js';
+import type { ElementClass, CreationOptions } from '../services/types.js';
 import type {
   CommonAttributes,
   Bounds,
@@ -62,7 +62,7 @@ export interface ParentFeature {
   detachChild(child: AnyNode): void;
   create<Options, Child extends AnyNode>(
     Constructor: ElementClass<Options, Child>,
-    options: Options,
+    options: NoInfer<CreationOptions<Options, Child>>,
   ): Child;
   remove(): this;
   remove(child: AnyNode): this;

package/src/resources/references.ts

@@ -30,16 +30,16 @@ function localReference(
   }
 }
 
+/** Connector ends link to their targets; the targets are not rendering resources. */
+export const isLink = (attribute: string): boolean =>
+  attribute === 'data-rasam-connector-start' || attribute === 'data-rasam-connector-end';
+
 /** Classifies local fragments for lookup/remapping; it never acquires a typed binding. */
 export function classifyReference(attribute: string, value: unknown): LocalReference | null {
   attribute = Attributes.normalizeName(attribute);
   if (typeof value !== 'string') return null;
   const source = value.replace(/^[ \t\r\n\f]+|[ \t\r\n\f]+$/g, '');
-  if (
-    attribute === 'href' ||
-    attribute === 'data-rasam-connector-start' ||
-    attribute === 'data-rasam-connector-end'
-  ) {
+  if (attribute === 'href' || isLink(attribute)) {
     const match = /^#([^\s#<>"'()\\\u0000-\u001f\u007f]+)$/.exec(source);
     return localReference('href', match?.[1]);
   }

package/src/services/catalog.ts

@@ -1,14 +1,16 @@
 import type { Registry } from './registry.js';
+import { elementKey } from './element-key.js';
 import type { ElementClass } from './types.js';
 
 /** Preflight a per-drawing catalog before changing the registry. */
 export function registerElements(registry: Registry, elements: readonly ElementClass[]): void {
   const pending = new Map<string, ElementClass>();
   for (const Constructor of elements) {
-    const previous = pending.get(Constructor.tag) ?? registry.get(Constructor.tag);
+    const key = elementKey(Constructor);
+    const previous = pending.get(key) ?? registry.registered(Constructor);
     if (previous && previous !== Constructor)
-      throw new Error(`Tag already registered: ${Constructor.tag}`);
-    pending.set(Constructor.tag, Constructor);
+      throw new Error(`${Constructor.variant ? 'Variant' : 'Tag'} already registered: ${key}`);
+    pending.set(key, Constructor);
   }
   for (const Constructor of pending.values()) registry.register(Constructor);
 }

package/src/services/claims.ts

@@ -0,0 +1,14 @@
+import type { AnyNode } from '../core/types.js';
+
+/** Internal claim order. A node keeps the number from its first claim, even if reclaimed. */
+const claimOrder = new WeakMap<AnyNode, number>();
+/** Claims so far: a constant-time marker for `claimedSince`, instead of copying every node. */
+export let claims = 0;
+
+export function recordClaim(node: AnyNode): void {
+  if (!claimOrder.has(node)) claimOrder.set(node, ++claims);
+}
+
+/** Registered nodes first claimed after `mark`, in `nodes` order (pass `registry.nodes`). */
+export const claimedSince = (nodes: readonly AnyNode[], mark: number): AnyNode[] =>
+  nodes.filter((node) => claimOrder.get(node)! > mark);

package/src/services/defs-manager.ts

@@ -56,6 +56,11 @@ export class DefsManager {
     return count;
   }
 
+  /** Nodes holding a typed reference to `target`, detached ones included, from the index. */
+  consumersOf(target: AnyNode): AnyNode[] {
+    return [...(this.consumersByTarget.get(target)?.keys() ?? [])];
+  }
+
   *geometryConsumers(target: AnyNode): IterableIterator<AnyNode> {
     for (const [consumer, attributes] of this.consumersByTarget.get(target) ?? [])
       if (attributes.has('href')) yield consumer;

package/src/services/element-key.ts

@@ -0,0 +1,14 @@
+import type { ElementClass } from './types.js';
+
+/** A tag, or `tag[attribute="value"]` for a variant. Variants share the constructor map. */
+export function elementKey(Constructor: ElementClass): string {
+  const variant = Constructor.variant;
+  if (!variant) return Constructor.tag;
+  if (
+    !/^data-[a-z0-9_.-]+$/.test(variant.attribute) ||
+    typeof variant.value != 'string' ||
+    !variant.value
+  )
+    throw new TypeError('Variants need a lowercase data-* attribute and a value');
+  return `${Constructor.tag}[${variant.attribute}="${variant.value}"]`;
+}

package/src/services/initialization.ts

@@ -0,0 +1,25 @@
+import type { AnyNode } from '../core/types.js';
+
+/** Internal extension hook, after the entire native/reconstructed tree is available. */
+export const initializeElement = Symbol('init');
+type Initializable = AnyNode & { [initializeElement]?: () => void };
+let pending: Initializable[] | undefined;
+
+export function initializeNode(node: AnyNode): void {
+  if (pending) pending.push(node);
+  else (node as Initializable)[initializeElement]?.();
+}
+
+/** Delay hooks until clone/import has restored references and copied model features. */
+export function withInitialization<Result>(callback: () => Result): Result {
+  if (pending) return callback();
+  pending = [];
+  try {
+    const result = callback();
+    // Initializers are idempotent; nested adoptions can append work while hooks run.
+    for (const node of pending) if (!node.isDestroyed) node[initializeElement]?.();
+    return result;
+  } finally {
+    pending = undefined;
+  }
+}