From 890e3b933b8b18cb29e35b207c720b8cddd7ce10 Mon Sep 17 00:00:00 2001 From: Anne van Kesteren Date: Wed, 8 Jul 2026 07:39:33 +0200 Subject: [PATCH 1/4] Editorial: improve ensure pre-insert validity This improves on two fronts: 1. Removing ambiguity by having individual conditions more clearly separated. 2. Reducing duplication by making the algorithm suitable for the replace operation as well. --- dom.bs | 152 +++++++++++++++++++++++++++------------------------------ 1 file changed, 72 insertions(+), 80 deletions(-) diff --git a/dom.bs b/dom.bs index a4b6e4b0..2e79d02d 100644 --- a/dom.bs +++ b/dom.bs @@ -2699,9 +2699,9 @@ boolean open (default false):

Mutation algorithms

-

To ensure pre-insert validity of a -node node into a node parent before null or a -node child: +

To ensure pre-insert validity given a +node node, a node parent, null or a +node child, and a boolean isReplace:

  1. If parent is not a {{Document}}, {{DocumentFragment}}, or {{Element}} @@ -2717,38 +2717,73 @@ boolean open (default false): {{CharacterData}} node, then throw a "{{HierarchyRequestError!!exception}}" {{DOMException}}. -

  2. If either node is a {{Text}} node and parent is a - document, or node is a doctype and parent is not a - document, then throw a "{{HierarchyRequestError!!exception}}" {{DOMException}}. +

  3. +

    If parent is not a document: + +

      +

    1. If node is a doctype, then throw a + "{{HierarchyRequestError!!exception}}" {{DOMException}}. + +

    2. Return. +

    + +

  4. If node is a {{Text}} node, then throw a + "{{HierarchyRequestError!!exception}}" {{DOMException}}. + +

  5. If node is a {{CharacterData}} node, then return. + +

  6. Let exclude be child if isReplace is true; otherwise null.

  7. -

    If parent is a document, and any of the statements below, switched on - the interface node implements, are true, then throw a - "{{HierarchyRequestError!!exception}}" {{DOMException}}. +

    If node is a {{DocumentFragment}} node: -

    -
    {{DocumentFragment}} -
    -

    If node has more than one element child or has a - {{Text}} node child. +

      +

    1. If node has more than one element child or has a + {{Text}} node child, then throw a + "{{HierarchyRequestError!!exception}}" {{DOMException}}. + +

    2. If node has no element child, then return. +

    -

    Otherwise, if node has one element child and either - parent has an element child, child is a - doctype, or child is non-null and a doctype is following - child. - +

  8. +

    If node is a {{DocumentFragment}} or {{Element}} node: -

    {{Element}} -

    parent has an element child, child is - a doctype, or child is non-null and a doctype is following - child. - +

      +
    1. +

      If any of the following are true: -

      {{DocumentType}} -

      parent has a doctype child, child is non-null - and an element is preceding child, or child is null - and parent has an element child. -

    9. + + +

    then throw a "{{HierarchyRequestError!!exception}}" {{DOMException}}. + +

  9. Return. +

+ +

  • Assert: node is a doctype. + +

  • +

    If any of the following are true: + +

    + +

    then throw a "{{HierarchyRequestError!!exception}}" {{DOMException}}.

    • @@ -2757,8 +2792,8 @@ boolean open (default false): into a node parent before null or node child:
      -

    1. Ensure pre-insert validity of node into parent before - child. +

    2. Ensure pre-insert validity given node, parent, + child, and false.

    3. Let referenceChild be child. @@ -3145,53 +3180,9 @@ to do these things asynchronously, however.

      To replace a node child with a node node within a node parent: - -

        -

      1. If parent is not a {{Document}}, {{DocumentFragment}}, or {{Element}} - node, then throw a "{{HierarchyRequestError!!exception}}" {{DOMException}}. - -

      2. If node is a host-including inclusive ancestor of parent, then - throw a "{{HierarchyRequestError!!exception}}" {{DOMException}}. - -

      3. If child's parent is not parent, then throw a - "{{NotFoundError!!exception}}" {{DOMException}}. - -

      4. If node is not a {{DocumentFragment}}, {{DocumentType}}, {{Element}}, or - {{CharacterData}} node, then throw a - "{{HierarchyRequestError!!exception}}" {{DOMException}}. - -

      5. If either node is a {{Text}} node and parent is a - document, or node is a doctype and parent is not a - document, then throw a "{{HierarchyRequestError!!exception}}" {{DOMException}}. - -

      6. -

        If parent is a document, and any of the statements below, switched on - the interface node implements, are true, then throw a - "{{HierarchyRequestError!!exception}}" {{DOMException}}. - -

        -
        {{DocumentFragment}} -
        -

        If node has more than one element child or has a - {{Text}} node child. - -

        Otherwise, if node has one element child and either - parent has an element child that is not - child or a doctype is following child. - -

        {{Element}} -

        parent has an element child that is not - child or a doctype is following child. - -

        {{DocumentType}} -

        parent has a doctype child that is not child, - or an element is preceding child. -

        - -

        The above statements differ from the pre-insert algorithm. +

      7. Ensure pre-insert validity given node, parent, + child, and true.

      8. Let referenceChild be child's next sibling. @@ -3589,7 +3580,7 @@ are:

      9. Let node be the result of converting nodes into a node given nodes and this's node document. -

      10. Ensure pre-insert validity of node into this before null. +

      11. Ensure pre-insert validity given node, this, null, and false.

      12. Replace all with node within this.

      @@ -9974,8 +9965,8 @@ result of cloning the contents of this. IE9 doesn't call splitText() if the offset is 0. This makes sense, but I go with what all other browsers do. --> -

    4. Ensure pre-insert validity of node into parent before - referenceNode. +

    5. Ensure pre-insert validity given node, parent, + referenceNode, and false.

    6. If range's start node is a {{Text}} node, then set referenceNode to the result of splitting it with offset @@ -11446,6 +11437,7 @@ Andreas Kling, Andreu Botella, Anthony Ramine, Arkadiusz Michalski, +Armen Michaeli, Arnaud Le Hors, Arun Ranganathan, Benjamin Gruenbaum, From 7a6d9e3dc4a9c518c0ab24a39caeaa0f40585fa1 Mon Sep 17 00:00:00 2001 From: Anne van Kesteren Date: Wed, 8 Jul 2026 07:44:41 +0200 Subject: [PATCH 2/4] nit --- dom.bs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/dom.bs b/dom.bs index 2e79d02d..ff2cb264 100644 --- a/dom.bs +++ b/dom.bs @@ -11437,7 +11437,7 @@ Andreas Kling, Andreu Botella, Anthony Ramine, Arkadiusz Michalski, -Armen Michaeli, +Armen Michaeli, Arnaud Le Hors, Arun Ranganathan, Benjamin Gruenbaum, From 908c1fbe366b64a2be97846455225c030fa9d35c Mon Sep 17 00:00:00 2001 From: Anne van Kesteren Date: Wed, 8 Jul 2026 14:41:35 +0200 Subject: [PATCH 3/4] Editorial: rename exclude to childToExclude --- dom.bs | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/dom.bs b/dom.bs index ff2cb264..a4ef46b0 100644 --- a/dom.bs +++ b/dom.bs @@ -2732,7 +2732,7 @@ boolean open (default false):

    7. If node is a {{CharacterData}} node, then return. -

    8. Let exclude be child if isReplace is true; otherwise null. +

    9. Let childToExclude be child if isReplace is true; otherwise null.

    10. If node is a {{DocumentFragment}} node: @@ -2754,7 +2754,7 @@ boolean open (default false):

      • parent has an element child that is not - exclude; + childToExclude;

      • child is non-null and a doctype is following child; or @@ -2774,7 +2774,7 @@ boolean open (default false):

        • parent has a doctype child that is not - exclude; + childToExclude;

        • child is non-null and an element is preceding child; or From f61fa73ecc4d29f86ce7566b216765f740b2b4ed Mon Sep 17 00:00:00 2001 From: Anne van Kesteren Date: Wed, 8 Jul 2026 14:48:02 +0200 Subject: [PATCH 4/4] Editorial: wrap line at 100 columns --- dom.bs | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/dom.bs b/dom.bs index a4ef46b0..343667dd 100644 --- a/dom.bs +++ b/dom.bs @@ -2732,7 +2732,8 @@ boolean open (default false):

        • If node is a {{CharacterData}} node, then return. -

        • Let childToExclude be child if isReplace is true; otherwise null. +

        • Let childToExclude be child if isReplace is true; otherwise + null.

        • If node is a {{DocumentFragment}} node: