fix: support app-owned scroll containers

[scarab-systems]

closes #2733

This takes a focused pass at the scroll-container part of this issue. I used Scarab boundary diagnostics to look for where the reported behavior crossed from app layout into router-owned scroll management, then used that as the repair boundary.

The boundary I found was that SvelteKit's router captures/restores scroll state from the window and applies navigation scrolls with window.scrollTo(...), while a common app-shell layout keeps the document fixed and scrolls an inner element instead. In that layout, SvelteKit can successfully navigate but still preserve the old visual scroll position because it is reading and writing the wrong scroll owner.

This PR adds an explicit data-sveltekit-scroll-container opt-in for that case. When present, SvelteKit reads/restores that element's scrollLeft/scrollTop; otherwise the existing window behavior is unchanged.

I looked through the previous attempts/discussion before shaping this:

• This does not try to auto-detect a scrollable element. That avoids the earlier concern that guessing could pick the wrong region, such as a sidebar, when multiple scroll areas exist.
• This is not the scroll-behavior: smooth workaround from fix: iOS scroll-behavior: smooth breaks navigation scrolling #8724/fix: use instant scroll behavior during navigation to fix scroll-behavior: smooth #15521. It leaves the existing window/smooth-scroll behavior alone and addresses the maintainer feedback that the main unresolved issue is finding the correct container to scroll.
• This includes the missing pieces that made earlier versions hard to review: a regression that fails before the runtime change, docs, generated attribute typing, and a patch changeset.

The regression fixture uses a fixed app shell with an inner <main data-sveltekit-scroll-container>. It verifies both forward navigation to the top and back-button scroll restoration. It also includes a data-sveltekit-scroll-container="false" wrapper so the selected scroll owner is explicit and test-protected.

Happy to adjust the attribute name, docs location, or shape of the opt-in if maintainers prefer a different public API.

---

Please don't delete this checklist! Before submitting the PR, please make sure you do the following:

• It's really useful if your PR references an issue where it is discussed ahead of time. In many cases, features are absent for a reason. For large changes, please create an RFC: https://github.com/sveltejs/rfcs
• This message body should clearly illustrate what problems it solves.
• Ideally, include a test that fails without this PR but passes with it.

Tests

• Run the tests with pnpm test and lint the project with pnpm lint and pnpm check

Checked in an isolated repo workspace:

• pnpm run format
• pnpm -F @sveltejs/kit prepublishOnly
• NODE_OPTIONS=--max-old-space-size=4096 pnpm run lint
• NODE_OPTIONS=--max-old-space-size=4096 pnpm run check
• NODE_OPTIONS=--max-old-space-size=4096 pnpm -F @sveltejs/kit test:unit
• pnpm --dir packages/kit/test/apps/basics test:cross-platform:dev --grep "app-owned container" --project=chromium-dev
• pnpm --dir packages/kit/test/apps/basics test:cross-platform:dev --grep "Scrolling" --project=chromium-dev
• pnpm --dir packages/kit/test/apps/basics test:cross-platform:build --grep "app-owned container" --project=chromium-build

Changesets

• If your PR makes a change that should be noted in one or more packages' changelogs, generate a changeset by running pnpm changeset and following the prompts. Changesets that add features should be minor and those that fix bugs should be patch. Please prefix changeset messages with fix:, feat:, or chore:.

Edits

• Please ensure that 'Allow edits from maintainers' is checked. PRs without this option may be closed.

Disclosure: This PR was prepared with AI assistance under human direction and review.

[pkg-svelte-dev]

Install the latest version of @sveltejs/kit from 3ecd821:

pnpm add https://pkg.svelte.dev/@sveltejs/kit/c/3ecd821e85598cdfb37d71b80c6e651995b38758

Open in pkg.svelte.dev: https://pkg.svelte.dev/repos/kit/pr/16427

Note

This PR is from a fork. A maintainer must approve approve each commit before it can be built and installed.

[changeset-bot]

🦋 Changeset detected

Latest commit: 3ecd821

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@sveltejs/kit	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR