I've got an example file here: https://notionparallax.github.io/paged_media_issue/ (see below for caveats)

I'd like to be able to tell where an element is on the page so that I can implement keep with for headers, and avoid starting a new section at the bottom of a page. E.g. this header should bump to the next page so that it's not stranded without its paragraph.

I had a crack at a handler:

class MyHandler extends Paged.Handler {
    constructor(chunker, polisher, caller) {
        super(chunker, polisher, caller);
    }

    afterPageLayout(pageFragment, page, breakToken) {
        let h = pageFragment.querySelector("h1.article-title");
        if(h !== null) {
            let pBox = page.element.getBoundingClientRect();
            let hBox = h.getBoundingClientRect();
            let pdelta = pBox.bottom - hBox.bottom;
            let botPC =  pdelta/pBox.height;
            if (botPC < 0.4) {
                breakToken.offset  = 0;
                // breakToken.node = h; // breaks: node.getAttribute is not a function
                // h.parentElement.classList.add("break-before"); // doesn't force a break
                console.log("pageFragment", pageFragment, "page", page, "breakToken", breakToken);
                console.log(h);
                console.log(pdelta, botPC,"*****\n\n\n");
            }
            
        }
    }
}
Paged.registerHandlers(MyHandler);

The handler has moved on a bit since this, but this is the gist of things. It's in control.js. It currently paints all headings that are too close to the bottom of the page in red.

This is a pretty crusty way of telling if there's a break needed, but I assume that this is the right direction, and I'm not barking up the wrong tree? (I'd imagine that the adobe way looks at the context a lot more.)

Context

This is a mini magazine that pulls my articles from Pocket, and lets me read them without getting distracted by notifications. It usually has an hour of content, but this particular one has two hours worth to give more opportunities for odd things to happen.

Caveats

There are a few other odd things that happen in this file, I don't want to muddy the waters with the reporting them as bugs right now, but I'll mention them so that you get what's going on.

• If you watch the toc while it's paginating, sometimes it gets stuck. If not all the articles get page numbers, then refreshing it usually fixes it.
• I'm a bit lost with the lifecycle of the beforeParsed function. Some things work well inside it, some don't work at all. Currently all the pre processing is outside it.