Docs: Fix Safari scrolling to anchors in iframes.

[mrdoob]

Related issue: #32302

Description

Fixes an issue where clicking on navigation links in Safari would not scroll to the correct position within the documentation iframe.

The problem occurred because Safari needs additional time to complete iframe layout before scrollIntoView can accurately position the target element. This was only noticeable when navigating via clicks - direct page loads with hash fragments worked fine due to browser's native hash handling.

The fix adds Safari-specific detection and applies a 100ms delay before scrolling, giving Safari time to properly lay out the iframe content.

[mrdoob]

This solves https://threejs.org/docs/?q=setviewport#Renderer.setViewport (reported by @WestLangley)
But doesn't solve https://threejs.org/docs/#TSL.Break ...

Needs more work/investigation.

[Mugen87]

I've tested a bit more and it seems increasing the timeout from 100 to 200 solves the issue on my macMini.

Given that TSL.html is by far the largest document, the Safari probably needs more time to make the page ready.

[Mugen87]

If we find no other solution, I would like to file a bug at the WebKit bug reporter. I've already searched but found no open bug about scrollIntoView() issues in context of iFrames.

https://bugs.webkit.org/buglist.cgi?bug_status=__open__&content=scrollIntoView&no_redirect=1&order=Importance&product=WebKit&query_format=specific

[Mugen87]

@mrdoob I've increased the timeout from 100ms to 250 ms which worked on my macMini and an iPad.

[WestLangley]

Increasing the time out does not work for me. I tried searching for "translate".

[Mugen87]

With what devices have you tested?

[WestLangley]

M1 iMac MacOS Tahoe 26.1 Safari 26.1.

To be clear, when searching for "translate", sometimes it works, and in other cases the iframe is blank, and scrolling is necessary to locate the proper position in the file.

[Mugen87]

It works for me on all my devices. But it starts failing if I decrease the timeout value.

Just for fun I have removed the element.scrollIntoView() call. In Chrome and Firefox, the navigation is still correct but Safari fails. The page in the iFrame is blank and the content only appears if I scroll up. Trying to select text also works.

So it seems the issue is not related to scrollIntoView(). The iFrame page isn't correctly loaded in the first place and that's maybe why scrollIntoView() fails as well.

[shotamatsuda]

I recently opened the new docs in Safari, and the whole TSL section is indeed unusable. After a couple of tries, the below works on my end (both macOS and iOS). Nothing is conclusive, but the reasons behind this are:

• It seems scrolling just after document load confuses Safari's document visible bounds, so it sometimes becomes blank until the user manually scrolls it. scrollRestoration = 'manual' eases it somewhat.
• pageshow is guaranteed to be triggered after load, and seems to fire after the document layout is done.

For testing: https://raw.githack.com/shotamatsuda/three.js/fix/docs-safari-scroll/docs/

( function () {

	const hash = window.location.hash.substring( 1 );

	if ( hash ) {

		window.history.scrollRestoration = 'manual';

		window.addEventListener( 'pageshow', function () {

			const element = document.getElementById( hash );

			if ( element ) element.scrollIntoView();

		}, { once: true } );

	}

} )();

[Mugen87]

That works for me on Safari and MacOS as well!

I like the fact that this is a general solution so we don't have to sniff for Safari.

[Mugen87]

Do you mind making a new PR with this code?