@rasamjs/core 0.1.2 → 0.3.0

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/dom/images.ts

@@ -20,7 +20,8 @@ export class ImageLoader {
     return () => {
       probe.removeEventListener('load', loaded);
       probe.removeEventListener('error', failed);
-      probe.removeAttribute('src');
+      // Resetting an already completed source starts a second native error request.
+      if (!probe.complete) probe.removeAttribute('src');
     };
   }
 }

package/src/elements/image.ts

@@ -44,7 +44,10 @@ export class SvgImage extends Shape<SVGImageElement, ImageOptions> {
 
   constructor(context: DrawingContext, options: ImageOptions = {}, existing?: SVGImageElement) {
     super(context, options, existing);
-    this.onDispose(() => this.cancelRequest());
+    this.onDispose(() => {
+      this.cancelRequest();
+      this.el.removeAttribute('href');
+    });
     if (this.source) this.context.scheduler.enqueue(this, '#image');
   }
 

package/src/interchange/clone.ts

@@ -7,7 +7,7 @@ import { dependencyRoots, remapIds } from './references.js';
 import { classifyReference } from '../resources/references.js';
 import { preflight, reconstruct, validateCloneContent } from './reconstruct.js';
 import type { CloneOptions } from './types.js';
-import { copyTextPolicies } from '../text/content.js';
+import { copyTextPolicies } from '../text/policies.js';
 
 export function cloneNode<Node extends AnyNode>(source: Node, options: CloneOptions = {}): Node {
   return source.context.changes.run(source, () => {
@@ -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/dom.ts

@@ -2,19 +2,29 @@ import { SVG_NAMESPACE, XLINK_NAMESPACE } from '../catalog/namespaces.js';
 
 /** Parsing and serialization operate on detached nodes in the destination document. */
 export class InterchangeDom {
-  static parse(owner: SVGElement, source: string): SVGElement[] {
+  static parse(owner: SVGElement, source: string, document = false): SVGElement[] {
     if (typeof source !== 'string' || source.length > 1_000_000)
       throw new TypeError('SVG import requires at most 1,000,000 characters');
-    if (/<!\s*(?:DOCTYPE|ENTITY)|<\?/i.test(source))
+    // A document prolog may hold an XML declaration and a DOCTYPE without an internal subset.
+    const prolog = document
+      ? /^\s*(?:<\?xml\s[^?]*\?>)?(?:\s|<!--(?:[^-]|-(?!->))*-->)*(?:<!DOCTYPE\s+svg\b[^[>]*>)?/i.exec(
+          source,
+        )![0]
+      : '';
+    const body = source.slice(prolog.length);
+    if (/<!\s*(?:DOCTYPE|ENTITY)|<\?/i.test(body))
       throw new TypeError('SVG import rejects declarations, entities and processing instructions');
     const Parser = owner.ownerDocument.defaultView?.DOMParser ?? globalThis.DOMParser;
     if (!Parser) throw new Error('SVG import requires DOMParser');
     const parsed = new Parser().parseFromString(
-      `<svg xmlns="${SVG_NAMESPACE}" xmlns:xlink="${XLINK_NAMESPACE}">${source}</svg>`,
+      `<svg xmlns="${SVG_NAMESPACE}" xmlns:xlink="${XLINK_NAMESPACE}">${body}</svg>`,
       'image/svg+xml',
     );
-    if (parsed.getElementsByTagName('parsererror').length)
-      throw new TypeError('Invalid SVG markup');
+    const failure = parsed.getElementsByTagName('parsererror')[0];
+    if (failure)
+      throw new SyntaxError(
+        `Not valid SVG: ${failure.textContent?.trim().split(/\r?\n/)[0] || 'Invalid SVG markup'}`,
+      );
     const roots: SVGElement[] = [];
     for (const node of parsed.documentElement.childNodes) {
       if (node.nodeType === 8 || (node.nodeType === 3 && !node.textContent.trim())) continue;
@@ -27,6 +37,25 @@ export class InterchangeDom {
           element.replaceChild(owner.ownerDocument.createTextNode(child.textContent), child);
     return roots;
   }
+  /** Called after passive validation so even discarded envelope attributes are checked. */
+  static unwrap(roots: SVGElement[], presentation: boolean): SVGElement[] {
+    const root = roots[0];
+    if (roots.length !== 1 || root.localName !== 'svg') return roots;
+    const children = [...root.children] as SVGElement[];
+    if (!presentation) return children;
+    const group = root.ownerDocument.createElementNS(SVG_NAMESPACE, 'g');
+    for (const attribute of [...root.attributes])
+      if (
+        !['x', 'y', 'width', 'height', 'viewBox', 'preserveAspectRatio', 'version'].includes(
+          attribute.name,
+        ) &&
+        attribute.namespaceURI !== 'http://www.w3.org/2000/xmlns/'
+      )
+        group.setAttributeNS(attribute.namespaceURI, attribute.name, attribute.value);
+    if (!group.attributes.length) return children;
+    group.append(...root.childNodes);
+    return [group];
+  }
   static serialize(element: SVGElement): string {
     const Serializer = element.ownerDocument.defaultView?.XMLSerializer ?? globalThis.XMLSerializer;
     if (!Serializer) throw new Error('SVG export requires XMLSerializer');

package/src/interchange/markup.ts

@@ -8,6 +8,31 @@ import { InterchangeDom } from './dom.js';
 import { preflight, reconstruct } from './reconstruct.js';
 import { validateImportContent } from './policy.js';
 import type { ExportOptions, ImportOptions } from './types.js';
+import { BBox } from '../math/bbox.js';
+import { isNestedViewport, viewportLength } from '../services/viewport.js';
+import { Attributes } from '../dom/attributes.js';
+
+function frameContent(source: AnyNode, envelope: SVGElement, padding: number): void {
+  const bounds = source.bounds('root');
+  if (bounds.status === 'unavailable')
+    throw new Error(`Cannot frame SVG content: ${bounds.reason}`);
+  const box =
+    'box' in bounds
+      ? bounds.box
+      : {
+          x: 0,
+          y: 0,
+          width: BBox.numeric(source.context.root?.getAttributeValue('width'), 800) ?? 800,
+          height: BBox.numeric(source.context.root?.getAttributeValue('height'), 600) ?? 600,
+        };
+  const width = box.width + padding * 2,
+    height = box.height + padding * 2;
+  if (![box.x - padding, box.y - padding, width, height].every(Number.isFinite))
+    throw new RangeError('SVG content frame must be finite');
+  envelope.setAttribute('viewBox', `${box.x - padding} ${box.y - padding} ${width} ${height}`);
+  envelope.setAttribute('width', String(width));
+  envelope.setAttribute('height', String(height));
+}
 
 export function exportSvg(source: AnyNode, options: ExportOptions = {}): string {
   source.assertLive();
@@ -15,6 +40,13 @@ export function exportSvg(source: AnyNode, options: ExportOptions = {}): string
     throw new TypeError('Unknown SVG export format');
   if (options.resources !== undefined && !['referenced', 'none'].includes(options.resources))
     throw new TypeError('Unknown export resource policy');
+  if (options.frame !== undefined && options.frame !== 'content')
+    throw new TypeError('Unknown SVG frame');
+  if (options.frame && options.format === 'subtree')
+    throw new TypeError('Content framing requires a document export');
+  const padding = options.padding ?? 0;
+  if (!Number.isFinite(padding) || padding < 0)
+    throw new RangeError('SVG padding must be nonnegative and finite');
   source.flush();
   const dependencies = options.resources === 'none' ? [] : dependencyRoots(source, 'local');
   const copies = new Map<AnyNode, SVGElement>();
@@ -25,20 +57,45 @@ export function exportSvg(source: AnyNode, options: ExportOptions = {}): string
     return InterchangeDom.serialize(element);
   }
   const document = element.ownerDocument;
+  const framedSubtree = options.frame === 'content' && source !== source.context.root;
   const envelope =
-    element.localName === 'svg' ? element : document.createElementNS(SVG_NAMESPACE, 'svg');
+    element.localName === 'svg' && !framedSubtree
+      ? element
+      : document.createElementNS(SVG_NAMESPACE, 'svg');
   if (envelope !== element) {
     for (const name of ['width', 'height', 'viewBox', 'preserveAspectRatio']) {
       const value = source.context.root?.getAttributeValue(name);
       if (value !== undefined) envelope.setAttribute(name, String(value));
     }
-    envelope.append(element);
+    if (framedSubtree && source.parent) {
+      // The snapshot retains its own transform and any nested SVG viewport. Only
+      // the omitted ancestors need mapping into the document-space content frame.
+      const mapping = document.createElementNS(SVG_NAMESPACE, 'g');
+      mapping.setAttribute('transform', source.context.bounds.matrix(source.parent).toString());
+      mapping.append(element);
+      envelope.append(mapping);
+    } else envelope.append(element);
   }
   if (dependencies.length) {
     const defs = document.createElementNS(SVG_NAMESPACE, 'defs');
     for (const dependency of dependencies) defs.append(snapshot(dependency, copies));
     envelope.prepend(defs);
   }
+  if (options.frame === 'content') {
+    frameContent(source, envelope, padding);
+    // Reframing changes percentage bases. Preserve each copied nested viewport's
+    // original placement and dimensions, including omitted 100% sizes.
+    for (const [node, copy] of copies) {
+      if (!isNestedViewport(node)) continue;
+      for (const name of ['x', 'y', 'width', 'height'] as const) {
+        const axis = name === 'x' || name === 'width' ? 'width' : 'height';
+        copy.setAttribute(
+          name,
+          String(viewportLength(node, name, axis, name === axis ? '100%' : 0)),
+        );
+      }
+    }
+  }
   return InterchangeDom.serialize(envelope);
 }
 
@@ -51,8 +108,22 @@ export function importSvg(
     assertCanAddChildren(parent);
     const index = options.index ?? parent.children.length;
     validateIndex(index, parent.children.length);
-    const roots = InterchangeDom.parse(parent.el, markup);
+    if (
+      options.document !== undefined &&
+      typeof options.document !== 'boolean' &&
+      !['presentation', 'replace'].includes(options.document)
+    )
+      throw new TypeError('Unknown document import mode');
+    if (
+      options.document === 'replace' &&
+      (parent !== parent.context.root || parent.children.length)
+    )
+      throw new TypeError('Document replacement requires an empty owning drawing');
+    let roots = InterchangeDom.parse(parent.el, markup, !!options.document);
     validateImportContent(roots, options);
+    const replace =
+      options.document === 'replace' && roots.length === 1 && roots[0].localName === 'svg';
+    if (options.document) roots = InterchangeDom.unwrap(roots, options.document !== true);
     preflight(parent.context, roots);
     remapIds(parent, roots);
     return reconstruct(parent, roots, (nodes) => {
@@ -60,6 +131,9 @@ export function importSvg(
       for (const node of nodes) parent[validateChild](node);
       for (let position = 0; position < nodes.length; position++)
         parent.add(nodes[position], index + position);
+      if (replace)
+        for (const name of Attributes.common)
+          if (!['id', 'class'].includes(name)) parent.setAttributeValue(name, undefined);
       return Object.freeze(nodes);
     });
   });

package/src/interchange/policy.ts

@@ -89,6 +89,12 @@ function validateUrl(tag: string, name: string, value: string, options: ImportOp
   if (reference) return;
   if (name === 'href') {
     if (value === '') return;
+    // Image documents are passive resources; keep embedded image files restorable.
+    if (
+      tag === 'image' &&
+      /^data:image\/(?:png|jpe?g|gif|webp|avif|svg\+xml)(?:;[^,]*)?,/i.test(value)
+    )
+      return;
     if (
       options.externalUrls === 'http' &&
       ['image', 'a', 'use'].includes(tag) &&

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/interchange/types.ts

@@ -10,9 +10,18 @@ export interface ExportOptions {
   format?: 'document' | 'subtree';
   /** Include reachable typed and unambiguous local references. CSS URLs are not traversed. */
   resources?: 'referenced' | 'none';
+  /** Frame geometric content in document coordinates rather than the current camera. */
+  frame?: 'content';
+  /** Nonnegative drawing units around a content frame; defaults to zero. */
+  padding?: number;
 }
 export interface ImportOptions {
   index?: number;
-  /** External URLs are rejected by default. Opt in to absolute HTTP(S) image/link/Use URLs. */
+  /** true unwraps children; 'presentation' retains scoped root attributes without
+   * the viewport. 'replace' additionally clears configured root presentation for a
+   * full document, and requires an empty owning drawing. Fragments keep defaults. */
+  document?: boolean | 'presentation' | 'replace';
+  /** External URLs are rejected by default; embedded data images are allowed on image elements.
+   * Opt in to absolute HTTP(S) image/link/Use URLs. */
   externalUrls?: 'reject' | 'http';
 }