Navigator loses the merged-archive root (package tree) on direct page load since Swift 6.3 renderers

[schiewe]

Description

Since the docc-render build shipped with Xcode 26.4 (Swift 6.3), documentation sites produced from merged archives (docc merge) no longer show the synthesized root node and sibling modules in the navigator when a module or symbol page is loaded directly (deep link or browser refresh). The navigator renders only the current module's subtree, without the package root. Navigating client-side from /documentation/ (where the full tree is shown) works — but any hard load of a deep URL loses the package tree.

This is a recent regression: the renderer shipped with Xcode ≤ 26.3 (js/index.5b6366e8.js) behaves correctly. Reproduced with the renderers from:

• Xcode 26.4.1 / 26.6 (Swift 6.3.x) — js/index.b232e9de.js — affected
• Xcode 27.0 beta 3 (Swift 6.4) — js/index.43237eed.js — affected

Checklist

• If possible, I've reproduced the issue using the main branch of this package. (Reproduced with the toolchain-shipped builds listed above, including the latest beta; not bisected against main.)
• This issue hasn't been addressed in an existing GitHub issue.

Expected Behavior

Direct loads of pages inside a merged archive show the same navigator as client-side navigation: the synthesized root with all merged modules.

Actual behavior

Hard-loading /documentation/<module>/ (or refreshing after navigating there) renders a navigator scoped to the current module only; the synthesized package root and sibling modules are missing. Opening /documentation/ shows the full tree, and client-side navigation from there retains it.

Steps To Reproduce

Minimal, spec-compliant repro (two trivial modules, plain docc merge, no post-processing):

export DEVELOPER_DIR=/Applications/Xcode-26.4.1.app/Contents/Developer
W=$(mktemp -d); cd "$W"
for M in AlphaKit BetaKit; do
  mkdir -p $M/sg
  printf '/// The %s entry class.\npublic class %sMain { public init() {}\n  /// Does the thing.\n  public func run() {} }\n' $M $M > $M/src.swift
  xcrun swiftc -emit-module -module-name $M -emit-module-path $M/$M.swiftmodule $M/src.swift
  xcrun swift-symbolgraph-extract -module-name $M -I $M \
    -target arm64-apple-macos26.0 -sdk "$(xcrun --sdk macosx --show-sdk-path)" \
    -output-dir $M/sg -minimum-access-level public
  xcrun docc convert --fallback-display-name $M \
    --fallback-bundle-identifier com.example.$(echo $M | tr A-Z a-z) \
    --fallback-bundle-version 1 --additional-symbol-graph-dir $M/sg \
    --output-path $M.doccarchive
done
xcrun docc merge AlphaKit.doccarchive BetaKit.doccarchive \
  --synthesized-landing-page-name "Spec SDK" --synthesized-landing-page-kind Package \
  --output-path merged.doccarchive
xcrun docc process-archive transform-for-static-hosting merged.doccarchive --output-path site
(cd site && python3 -m http.server 8000)

1. Open http://localhost:8000/documentation/ → navigator shows Spec SDK → AlphaKit, BetaKit ✅
2. Open http://localhost:8000/documentation/alphakit/ directly (or refresh after navigating there) → navigator shows only AlphaKit's contents; the Spec SDK root and BetaKit are missing ❌

Replacing site/js + site/index.html etc. with the render template from an Xcode ≤ 26.3 toolchain (usr/share/docc/render, js/index.5b6366e8.js) and reloading step 2 shows the expected full tree — the archive data is identical, only the renderer differs.

Notes:

• index/index.json contains the full tree (root node with both modules) and includedArchiveIdentifiers in all cases; the RenderNode schema is 0.3.0 for both toolchains, so this appears to be purely a renderer-side scoping change/regression on initial route resolution.
• Also reproduced with a real-world 5-module merged archive.
• Also filed with Apple as FB23741608.

Swift-DocC-Render Version Information

Toolchain-shipped builds: js/index.b232e9de.js (Xcode 26.4.1 / 26.6, Swift 6.3.x) and js/index.43237eed.js (Xcode 27.0 beta 3, Swift 6.4); last known-good build js/index.5b6366e8.js (Xcode 26.0.1–26.3, Swift 6.2.x).

[schiewe]

Also filed with Apple as FB23741608.

[mportiz08]

I was able to narrow this down to the merge commit from #981 that first introduced this issue.

@marinaaisa can you help investigate this since you worked on that PR?

[heckj]

I was just about to come file the same issue, spotted while working on prototypes for combined Swift documentation, so I've got an additional reproduction case if it helps.

My prototype merged catalog is available via GitHub pages at https://heckj.github.io/docs/main/documentation/, and if you drill into one of the combined catalogs (DocC for example) and then reload the browser, all the parallel navigation pieces disappear - the index.json that's presented from within that catalog doesn't appear to reflect the neighbor catalogs that are merged into the combined archive.

(latest example was built with Swift 6.4)

[VictorPuga]

Found the likely cause (with some AI-assisted digging): extractRootModule in src/utils/navigatorData.js (added in #981) flattens the root and its nested modules into one list, then picks whichever entry's path matches the current URL. On /documentation/alphakit/, that matches AlphaKit itself instead of falling back to the package root, so AlphaKit gets treated as root and the rest of the tree disappears. Before #981 this only checked the top-level array, which for merged archives has just one entry, so it always resolved to the true root.

Happy to send a PR scoping the URL match to top-level siblings only, if that sounds right.

[marinaaisa]

Found the likely cause (with some AI-assisted digging): extractRootModule in src/utils/navigatorData.js (added in #981) flattens the root and its nested modules into one list, then picks whichever entry's path matches the current URL. On /documentation/alphakit/, that matches AlphaKit itself instead of falling back to the package root, so AlphaKit gets treated as root and the rest of the tree disappears. Before #981 this only checked the top-level array, which for merged archives has just one entry, so it always resolved to the true root.

Happy to send a PR scoping the URL match to top-level siblings only, if that sounds right.

please, open a PR if you can, that would be very useful, thanks! @VictorPuga

[VictorPuga]

Here's the PR: #1032