"beforebegin"/"afterend" must absolutely throw if you try to insert text or element. But inserting comments or using "afterbegin"/"beforeend" seems ok.

In other words, we should remove the explicit throwing if the context is a document, but we should reword the actual insertion of the fragment in terms of calling insertBefore and rethrow any exceptions that that throws.

(In reply to comment #1)
> "beforebegin"/"afterend" must absolutely throw if you try to insert text or
> element. 

The current spec doesn't throw if the parent is null, either.

> But inserting comments or using "afterbegin"/"beforeend" seems ok.

WebKit doesn't support it.

> In other words, we should remove the explicit throwing if the context is a
> document, but we should reword the actual insertion of the fragment in terms of
> calling insertBefore and rethrow any exceptions that that throws.

There's little value in being able to insert comments or whitespace using insertAdjacentHTML, but supporting that case would add complexity. We'd need to deoptimize the "afterend" case in Gecko when insertAdjacentHTML is invoked on the root element. Is being able to insert comments really worth the trouble compared to keeping the spec as-is or making the parent-is-document case return silently without doing anything?

(In reply to comment #2)
> (In reply to comment #1)
> > "beforebegin"/"afterend" must absolutely throw if you try to insert text
> > or element. 
> 
> The current spec doesn't throw if the parent is null, either.

That seems like a bug in the spec.

> > But inserting comments or using "afterbegin"/"beforeend" seems ok.
> 
> WebKit doesn't support it.

Which "it"? And it's not immediately clear why webkit not supporting it matters?

> > In other words, we should remove the explicit throwing if the context is a
> > document, but we should reword the actual insertion of the fragment in
> > terms of calling insertBefore and rethrow any exceptions that that throws.
> 
> There's little value in being able to insert comments or whitespace using
> insertAdjacentHTML, but supporting that case would add complexity. We'd need
> to deoptimize the "afterend" case in Gecko when insertAdjacentHTML is
> invoked on the root element. Is being able to insert comments really worth
> the trouble compared to keeping the spec as-is or making the
> parent-is-document case return silently without doing anything?

I'm not sure what you mean by "deoptimize".

A good implementation strategy seems to be to detect when parsing into the document node (which can happen for innerHTML, outerHTML and insertAdjecentHTML). In gecko this requires a single inlined flag check, so not a performance problem for the common case.

When parsing into the document node, use a fragment as parsing target and then insert the fragment using insertBefore or other appropriate DOM method and rethrow any exceptions that that throws.

(In reply to comment #3)
> (In reply to comment #2)
> > (In reply to comment #1)
> > > "beforebegin"/"afterend" must absolutely throw if you try to insert text
> > > or element. 
> > 
> > The current spec doesn't throw if the parent is null, either.
> 
> That seems like a bug in the spec.

The spec is describing an existing feature and implementations that predated the spec didn't throw in that case.

> > > But inserting comments or using "afterbegin"/"beforeend" seems ok.
> > 
> > WebKit doesn't support it.
> 
> Which "it"? 

Inserting comments outside the root element using insertAdjacentHTML.

> And it's not immediately clear why webkit not supporting it
> matters?

It's an indicator that sites probably don't try to insert comments above the root element too much using insertAdjacentHTML().

> > > In other words, we should remove the explicit throwing if the context is a
> > > document, but we should reword the actual insertion of the fragment in
> > > terms of calling insertBefore and rethrow any exceptions that that throws.
> > 
> > There's little value in being able to insert comments or whitespace using
> > insertAdjacentHTML, but supporting that case would add complexity. We'd need
> > to deoptimize the "afterend" case in Gecko when insertAdjacentHTML is
> > invoked on the root element. Is being able to insert comments really worth
> > the trouble compared to keeping the spec as-is or making the
> > parent-is-document case return silently without doing anything?
> 
> I'm not sure what you mean by "deoptimize".

I mean having to have yet another check before we decide whether we can parse directly into the context node.

> A good implementation strategy seems to be to detect when parsing into the
> document node (which can happen for innerHTML, outerHTML and
> insertAdjecentHTML). In gecko this requires a single inlined flag check, so not
> a performance problem for the common case.
> 
> When parsing into the document node, use a fragment as parsing target and then
> insert the fragment using insertBefore or other appropriate DOM method and
> rethrow any exceptions that that throws.

But why bother doing any of this compared to not letting anything be inserted before or after the root element? Is there a use case that Web authors really need addressed here?

I am told that

  document.documentElement.insertAdjacentHTML("beforebegin", "<div></div>")

adds a second element child to the document in IE8 and IE9, and throws (per spec) in IE10, and that it throws in the null-parent case as well. That is, IE appears to match Gecko.

After discussion with Henri, I went with throwing in both cases.

https://bitbucket.org/ms2ger/dom-parsing-and-serialization/changeset/ee0ba6d66250