[ryan-son]

Summary

Necto 0.2.2 (2026-10-15) splits its products and rewrites URLSession capture (toss/necto#20, #29). Two things follow for this plugin:

• The README setup no longer compiles on the newest 0.2.x. NectoURLSessionCapture is gone; URLSessionNetworkPlugin now lives in the separate product NectoURLSessionCapturePlugin. Because the README asks for .upToNextMinor(from: "0.2.0"), a new app resolves 0.2.2 and fails at import NectoURLSessionCapture. The package itself builds (the weekly "Necto latest" job passes); only the user-facing setup is wrong.
• Registration order no longer matters. Capture no longer registers a URLProtocol or resends requests on an ephemeral session. It hooks URLSession and its tasks and watches the app's own transfer (Sources/NectoURLSessionCapturePlugin/NectoURLSessionHooks.swift).

Changes:

• Package.swift requires .upToNextMinor(from: "0.2.2"). Both examples pin 0.2.2.
• README, docs/usage.md and docs/design.md (and their -ko copies):
  • Name the optional NectoURLSessionCapturePlugin product and its import.
  • Say the order doesn't matter.
  • Replace the old cost note (the ephemeral resend skipped delegates, cookies and cache) with the real one: private Foundation hooks, which Necto says not to link into apps that prohibit private APIs.
  • Cite upstream at 0.2.2. The other cited files are unchanged, or were re-measured.
• The panel's registration order warning is removed (Panel/src/traffic/order.ts and its tests). It fired on two causes, mocks missing from Necto's records and passthroughs logged twice. Neither happens on 0.2.2, and if the warning fired anyway, its advice ("register Map Local first") would be wrong. The missing-plugin hint drops "after Map Local".
• script/verify-controls ③ no longer names Necto_NectoDefaultPlugins.bundle, which 0.2.2 does not build. NectoSDK carries no resource bundle now, so the Necto trace is the executable. The synthetic bundle in script/test-verify-release is renamed to one 0.2.2 does build.

Unchanged on purpose: interception stays a URLProtocol. Necto's move fits an observer that must not change behaviour. Map Local replaces responses, and passthroughs already load natively (canInit returns false for them). import NectoModel with only the NectoSDK product is what Necto's own docs/tutorial-device.md does.

Changelog

The ## 0.2.0 lines go in with #8, which owns that section:

• Requires Necto 0.2.2. To see real responses, link NectoURLSessionCapturePlugin and import NectoURLSessionCapturePlugin; the registration order no longer matters.
• The traffic tab's registration order warning is gone, since Necto 0.2.2 can't produce what it detected.

Agent interface

No change. No operation, binding, input, output, error code or maplocal.state field changes (Panel/public/manifest.json is untouched). network.list, network.detail and network.observe still resolve to Necto's necto.device.network-records.* on 0.2.2. This was measured through necto-cli plugin send io.github.ryan-son.maplocal network.list and network.detail.

Test Plan

Measured in Necto 0.2.2 (Mac app and SDK, iPhone SE 3rd gen simulator on iOS 18.4):

• The setup: a copy of QuickStart linking NectoURLSessionCapturePlugin, with a rule mocking GET httpbin.org/json to 418 and /uuid passing through. It ran five rounds per registration order.
• The rules were set and the results read with necto-cli.

Order	Necto records	Map Local events
Map Local first	/json 418 ×5, /uuid 200 ×5	mocked 5, passthrough 5
Network plugin first	/json 418 ×5, /uuid 200 ×5	mocked 5, passthrough 5

• A mocked record's detail carries X-Map-Local: json/mock and the mocked body.
• Our event's date minus Necto's startedAtMilliseconds was 0.11–12.71 ms, inside the one-sided 0–50 ms pairing window.
• The app built with import NectoURLSessionCapturePlugin, which the README now uses.

Local checks:

• cd Panel && npx tsc --noEmit: OK.
• npx vitest run: 1100, down from 1143.
  • The 43 removed tests all checked the order warning: 32 in order.test.ts, with test.each expanded, and 3 in order.perf.test.ts. The other 8 came out of connect, traffic/view and view tests.
  • Connect tests that also checked the store keep their store assertions.
• script/build-panel regenerated EmbeddedPanel.swift.
• script/check-doc-pairs, script/check-doc-links and script/lint-guard: OK.
• script/test-verify-release: all ok.
• script/verify-controls: ① to ⑥ ok, with the examples resolving Necto 0.2.2.
• swift test:
  • MapLocalCoreTests: 131 passed.
  • NectoMapLocalPluginTests: 91 tests, one failed in the full script/ci run with a 60 s time limit ("a delayed response arrives only after the clock has moved…", URLProtocolTests.swift:226). The machine's load average was 850–920 at the time. The test uses a TestClock and touches nothing from Necto. Rerun alone, its 17-test URLProtocol group passed twice, in 21.7 s and 171.6 s. This PR's GitHub CI is the clean full run.

Not verified:

• The panel after the warning removal, in Necto. No screenshots: the banner never showed in normal use, and nothing else in the layout changed.
• A device over USB.
• iOS versions other than 18.4.