From a13e2b5dcce43a09a85ec75bfeb697389fcfa779 Mon Sep 17 00:00:00 2001 From: Anne van Kesteren Date: Tue, 25 Nov 2025 10:43:57 +0100 Subject: [PATCH 1/5] Editorial: modernize mutation algorithms Plus some minor drive-by fixes. --- dom.bs | 116 +++++++++++++++++++++++++++++++++++---------------------- 1 file changed, 71 insertions(+), 45 deletions(-) diff --git a/dom.bs b/dom.bs index de8f62ff..b3bd17cd 100644 --- a/dom.bs +++ b/dom.bs @@ -145,7 +145,7 @@ first following sibling or null if it has no

  • Let tokens be a new ordered set. -

  • For each token of inputTokens, append +

  • For each token of inputTokens: append token to tokens.

  • Return tokens. @@ -2684,8 +2684,9 @@ boolean open (default false):

    Mutation algorithms

    +

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

      @@ -2735,9 +2736,11 @@ boolean open (default false): and parent has an element child.
    +
    -

    To pre-insert a node into a -parent before a child, run these steps: +

    +

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

    1. Ensure pre-insert validity of node into parent before @@ -2753,7 +2756,9 @@ boolean open (default false):

    2. Return node.

    +
    +

    Specifications may define insertion steps for all or some nodes. The algorithm is passed insertedNode, as indicated in the insert algorithm @@ -2761,6 +2766,7 @@ below. These steps must not modify the node tree that insertedNodeparticipates in, create browsing contexts, fire events, or otherwise execute JavaScript. These steps may [=queue a global task|queue tasks=] to do these things asynchronously, however. +

    While the insertion steps cannot execute JavaScript (among other things), they will @@ -2806,6 +2812,7 @@ below. These steps must not modify the node tree that insertedNode +

    Specifications may also define post-connection steps for all or some nodes. The algorithm is passed connectedNode, as indicated in the @@ -2818,14 +2825,19 @@ or otherwise execute JavaScript. These steps allow a batch of nodes to be inserted atomically with respect to script, with all major side effects occurring after the batch insertions into the node tree is complete. This ensures that all pending node tree insertions completely finish before more insertions can occur. +

    +

    Specifications may define children changed steps for all or some nodes. The algorithm is passed no argument and is called from insert, remove, and replace data. +

    -

    To insert a node into a parent -before a child, with an optional suppress observers flag, run these steps: +

    +

    To insert a node node into a +node parent before null or a node child, with an +optional boolean suppressObservers (default false):

    1. Let nodes be node's children, if node is a @@ -2839,15 +2851,14 @@ before a child, with an optional suppress observers flag, run

      If node is a {{DocumentFragment}} node:

        -

      1. Remove its children with the suppress observers flag - set. +

      2. Remove its children with + suppressObservers set to true.

      3. Queue a tree mutation record for node with « », nodes, null, and null. -

        This step intentionally does not pay attention to the - suppress observers flag. +

        This step intentionally does not pay attention to suppressObservers.

    2. @@ -2948,7 +2959,7 @@ before a child, with an optional suppress observers flag, run
    -

  • If suppress observers flag is unset, then queue a tree mutation record for +

  • If suppressObservers is false, then queue a tree mutation record for parent with nodes, « », previousSibling, and child.

  • Run the children changed steps for parent. @@ -2977,8 +2988,17 @@ before a child, with an optional suppress observers flag, run

  • For each node of staticNodeList, if node is connected, then run the post-connection steps with node. + + +

    +

    To append a node node to a +node parent: pre-insert node into parent before +null. +

    +
    +

    Specifications may define moving steps for all or some nodes. The algorithm is passed a node movedNode, and a node-or-null @@ -2987,10 +3007,11 @@ algorithm is passed a node movedNode, and a movedNode participates in, create browsing contexts, fire events, or otherwise execute JavaScript. These steps may queue tasks to do these things asynchronously, however. +

    - +

    To move a node node into a node -newParent before a node-or-null child: +newParent before null or a node child:

      @@ -3115,14 +3136,13 @@ to do these things asynchronously, however.

    1. Queue a tree mutation record for newParent with « node », « », newPreviousSibling, and child.

    +
    +
    -

    To append a node to a parent, -pre-insert node into parent before null. - - -

    To replace a child with node -within a parent, run these steps: +

    +

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

  • Insert node into parent before referenceChild - with the suppress observers flag set. + with suppressObservers set to true.

  • Queue a tree mutation record for parent with nodes, removedNodes, previousSibling, and referenceChild.

  • Return child. + - -

    To replace all with a node -within a parent, run these steps: +

    +

    To replace all with a node or +null node within a node parent:

    1. Let removedNodes be parent's children. @@ -3221,10 +3243,10 @@ within a parent, run these steps:

    2. Otherwise, if node is non-null, set addedNodes to « node ».

    3. Remove all parent's children, in tree order, - with the suppress observers flag set. + with suppressObservers set to true.

    4. If node is non-null, then insert node into - parent before null with the suppress observers flag set. + parent before null with suppressObservers set to true.

    5. If either addedNodes or removedNodes is not empty, then queue a tree mutation record for parent with addedNodes, @@ -3233,10 +3255,13 @@ within a parent, run these steps:

      This algorithm does not make any checks with regards to the node tree constraints. Specification authors need to use it wisely. +

    +
    -

    To pre-remove a child from a -parent, run these steps: +

    +

    To pre-remove a node child +from a node parent:

    1. If child's parent is not parent, then throw a @@ -3247,16 +3272,19 @@ within a parent, run these steps:

    2. Return child.

    +
    - +

    Specifications may define removing steps for all or some nodes. The algorithm is passed a node removedNode and a node-or-null oldParent, as indicated in the remove algorithm below. +

    +

    To remove a node node, with an -optional suppress observers flag, run these steps: +optional boolean suppressObservers (default false):

    1. Let parent be node's parent. @@ -3328,12 +3356,13 @@ optional suppress observers flag, run these steps: source is registered to node's registered observer list. -

    2. If suppress observers flag is unset, then queue a tree mutation record for +

    3. If suppressObservers is false, then queue a tree mutation record for parent with « », « node », oldPreviousSibling, and oldNextSibling.

    4. Run the children changed steps for parent.

    +

    Mixin {{NonElementParentNode}}

    @@ -4171,7 +4200,7 @@ method steps are:

  • Let nodes be the inclusive ancestors of target.

  • -

    For each node in nodes, and then for each +

    For each node of nodes, and then for each registered of node's registered observer list:

      @@ -7762,7 +7791,7 @@ return this's custom element registry.

    1. Let elements be this's inclusive ancestors that are elements, in reverse tree order. -

    2. For each element in elements, if +

    3. For each element of elements, if match a selector against an element, using s, element, and scoping root this, returns success, return element. [[!SELECTORS4]] @@ -9135,7 +9164,7 @@ method steps are: original start offset, count original start node's length − original start offset, data the empty string. -

    4. For each node in nodes to remove, in tree order, +

    5. For each node of nodes to remove, in tree order, remove node.

    6. If original end node is a {{CharacterData}} node, then @@ -9339,9 +9368,8 @@ method steps are: clone.

    -
  • For each contained child in contained children, - append contained child to - fragment. +

  • For each contained child of contained children: append + contained child to fragment.

  • If last partially contained child is a {{CharacterData}} node: @@ -9547,15 +9575,13 @@ of a live range range, run these steps:

  • - For each contained child in - contained children: +

    For each contained child of contained children:

      -
    1. Let clone be a clone of - contained child with the clone children flag set. +

    2. Let clone be a clone of contained child + with subtree set to true. -

    3. Append clone to - fragment. +

    4. Append clone to fragment.

  • @@ -10638,7 +10664,7 @@ method steps are: "{{InvalidCharacterError!!exception}}" {{DOMException}}. -

  • For each token of tokens, append +

  • For each token of tokens: append token to this's token set.

  • Run the update steps. @@ -10660,7 +10686,7 @@ method steps are: "{{InvalidCharacterError!!exception}}" {{DOMException}}. -

  • For each token in tokens, remove token from +

  • For each token of tokens: remove token from this's token set.

  • Run the update steps. From 7e0be5bc898196a080eb2b450b3ae2b1a6e926a0 Mon Sep 17 00:00:00 2001 From: Anne van Kesteren Date: Tue, 25 Nov 2025 10:46:48 +0100 Subject: [PATCH 2/5] Update dom.bs --- dom.bs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/dom.bs b/dom.bs index b3bd17cd..fd1ea3e4 100644 --- a/dom.bs +++ b/dom.bs @@ -3219,7 +3219,7 @@ a node node within a node parent DocumentFragment node. -->

  • Insert node into parent before referenceChild - with suppressObservers set to true. + with suppressObservers set to true.

  • Queue a tree mutation record for parent with nodes, removedNodes, previousSibling, and referenceChild. @@ -9579,7 +9579,7 @@ of a live range range, run these steps:

    1. Let clone be a clone of contained child - with subtree set to true. + with subtree set to true.

    2. Append clone to fragment.

    From f491f753505c98b337102ae931a24a2690646faa Mon Sep 17 00:00:00 2001 From: Anne van Kesteren Date: Tue, 25 Nov 2025 10:47:45 +0100 Subject: [PATCH 3/5] Update dom.bs --- dom.bs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/dom.bs b/dom.bs index fd1ea3e4..a50303c2 100644 --- a/dom.bs +++ b/dom.bs @@ -3001,7 +3001,7 @@ null.

    Specifications may define moving steps for all or some nodes. The -algorithm is passed a node movedNode, and a node-or-null +algorithm is passed a node movedNode, and a node-or-null oldParent as indicated in the move algorithm below. Like the insertion steps, these steps must not modify the node tree that movedNode participates in, create browsing contexts, From 37f39f1afc0e524e2923f81c6c02d730a29228ad Mon Sep 17 00:00:00 2001 From: Anne van Kesteren Date: Tue, 25 Nov 2025 10:49:38 +0100 Subject: [PATCH 4/5] Update dom.bs --- dom.bs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/dom.bs b/dom.bs index a50303c2..44dfada9 100644 --- a/dom.bs +++ b/dom.bs @@ -2834,7 +2834,7 @@ that all pending node tree insertions completely finish before more inser remove, and replace data.

    -
    +

    To insert a node node into a node parent before null or a node child, with an optional boolean suppressObservers (default false): @@ -3282,7 +3282,7 @@ algorithm is passed a node removedNode and a algorithm below.

    -
    +

    To remove a node node, with an optional boolean suppressObservers (default false): From ad08312bdf4e568770f1d13f08626b16eca601d9 Mon Sep 17 00:00:00 2001 From: Anne van Kesteren Date: Tue, 25 Nov 2025 11:05:07 +0100 Subject: [PATCH 5/5] correct for each punctuation --- dom.bs | 50 +++++++++++++++++++++++++------------------------- 1 file changed, 25 insertions(+), 25 deletions(-) diff --git a/dom.bs b/dom.bs index 44dfada9..d2af7842 100644 --- a/dom.bs +++ b/dom.bs @@ -962,7 +962,7 @@ correct defaults.

    relative high resolution coarse time given time and event's relevant global object. -

  • For each member → value of dictionary, if +

  • For each member → value of dictionary: if event has an attribute whose identifier is member, then initialize that attribute to value. @@ -1263,8 +1263,8 @@ method steps are:

    To remove all event listeners, given an {{EventTarget}} object -eventTarget, for each listener of eventTarget's -event listener list, remove an event listener with +eventTarget: for each listener of eventTarget's +event listener list: remove an event listener with eventTarget and listener.

    HTML needs this to define document.open(). [[HTML]] @@ -1383,7 +1383,7 @@ property of the event being dispatched.

  • Let touchTargets be a new list.

  • For each touchTarget of event's - touch target list, append the result of retargeting + touch target list: append the result of retargeting touchTarget against target to touchTargets.

  • Append to an event path with event, target, @@ -1430,7 +1430,7 @@ property of the event being dispatched.

  • Let touchTargets be a new list.

  • For each touchTarget of event's - touch target list, append the result of retargeting + touch target list: append the result of retargeting touchTarget against parent to touchTargets.

  • @@ -2644,7 +2644,7 @@ boolean open (default false):

  • Set slot's assigned nodes to slottables. -

  • For each slottable of slottables, set slottable's +

  • For each slottable of slottables: set slottable's assigned slot to slot. @@ -2866,11 +2866,11 @@ optional boolean suppressObservers (default f

    1. For each live range whose start node is parent and - start offset is greater than child's index, increase + start offset is greater than child's index: increase its start offset by count.

    2. For each live range whose end node is parent and - end offset is greater than child's index, increase + end offset is greater than child's index: increase its end offset by count.

    @@ -2980,12 +2980,12 @@ optional boolean suppressObservers (default f

    1. For each shadow-including inclusive descendant inclusiveDescendant of - node, in shadow-including tree order, append + node, in shadow-including tree order: append inclusiveDescendant to staticNodeList.

    • -

  • For each node of staticNodeList, if node is +

  • For each node of staticNodeList: if node is connected, then run the post-connection steps with node. @@ -3051,7 +3051,7 @@ to do these things asynchronously, however.

  • For each {{NodeIterator}} object iterator whose root's node document is node's - node document, run the NodeIterator pre-remove steps given + node document: run the NodeIterator pre-remove steps given node and iterator.

  • Let oldPreviousSibling be node's previous sibling. @@ -3082,11 +3082,11 @@ to do these things asynchronously, however.

    1. For each live range whose start node is newParent and - start offset is greater than child's index, increase + start offset is greater than child's index: increase its start offset by 1.

    2. For each live range whose end node is newParent and - end offset is greater than child's index, increase + end offset is greater than child's index: increase its end offset by 1.

    @@ -3295,7 +3295,7 @@ optional boolean suppressObservers (default fal

  • For each {{NodeIterator}} object iterator whose root's node document is node's - node document, run the NodeIterator pre-remove steps given + node document: run the NodeIterator pre-remove steps given node and iterator.

  • Let oldPreviousSibling be node's previous sibling. @@ -3955,7 +3955,7 @@ run these steps:

  • Empty mo's record queue.

  • For each node of mo's - node list, remove all + node list: remove all transient registered observers whose observer is mo from node's registered observer list. @@ -3964,7 +3964,7 @@ run these steps: and "report", and with callback this value mo. -

  • For each slot of signalSet, fire an event named +

  • For each slot of signalSet: fire an event named slotchange, with its {{Event/bubbles}} attribute set to true, at slot. @@ -4138,12 +4138,12 @@ method steps are:

  • For each registered of target's - registered observer list, if registered's + registered observer list: if registered's observer is this:

    1. For each node of this's - node list, remove all + node list: remove all transient registered observers whose source is registered from node's registered observer list. @@ -4169,7 +4169,7 @@ method steps are:

      1. For each node of this's - node list, remove any registered observer from + node list: remove any registered observer from node's registered observer list for which this is the observer. @@ -4793,22 +4793,22 @@ each descendant exclusive Text node nod

        While currentNode is an exclusive Text node:

          -

        1. For each live range whose start node is currentNode, +

        2. For each live range whose start node is currentNode: add length to its start offset and set its start node to node. -

        3. For each live range whose end node is currentNode, add +

        4. For each live range whose end node is currentNode: add length to its end offset and set its end node to node.

        5. For each live range whose start node is currentNode's parent and start offset is currentNode's - index, set its start node to node and its + index: set its start node to node and its start offset to length.

        6. For each live range whose end node is currentNode's parent and end offset is currentNode's - index, set its end node to node and its + index: set its end node to node and its end offset to length.

        7. Add currentNode's length to length. @@ -7791,7 +7791,7 @@ return this's custom element registry.

        8. Let elements be this's inclusive ancestors that are elements, in reverse tree order. -

        9. For each element of elements, if +

        10. For each element of elements: if match a selector against an element, using s, element, and scoping root this, returns success, return element. [[!SELECTORS4]] @@ -9164,7 +9164,7 @@ method steps are: original start offset, count original start node's length − original start offset, data the empty string. -

        11. For each node of nodes to remove, in tree order, +

        12. For each node of nodes to remove, in tree order: remove node.

        13. If original end node is a {{CharacterData}} node, then