@rasamjs/core 0.1.2 → 0.3.0

package/src/components/component.ts

@@ -0,0 +1,401 @@
+import { Group } from '../elements/group.js';
+import type { DrawingContext } from '../services/context.js';
+import type { SvgTemplate } from '../template/svg-tag.js';
+import { beginChangeGroup } from '../changes.js';
+import { derivesChildren, markDerived } from '../changes/derived.js';
+import { initializeElement } from '../services/initialization.js';
+import { definition, isSize, validatePorts, validateProp } from './metadata.js';
+import { ComponentView } from './view.js';
+import { ComponentChanges } from './changes.js';
+import { Attributes } from '../dom/attributes.js';
+import type { AttributeValue, Length, PortDefinition } from '../types/common.js';
+import type { creationOptions } from '../services/types.js';
+import type {
+  ActionDefinition,
+  ComponentDefinition,
+  ComponentProps,
+  PropDefinition,
+  PropOptions,
+  PropValue,
+  ComponentFields,
+} from './types.js';
+
+export const installField = Symbol('installComponentField');
+export const assertField = Symbol('assertComponentField');
+export const editComponent = Symbol('editComponent');
+export const registerAction = Symbol('registerComponentAction');
+const restoredHooks = new WeakSet<Component>();
+interface Field {
+  readonly kind: 'prop' | 'state';
+  readonly initial: unknown;
+  readonly options: PropOptions;
+  value: unknown;
+}
+const sizes = ['width', 'height'] as const;
+const copy = <Value>(value: Value): Value =>
+  value && typeof value === 'object' ? structuredClone(value) : value;
+
+/** A closed rasam group whose children are rendered from decorated props and live state. */
+export abstract class Component extends Group {
+  declare readonly [creationOptions]: ComponentFields<this>;
+  static override readonly ownsChildren = true;
+  /** @internal History restores props; the component redraws its children after replay. */
+  static readonly [derivesChildren] = true;
+  readonly #fields = new Map<string, Field>();
+  readonly #view = new ComponentView(this);
+  #initialized = false;
+  #constructing = true;
+  #schedule?: () => void;
+  #observedProps: ComponentProps = {};
+  #propsCache?: { raw: string | number | undefined; props: ComponentProps };
+  #propDefinitions?: readonly PropDefinition[];
+  readonly #actions = new Map<string, string>();
+  #ports?: { props: ComponentProps; ports: readonly PortDefinition[] };
+  #readingPorts = false;
+
+  readonly #input: ComponentProps;
+  readonly #reserved: ReadonlySet<string>;
+
+  constructor(context: DrawingContext, input: ComponentProps = {}, existing?: SVGGElement) {
+    super(context, {}, existing);
+    this.#input = input;
+    this.#reserved = new Set(Object.getOwnPropertyNames(this));
+  }
+
+  get componentDefinition(): ComponentDefinition {
+    return definition(this.constructor);
+  }
+  get editRules() {
+    const { rotate, flip, resize } = this.componentDefinition;
+    return Object.freeze({ rotate, flip, resize });
+  }
+  get propDefinitions(): readonly PropDefinition[] {
+    return (this.#propDefinitions ??= Object.freeze(
+      [...this.#fields]
+        .filter(([, field]) => field.kind === 'prop')
+        .map(([name, field]) =>
+          Object.freeze({ ...field.options, name, initial: field.initial as PropValue }),
+        ),
+    ));
+  }
+
+  /** `@action` methods with their undo labels, in declaration order; overrides relabel. */
+  get actionDefinitions(): readonly ActionDefinition[] {
+    return Object.freeze([...this.#actions].map(([name, label]) => Object.freeze({ name, label })));
+  }
+
+  /** @internal The `@action` decorator records each method once per instance. */
+  [registerAction](name: string, label: string): void {
+    this.#actions.set(name, label);
+  }
+
+  render(): SvgTemplate {
+    throw new TypeError('Components must implement render()');
+  }
+
+  /**
+   * Override to declare connection points, in local coordinates at 0°, from props and
+   * the saved size. Live state never moves a port. Defaults to none.
+   */
+  ports(): readonly PortDefinition[] {
+    return [];
+  }
+
+  /** Validated, frozen `ports()`, computed again only when the saved props change. */
+  get portDefinitions(): readonly PortDefinition[] {
+    const props = this.#readProps();
+    if (this.#ports?.props === props) return this.#ports.ports;
+    this.#readingPorts = true;
+    try {
+      const ports = validatePorts(this.ports());
+      this.#ports = { props, ports };
+      return ports;
+    } finally {
+      this.#readingPorts = false;
+    }
+  }
+  created(): void {}
+  destroyed(): void {}
+  changed(_name: string): void {}
+
+  override validateAttribute(name: string, value: AttributeValue): void {
+    super.validateAttribute(name, value);
+    if (
+      Attributes.normalizeName(name) === 'data-rasam-props' &&
+      #initialized in this &&
+      this.#initialized
+    )
+      this.#assertProps(parseProps(value));
+  }
+
+  override setAttributeValue(name: string, value: AttributeValue): this {
+    if (restoredHooks.has(this) && Attributes.normalizeName(name) === 'data-rasam-props')
+      return this;
+    return super.setAttributeValue(name, value);
+  }
+
+  override attrs(values: Parameters<Group['attrs']>[0]): this {
+    if (restoredHooks.has(this))
+      values = Object.fromEntries(
+        Object.entries(values).filter(
+          ([name]) => Attributes.normalizeName(name) !== 'data-rasam-props',
+        ),
+      );
+    return super.attrs(values);
+  }
+
+  /** `resize: 'props'` components keep their size as saved `width` and `height` props. */
+  get #sized(): boolean {
+    return this.componentDefinition.resize === 'props';
+  }
+
+  override width(): Length | null;
+  override width(value: Length): this;
+  override width(value?: Length): Length | null | this {
+    if (!this.#sized) return value === undefined ? super.width() : super.width(value);
+    return value === undefined ? this.#size('width') : this.size(value, this.#size('height'));
+  }
+  override height(): Length | null;
+  override height(value: Length): this;
+  override height(value?: Length): Length | null | this {
+    if (!this.#sized) return value === undefined ? super.height() : super.height(value);
+    return value === undefined ? this.#size('height') : this.size(this.#size('width'), value);
+  }
+
+  /** For `resize: 'props'`, one undo step that redraws at once, so callers read new bounds. */
+  override size(width: Length, height?: Length): this {
+    if (!this.#sized) return super.size(width, height);
+    this.assertLive();
+    const next = {
+      width: toSize(width),
+      height: height === undefined ? undefined : toSize(height),
+    };
+    const target = {
+      width: next.width,
+      height: next.height ?? (next.width * this.#size('height')) / this.#size('width'),
+    };
+    if (restoredHooks.has(this)) return this;
+    if (target.width === this.#size('width') && target.height === this.#size('height')) return this;
+    this[editComponent](`Resize ${this.componentDefinition.name}`, () => {
+      this.setAttributeValue(
+        'data-rasam-props',
+        JSON.stringify({ ...this.#readProps(), ...target }),
+      );
+    });
+    if (this.#initialized && this.#notifyProps()) this.#redraw();
+    return this;
+  }
+
+  #size(name: (typeof sizes)[number]): number {
+    const saved = this.#readProps()[name] ?? this.#input[name];
+    return isSize(saved) ? saved : this.componentDefinition[name]!;
+  }
+
+  resetState(): void {
+    this.assertLive();
+    for (const [name, field] of this.#fields)
+      if (field.kind === 'state') Reflect.set(this, name, copy(field.initial));
+  }
+
+  /** @internal Called after decorated fields and reconstructed children are available. */
+  [initializeElement](): void {
+    if (this.#initialized) return;
+    const metadata = this.componentDefinition;
+    const saved = this.#readProps();
+    const rawVersion = this.getAttributeValue('data-rasam-version');
+    const version = rawVersion === undefined ? metadata.version : Number(rawVersion);
+    if (!Number.isInteger(version) || version < 1 || version > metadata.version)
+      throw new TypeError(`Unsupported ${metadata.type} component version: ${rawVersion}`);
+    if (version < metadata.version && !metadata.migrate)
+      throw new TypeError(`No migration for ${metadata.type} version ${version}`);
+    const values = version < metadata.version ? metadata.migrate!(saved, version) : saved;
+    this.#assertProps(values);
+    this.#assertProps(this.#input);
+    const props: Record<string, PropValue> = {};
+    for (const [name, field] of this.#fields)
+      if (field.kind === 'prop') {
+        const value = Object.hasOwn(this.#input, name)
+          ? this.#input[name]
+          : Object.hasOwn(values, name)
+            ? values[name]
+            : field.initial;
+        validateProp(value, field.initial as PropValue, field.options, name);
+        props[name] = value;
+      }
+    if (metadata.resize === 'props')
+      for (const name of sizes)
+        props[name] = (this.#input[name] ?? values[name] ?? metadata[name]) as number;
+    this.#initialized = true;
+    if (!this.context.changes.replaying) {
+      this.setAttributeValue('data-rasam-version', metadata.version);
+      this.setAttributeValue('data-rasam-props', JSON.stringify(props));
+      this.#redraw();
+    }
+    this.#observedProps = this.#readProps();
+    const changes = ComponentChanges.for(this);
+    const binding = {
+      node: this,
+      derive: () => {
+        if (this.#notifyProps()) this.#redraw();
+      },
+      replay: () => {
+        this.#notifyProps();
+      },
+      paint: () => this.#redraw(),
+    };
+    const stop = changes.bind(binding);
+    this.#schedule = () => changes.schedule(binding);
+    this.onDispose(() => {
+      stop();
+      this.destroyed();
+    });
+    this.context.changes.local(() => {
+      if (this.adopting) restoredHooks.add(this);
+      try {
+        this.created();
+      } finally {
+        restoredHooks.delete(this);
+        this.#constructing = false;
+      }
+      // A newly constructed, detached node is not eligible for change derivation yet.
+      if (this.#readProps() !== this.#observedProps && this.#notifyProps()) this.#redraw();
+    });
+  }
+
+  /** @internal Field decorators install accessors after their initializers execute. */
+  [assertField](name: string): void {
+    if (name in Component.prototype || this.#fields.has(name) || this.#reserved.has(name))
+      throw new TypeError(`Component field conflicts with an inherited rasam member: ${name}`);
+  }
+
+  /** @internal Field decorators install accessors after their initializers execute. */
+  [installField](
+    name: string,
+    kind: 'prop' | 'state',
+    options: PropOptions,
+    initial: unknown,
+  ): void {
+    this[assertField](name);
+    if (kind === 'prop') validateProp(initial, initial as PropValue, options, name);
+    const field: Field = {
+      kind,
+      options: Object.freeze({
+        ...options,
+        ...(options.options ? { options: Object.freeze([...options.options]) } : {}),
+      }),
+      initial: copy(initial),
+      value: initial,
+    };
+    this.#fields.set(name, field);
+    this.#propDefinitions = undefined;
+    Object.defineProperty(this, name, {
+      enumerable: true,
+      configurable: false,
+      get: () => {
+        if (kind === 'state') {
+          if (this.#readingPorts) throw new TypeError(`ports() cannot read live state: ${name}`);
+          return field.value;
+        }
+        const props = this.#readProps();
+        return Object.hasOwn(props, name)
+          ? props[name]
+          : Object.hasOwn(this.#input, name)
+            ? this.#input[name]
+            : initial;
+      },
+      set: (value: unknown) => {
+        this.assertLive();
+        if (kind === 'state') {
+          if (Object.is(field.value, value)) return;
+          field.value = value;
+          if (this.#initialized) {
+            this.changed(name);
+            this.#schedule?.();
+          }
+          return;
+        }
+        if (restoredHooks.has(this)) return;
+        validateProp(value, initial as PropValue, options, name);
+        if (Object.is(Reflect.get(this, name), value)) return;
+        this[editComponent](`Set ${options.label ?? name}`, () => {
+          this.setAttributeValue(
+            'data-rasam-props',
+            JSON.stringify({ ...this.#readProps(), [name]: value }),
+          );
+        });
+      },
+    });
+  }
+
+  /** @internal Actions share one change group across nested calls and instances. */
+  [editComponent]<Result>(label: string, callback: () => Result): Result {
+    this.assertLive();
+    if (this.#constructing || this.context.changes.currentGroup !== undefined) return callback();
+    const group = beginChangeGroup(this, { source: 'components', label });
+    try {
+      const result = group.run(callback);
+      if (result && typeof (result as PromiseLike<unknown>).then === 'function')
+        throw new TypeError('Component actions must be synchronous');
+      group.end();
+      return result;
+    } catch (error) {
+      try {
+        group.cancel();
+      } catch (rollback) {
+        throw new AggregateError([error, rollback], 'Component edit and rollback failed');
+      }
+      throw error;
+    }
+  }
+
+  #readProps(): ComponentProps {
+    // Retain ordinary field-read semantics for destroyed() and post-disposal inspection.
+    const raw = this.attributes.get('data-rasam-props');
+    if (this.#propsCache && this.#propsCache.raw === raw) return this.#propsCache.props;
+    this.#propsCache = { raw, props: Object.freeze(parseProps(raw)) };
+    return this.#propsCache.props;
+  }
+  #assertProps(props: ComponentProps): void {
+    if (!props || typeof props !== 'object' || Array.isArray(props))
+      throw new TypeError('Component props must be an object');
+    for (const [name, value] of Object.entries(props)) {
+      if (this.#sized && (sizes as readonly string[]).includes(name)) {
+        if (!isSize(value)) throw new RangeError(`Component ${name} must be a positive number`);
+        continue;
+      }
+      const field = this.#fields.get(name);
+      if (!field || field.kind !== 'prop') throw new TypeError(`Unknown component prop: ${name}`);
+      validateProp(value, field.initial as PropValue, field.options, name);
+    }
+  }
+  #notifyProps(): boolean {
+    const props = this.#readProps(),
+      previous = this.#observedProps;
+    if (props === previous) return false;
+    this.#observedProps = props;
+    const names = [...this.propDefinitions.map((field) => field.name), ...sizes].filter(
+      (name) => !Object.is(previous[name], props[name]),
+    );
+    for (const name of names) this.changed(name);
+    return names.length > 0;
+  }
+  #redraw(): void {
+    this.withOwnChildren(() => this.#view.render(this.render()));
+    markDerived(this);
+  }
+}
+
+/** Sizes are user units of at least 1, so a collapsing resize never reaches zero. */
+function toSize(value: Length): number {
+  const size = typeof value === 'number' ? value : Number(value);
+  if (!Number.isFinite(size) || size < 0)
+    throw new RangeError('Component sizes must be finite non-negative numbers');
+  return Math.max(size, 1);
+}
+
+function parseProps(raw: AttributeValue): ComponentProps {
+  const props: unknown = raw == null ? {} : JSON.parse(String(raw));
+  if (!props || typeof props !== 'object' || Array.isArray(props))
+    throw new TypeError('Component props must be a JSON object');
+  return props as ComponentProps;
+}

package/src/components/decorators.ts

@@ -0,0 +1,104 @@
+import {
+  Component,
+  installField,
+  assertField,
+  editComponent,
+  registerAction,
+} from './component.js';
+import { defineComponent } from './metadata.js';
+import { initializeElement } from '../services/initialization.js';
+import { destroySubtrees } from '../core/destruction.js';
+import { withInternalStructure } from '../mixins/parent-internals.js';
+import type { ComponentClass, ComponentOptions, PropOptions } from './types.js';
+
+export function component(options: ComponentOptions) {
+  return <Class extends ComponentClass>(
+    target: Class,
+    _context: ClassDecoratorContext<Class>,
+  ): Class => {
+    if (!(target.prototype instanceof Component))
+      throw new TypeError('@component requires extends Component');
+    const Base = target as ComponentClass;
+    const Decorated = class extends Base {
+      constructor(...args: ConstructorParameters<ComponentClass>) {
+        const context = args[0],
+          before = new Set(context.registry.nodes);
+        try {
+          super(...args);
+          if (new.target === Decorated && !this.adopting) this[initializeElement]();
+        } catch (error) {
+          const created = context.registry.nodes.filter((node) => !before.has(node));
+          if (created.length) {
+            try {
+              withInternalStructure(() => created[0][destroySubtrees](created));
+            } catch (cleanup) {
+              throw new AggregateError(
+                [error, cleanup],
+                'Component construction and cleanup failed',
+              );
+            }
+          }
+          throw error;
+        }
+      }
+    };
+    // Inherit edit rules from the decorated application base, not this wrapper's implementation base.
+    defineComponent(Decorated, options);
+    Object.defineProperty(Decorated, 'variant', {
+      value: Object.freeze({ attribute: 'data-rasam-component', value: options.type }),
+    });
+    return Decorated as Class;
+  };
+}
+
+function field(kind: 'prop' | 'state', options: PropOptions) {
+  return <Host extends Component, Value>(
+    _target: undefined,
+    context: ClassFieldDecoratorContext<Host, Value>,
+  ) => {
+    if (
+      context.kind !== 'field' ||
+      context.private ||
+      context.static ||
+      typeof context.name !== 'string'
+    )
+      throw new TypeError(`@${kind} requires a public instance field`);
+    context.addInitializer(function () {
+      this[installField](context.name as string, kind, options, context.access.get(this));
+    });
+    return function (this: Host, value: Value): Value {
+      // Validate before the JS field definition can overwrite a base instance member.
+      this[assertField](context.name as string);
+      return value;
+    };
+  };
+}
+export function prop(options: PropOptions = {}) {
+  return field('prop', options);
+}
+export function state() {
+  return field('state', {});
+}
+
+export function action(label: string) {
+  return <Host extends Component, Args extends unknown[], Result>(
+    method: (this: Host, ...args: Args) => Result,
+    context: ClassMethodDecoratorContext<Host, (this: Host, ...args: Args) => Result>,
+  ) => {
+    if (
+      context.static ||
+      context.private ||
+      typeof context.name !== 'string' ||
+      !label.trim() ||
+      method.constructor.name === 'AsyncFunction'
+    )
+      throw new TypeError('@action requires a synchronous public instance method and label');
+    const name = context.name;
+    context.addInitializer(function () {
+      this[registerAction](name, label);
+    });
+    return function (this: Host, ...args: Args): Result {
+      return this[editComponent](label, () => method.apply(this, args));
+    };
+  };
+}

package/src/components/metadata.ts

@@ -0,0 +1,111 @@
+import type { PortDefinition } from '../types/common.js';
+import type {
+  ComponentClass,
+  ComponentDefinition,
+  ComponentOptions,
+  PropOptions,
+  PropValue,
+} from './types.js';
+
+const definitions = new WeakMap<object, ComponentDefinition>();
+
+export function definition(Constructor: object): ComponentDefinition {
+  const result = definitions.get(Constructor);
+  if (!result) throw new TypeError('Component classes require their own @component decorator');
+  return result;
+}
+
+export function defineComponent(Constructor: ComponentClass, options: ComponentOptions): void {
+  let parent = Object.getPrototypeOf(Constructor);
+  while (parent && !definitions.has(parent)) parent = Object.getPrototypeOf(parent);
+  const inherited = definitions.get(parent);
+  const result = {
+    category: 'General',
+    version: 1,
+    rotate: 'free',
+    flip: true,
+    resize: 'scale',
+    ...(inherited
+      ? {
+          rotate: inherited.rotate,
+          flip: inherited.flip,
+          resize: inherited.resize,
+          width: inherited.width,
+          height: inherited.height,
+        }
+      : {}),
+    ...options,
+  } as ComponentDefinition;
+  if (result.resize === 'props')
+    Object.assign(result, { width: result.width ?? 100, height: result.height ?? 100 });
+  if (!/^[a-z][a-z0-9-]*$/.test(result.type) || !result.name?.trim() || !result.category?.trim())
+    throw new TypeError('Components need a lowercase type, display name and category');
+  if (!Number.isInteger(result.version) || result.version < 1)
+    throw new TypeError('Component version must be a positive integer');
+  if (
+    result.rotate !== 'free' &&
+    result.rotate !== false &&
+    (!Number.isFinite(result.rotate) ||
+      result.rotate <= 0 ||
+      Math.abs(360 / result.rotate - Math.round(360 / result.rotate)) > 1e-8)
+  )
+    throw new TypeError('Rotation steps must be positive divisors of 360');
+  if (typeof result.flip !== 'boolean' || !['scale', 'props', false].includes(result.resize))
+    throw new TypeError('Invalid component flip or resize rule');
+  if (
+    result.resize === 'props'
+      ? !isSize(result.width) || !isSize(result.height)
+      : result.width !== undefined || result.height !== undefined
+  )
+    throw new TypeError("Default sizes need resize: 'props' and positive finite numbers");
+  definitions.set(Constructor, Object.freeze(result));
+}
+
+/** A saved size of a `resize: 'props'` component, in user units. */
+export const isSize = (value: unknown): value is number =>
+  typeof value === 'number' && Number.isFinite(value) && value > 0;
+
+export function validateProp(
+  value: unknown,
+  initial: PropValue,
+  options: PropOptions,
+  name: string,
+): asserts value is PropValue {
+  if (value !== null && !['string', 'number', 'boolean'].includes(typeof value))
+    throw new TypeError(`Invalid component prop: ${name}`);
+  if (value !== null && initial !== null && typeof value !== typeof initial)
+    throw new TypeError(`Wrong type for component prop: ${name}`);
+  if (
+    typeof value === 'number' &&
+    (!Number.isFinite(value) ||
+      value < (options.min ?? -Infinity) ||
+      value > (options.max ?? Infinity))
+  )
+    throw new RangeError(`Component prop is outside its limits: ${name}`);
+  if (options.options && !options.options.includes(value as PropValue))
+    throw new RangeError(`Unknown option for component prop: ${name}`);
+}
+
+const sides: readonly unknown[] = ['left', 'right', 'top', 'bottom'];
+
+/** Checks what `ports()` returned and freezes a copy with only the known fields. */
+export function validatePorts(ports: unknown): readonly PortDefinition[] {
+  if (!Array.isArray(ports)) throw new TypeError('Component ports() must return an array');
+  const names = new Set<string>();
+  return Object.freeze(
+    ports.map((port: Partial<PortDefinition> | null) => {
+      const { name, x, y, side } = port ?? {};
+      if (typeof name !== 'string' || !name)
+        throw new TypeError('Component port names must be non-empty strings');
+      if (names.has(name)) throw new TypeError(`Duplicate component port: ${name}`);
+      names.add(name);
+      if (!Number.isFinite(x) || !Number.isFinite(y))
+        throw new RangeError(`Component port ${name} needs finite x and y`);
+      if (side !== undefined && !sides.includes(side))
+        throw new TypeError(`Unknown side for component port ${name}: ${String(side)}`);
+      return Object.freeze(
+        side === undefined ? { name, x: x!, y: y! } : { name, x: x!, y: y!, side },
+      );
+    }),
+  );
+}

package/src/components/registry.ts

@@ -0,0 +1,79 @@
+import type { AnyNode } from '../core/types.js';
+import type { ParentNode } from '../mixins/types.js';
+import type { ElementClass } from '../services/types.js';
+import { Guards } from '../mixins/guards.js';
+import { ComponentChanges } from './changes.js';
+import { Component } from './component.js';
+import { definition } from './metadata.js';
+import type { ComponentClass, ComponentDefinition } from './types.js';
+
+/** Per-drawing type registration, palette metadata, icons and unknown-type warnings. */
+export class ComponentTypes {
+  private readonly types = new Map<string, ComponentClass>();
+  private readonly warned = new Set<string>();
+  private readonly seen = new WeakSet<AnyNode>();
+  private readonly stop: () => void;
+  constructor(
+    private readonly drawing: AnyNode,
+    types: readonly ComponentClass[] = [],
+  ) {
+    for (const Constructor of types) this.register(Constructor);
+    this.stop = ComponentChanges.for(drawing).discover({
+      added: (node) => this.inspect(node),
+      identityChanged: (node) => this.warn(node),
+    });
+    drawing.onDispose(() => this.destroy());
+    this.inspect(drawing);
+  }
+  private inspect(node: AnyNode): void {
+    if (this.seen.has(node) || node.isDestroyed) return;
+    this.seen.add(node);
+    this.warn(node);
+    if (Guards.isParent(node)) for (const child of node.children) this.inspect(child);
+  }
+  private warn(node: AnyNode): void {
+    const type = node.getAttributeValue('data-rasam-component');
+    if (type !== undefined && !(node instanceof Component) && !this.warned.has(String(type))) {
+      this.warned.add(String(type));
+      console.warn(`Unknown rasam component type: ${type}; loaded as a plain group`);
+    }
+  }
+  register(Constructor: ComponentClass): this {
+    const metadata = definition(Constructor),
+      previous = this.types.get(metadata.type);
+    if (previous && previous !== Constructor)
+      throw new Error(`Component type already registered: ${metadata.type}`);
+    this.drawing.context.registry.register(Constructor as ElementClass);
+    this.types.set(metadata.type, Constructor);
+    return this;
+  }
+  list(category?: string): readonly ComponentDefinition[] {
+    return Object.freeze(
+      [...this.types.values()]
+        .map((Constructor) => definition(Constructor))
+        .filter((metadata) => category === undefined || metadata.category === category)
+        .sort((a, b) => a.category.localeCompare(b.category) || a.name.localeCompare(b.name)),
+    );
+  }
+  get(type: string): ComponentClass | undefined {
+    return this.types.get(type);
+  }
+  icon(type: string, parent: ParentNode): Component {
+    const Constructor = this.get(type);
+    if (!Constructor) throw new TypeError(`Unknown component type: ${type}`);
+    return parent.create(Constructor as ElementClass<{}, Component>, {});
+  }
+  resetState(): void {
+    for (const node of this.drawing.descendants()) if (node instanceof Component) node.resetState();
+  }
+  destroy(): void {
+    this.stop();
+  }
+}
+
+/** Compose with selection's existing filter to keep rendered children closed. */
+export function isComponentChild(node: AnyNode): boolean {
+  for (let parent = node.parent; parent; parent = parent.parent)
+    if (parent instanceof Component) return true;
+  return false;
+}