@rasamjs/core 0.1.2 → 0.3.0

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/transformable.ts

@@ -53,8 +53,8 @@ export const Transformable: MixinTransformable = (BaseClass) => {
     matrix(): Matrix;
     matrix(value: Matrix | MatrixValues): this;
     matrix(value?: Matrix | MatrixValues): Matrix | this {
+      if (value === undefined) return this.localMatrix();
       return mutation(this, () => {
-        if (value === undefined) return this.localMatrix();
         this.assertLive();
         const matrix = Matrix.from(value);
         this.#matrixMode = true;
@@ -110,33 +110,31 @@ export const Transformable: MixinTransformable = (BaseClass) => {
     transformState(): TransformState;
     transformState(state: TransformState): this;
     transformState(state?: TransformState): TransformState | this {
-      return mutation(this, () => {
-        this.assertLive();
-        if (state !== undefined) return this.restoreTransformState(state);
-        const { base, geometry } = this.mappingState();
-        const transform = this.getAttributeValue('transform');
-        const common = {
-          tag: this.context.dom.tag(this.el),
-          transform: transform === undefined ? null : String(transform),
-          geometry: Object.freeze(geometry.toArray()),
-          attributes: geometrySnapshot(this),
-        };
-        if (this.#matrixMode || transform !== this.#lastTransform)
-          return Object.freeze({
-            ...common,
-            mode: 'matrix',
-            matrix: Object.freeze(base.toArray()),
-          });
-        const components = this.components;
+      this.assertLive();
+      if (state !== undefined) return mutation(this, () => this.restoreTransformState(state));
+      const { base, geometry } = this.mappingState();
+      const transform = this.getAttributeValue('transform');
+      const common = {
+        tag: this.context.dom.tag(this.el),
+        transform: transform === undefined ? null : String(transform),
+        geometry: Object.freeze(geometry.toArray()),
+        attributes: geometrySnapshot(this),
+      };
+      if (this.#matrixMode || transform !== this.#lastTransform)
         return Object.freeze({
           ...common,
-          mode: 'components',
-          position: components.position,
-          rotation: components.rotation,
-          scale: components.scale,
-          origin: components.origin,
-          automaticOrigin: !components.explicitOrigin,
+          mode: 'matrix',
+          matrix: Object.freeze(base.toArray()),
         });
+      const components = this.components;
+      return Object.freeze({
+        ...common,
+        mode: 'components',
+        position: components.position,
+        rotation: components.rotation,
+        scale: components.scale,
+        origin: components.origin,
+        automaticOrigin: !components.explicitOrigin,
       });
     }
 

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/raster/frame.ts

@@ -0,0 +1,53 @@
+import type { AnyNode } from '../core/types.js';
+import { exportSvg } from '../interchange/markup.js';
+import type { RasterOptions } from './types.js';
+export function prepareRaster(root: AnyNode, options: RasterOptions) {
+  root.assertLive();
+  const document = root.el.ownerDocument,
+    view = document.defaultView;
+  if (!view) throw new Error('Raster export needs a browser document');
+  const type = options.type ?? 'image/png',
+    scale = options.scale ?? 1,
+    frame = options.frame ?? 'content',
+    padding = options.padding ?? 0;
+  if (!['image/png', 'image/webp', 'image/jpeg'].includes(type))
+    throw new TypeError('Unknown raster image type');
+  if (!Number.isFinite(scale) || scale <= 0)
+    throw new RangeError('Raster scale must be positive and finite');
+  if (!Number.isFinite(padding) || padding < 0)
+    throw new RangeError('Raster padding must be nonnegative and finite');
+  if (!['content', 'viewBox'].includes(frame)) throw new TypeError('Unknown raster frame');
+  const background = options.background ?? (type === 'image/jpeg' ? '#ffffff' : undefined);
+  if (
+    background !== undefined &&
+    (typeof background !== 'string' || !view.CSS.supports('color', background))
+  )
+    throw new TypeError('Raster background must be a CSS color');
+  const markup = exportSvg(root, { frame: frame === 'content' ? 'content' : undefined, padding });
+  const svg = new view.DOMParser().parseFromString(markup, 'image/svg+xml').documentElement;
+  const box = svg
+    .getAttribute('viewBox')
+    ?.trim()
+    .split(/[\s,]+/)
+    .map(Number);
+  const extent = root.context.root!.el.getBoundingClientRect();
+  const length = (name: 'width' | 'height', fallback: number) => {
+    const value = svg.getAttribute(name) ?? '';
+    return /^\d+(?:\.\d+)?(?:px)?$/.test(value) ? parseFloat(value) : fallback;
+  };
+  const width = box?.length === 4 ? box[2] : length('width', extent.width),
+    height = box?.length === 4 ? box[3] : length('height', extent.height);
+  const pixels = [Math.ceil(width * scale), Math.ceil(height * scale)];
+  if (
+    !pixels.every((value) => Number.isSafeInteger(value) && value > 0 && value <= 32767) ||
+    pixels[0] * pixels[1] > 16777216
+  )
+    throw new RangeError(
+      'Raster export needs positive dimensions, at most 32767 per axis and 16777216 pixels; reduce scale or add padding to zero-size content',
+    );
+  svg.setAttribute('width', String(pixels[0]));
+  svg.setAttribute('height', String(pixels[1]));
+  if (!box) svg.setAttribute('viewBox', `0 0 ${width} ${height}`);
+  return { document, svg, type, background, width: pixels[0], height: pixels[1] };
+}
+export type RasterSnapshot = ReturnType<typeof prepareRaster>;

package/src/raster/images.ts

@@ -0,0 +1,73 @@
+/** Inline supported image resources; SVG-as-image rendering cannot load external files. */
+const xlink = 'http://www.w3.org/1999/xlink';
+export async function embedImages(
+  svg: Element,
+  document: Document,
+  base: string,
+  ancestors: readonly string[] = [],
+): Promise<void> {
+  const view = document.defaultView!;
+  for (const image of svg.querySelectorAll('image,feImage')) {
+    const href = image.getAttribute('href') ?? image.getAttributeNS(xlink, 'href');
+    if (!href || href.startsWith('#')) continue;
+    const url = new URL(href, base);
+    if (
+      url.protocol !== 'data:' &&
+      (!['http:', 'https:'].includes(url.protocol) || url.origin !== new URL(document.URL).origin)
+    )
+      throw new Error('Raster export supports only same-origin and data-URL images');
+    if (ancestors.length >= 8 || ancestors.includes(url.href))
+      throw new Error('Raster image resources are cyclic or too deeply nested');
+    let blob: Blob;
+    try {
+      const response = await view.fetch(
+        url.href,
+        url.protocol === 'data:'
+          ? {}
+          : { mode: 'same-origin', credentials: 'same-origin', redirect: 'error' },
+      );
+      if (!response.ok) throw new Error(`HTTP ${response.status}`);
+      blob = await response.blob();
+    } catch (cause) {
+      throw new Error('Cannot load a raster image resource', { cause });
+    }
+    const mime = blob.type.split(';')[0].toLowerCase();
+    if (
+      ![
+        'image/png',
+        'image/jpeg',
+        'image/webp',
+        'image/gif',
+        'image/avif',
+        'image/svg+xml',
+      ].includes(mime)
+    )
+      throw new Error('Unsupported raster image resource type');
+    if (mime === 'image/svg+xml') {
+      const nested = new view.DOMParser().parseFromString(await blob.text(), 'image/svg+xml');
+      if (nested.querySelector('parsererror') || nested.documentElement.localName !== 'svg')
+        throw new Error('Invalid SVG image resource');
+      await embedImages(
+        nested.documentElement,
+        document,
+        url.protocol === 'data:' ? base : url.href,
+        [...ancestors, url.href],
+      );
+      blob = new view.Blob([new view.XMLSerializer().serializeToString(nested)], { type: mime });
+    }
+    const data = await new Promise<string>((resolve, reject) => {
+      const reader = new view.FileReader();
+      reader.onload = () => resolve(String(reader.result));
+      reader.onerror = () => reject(new Error('Cannot encode a raster image resource'));
+      reader.readAsDataURL(blob);
+    });
+    await new Promise<void>((resolve, reject) => {
+      const decoded = new view.Image();
+      decoded.onload = () => resolve();
+      decoded.onerror = () => reject(new Error('Cannot decode a raster image resource'));
+      decoded.src = data;
+    });
+    image.removeAttributeNS(xlink, 'href');
+    image.setAttribute('href', data);
+  }
+}

package/src/raster/render.ts

@@ -0,0 +1,45 @@
+import type { RasterSnapshot } from './frame.js';
+export async function renderRaster({
+  document,
+  svg,
+  type,
+  background,
+  width,
+  height,
+}: RasterSnapshot): Promise<Blob> {
+  const view = document.defaultView!;
+  const url = view.URL.createObjectURL(
+    new view.Blob([new view.XMLSerializer().serializeToString(svg)], { type: 'image/svg+xml' }),
+  );
+  try {
+    const image = new view.Image();
+    await new Promise<void>((resolve, reject) => {
+      image.onload = () => resolve();
+      image.onerror = () => reject(new Error('Cannot decode SVG for raster export'));
+      image.src = url;
+    });
+    const canvas = document.createElement('canvas');
+    canvas.width = width;
+    canvas.height = height;
+    const context = canvas.getContext('2d');
+    if (!context) throw new Error('Raster export needs a 2D canvas context');
+    if (background !== undefined) {
+      context.fillStyle = background;
+      context.fillRect(0, 0, canvas.width, canvas.height);
+    }
+    context.drawImage(image, 0, 0, canvas.width, canvas.height);
+    return await new Promise<Blob>((resolve, reject) =>
+      canvas.toBlob((blob) => {
+        if (!blob) reject(new Error('Browser could not encode the raster image'));
+        else if (blob.type !== type) reject(new Error(`Browser cannot encode ${type}`));
+        else resolve(blob);
+      }, type),
+    );
+  } catch (cause) {
+    if ((cause as { name?: string })?.name === 'SecurityError')
+      throw new Error('Cannot export image: canvas is tainted by cross-origin content', { cause });
+    throw cause;
+  } finally {
+    view.URL.revokeObjectURL(url);
+  }
+}

package/src/raster/types.ts

@@ -0,0 +1,9 @@
+export interface RasterOptions {
+  readonly type?: 'image/png' | 'image/webp' | 'image/jpeg';
+  readonly scale?: number;
+  readonly background?: string;
+  /** Content bounds by default; viewBox exports the current document camera. */
+  readonly frame?: 'content' | 'viewBox';
+  /** Drawing units around content bounds, default zero. */
+  readonly padding?: number;
+}

package/src/raster.ts

@@ -0,0 +1,13 @@
+import type { AnyNode } from './core/types.js';
+import type { RasterOptions } from './raster/types.js';
+import { prepareRaster } from './raster/frame.js';
+import { embedImages } from './raster/images.js';
+import { renderRaster } from './raster/render.js';
+export type { RasterOptions };
+
+/** Snapshot and render a passive SVG document without changing its camera or model. */
+export async function exportImage(root: AnyNode, options: RasterOptions = {}): Promise<Blob> {
+  const snapshot = prepareRaster(root, options);
+  await embedImages(snapshot.svg, snapshot.document, root.el.baseURI);
+  return renderRaster(snapshot);
+}

package/src/resources/references.ts

@@ -30,12 +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') {
+  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/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;
+  }
+}

package/src/services/registry.ts

@@ -4,6 +4,9 @@ import { validateAttributeValue } from '../core/attribute-validation.js';
 import { validateNativeElement } from '../core/native-validation.js';
 import type { AnyNode } from '../core/types.js';
 import type { ParentNode } from '../mixins/types.js';
+import { withInternalStructure } from '../mixins/parent-internals.js';
+import { elementKey } from './element-key.js';
+import { initializeNode, withInitialization } from './initialization.js';
 import type { DrawingContext } from './context.js';
 import type { ElementClass } from './types.js';
 
@@ -11,6 +14,8 @@ export class Registry {
   private static readonly identity = new WeakMap<SVGElement, AnyNode>();
   private readonly wrappers = new Map<SVGElement, AnyNode>();
   private readonly constructors = new Map<string, ElementClass>();
+  /** Tags that have variants, with the attributes that select them. */
+  private readonly variantAttributes = new Map<string, Set<string>>();
 
   constructor(private readonly context: DrawingContext) {}
 
@@ -19,18 +24,45 @@ export class Registry {
   }
 
   register<Options, Result extends AnyNode>(Constructor: ElementClass<Options, Result>): this {
-    const previous = this.constructors.get(Constructor.tag);
+    const key = elementKey(Constructor);
+    const previous = this.constructors.get(key);
     if (previous === Constructor) return this;
-    if (previous && previous !== Constructor)
-      throw new Error(`Tag already registered: ${Constructor.tag}`);
-    this.constructors.set(Constructor.tag, Constructor);
+    if (previous)
+      throw new Error(`${Constructor.variant ? 'Variant' : 'Tag'} already registered: ${key}`);
+    this.constructors.set(key, Constructor);
+    const variant = Constructor.variant;
+    if (variant) {
+      const attributes = this.variantAttributes.get(Constructor.tag) ?? new Set<string>();
+      this.variantAttributes.set(Constructor.tag, attributes.add(variant.attribute));
+    }
     return this;
   }
 
+  /** The tag's base constructor, ignoring variants. */
   get(tag: string): ElementClass | undefined {
     return this.constructors.get(tag);
   }
 
+  /** The constructor registered for the same tag or variant as `Constructor`, if any. */
+  registered(Constructor: ElementClass): ElementClass | undefined {
+    return this.constructors.get(elementKey(Constructor));
+  }
+
+  variant(tag: string, attribute: string, value: string): ElementClass | undefined {
+    return this.constructors.get(`${tag}[${attribute}="${value}"]`);
+  }
+
+  /** The constructor for a native element: a matching variant, else the tag's base. */
+  resolve(element: SVGElement): ElementClass | undefined {
+    const tag = this.context.dom.tag(element);
+    for (const attribute of this.variantAttributes.get(tag) ?? []) {
+      const value = element.getAttribute(attribute);
+      const Constructor = value === null ? undefined : this.variant(tag, attribute, value);
+      if (Constructor) return Constructor;
+    }
+    return this.constructors.get(tag);
+  }
+
   /** Creates a fresh wrapper for binding initialization, without constructor defaults or mounting. */
   createEmpty(tag: string, context = this.context): AnyNode {
     const Constructor = this.get(tag);
@@ -61,6 +93,7 @@ export class Registry {
     for (const node of this.wrappers.values()) this.forget(node);
     this.wrappers.clear();
     this.constructors.clear();
+    this.variantAttributes.clear();
   }
 
   adopt(element: SVGElement, parent?: ParentNode): AnyNode {
@@ -77,14 +110,17 @@ export class Registry {
       ancestor;
       ancestor = this.context.dom.svgParent(ancestor)
     ) {
-      const Constructor = this.get(this.context.dom.tag(ancestor));
+      const Constructor = this.resolve(ancestor);
       if (Constructor?.opaqueContent)
         throw new Error('Cannot adopt descendants across an opaque native boundary');
       for (const tag of Constructor?.forbiddenDescendantTags ?? []) forbidden.add(tag);
     }
     this.validateTree(element, forbidden);
-    const wrapped = this.wrapTree(element);
-    return parent ? parent.add(wrapped) : wrapped;
+    // Adoption reproduces a native tree exactly, so it may fill owned children.
+    return withInitialization(() => {
+      const wrapped = withInternalStructure(() => this.wrapTree(element));
+      return parent ? parent.add(wrapped) : wrapped;
+    });
   }
 
   private assertAdoptionParent(parent: ParentNode | undefined): void {
@@ -103,7 +139,7 @@ export class Registry {
       if (existing.context !== this.context) throw new Error('Cross-root adoption is unsupported');
       return;
     }
-    const Constructor = this.get(tag);
+    const Constructor = this.resolve(element);
     if (!this.context.dom.isSvg(element) || !Constructor)
       throw new TypeError(`Unsupported SVG tag: ${tag}`);
     Constructor[validateNativeElement]?.(element);
@@ -130,16 +166,17 @@ export class Registry {
   private wrapTree(element: SVGElement): AnyNode {
     const existing = Registry.wrapper(element);
     if (existing) return existing;
-    const Constructor = this.get(this.context.dom.tag(element));
+    const Constructor = this.resolve(element)!;
     const children = this.managedChildren(element);
     const node = new Constructor(this.context, {}, element);
     if (Constructor.isContainer)
       (node as ParentNode).adoptChildren(children.map((child) => this.wrapTree(child)));
+    initializeNode(node);
     return node;
   }
 
   private managedChildren(element: SVGElement): SVGElement[] {
-    const Constructor = this.get(this.context.dom.tag(element));
+    const Constructor = this.resolve(element);
     if (Constructor?.opaqueContent) return [];
     return this.context.dom
       .children(element)

package/src/services/types.ts

@@ -7,6 +7,23 @@ import { validateNativeElement } from '../core/native-validation.js';
 
 // Registry
 
+/** Type-only capability for constructors whose options come from instance fields. */
+export declare const creationOptions: unique symbol;
+export type CreationOptions<Options, Instance> = Instance extends {
+  readonly [creationOptions]: infer Fields;
+}
+  ? Fields
+  : Options;
+
+/**
+ * Selects a subclass for elements that share a tag, by the exact value of one `data-*`
+ * attribute. Instances always carry that value, and it can't change.
+ */
+export interface ElementVariant {
+  readonly attribute: string;
+  readonly value: string;
+}
+
 export interface ElementClass<Options = any, Result extends AnyNode = AnyNode> {
   readonly tag: string;
   readonly attributeNames: readonly string[];
@@ -15,6 +32,10 @@ export interface ElementClass<Options = any, Result extends AnyNode = AnyNode> {
   readonly childTags?: readonly string[] | undefined;
   readonly forbiddenDescendantTags?: readonly string[] | undefined;
   readonly opaqueContent?: boolean;
+  /** Registers the class for one attribute value of its tag instead of the whole tag. */
+  readonly variant?: ElementVariant | undefined;
+  /** Children belong to the class: outside structural edits throw. */
+  readonly ownsChildren?: boolean;
   [validateAttributeValue]?(name: string, value: AttributeValue): void;
   [validateNativeElement]?(element: SVGElement): void;
   new (context: DrawingContext, options: Options, existing?: any): Result;