function createElementForTag<T extends INode>(dom: IDOM<T>, tagName: string, props?: Record<string, string | HTMLTargetedInstruction>, children?: ArrayLike<unknown>): RenderPlan<T> {
  if (Tracer.enabled) { Tracer.enter('createElement', 'createElementForTag', slice.call(arguments)); }
  const instructions: HTMLTargetedInstruction[] = [];
  const allInstructions: HTMLTargetedInstruction[][] = [];
  const dependencies: IRegistry[] = [];
  const element = dom.createElement(tagName);
  let hasInstructions = false;

  if (props) {
    Object.keys(props)
      .forEach(to => {
        const value = props[to];

        if (isHTMLTargetedInstruction(value)) {
          hasInstructions = true;
          instructions.push(value);
        } else {
          dom.setAttribute(element, to, value);
        }
      });
  }

  if (hasInstructions) {
    dom.makeTarget(element);
    allInstructions.push(instructions);
  }

  if (children) {
    addChildren(dom, element, children, allInstructions, dependencies);
  }

  if (Tracer.enabled) { Tracer.leave(); }
  return new RenderPlan(dom, element, allInstructions, dependencies);
}

/**
 * A (temporary) standalone function that purely does the DOM processing (lifting) related to template controllers.
 * It's a first refactoring step towards separating DOM parsing/binding from mutations.
 */
function processTemplateControllers(dom: IDOM, manifestProxy: IParentNodeSymbol, manifest: IElementSymbol): void {
  const manifestNode = manifest.physicalNode as HTMLElement;
  let current = manifestProxy as TemplateControllerSymbol;
  let currentTemplate: HTMLTemplateElement;
  while ((current as IParentNodeSymbol) !== manifest) {
    if (current.template === manifest) {
      // the DOM linkage is still in its original state here so we can safely assume the parentNode is non-null
      manifestNode.parentNode.replaceChild(current.marker as Node, manifestNode);

      // if the manifest is a template element (e.g. <template repeat.for="...">) then we can skip one lift operation
      // and simply use the template directly, saving a bit of work
      if (manifestNode.nodeName === 'TEMPLATE') {
        current.physicalNode = manifestNode as HTMLTemplateElement;
        // the template could safely stay without affecting anything visible, but let's keep the DOM tidy
        manifestNode.remove();
      } else {
        // the manifest is not a template element so we need to wrap it in one
        currentTemplate = current.physicalNode = dom.createTemplate() as HTMLTemplateElement;
        currentTemplate.content.appendChild(manifestNode);
      }
    } else {
      currentTemplate = current.physicalNode = dom.createTemplate() as HTMLTemplateElement;
      currentTemplate.content.appendChild(current.marker as Node);
    }
    manifestNode.removeAttribute(current.syntax.rawName);
    current = current.template as TemplateControllerSymbol;
  }
}

function createElementForType<T extends INode>(dom: IDOM<T>, Type: ICustomElementType<T>, props?: object, children?: ArrayLike<unknown>): RenderPlan<T> {
  if (Tracer.enabled) { Tracer.enter('createElement', 'createElementForType', slice.call(arguments)); }
  const tagName = Type.description.name;
  const instructions: HTMLTargetedInstruction[] = [];
  const allInstructions = [instructions];
  const dependencies: IRegistry[] = [];
  const childInstructions: HTMLTargetedInstruction[] = [];
  const bindables = Type.description.bindables;
  const element = dom.createElement(tagName);

  dom.makeTarget(element);

  if (!dependencies.includes(Type)) {
    dependencies.push(Type);
  }

  instructions.push(new HydrateElementInstruction(tagName, childInstructions));

  if (props) {
    Object.keys(props)
      .forEach(to => {
        const value: HTMLTargetedInstruction | string = props[to];

        if (isHTMLTargetedInstruction(value)) {
          childInstructions.push(value);
        } else {
          const bindable = bindables[to];

          if (bindable) {
            childInstructions.push({
              type: TargetedInstructionType.setProperty,
              to,
              value
            });
          } else {
            childInstructions.push(new SetAttributeInstruction(value, to));
          }
        }
      });
  }

  if (children) {
    addChildren(dom, element, children, allInstructions, dependencies);
  }

  if (Tracer.enabled) { Tracer.leave(); }
  return new RenderPlan<T>(dom, element, allInstructions, dependencies);
}

function addChildren<T extends INode>(dom: IDOM<T>, parent: T, children: ArrayLike<unknown>, allInstructions: HTMLTargetedInstruction[][], dependencies: IRegistry[]): void {
  for (let i = 0, ii = children.length; i < ii; ++i) {
    const current = children[i];

    switch (typeof current) {
      case 'string':
        dom.appendChild(parent, dom.createTextNode(current));
        break;
      case 'object':
        if (dom.isNodeInstance(current)) {
          dom.appendChild(parent, current);
        } else if ('mergeInto' in (current as RenderPlan)) {
          (current as RenderPlan<T>).mergeInto(parent, allInstructions, dependencies);
        }
    }
  }
}

  constructor(dom: IDOM<Node>, $customElement: ICustomElement<Node>, host: Node) {
    if (host.childNodes.length) {
      this.childNodes = PLATFORM.toArray(host.childNodes);
    } else {
      this.childNodes = PLATFORM.emptyArray;
    }

    this.host = dom.convertToRenderLocation(host) as CustomElementHost<Node>;
    this.host.$customElement = $customElement;
  }

function processReplacePart(dom: IDOM, replacePart: ReplacePartSymbol, manifestProxy: IParentNodeSymbol | ISymbolWithMarker): void {
    let proxyNode: HTMLElement;
    let currentTemplate: HTMLTemplateElement;
    if (manifestProxy.flags & SymbolFlags.hasMarker) {
      proxyNode = (manifestProxy as ISymbolWithMarker).marker as HTMLElement;
    } else {
      proxyNode = manifestProxy.physicalNode as HTMLElement;
    }
    if (proxyNode.nodeName === 'TEMPLATE') {
      // if it's a template element, no need to do anything special, just assign it to the replacePart
      replacePart.physicalNode = proxyNode as HTMLTemplateElement;
    } else {
      // otherwise wrap the replace-part in a template
      currentTemplate = replacePart.physicalNode = dom.createTemplate() as HTMLTemplateElement;
      currentTemplate.content.appendChild(proxyNode);
    }
}

      .forEach(to => {
        const value = props[to];

        if (isHTMLTargetedInstruction(value)) {
          hasInstructions = true;
          instructions.push(value);
        } else {
          dom.setAttribute(element, to, value);
        }
      });

 public subscribeToChildrenChange(callback: () => void): void {
   // TODO: add a way to dispose/disconnect
   this.dom.createNodeObserver(this.shadowRoot, callback, childObserverOptions);
 }

 public bind(): void {
   this.nodeObserver = this.dom.createNodeObserver(this.obj, this.handleNodeChange.bind(this), childObserverOptions) as MutationObserver;
 }

 /** @internal */
 public mergeInto(parent: T, instructions: HTMLTargetedInstruction[][], dependencies: IRegistry[]): void {
   this.dom.appendChild(parent, this.node);
   instructions.push(...this.instructions);
   dependencies.push(...this.dependencies);
 }