That's what you requested to do: the new data is inserted after the end
of the character element at the caret position, which may be further from
the current caret position. If you want to insert at the caret position,
there seems to be no non-trivial way to do it by default.

Try this to create an element boundary at the caret position, then insert
AfterEnd (or BeforeStart) can be used.

import javax.swing.text.*;
import java.io.IOException;

import javax.swing.text.html.HTMLDocument;
import javax.swing.text.html.HTMLEditorKit;
import javax.swing.text.html.StyleSheet;

public class HTMLDocument2
   extends HTMLDocument
{
   public HTMLDocument2(StyleSheet s)
   {
    super(s);
   }
   

   private void ensureLeafBoundary(int position)
   {
    Element e = getCharacterElement(position);
   
    if (position != e.getStartOffset())
    {
       // somewhat hacky too avoid low-level ElementBuffer stuff
       setCharacterAttributes(position, Math.min(getLength(), e.getEndOffset()) - position, SimpleAttributeSet.EMPTY, false);
    }
   }
       

   public void insertAtLeaf(int position, String htmlText)
   {
    try
    {
       ensureLeafBoundary(position);
       
       insertBeforeStart(getCharacterElement(position), htmlText);
    }
    catch (BadLocationException e)
    {
       throw new IllegalArgumentException(e.getMessage());
    }
    catch (IOException e)
    {
       throw new RuntimeException(e.getMessage());
    }
       
   }
}

class HTMLEditorKit2
   extends HTMLEditorKit
{
   public HTMLEditorKit2()
   {
   }
   
   public Document createDefaultDocument()
   {
    StyleSheet sheet = getStyleSheet();

    StyleSheet styles = new StyleSheet();
   
    styles.addStyleSheet(sheet);
   
    HTMLDocument result = new HTMLDocument2(styles);
   
    result.setParser(getParser());
   
    result.setAsynchronousLoadPriority(4);
   
    result.setTokenThreshold(100);
   
    return result;
   }
}

class HTMLTest
{
   public static void main(String[] args)
   {
    javax.swing.JFrame f = new javax.swing.JFrame();

    final javax.swing.JEditorPane t = new javax.swing.JEditorPane();
    t.setEditorKit(new HTMLEditorKit2());

    final HTMLDocument2 d = (HTMLDocument2)t.getDocument();

    javax.swing.JButton add = new javax.swing.JButton("Add");
    add.addActionListener(new java.awt.event.ActionListener()
    {
       public void actionPerformed(java.awt.event.ActionEvent e)
       {
        d.insertAtLeaf(t.getCaretPosition(), "<B>Text<P>More <em>data");
       }
    });
   
    f.getContentPane().add(new javax.swing.JScrollPane(t));
    f.getContentPane().add(add, "South");

    f.setSize(500, 400); f.show();
   }
}

Christian