@rasamjs/core 0.2.0 → 0.3.1

package/src/services/registry.ts

@@ -4,13 +4,19 @@ 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';
+import { recordClaim } from './claims.js';
 
 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 +25,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);
@@ -51,6 +84,7 @@ export class Registry {
     if (!this.context.dom.owns(node.el)) throw new Error('Element belongs to another document');
     Registry.identity.set(node.el, node);
     this.wrappers.set(node.el, node);
+    recordClaim(node);
   }
 
   forget(node: AnyNode): void {
@@ -61,6 +95,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 +112,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 +141,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 +168,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;

package/src/template/parts.ts

@@ -1,9 +1,10 @@
 import type { AnyNode } from '../core/types.js';
 import { Attributes } from '../dom/attributes.js';
 import type { DomFactory } from '../dom/create.js';
-import type { MarkupNode } from '../dom/types.js';
+import type { MarkupElement } from '../dom/types.js';
 import { Guards } from '../mixins/guards.js';
 import type { Registry } from '../services/registry.js';
+import type { ElementClass } from '../services/types.js';
 import type { TemplateValue } from './svg-tag.js';
 import type { TextBinding } from '../text/internals.js';
 import { classifyReference } from '../resources/references.js';
@@ -15,21 +16,36 @@ export interface TemplateDescription {
   readonly attributes: Readonly<Record<string, readonly PartValue[]>>;
   readonly children: readonly TemplateDescription[];
   readonly text: readonly PartValue[];
-  readonly content: readonly (TemplateDescription | { readonly parts: readonly PartValue[] })[];
+  readonly content: readonly ContentItem[];
 }
 
+/** An element, or a text run whose number parts are hole indexes (child holes outside text). */
+export type ContentItem = TemplateDescription | { readonly parts: readonly PartValue[] };
+
 export class TemplateCompiler {
-  private static readonly cache = new WeakMap<
-    TemplateStringsArray,
-    readonly TemplateDescription[]
-  >();
+  private static readonly cache = new WeakMap<TemplateStringsArray, readonly ContentItem[]>();
   private readonly counts: number[];
 
   private constructor(strings: TemplateStringsArray) {
     this.counts = new Array<number>(strings.length - 1).fill(0);
   }
 
+  /** Top-level elements; templates with top-level child holes need `content()`. */
   static compile(dom: DomFactory, strings: TemplateStringsArray): readonly TemplateDescription[] {
+    const content = TemplateCompiler.content(dom, strings);
+    if (
+      content.some(
+        (item) =>
+          !('tag' in item) &&
+          item.parts.some((part) => part !== '' && (typeof part == 'number' || part.trim())),
+      )
+    )
+      throw new TypeError('Template text must be inside a text element');
+    return content.filter((item): item is TemplateDescription => 'tag' in item);
+  }
+
+  /** Top-level content in order: elements and text runs that may hold child holes. */
+  static content(dom: DomFactory, strings: TemplateStringsArray): readonly ContentItem[] {
     const cached = TemplateCompiler.cache.get(strings);
     if (cached) return cached;
     if (strings.some((part) => /rasamHole\d+End/.test(part)))
@@ -38,51 +54,55 @@ export class TemplateCompiler {
     const source = strings
       .map((part, index) => part + (index < strings.length - 1 ? `rasamHole${index}End` : ''))
       .join('');
-    const result: TemplateDescription[] = [];
-    for (const node of dom.parse(source)) {
-      const description = compiler.describe(node);
-      if (description) result.push(description);
-    }
+    const result: ContentItem[] = [];
+    for (const node of dom.parse(source))
+      result.push('text' in node ? { parts: compiler.split(node.text) } : compiler.describe(node));
     if (compiler.counts.some((count) => count !== 1))
       throw new TypeError('Bindings must appear in attribute values or text elements');
     TemplateCompiler.cache.set(strings, result);
     return result;
   }
 
+  /** `parent` is the container class that receives `content`, for its child rules. */
   static validate(
-    descriptions: readonly TemplateDescription[],
+    content: readonly ContentItem[],
     registry: Registry,
     forbidden: ReadonlySet<string> = new Set(),
+    parent?: ElementClass,
   ): void {
-    for (const description of descriptions) {
+    for (const description of content) {
+      if (!('tag' in description)) {
+        if (description.parts.some((part) => typeof part == 'string' && part.trim()))
+          throw new TypeError('Template text must be inside a text element');
+        continue;
+      }
       const Constructor = registry.get(description.tag);
       if (forbidden.has(description.tag))
         throw new TypeError('Nested links or forbidden descendants are unsupported');
       if (!Constructor) throw new TypeError(`Unsupported template tag: ${description.tag}`);
+      if (parent?.childTags && !parent.childTags.includes(description.tag))
+        throw new TypeError(`${parent.tag} only accepts ${parent.childTags.join(', ')} children`);
       for (const name of Object.keys(description.attributes)) {
         if (!Constructor.attributeNames.includes(name) && !/^(?:data|aria)-[\w-]+$/.test(name))
           throw new TypeError(`Unsupported template attribute: ${name}`);
       }
       if (description.children.length > 0 && !Constructor.isContainer)
         throw new TypeError('Only containers may have element children');
+      // Outside text elements, holes between children are child holes, so only containers take them.
       if (
-        Constructor.childTags &&
-        description.children.some((child) => !Constructor.childTags.includes(child.tag))
-      )
-        throw new TypeError(
-          `${description.tag} only accepts ${Constructor.childTags.join(', ')} children`,
-        );
-      if (
-        description.text.some((part) => typeof part === 'number' || part.trim()) &&
-        !Constructor.isText
+        !Constructor.isText &&
+        description.text.some((part) =>
+          typeof part == 'number' ? !Constructor.isContainer : part.trim(),
+        )
       )
         throw new TypeError('Text bindings require a text element');
       TemplateCompiler.validate(
-        description.children,
+        Constructor.isText ? description.children : description.content,
         registry,
         Constructor.forbiddenDescendantTags
           ? new Set([...forbidden, ...Constructor.forbiddenDescendantTags])
           : forbidden,
+        Constructor,
       );
     }
   }
@@ -101,11 +121,7 @@ export class TemplateCompiler {
     return parts;
   }
 
-  private describe(node: MarkupNode): TemplateDescription | null {
-    if ('text' in node) {
-      if (node.text.trim()) throw new TypeError('Template text must be inside a text element');
-      return null;
-    }
+  private describe(node: MarkupElement): TemplateDescription {
     if (/rasamHole\d+End/.test(node.tag)) throw new TypeError('Dynamic tag names are unsupported');
     const attributes: Record<string, readonly PartValue[]> = {};
     for (const [rawName, value] of Object.entries(node.attributes)) {
@@ -121,7 +137,7 @@ export class TemplateCompiler {
     }
     const text: PartValue[] = [];
     const children: TemplateDescription[] = [];
-    const content: (TemplateDescription | { readonly parts: readonly PartValue[] })[] = [];
+    const content: ContentItem[] = [];
     for (const child of node.children) {
       if ('text' in child) {
         const parts = this.split(child.text);
@@ -129,10 +145,8 @@ export class TemplateCompiler {
         content.push({ parts });
       } else {
         const description = this.describe(child);
-        if (description) {
-          children.push(description);
-          content.push(description);
-        }
+        children.push(description);
+        content.push(description);
       }
     }
     return { tag: node.tag, attributes, children, text, content };
@@ -140,8 +154,6 @@ export class TemplateCompiler {
 }
 
 export class BindingPart {
-  private previous: string | undefined;
-
   constructor(
     private readonly node: AnyNode,
     private readonly name: string | null,
@@ -183,15 +195,18 @@ export class BindingPart {
     }
   }
 
-  commit(value: string | undefined, initial = false): void {
-    if (!initial && value === this.previous) return;
+  commit(value: string | undefined): void {
     if (this.name === null) {
       if (!Guards.isTextual(this.node))
         throw new TypeError('Text binding requires the Textual mixin');
+      if ((this.textBinding ? this.textBinding.value : this.node.text()) === (value ?? '')) return;
       if (this.textBinding) this.textBinding.set(value ?? '');
       else this.node.text(value ?? '');
-    } else this.node.setAttributeValue(this.name, value);
-    this.previous = value;
+    } else {
+      const current = this.node.getAttributeValue(this.name);
+      if ((current === undefined ? undefined : String(current)) === value) return;
+      this.node.setAttributeValue(this.name, value);
+    }
   }
 
   private static primitive(value: TemplateValue): string {

package/src/template/render.ts

@@ -1,73 +1,180 @@
 import { mutation } from '../changes/mutation.js';
 import type { AnyNode } from '../core/types.js';
+import { destroySubtrees } from '../core/destruction.js';
 import type { ParentNode } from '../mixins/types.js';
 import { Guards } from '../mixins/guards.js';
 import { Group } from '../elements/group.js';
 import type { Registry } from '../services/registry.js';
+import type { ElementClass } from '../services/types.js';
 import { BindingPart, TemplateCompiler } from './parts.js';
-import type { TemplateDescription } from './parts.js';
-import type { SvgTemplate } from './svg-tag.js';
+import type { ContentItem, TemplateDescription } from './parts.js';
+import { SvgTemplate } from './svg-tag.js';
+import type { TemplateValue } from './svg-tag.js';
 import { appendTextSlot, type TextBinding } from '../text/internals.js';
 
-export class TemplateInstance {
-  readonly host: Group;
-  readonly nodes: readonly AnyNode[];
-  private readonly parts: BindingPart[] = [];
+type Segment = AnyNode | ChildPart;
+/** The nodes and child holes one template places in one parent, from index `base()`. */
+interface Sequence {
+  parent: ParentNode;
+  readonly segments: Segment[];
+  base(): number;
+}
+
+const size = (segments: readonly Segment[]) =>
+  segments.reduce((total, segment) => total + (segment instanceof ChildPart ? segment.size : 1), 0);
+const flat = (segments: readonly Segment[]): AnyNode[] =>
+  segments.flatMap((segment) => (segment instanceof ChildPart ? segment.nodes : [segment]));
+/** Semantic disposal: unlike `destroy()`, undo can restore it and history isn't cleared. */
+const dispose = (nodes: readonly AnyNode[]) => {
+  const live = nodes.filter((node) => !node.isDestroyed);
+  if (live.length) live[0][destroySubtrees](live);
+};
+
+/** Flattens a child hole's value into templates. */
+function templates(value: TemplateValue, out: SvgTemplate[] = []): SvgTemplate[] {
+  if (value instanceof SvgTemplate) out.push(value);
+  else if (typeof value == 'object' && value && Symbol.iterator in value)
+    for (const item of value) templates(item, out);
+  else if (value != null && typeof value != 'boolean' && value !== '')
+    throw new TypeError('Child bindings take templates, iterables of them, or null');
+  return out;
+}
+
+/**
+ * Validates and builds an update without changing the drawing: new items are built in
+ * detached `stagings` groups. The returned commit applies it.
+ */
+type Prepare = (values: readonly TemplateValue[], stagings: Group[]) => () => void;
+
+/** Prepares and commits, disposing the staging groups whether or not it succeeds. */
+function commit(prepare: Prepare, values: readonly TemplateValue[]): void {
+  const stagings: Group[] = [];
+  try {
+    prepare(values, stagings)();
+  } finally {
+    dispose(stagings);
+  }
+}
+
+/** A hole between elements: the items it renders, reused by index while their literal matches. */
+class ChildPart {
+  private items: Mount[] = [];
+  constructor(
+    private readonly sequence: Sequence,
+    private readonly hole: number,
+    private readonly registry: Registry,
+  ) {}
+
+  get size(): number {
+    return this.items.reduce((total, item) => total + item.size, 0);
+  }
+  get nodes(): AnyNode[] {
+    return this.items.flatMap((item) => item.nodes);
+  }
+  /** The index of this part's first node, or of `item`'s first node. */
+  private start(item?: Mount): number {
+    const { segments } = this.sequence;
+    let index = this.sequence.base() + size(segments.slice(0, segments.indexOf(this)));
+    for (const other of item ? this.items : []) {
+      if (other === item) break;
+      index += other.size;
+    }
+    return index;
+  }
+
+  readonly prepare: Prepare = (values, stagings) => {
+    const parent = this.sequence.parent;
+    const forbidden = new Set<string>();
+    for (let node: AnyNode | null = parent; node; node = node.parent)
+      for (const tag of (node.constructor as ElementClass).forbiddenDescendantTags ?? [])
+        forbidden.add(tag);
+    const plans = templates(values[this.hole]).map((template, index) => {
+      const item = this.items[index];
+      if (item?.template.strings === template.strings)
+        return { item, commit: item.prepare(template.values, stagings) };
+      const content = TemplateCompiler.content(parent.context.dom, template.strings);
+      TemplateCompiler.validate(
+        content,
+        this.registry,
+        forbidden,
+        parent.constructor as ElementClass,
+      );
+      const staging = new Group(parent.context);
+      stagings.push(staging);
+      return { item: new Mount(template, staging, this.registry, content) };
+    });
+    return () => {
+      const items = plans.map((plan) => plan.item);
+      dispose(this.items.filter((item) => !items.includes(item)).flatMap((item) => item.nodes));
+      this.items = items;
+      for (const { item, commit } of plans)
+        if (!commit) {
+          // Detach first, so history records new nodes rather than a move from staging.
+          for (const node of item.nodes) parent.add(node.remove());
+          item.sequence.parent = parent;
+          item.sequence.base = () => this.start(item);
+        }
+      for (const plan of plans) plan.commit?.();
+      let index = this.start();
+      for (const node of this.nodes) parent.add(node, index++);
+    };
+  };
+}
+
+/** One template's nodes and parts, mounted as a sequence inside a parent. */
+class Mount {
+  readonly sequence: Sequence;
+  private readonly parts: (BindingPart | ChildPart)[] = [];
 
   constructor(
-    parent: ParentNode,
     readonly template: SvgTemplate,
-    registry: Registry,
-    descriptions: readonly TemplateDescription[],
+    parent: ParentNode,
+    private readonly registry: Registry,
+    content: readonly ContentItem[],
   ) {
-    this.host = new Group(parent.context);
-    try {
-      this.nodes = descriptions.map((description) =>
-        this.instantiate(description, this.host, registry),
-      );
-    } catch (error) {
-      this.host.destroy();
-      throw error;
-    }
+    this.sequence = { parent, segments: [], base: () => 0 };
+    this.fill(content, this.sequence);
   }
 
-  get isDestroyed(): boolean {
-    return this.host.isDestroyed;
+  get size(): number {
+    return size(this.sequence.segments);
+  }
+  get nodes(): AnyNode[] {
+    return flat(this.sequence.segments);
   }
 
-  update(template: SvgTemplate): this {
-    return mutation(this, () => {
-      this.host.assertLive();
-      if (template.strings !== this.template.strings)
-        throw new TypeError('An instance can only update its original template');
-      const changes = this.parts.map((part) => {
-        const value = part.evaluate(template.values);
-        part.validate(value);
-        return { part, value };
-      });
-      this.host.batch(() => {
-        for (const { part, value } of changes) part.commit(value);
-      });
-      return this;
+  /** Validates every binding first, so an update changes all or nothing. */
+  readonly prepare: Prepare = (values, stagings) => {
+    const commits = this.parts.map((part) => {
+      if (part instanceof ChildPart) return part.prepare(values, stagings);
+      const value = part.evaluate(values);
+      part.validate(value);
+      return () => part.commit(value);
     });
-  }
+    return () => commits.forEach((commit) => commit());
+  };
 
-  destroy(): void {
-    this.host.destroy();
+  private fill(content: readonly ContentItem[], sequence: Sequence): void {
+    for (const item of content) {
+      if ('tag' in item) sequence.segments.push(this.element(item, sequence.parent));
+      else
+        for (const hole of item.parts)
+          if (typeof hole == 'number') {
+            const part = new ChildPart(sequence, hole, this.registry);
+            sequence.segments.push(part);
+            this.parts.push(part);
+            commit(part.prepare, this.template.values);
+          }
+    }
   }
-
-  private instantiate(
-    description: TemplateDescription,
-    parent: ParentNode,
-    registry: Registry,
-  ): AnyNode {
-    const node = registry.createEmpty(description.tag, parent.context);
+  private element(description: TemplateDescription, parent: ParentNode): AnyNode {
+    const node = this.registry.createEmpty(description.tag, parent.context);
     parent.add(node);
     for (const [name, values] of Object.entries(description.attributes))
       this.bind(new BindingPart(node, name, values));
     if (appendTextSlot in node && Guards.isParent(node)) {
       for (const part of description.content) {
-        if ('tag' in part) this.instantiate(part, node, registry);
+        if ('tag' in part) this.element(part, node);
         else {
           const binding = (node[appendTextSlot] as (value: string) => TextBinding)('');
           this.bind(new BindingPart(node, null, part.parts, binding));
@@ -75,22 +182,69 @@ export class TemplateInstance {
       }
       return node;
     }
-    if (description.text.length > 0 && Guards.isTextual(node))
-      this.bind(new BindingPart(node, null, description.text));
+    if (Guards.isTextual(node)) {
+      if (description.text.length > 0) this.bind(new BindingPart(node, null, description.text));
+    } else if (Guards.isParent(node)) {
+      this.fill(description.content, { parent: node, segments: [], base: () => 0 });
+      return node;
+    }
     if (description.children.length > 0 && !Guards.isParent(node))
       throw new TypeError('Children require the Parent mixin');
-    for (const child of description.children) this.instantiate(child, node as ParentNode, registry);
+    for (const child of description.children) this.element(child, node as ParentNode);
     return node;
   }
 
   private bind(part: BindingPart): void {
     const value = part.evaluate(this.template.values);
     part.validate(value);
-    part.commit(value, true);
+    part.commit(value);
     this.parts.push(part);
   }
 }
 
+export class TemplateInstance {
+  readonly host: Group;
+  private readonly mount: Mount;
+
+  constructor(
+    parent: ParentNode,
+    readonly template: SvgTemplate,
+    registry: Registry,
+    content: readonly ContentItem[],
+  ) {
+    this.host = new Group(parent.context);
+    try {
+      this.mount = new Mount(template, this.host, registry, content);
+    } catch (error) {
+      this.host.destroy();
+      throw error;
+    }
+  }
+
+  /** The current top-level nodes, including those that child holes render. */
+  get nodes(): readonly AnyNode[] {
+    return this.mount.nodes;
+  }
+
+  get isDestroyed(): boolean {
+    return this.host.isDestroyed;
+  }
+
+  update(template: SvgTemplate): this {
+    return mutation(this, () => {
+      this.host.assertLive();
+      if (template.strings !== this.template.strings)
+        throw new TypeError('An instance can only update its original template');
+      this.host.batch(() => commit(this.mount.prepare, template.values));
+      return this;
+    });
+  }
+
+  destroy(): void {
+    this.host.destroy();
+  }
+}
+
 export class Renderer {
   private static readonly renderers = new WeakMap<ParentNode, Renderer>();
   private instance: TemplateInstance | null = null;
@@ -126,12 +280,15 @@ export class Renderer {
       this.instance.template.strings === template.strings
     )
       return this.instance.update(template);
-    const descriptions = TemplateCompiler.compile(this.parent.context.dom, template.strings);
-    TemplateCompiler.validate(descriptions, this.registry);
-    const instance = new TemplateInstance(this.parent, template, this.registry, descriptions);
+    const content = TemplateCompiler.content(this.parent.context.dom, template.strings);
+    TemplateCompiler.validate(content, this.registry);
+    const instance = new TemplateInstance(this.parent, template, this.registry, content);
     try {
-      this.instance?.destroy();
-      this.parent.add(instance.host);
+      // Replacing a template disposes the old one semantically, so undo restores it.
+      this.parent.context.changes.run(this.parent, () => {
+        if (this.instance) dispose([this.instance.host]);
+        this.parent.add(instance.host);
+      });
     } catch (error) {
       instance.destroy();
       throw error;