acdream/docs/superpowers/specs/2026-05-13-phase-b4b-design.md

# Phase B.4b — Outbound Use Handler Wiring

**Status:** Design spec, created 2026-05-13 after L.2g slice 1 ship handoff.
**Branch:** `claude/compassionate-wilson-23ff99` (worktree `compassionate-wilson-23ff99`).
**Predecessors:**
- [docs/research/2026-05-12-l2g-slice1-shipped-handoff.md](../../research/2026-05-12-l2g-slice1-shipped-handoff.md)
  — L.2g slice 1 shipped the inbound `SetState (0xF74B)` pipeline; visual
  test was deferred when investigation uncovered that the outbound Use
  handler had never been wired.
- [docs/ISSUES.md](../../ISSUES.md) #57 — B.4 interaction-handler gap
  filed 2026-05-12, promoted to Phase B.4b.
- Phase B.4 (`InteractRequests` wire builders + `InputAction` enum +
  `KeyBindings`, shipped 2026-04-28 per memory; commit history confirms
  the wire builders + bindings but not the handler).

**Milestone:** M1 — Walkable + clickable world. Demo scenario *"open
the inn door"* depends on this slice landing. Once B.4b lands,
L.2g slice 1's deferred visual test verifies in the same scenario.

**Estimate:** ~80 LOC, 1-2 subagent dispatches, ~30 minutes implementation.

---

## TL;DR

Phase B.4 (2026-04-28) shipped half of itself: the wire-message
builders (`InteractRequests.BuildUse` / `BuildUseWithTarget` /
`BuildTeleToLifestone`), the `InputAction` enum entries
(`SelectLeft` / `SelectDblLeft` / `UseSelected` / etc.), and the
default keybindings. What was never landed: a handler that picks an
entity at the mouse position when the user clicks, stores the
selection, and sends a `BuildUse` packet.

Two further gaps surfaced during this session's exploration that the
L.2g handoff and ISSUES.md #57 both miss-claim as "exists":
- `WorldPicker` — does NOT exist in `src/`. Doc-only.
- `SelectionState` — does NOT exist in `src/`. Doc-only.
- `InteractRequests.BuildPickUp` — does NOT exist; only `BuildUse`,
  `BuildUseWithTarget`, and `BuildTeleToLifestone` are present.

B.4b creates the minimum new structure to close the gap: one new
file (`WorldPicker.cs` as a stateless static helper), one rename
(`_selectedTargetGuid` → `_selectedGuid` on `GameWindow`, unifying
combat + interaction selection), and three switch cases in
`GameWindow.OnInputAction` (for `SelectLeft`, `SelectDblLeft`,
`UseSelected`). `SelectionState` as a class extraction is deferred
to whenever the M2 HUD wants a `SelectionChanged` event; per CLAUDE.md
"don't add abstractions beyond what the task requires."

`BuildPickUp` (F-key) is out of scope — not on the Holtburg inn-door
critical path. Filed as a follow-up.

---

## Why B.4b (and not "fix B.4" or "Phase B.5")

| Option | Verdict |
|---|---|
| **Reopen "Phase B.4" and amend** | Rejected. B.4 is in memory + commit history as shipped 2026-04-28; reopening creates retroactive confusion. The gap is real; promote it to its own short-lived sub-phase per the L.2/L.2g precedent. |
| **Roll into M2 interaction work** | Rejected. M2 is creatures + combat + a real selection HUD — weeks of work. The doors-open scenario is M1. Need a small slice that unblocks the M1 visual test without dragging M2 forward. |
| **New phase "B.4b — Outbound Use handler wiring"** | **Selected.** Mirrors the L.2d → L.2g lettered-sub-phase pattern. Phase-sized (30-50 LOC was the initial estimate; final is closer to ~80 with the picker file), commit-trackable, closeable as soon as the visual test passes. |

---

## Problem evidence

Discovered 2026-05-12 while running the L.2g slice 1 visual test. The
input dispatcher correctly fires `SelectDblLeft` on every double-left-
click — the diagnostic `[input] SelectDblLeft Press` line shows in the
log — but `GameWindow.OnInputAction`'s switch has zero `case
InputAction.SelectLeft / SelectDblLeft / UseSelected` branches.
Nothing downstream listens. The click silently dies.

From `GameWindow.cs:8546-8646` (the full `OnInputAction` switch as of
this morning's L.2g merge):

```
switch (action)
{
    case InputAction.AcdreamToggleDebugPanel: ...
    case InputAction.AcdreamToggleCollisionWires: ...
    case InputAction.AcdreamDumpNearby: ...
    case InputAction.AcdreamCycleTimeOfDay: ...
    // ... 12 other Acdream*/Combat*/Toggle* cases ...
    case InputAction.SelectionClosestMonster:
        SelectClosestCombatTarget(showToast: true);
        break;
    case InputAction.EscapeKey: ...
}
```

`SelectionClosestMonster` (Q-cycle combat target) is the *only*
selection-related case. `SelectLeft` / `SelectDblLeft` / `SelectRight`
/ `UseSelected` / `SelectionPickUp` / all the other Select-family
actions have no cases at all.

Inbound side (L.2g slice 1) is wired and ready to receive the
server's reply. Outbound is the only block.

---

## Current acdream state

| Component | State |
|---|---|
| `InteractRequests.BuildUse(seq, guid)` wire builder | shipped at `src/AcDream.Core.Net/Messages/InteractRequests.cs:37` |
| `InteractRequests.BuildUseWithTarget` | shipped at same file:51 |
| `InteractRequests.BuildPickUp` | DOES NOT EXIST (handoff was wrong) |
| `InputAction.SelectLeft` / `SelectDblLeft` / `SelectRight` / `UseSelected` / `SelectionPickUp` | defined in `InputAction` enum |
| KeyBindings: LMB → `SelectLeft`, LMB-dblclick → `SelectDblLeft`, RMB → `SelectRight`, R → `UseSelected`, F → `SelectionPickUp` | wired in `src/AcDream.UI.Abstractions/Input/KeyBindings.cs:303-320, 172, 210` |
| `WorldPicker` class | DOES NOT EXIST (handoff was wrong) |
| `SelectionState` class | DOES NOT EXIST (handoff was wrong) |
| Selection field on GameWindow | exists as `_selectedTargetGuid` but combat-only (used by `SelectClosestCombatTarget` and `ToggleLiveCombatMode`) |
| `WorldSession.NextGameActionSequence()` | shipped; outbound chat/move already uses it |
| `WorldSession.SendGameAction(byte[])` | shipped; outbound chat/move already uses it |
| `OnInputAction` switch case for `Select*` / `UseSelected` | MISSING — **the gap** |

---

## Design

### Architecture

One new file + edits to `GameWindow.cs`.

**New:** `src/AcDream.Core/Selection/WorldPicker.cs` — static helper
class in `AcDream.Core.Selection` namespace. Two pure methods, no
state, no DI. **Lives in Core** (not App) because it has no App-layer
dependencies: it operates on `WorldEntity` (Core) plus
`System.Numerics` matrices/vectors. Putting it in Core also means it
can be unit-tested via the existing `AcDream.Core.Tests` project; no
new test project required (`AcDream.App.Tests` does not exist as of
2026-05-13 and creating it would add more LOC than the picker
itself).

**Edited:** `src/AcDream.App/Rendering/GameWindow.cs`:
1. Rename field `_selectedTargetGuid` → `_selectedGuid` (project-wide
   find/replace; ~5 call sites all inside `GameWindow.cs`). Unifies
   combat + interaction selection on one field. Retail-faithful: AC
   has one "current target" not two.
2. Add three switch cases to `OnInputAction`: `SelectLeft`,
   `SelectDblLeft`, `UseSelected`.

`SelectionState` as a separate class is deferred. Reason: only two
consumers today (combat Q-cycle, click handler). The class earns its
keep when consumer #3 (HUD widget that subscribes to
`SelectionChanged`) lands in M2. Premature otherwise.

### Components

#### `WorldPicker.BuildRay`

Standard mouse-to-world unprojection. Convert pixel `(mouseX, mouseY)`
to NDC `(2*mouseX/vpW - 1, 1 - 2*mouseY/vpH)`, unproject the near
point (`ndc.z = -1`) and far point (`ndc.z = +1`) through
`inverse(projection) → inverse(view)`, return `(origin = near,
direction = normalize(far - near))`.

Signature:
```csharp
public static (Vector3 Origin, Vector3 Direction) BuildRay(
    float mouseX, float mouseY,
    float viewportW, float viewportH,
    Matrix4x4 view, Matrix4x4 projection);
```

~20 LOC. Pure math. No exception paths — the OpenGL view/proj matrices
we hand it are always invertible.

#### `WorldPicker.Pick`

Ray-sphere intersection against each candidate entity's `Position`
with radius 5.0f (matches `WorldEntity.DefaultAabbRadius`). Skip the
self-guid (player). Track the closest hit with `t < maxDistance` (50m
default). Return the picked entity's `ServerGuid`, or `null` for miss.

Signature:
```csharp
public static uint? Pick(
    Vector3 origin, Vector3 direction,
    IEnumerable<WorldEntity> candidates,
    uint skipServerGuid,
    float maxDistance = 50f);
```

~30 LOC. Excludes entities with `ServerGuid == 0` (atlas-tier scenery
+ dat-hydrated statics) — those have no server-side identity, so a
`BuildUse` against them would carry guid=0 and be rejected.

Sphere intersection math (geometric form): for each candidate, compute
`oc = origin - entity.Position`, `b = dot(oc, direction)`, `c =
dot(oc, oc) - r²`, discriminant `d = b² - c`. If `d < 0` no hit.
Otherwise `t = -b - sqrt(d)` is the near intersection; track smallest
positive `t < maxDistance`.

#### `OnInputAction` switch cases

Three new cases right before the `EscapeKey` case (preserve the
existing case ordering by feature group):

```csharp
case InputAction.SelectLeft:
    PickAndStoreSelection(useImmediately: false);
    break;

case InputAction.SelectDblLeft:
    PickAndStoreSelection(useImmediately: true);
    break;

case InputAction.UseSelected:
    UseCurrentSelection();
    break;
```

Plus three private helper methods on `GameWindow`:

- `PickAndStoreSelection(bool useImmediately)`: pull `_lastMouseX/Y`,
  `_cameraController.Active.View/Projection`, `_window.Size`; call
  `WorldPicker.BuildRay` → `WorldPicker.Pick`; on hit, set
  `_selectedGuid = picked`, toast "Selected: {name}", emit diagnostic
  `[B.4b] pick guid=0x{picked:X8} name={DescribeLiveEntity(picked)}`. If
  `useImmediately`, also call `SendUse(picked)`. On miss, toast
  "Nothing to select" (no diagnostic line, no state change).
- `UseCurrentSelection()`: if `_selectedGuid is uint sel`, call
  `SendUse(sel)`. Otherwise toast "Nothing selected".
- `SendUse(uint guid)`: gate on `_liveSession?.CurrentState ==
  InWorld`; `seq = _liveSession.NextGameActionSequence()`; `body =
  InteractRequests.BuildUse(seq, guid)`;
  `_liveSession.SendGameAction(body)`; diagnostic
  `[B.4b] use guid=0x{guid:X8} seq={seq}`.

All three switch branches honor the existing `if (activation !=
ActivationType.Press) return;` filter above the switch.

### Data flow (happy path)

```
mouse double-click on door at pixel (540, 320)
    -> Silk.NET window event
InputDispatcher.OnMouseDown -> DoubleClick chord match
    ->
InputDispatcher.Fired(SelectDblLeft, Press)
    ->
GameWindow.OnInputAction(SelectDblLeft, Press)
    ->
PickAndStoreSelection(useImmediately: true)
    -> pulls _lastMouseX/Y + _cameraController.Active.View/Projection
WorldPicker.BuildRay(540, 320, vpW, vpH, view, proj) -> (origin, dir)
    ->
WorldPicker.Pick(origin, dir, _entitiesByServerGuid.Values,
                 _playerServerGuid, 50f) -> 0xDoorGuid
    ->
_selectedGuid = 0xDoorGuid
toast "Selected: Door"
log "[B.4b] pick guid=0x000F4244 name=Door"
    ->
SendUse(0xDoorGuid)
    ->
seq = _liveSession.NextGameActionSequence()
body = InteractRequests.BuildUse(seq, 0xDoorGuid)
_liveSession.SendGameAction(body)
log "[B.4b] use guid=0x000F4244 seq=N"
    -> ACE processes Use, calls Door.Open()
ACE broadcasts UpdateMotion(NonCombat,On) -> swing animation
ACE broadcasts SetState(guid=0xDoor, state=0x14)
    ->
WorldSession.StateUpdated event fires (L.2g slice 1 path)
    ->
ShadowObjectRegistry.UpdatePhysicsState(doorGuid, 0x14)
    -> next physics tick
CollisionExemption.ShouldSkip returns true -> door no longer blocks
    ->
player walks through doorway
```

### Error handling / edge cases

- **No entity hit** (clicked on terrain, sky, empty space): `Pick`
  returns `null`. No `_selectedGuid` change. Toast "Nothing to
  select". No network send.
- **ImGui consuming the click**: `InputDispatcher` already filters
  via `wantCaptureMouse`. `OnInputAction` only fires when the click
  was outside ImGui panels. No new guard needed.
- **No live session / not in world**: `SendUse` short-circuits early.
  Toast "Not in world" for debug visibility. Picker still runs (cheap;
  fine to leave selection state updated even offline).
- **`UseSelected` with no current selection**: toast "Nothing
  selected". No network send.
- **Selected entity despawns between select and use**: `BuildUse`
  still sends the cached guid. ACE replies with `UseDone` carrying
  `WeenieError.InvalidObject` (a non-zero error code). That error
  already flows into the chat-log channel via the existing
  `GameEventType.UseDone` handler; no new code needed.
- **Ray construction degenerate**: if `direction.LengthSquared() < eps`,
  treat as no-hit and return null from `Pick`. Defensive — should
  never trigger for sane view/proj matrices.
- **Entity at exactly `_selectedGuid` despawns silently while
  selected** (e.g. NPC walks out of streaming range): `_selectedGuid`
  becomes a stale reference. Acceptable for B.4b — the next
  `UseSelected` either sends a guid the server now doesn't recognize
  (server replies with an error, harmless) or the player picks a new
  target before pressing R. Stale-selection cleanup is M2 HUD work.

### Testing

**Unit tests** — `tests/AcDream.Core.Tests/Selection/WorldPickerTests.cs`
(new file in existing test project):

| Test | Scenario | Asserts |
|---|---|---|
| `BuildRay_CenterOfViewport_ReturnsForwardRay` | mouse at (vpW/2, vpH/2), identity view, simple perspective proj | direction approx -Z (camera-forward) within eps |
| `BuildRay_OffsetMouse_DeflectsRay` | mouse right-of-center, same camera | direction.X > 0 (deflects toward camera-right) |
| `Pick_RayThroughEntity_ReturnsServerGuid` | synthetic entity at (0,0,-10) with ServerGuid=0xABCD, ray from origin along -Z | returns 0xABCD |
| `Pick_RayMisses_ReturnsNull` | same entity, ray aimed at +X | returns null |
| `Pick_TwoEntitiesInLine_ReturnsCloser` | entities at -5 and -10, ray along -Z | returns the -5 one |
| `Pick_SkipsSkipGuid` | one entity at -10 with guid=0xABCD, skipServerGuid=0xABCD | returns null |
| `Pick_SkipsZeroServerGuid` | entity with ServerGuid=0 (dat-hydrated scenery) in path | returns null |
| `Pick_BeyondMaxDistance_ReturnsNull` | entity at -100, default maxDist=50 | returns null |

**Switch-case behavior** — not unit-tested. Would require mocking
`GameWindow` + `WorldSession` + `InputDispatcher` + `CameraController`,
high cost low value for a 3-case wiring change. Verified at runtime via
visual test.

**Runtime verification** — Holtburg inn doorway scenario (per the L.2g
slice 1 handoff reproducibility recipe):

```powershell
$env:ACDREAM_DAT_DIR        = "$env:USERPROFILE\Documents\Asheron's Call"
$env:ACDREAM_LIVE           = "1"
$env:ACDREAM_TEST_HOST      = "127.0.0.1"
$env:ACDREAM_TEST_PORT      = "9000"
$env:ACDREAM_TEST_USER      = "testaccount"
$env:ACDREAM_TEST_PASS      = "testpassword"
$env:ACDREAM_DEVTOOLS       = "1"
$env:ACDREAM_PROBE_BUILDING = "1"
$env:ACDREAM_PROBE_RESOLVE  = "1"
dotnet run --project src\AcDream.App\AcDream.App.csproj -c Debug 2>&1 |
  Tee-Object -FilePath "launch-b4b.log"
```

Then in-client: walk to the Holtburg inn doorway, double-left-click
the closed door, wait for swing animation, walk through. After 30s,
watch auto-close.

Expected log grep:

```powershell
Select-String -Path launch-b4b.log -Pattern `
  "B.4b|setstate-hex|setstate.*guid|input.*SelectDblLeft|entity-source.*Door"
```

Expected matches:
- `[input] SelectDblLeft Press` (dispatcher fires — already worked pre-B.4b)
- **NEW:** `[B.4b] use guid=0x000F4244 seq=N` (B.4b send fires)
- `[setstate-hex] body.len=16 ...` (server replied — L.2g hex probe)
- `[setstate] guid=0x000F4244 state=0x00000014` (door opens — L.2g
  per-tick probe) — **NB:** if state is `0x4` only (not `0x14`),
  follow the L.2g slice-1 review's "Important note" → file a tiny
  L.2g slice 1b to widen `CollisionExemption.ShouldSkip`.
- `[setstate] guid=0x000F4244 state=0x00000000` ~30s later (auto-close).
- Player visibly walks through doorway during the open window.

### Slice plan

This is one slice. No further sub-slicing.

| Step | Files | LOC | Subagent? |
|---|---|---|---|
| 1. Write `WorldPickerTests.cs` (TDD: tests first) | `tests/AcDream.Core.Tests/Selection/WorldPickerTests.cs` (new) | ~80 | Yes (Sonnet) — bounded TDD task |
| 2. Create `WorldPicker.cs` static helper | `src/AcDream.Core/Selection/WorldPicker.cs` (new) | ~50 | Same agent as step 1 |
| 3. Rename `_selectedTargetGuid` → `_selectedGuid` in `GameWindow.cs` | 1 file edit | ~5 sites | Manual or Sonnet |
| 4. Add 3 switch cases + 3 helper methods in `GameWindow.OnInputAction` | 1 file edit | ~40 | Manual or Sonnet |
| 5. `dotnet build` + `dotnet test` green | — | — | Manual |
| 6. Visual test at Holtburg inn doorway + log grep | — | — | Manual (user) |
| 7. Commit + close #57 + update roadmap + update memory | — | — | Manual |

Total: ~80 LOC new code + ~80 LOC tests + ~50 LOC edits. One commit
(or two: picker + test as one, handler wiring + rename as another).

### Acceptance criteria

- [ ] `dotnet build` green
- [ ] `dotnet test` green; 8 new `WorldPickerTests` pass
- [ ] Double-left-click on closed door in Holtburg inn doorway:
  - [ ] Log shows `[B.4b] pick guid=0x... name=Door`
  - [ ] Log shows `[B.4b] use guid=0x... seq=N`
  - [ ] Log shows `[setstate] guid=0x... state=0x14` (or `0x4`) shortly after
  - [ ] Door swings open visually (animation plays)
  - [ ] Player can walk through threshold (no `RESOLVE`-line wall hits)
- [ ] R hotkey with no selection: toast "Nothing selected", no send.
- [ ] R hotkey after selecting a door (single click) but not using it
  (no double-click): sends `BuildUse` for the same guid.
- [ ] Single left-click on terrain (or sky): toast "Nothing to select",
  no send.
- [ ] Q-cycle (combat closest-target) still works after the
  `_selectedTargetGuid` → `_selectedGuid` rename.
- [ ] ISSUES.md #57 moved to "Recently closed" with this commit's SHA.
- [ ] Roadmap "shipped" table updated.
- [ ] CLAUDE.md "Currently in Phase L.2" paragraph updated to reflect
  L.2g slice 1 + B.4b verified, next phase candidate is the next
  preference-order item from the candidate list.

### Non-goals / explicitly deferred

- **`BuildPickUp` (F-key pickup)** — `InteractRequests` doesn't have
  this builder yet. Out of M1 critical path; file as a follow-up note.
- **`UseWithTarget`** — wire builder exists but no client-side UX yet
  (cursor-on-item then click-on-target). M2 work.
- **`SelectionState` as a class with `SelectionChanged` event** — wait
  for HUD consumer in M2.
- **Hover-highlight / cursor change on hover** — UX polish, M2/M3.
- **Right-click `SelectRight` radial menu** — M3.
- **Selected-entity HUD widget (name, vitals)** — M2.
- **Stale-selection auto-clear when target despawns** — M2 HUD work.
- **Mesh-accurate picking (vs. 5m sphere)** — optimization for later;
  the 5m sphere is the retail "fast bbox" first pass, which retail
  followed with a per-triangle test on the candidate. Add only if a
  visual-test session reports a wrong-entity pick.

### Risks / open questions

| Risk | Mitigation |
|---|---|
| **5m sphere too generous at doorways** — picks the wall or NPC inside the inn instead of the door | First visual test pass settles it. If it picks the wrong entity, tighten the radius to 3m or add a closer-than-furthest tiebreak by entity type. |
| **Camera-mode mismatch** — in fly/orbit mode the ray origin should be the camera position, not the player. | Resolved by using `_cameraController.Active.View` which is the camera's view matrix regardless of mode. The picker doesn't care about player position. |
| **State value `0x4` vs `0x14`** — L.2g slice-1 review flagged that `CollisionExemption.ShouldSkip` requires both `ETHEREAL (0x4)` AND `IGNORE_COLLISIONS (0x10)`. If ACE sends only `0x4`, the exemption won't fire. | Settled by the same visual test's `[setstate]` log line. If `0x4` only, file a tiny L.2g slice 1b to widen the check; that's a one-line edit and out of B.4b scope. |
| **`_lastMouseX/Y` at click time vs. dispatcher-fire time** — if there's a frame of latency between Silk's mouse-down event and the dispatcher fire, the mouse may have moved. | Silk fires mouse-down synchronously; `_lastMouseX/Y` are updated on every move, so they hold the click position at the moment the dispatcher fires. Verified by reading the existing `OnMouseDown` path. Low risk. |
| **Entity not in `_entitiesByServerGuid` despite being visible** — e.g. dat-hydrated EnvCell statics have `ServerGuid=0` and won't be pickable | Acceptable for B.4b. Doors and NPCs in Holtburg are server-spawned with non-zero `ServerGuid`. Dat-hydrated statics (fireplaces, decorations) aren't meant to be Use-able. |

### Open question after slice ships (L.2g slice 1b)

The L.2g slice-1 final-review "Important note" — does ACE's
`PhysicsObj.cs:787-791` set both `ETHEREAL_PS (0x4)` AND
`IGNORE_COLLISIONS_PS (0x10)` simultaneously when doors open, or only
ETHEREAL? B.4b's visual test settles this. If the hex shows `0x4`
alone, file L.2g slice 1b to either widen `CollisionExemption.ShouldSkip`
to `((state & ETHEREAL_PS) != 0)` alone, or set both bits in
`UpdatePhysicsState`. Decision deferred until evidence lands.

---

## Reproducibility

Same launch recipe as L.2g slice 1 (above). Visual verification is the
same scenario — both L.2g slice 1 and B.4b verified together. No
separate L.2g visual test session needed.

---

## Worktree

Branch: `claude/compassionate-wilson-23ff99`, worktree
`compassionate-wilson-23ff99`. Clean off main (commit `eea9b4d` =
the L.2g slice 1 merge from the previous session).

After ship: merge to main, close #57, update CLAUDE.md + roadmap +
memory, archive this spec + the impl plan.