# lib-core.interaction

P.0 proximity-trigger + action-dispatch lib. Register triggers with
`(target_x, target_y, range, action_name, callback)`; per-frame
`update(actor_x, actor_y)` checks distance + `was_action_pressed` and
fires the nearest matching trigger per `action_name`.

- Lib-ID: `lib-core.interaction`
- Version: `0.1.0`
- Spec: `meta/docs/superpowers/specs/2026-05-10-p0-lib-interaction-design.md`

Forward-compat stubs (DEPRECATED-MVP) for AABB-targets, action-effect-
pipeline integration, visual-feedback / moodlet, action-cycling,
hold-vs-press, per-action-resolution-override, callback pcall-wrap,
target-entity-binding, range-shape variants.

## API
- `interaction.register(target_x, target_y, range, action_name, callback) → id`
- `interaction.unregister(id)` — silent no-op if id unknown
- `interaction.update(actor_x, actor_y)` — proximity-check + dispatch
- `interaction.list() → array of { id, target_x, target_y, range, action_name }`
- `interaction.trigger_count() → integer`

## Conventions
- Targets are points (not AABBs in P.0). `range` is scalar pixel-radius.
- Distance: `engine.spatial.distance(actor, target) ≤ range`.
- Multi-match resolution: per `action_name`, only NEAREST in-range trigger
  fires per update. Different `action_name`s are independent (all may fire
  the same frame).
- Was-pressed semantics: `input.was_action_pressed` (single-frame edge).
- Callback receives `info = { actor_x, actor_y, target_x, target_y,
  distance, trigger_id, action_name }`. Closures may ignore the arg
  (`function() ... end` is legal).
- Loud Lua-errors on API misuse (non-number coords, non-positive range,
  non-string action_name, non-function callback).
- Silent-accept for `action_name` that hasn't been registered with
  `lib-core.input` — the trigger simply never fires (matches input-lib's
  silent-false convention).
- Callback errors bubble up (no pcall-wrap in P.0). Resilience is
  E.9 refactor target.

## Consumer pattern
```lua
local interaction = require("lib-core.interaction")
local input       = require("lib-core.input")

input.bind("interact", { engine.input.KEY_E })

local sign = { x = 144, y = 144, text = "Hier steht: ..." }
interaction.register(sign.x, sign.y, 40, "interact", function(info)
    engine.print(sign.text)
end)

function update(ctx, dt)
    -- (after player.update; reads player center)
    interaction.update(player_center_x, player_center_y)
end
```