[codex] Preserve nested Swift specializations

ArchiveScript.sh

@@ -422,7 +422,12 @@ if $COMMIT_PUSH; then
         cp docs/appcast.xml "$tmp_appcast"
         run git fetch origin main
         APPCAST_BRANCH="appcast-for-$VERSION_TAG"
-        run git checkout -B "$APPCAST_BRANCH" origin/main
+        # Archive runs `xcodebuild -resolvePackageDependencies`, which mutates
+        # the workspace's Package.resolved. Those changes do NOT belong in the
+        # appcast PR and would otherwise block `git checkout` with a "local
+        # changes would be overwritten" abort. docs/appcast.xml is safely in
+        # $tmp_appcast and gets re-applied below, so a forced checkout is fine.
+        run git checkout -f -B "$APPCAST_BRANCH" origin/main
         cp "$tmp_appcast" docs/appcast.xml
         rm -f "$tmp_appcast"
         if git diff --quiet docs/appcast.xml; then

CLAUDE.md

@@ -268,6 +268,20 @@ override func setupBindings(for viewModel: MyViewModel) {
 | `VStackView(alignment:spacing:) { ... }` | `NSStackView(orientation: .vertical)` |
 | `HStackView(spacing:) { ... }` | `NSStackView(orientation: .horizontal)` |
 | `ScrollView()` | `NSScrollView()` |
+| `final class XxxView: LayerBackedView` | `final class XxxView: NSView` (when it needs `cornerRadius` / border / `backgroundColor` / shadow) |
+
+**Layer-backed views** — any custom AppKit view that needs layer-level visuals (rounded corners, border, background color, shadow) MUST inherit `UIFoundationAppKit.LayerBackedView`, never raw `NSView` with hand-rolled `wantsLayer = true` + `layer?.cornerRadius / layer?.borderColor / layer?.backgroundColor = ....cgColor`. The base class already sets `wantsLayer + layerContentsRedrawPolicy = .onSetNeedsDisplay` and centralizes everything in `updateLayer()`, so:
+
+- Assign the exposed `NSColor?` properties directly — `backgroundColor = NSColor(light:dark:)`, `borderColor = ...` — **without** `.cgColor`. Dynamic colors re-resolve on appearance change automatically; you do NOT need to override `viewDidChangeEffectiveAppearance`.
+- One-time setup goes in `override func setup()` (called by `commonInit`); first-layout work goes in `override func firstLayout()`. Don't repeat `wantsLayer = true` in `init`.
+- Available properties: `cornerRadius`, `borderWidth`, `borderColor`, `borderPositions`, `borderLocation`, `borderInsets`, `backgroundColor`, `shadowColor`, `shadowOpacity`, `shadowOffset`, `shadowRadius`, `shadowPath`.
+- **Gotcha — `borderPositions` defaults to `[]`, so the border won't render** even with non-zero `borderWidth` + non-nil `borderColor`. To draw a full rounded border you MUST set `borderPositions = .all`:
+  ```swift
+  cornerRadius = 8
+  borderWidth = 1
+  borderColor = NSColor(light: ..., dark: ...)
+  borderPositions = .all   // ← otherwise the previous 3 lines are ignored
+  ```
 
 **View initialization** — `.then {}` returns the configured object (for assignment):
 ```swift

Changelogs/v2.1.0-beta.2.md

@@ -0,0 +1,112 @@
+# v2.1.0-beta.2
+
+Second public preview of the **2.1** line. Headline additions: a new
+**Relationships** tab in the Inspector, a **Batch Export** flow from the File
+menu, and **selection history** in the toolbar. Plus a stack of performance
+and stability fixes carried over from beta.1.
+
+This is a `beta` build — only clients that opted in via
+**Settings → Updates → Include pre-release versions** receive it.
+
+---
+
+## New Features
+
+### Inspector → Relationships
+A new **Relationships** tab sits between *Hierarchy* and *Specialization* and
+shows where a type is referenced across the binaries you have loaded.
+
+- Surfaces inbound references (who uses this type) and outbound references
+  (what this type depends on), drawn from a dedicated relationships engine.
+- Works across binaries: if the indexed images include the consumers of a
+  type, they show up regardless of which dylib defines it.
+- The list lays out cleanly even when a type has no relationships — an empty
+  state explains why instead of showing a blank tab.
+
+### Batch Export
+Export the interfaces of multiple images in one pass without opening each
+document individually.
+
+- New **File → Export Multiple Images…** entry walks you through image
+  selection, format selection, and destination directory in a single sheet.
+- Per-language format choices (Objective-C `.h`, Swift surface, etc.) are
+  remembered across runs, so the next export starts where you left off.
+- The completion summary now uses stat cards to show how many files
+  succeeded, failed, or were skipped, and lists each failure individually so
+  you can re-run only what broke.
+- Export file names are clamped below the APFS `NAME_MAX` limit, so long
+  Swift-mangled names no longer produce errors mid-batch.
+
+### Selection History in the Toolbar
+The toolbar now drives back / forward navigation off a true selection
+history cursor, the way Xcode and Finder do.
+
+- Picking a sidebar item, drilling into a type, and switching between
+  Hierarchy / Relationships / Specialization tabs all push onto the same
+  stack.
+- The buttons enable / disable based on what's actually in the history, so
+  you never end up clicking back into nothing.
+- The active inspector tab is preserved when you move between selections, so
+  jumping back into a type returns you to the panel you were last reading.
+
+### Sidebar: smarter expansion
+- Single-clicking a non-leaf row now expands it (matching how the rest of
+  macOS treats outline rows).
+- A new setting caps how deep a double-click expands an entire subtree, so
+  you can preview a framework without exploding hundreds of children.
+
+---
+
+## Performance
+
+- **Type-picker prep moved off the main thread.** When you open the
+  Specialization sheet for a generic with a wide constraint, the candidate
+  list (10k+ entries in common cases) is now built on a background queue
+  with a `LoadingButton` placeholder — the UI no longer hangs while the
+  list is being assembled.
+- **Lazy cell view models for the type picker.** A new
+  `DifferentiableBox` wrapper defers per-row view-model construction until
+  the row is actually rendered, cutting time-to-first-frame on large
+  candidate lists by roughly an order of magnitude.
+- **macOS 26 navbar push cost cut.** Pushing the inspector when the user
+  selects a new sidebar row reuses the existing view controllers instead of
+  rebuilding them, removing a visible flash that appeared on macOS 26.
+
+---
+
+## Bug Fixes
+
+- The Inspector no longer races against `reloadData()` when you click
+  through the sidebar rapidly — in-flight reloads are now cancelled before
+  the next one starts.
+- Indexing skips weak-load dylibs that are shadowed by the dyld shared
+  cache, so they no longer show up as "missing" entries.
+- Injected servers now resolve their main binary path through the dyld
+  registry, which fixes the inspector failing to load for some injection
+  targets.
+- XPC peer activation runs after the modifier installs its handlers,
+  closing a small race window that could drop the first request on a fresh
+  connection.
+- Inspector specialization rows can no longer be selected by accident — the
+  parameter table now refuses row selection the way the rest of the
+  inspector does.
+- Decoding the `runtimeObjectsInImage` response now uses the right request
+  type, so the inspector populates correctly for some injection scenarios
+  that previously returned an empty list.
+
+---
+
+## Under the Hood
+
+- The RuntimeViewer ↔ helper transport was rebuilt on top of the upstream
+  `swift-helper-service` library — XPC connection, peer lifecycle, and
+  daemon entry all delegate to the library now, leaving this repo with a
+  thin set of Runtime-specific adapters.
+- `RuntimeViewerCore` was split: parsing lives in dedicated indexers, the
+  relationships engine has its own resolver, and `RuntimeSwiftSection` was
+  carved into focused extensions instead of one growing file.
+- Document navigation is now state-driven from `DocumentState.selectionStack`
+  rather than ad-hoc coordinator calls, which is what unlocks the toolbar
+  history behaviour above.
+- The communication layer was tightened (sealed `VoidResponse`, prefixed
+  shared transport types with `Runtime*`, dropped `@unchecked Sendable`).

Changelogs/v2.1.0-beta.3.md

@@ -0,0 +1,79 @@
+# v2.1.0-beta.3
+
+Third public preview of the **2.1** line. Stability focus on top of
+[beta.2](v2.1.0-beta.2.md): one critical crash fix in the Bonjour-based
+network connection, plus a MachOSwiftSection bump that picks up an
+SwiftUI-related opaque-type parsing fix. Everything else carries over
+from beta.2 unchanged.
+
+This is a `beta` build — only clients that opted in via
+**Settings → Updates → Include pre-release versions** receive it.
+
+---
+
+## Bug Fixes
+
+### Crash on Bonjour-routed peers under batched receives
+Inspecting an iOS / visionOS / Apple TV target over Bonjour, or pushing a
+batch-export through a Bonjour connection, could crash with
+`EXC_BAD_ACCESS` once a single `NWConnection.receive` carried more than a
+few dozen small frames (heartbeats, acks, or export chunks). The crash hit
+the connection's dispatch-queue worker thread with a 13_000+ frame stack
+overflow.
+
+Two compounding factors fed the overflow on this code path:
+
+1. `RuntimeMessageChannel`'s message-dispatch loop accessed two
+   `@Mutex`-decorated properties (`receivedDataContinuation`,
+   `onMessageReceived`) on every iteration. The macro-generated `_modify`
+   coroutine accessor pinned ~280 bytes of coroutine context on the caller's
+   frame per access and the frames did not unwind between iterations.
+
+2. `RuntimeNetworkConnection.observeIncomingMessages` spawned a fresh
+   `Task { await handleReceivedMessage(data) }` for each message inside that
+   same loop, adding another ~10 frames per iteration on top of (1).
+
+The fix:
+
+- The dispatch loop now snapshots both properties into locals before the hot
+  loop, so each iteration only touches local variables and the `_modify`
+  coroutine frames no longer accumulate.
+- `RuntimeNetworkConnection` now matches `RuntimeLocalSocketConnection` and
+  `RuntimeDirectTCPConnection`: the callback only does a non-blocking
+  `yield` into an unbounded `AsyncStream<Data>`, and one long-lived consumer
+  task drains it. Early messages yielded before the consumer task reaches
+  `for await` are buffered, preserving FIFO across the entire receive burst.
+
+Regression tests cover a 10k-message burst delivered from a dispatch queue
+plus a disabled reproducer that replays the pre-fix per-message-Task shape
+for manual verification.
+
+### Cross-image opaque-type parsing crash (via MachOSwiftSection 0.12.0-beta.3)
+Bumps MachOSwiftSection to **0.12.0-beta.3**, which fixes a crash when an
+indexed image references a Swift opaque-return type whose underlying
+descriptor lives in a sibling loaded image — e.g. SwiftUI body code that
+resolves `View.searchFieldStyle(_:)` against `DVTUserInterfaceKit`. Before
+the bump, the `MachOContext<MachOImage>` decoder treated the symbolic
+reference offset as in-image and walked off into `__PAGEZERO`. The decoder
+now mirrors the Swift runtime and resolves the descriptor through the
+in-process pointer scheme, making cross-image references transparent.
+
+The same MachOSwiftSection bump also brings:
+
+- **SymbolIndexStore self-cleanup** — short-lived indexers now release their
+  cache entry on `deinit` instead of leaking it for the full process
+  lifetime.
+- **`SharedCache` management API** — `contains` / `remove` / `removeAll`
+  let holders explicitly tear down cache entries on disposal.
+- Internal refactors that fold `GenericContext` initialisers onto the
+  unified `ReadingContext` path, fixing a latent negative-size bug in the
+  legacy in-process decoder.
+
+---
+
+## Carried Over From beta.2
+
+All features from [v2.1.0-beta.2](v2.1.0-beta.2.md) ship unchanged: the
+Inspector **Relationships** tab, the **Batch Export** flow under *File →
+Export Multiple Images…*, selection history in the toolbar, and the
+underlying communication-layer hardening.

Changelogs/v2.1.0-beta.4.md

@@ -0,0 +1,90 @@
+# v2.1.0-beta.4
+
+Fourth public preview of the **2.1** line. Re-rolls the Bonjour crash fix from
+[beta.3](v2.1.0-beta.3.md): beta.3's release binary still overflowed the
+dispatch-queue worker stack inside `AsyncStream.yield`. Everything else
+carries over from beta.3 unchanged.
+
+This is a `beta` build — only clients that opted in via
+**Settings → Updates → Include pre-release versions** receive it.
+
+---
+
+## Bug Fixes
+
+### Bonjour-connection crash regression vs. beta.3
+beta.3 shipped two coordinated fixes for the original v2.1.0-beta.2
+`EXC_BAD_ACCESS` on a Bonjour batched receive:
+
+- snapshot `RuntimeMessageChannel`'s `@Mutex`-backed properties into
+  locals before the hot loop, and
+- bridge `RuntimeNetworkConnection.onMessageReceived` through an
+  `AsyncStream<Data>` drained by one long-lived consumer task.
+
+In debug builds the combination was enough. In release, the binary still
+crashed in `AsyncStream._Storage.yield` with a stack-guard fault — the
+crash backtrace showed two `RuntimeViewer` offsets (`0xe88a0` / `0x6c33c`)
+recursing tightly inside a single `connection.receive` callback on the
+`com.RuntimeViewer.RuntimeViewerCommunication.RuntimeNetworkConnection`
+queue. The `@Mutex` macro's `_modify` coroutine accessor still pinned
+coroutine context on the caller's frame across iterations even with the
+snapshot in place, just less of it.
+
+This build drops the `@Mutex` macro from `RuntimeMessageChannel` entirely
+and goes back to the hand-rolled `Mutex<T>` + `withLock` form that shipped
+in v2.1.0-beta.1 (which never crashed on this path). `withLock` is a plain
+synchronous function — no coroutine, no caller-frame pinning, the stack
+unwinds cleanly between iterations.
+
+The buffered-stream bridge from beta.3 stays in place: callback only does
+a non-blocking `yield` and the long-lived consumer task drains
+`handleReceivedMessage` off the dispatch-queue stack.
+
+---
+
+## Known Issues
+
+### Remote-Server background indexing stalls image loading
+
+When the remote engine acting as the Server side (iOS Simulator, iPad /
+iPhone over Bonjour, etc.) has **background indexing** enabled, image
+loading on the connecting client stalls — the sidebar shows neither image
+contents nor a loading progress indicator.
+
+`LoadImageForBackgroundIndexingRequest` on the Server side ends up calling
+`dlopen` on the peer's own main-executable path. On the iOS Simulator dyld
+rewrites that through the simruntime root prefix and the call fails with
+`(no such file)`; on any platform `dlopen` of an already-loaded main exec
+fails by definition. The resulting `DyldOpenError` is echoed back as a
+`RuntimeNetworkRequestError`, but that payload carries no `identifier`
+field, so the peer can't decode it as a `RuntimeRequestData` envelope —
+its own catch arm echoes yet another error, and the two sides ping-pong
+on the shared `sendSemaphore`, starving real traffic (image-list pushes,
+indexing progress, on-demand object requests).
+
+**Workaround**: turn off background indexing on the remote-Server side
+until the next build.
+
+**Status**: two-part fix planned for the next build — guard
+`_loadImageForBackgroundIndexing` against already-loaded images on the
+indexer side, and harden each connection's envelope-decode-failure arm to
+swallow rather than echo, so a single peer-handler failure can never
+amplify into a ping-pong again.
+
+---
+
+## Carried Over From beta.3
+
+All changes from [v2.1.0-beta.3](v2.1.0-beta.3.md) ship unchanged:
+
+- MachOSwiftSection 0.12.0-beta.3 bump (opaque-type symbolic-ref fix +
+  SymbolIndexStore self-cleanup + SharedCache management API).
+- Remote-pin refresh across `RuntimeViewerCore` / `RuntimeViewerPackages`
+  to the current latest tag of each non-pinned dependency.
+- ArchiveScript: force-checkout in the detached-HEAD branch so the
+  appcast PR step no longer aborts on archive-time `Package.resolved`
+  drift.
+
+And from [v2.1.0-beta.2](v2.1.0-beta.2.md) the Inspector **Relationships**
+tab, **Batch Export**, selection history, and the underlying
+communication-layer hardening.