Fix ControllerHub docs and test logical ID lifecycle #27

Candidate status

Selected by Cycle 5 research gate #29. Scope is limited to correcting the public ControllerHub example and testing the SDK's caller-assigned logical-ID lifecycle. The selection does not authorize automatic physical-device discovery or promise host/browser slot recovery.

Repository evidence

• At main 62e8b95, packages/core/README.md calls hub.createController, but the exported ControllerHub exposes add, get, has, list, states, and disconnectAll. The documented two-controller example therefore calls a method the public class does not provide.
• Existing hub coverage covers two initialized dry-run controllers with distinct IDs and profile entries, but does not assert independent state, duplicate logical-ID rejection, or reuse after disconnectAll. The current duplicate check also precedes an await, so concurrent adds with the same ID may both construct controllers before either is recorded.
• The hub accepts caller-supplied logical IDs and rejects duplicate IDs before constructing a second controller. It does not discover physical devices or own browser/OS slot identity.

External evidence and limits

Several independent projects report controller ownership or lifecycle failures: Steam for Linux #13665 (2026-09-29) describes already-running apps losing input after Steam recreates a virtual pad; #13418 (2026-07-15) reports a Steam Deck game losing input after switching to Discord; Jellyfin Web #8379 (2026-08-19) reports two controllers overwriting shared navigation state; and Cockpit #3088 (2026-09-22) requests that an active joystick remain the primary input when another connects.

Romm-broker #46 and Selkies #431 are the same reporter's cross-posted slot-conflict report and count as one report. These examples concern other projects and mostly upstream/browser/host behavior. They support investigating clear ownership boundaries; they do not prove prevalence or an OpenController defect.

Acceptance

• Replace the invalid hub.createController calls in the README with the actual public API and ensure the example is checked against the real TypeScript surface.
• Reject duplicate logical IDs for both sequential and concurrent add calls; release any pending-ID reservation if controller creation fails so a later retry can succeed.
• Add focused tests that disconnectAll clears the hub so the same caller-owned ID can be added again.
• Strengthen the existing two-controller test with explicit assertions that updating one logical controller does not alter the other controller state.
• Document that hub IDs are caller-assigned logical identifiers, not stable physical-device or OS/browser slot identities.
• Run focused core tests, typecheck, and the repository's required CI checks.

Non-goals

Do not add physical controller detection, infer identity from display names or indices, change native adapter ownership, or promise automatic reconnect across operating systems. Do not claim this SDK change repairs Steam, SDL, a browser, streaming host, or a game.

Estimate: low to medium, roughly 1–2 days. The first-party documentation/API mismatch is directly verified; external reports provide category context only.