feat(bindings): the translation contract — every target accounts for the full vocabulary

[ivanbanov]

Problem

The vocabulary (EventBindings + AttrBindings, 60 keys) is a closed set, but each target's normalize restates it as untyped data — Record<string, string> maps plus ad-hoc HANDLER_DROP/ATTR_DROP sets. Nothing checks coverage: add a vocabulary key and every target still compiles, with the new binding silently falling through the unknown-key passthrough onto the host (onWheel landing verbatim on a RN View). The native normalizer even states the rule in a comment ("every vocabulary key must be accounted for — an unlisted key would leak") — but only discipline enforced it, and #54 shows this failure class is real.

The contract

shared/bindings owns the vocabulary, so it now also owns the translation shape — types only, nothing added at runtime:

export type HandlerKey = keyof EventBindings
export type AttrKey = keyof AttrBindings
export type HandlerTargets = Record<HandlerKey, string | null>
export type AttrTargets = Record<AttrKey, string | null>

Every target's maps are annotated against it. Record, not Partial: every key is required, excess keys are rejected, and null is a declared drop — the substrate says "I cannot express this" in a reviewable diff instead of a hand-maintained set:

export const HANDLER_MAP: HandlerTargets = {
  onPress: 'onPress',
  onWheel: null, // no RN analog — declared, not forgotten
  // ...every other vocabulary key, required by the type
}

A new vocabulary key now breaks all three targets' typecheck until each decides — mapped or dropped, never leaked. The passthrough survives, but only for keys outside the vocabulary (data-state, consumer extras).

No behavior change

• HANDLER_DROP/ATTR_DROP sets fold into null entries (native, opentui).
• Native's accessibilityState fold now derives its key set from the ledger, so routing can't drift from the declaration; the accessibilityValue sub-key table stays.
• The two implicit passthroughs that rode the leak path on purpose — native role, opentui disabled — become explicit renames with the same output.
• The bindings dependency is devDependencies + import type only: verified erased from every target's dist (js and d.ts).

Verification

• A conformance test per target walks its ledger: every binding lands on its declared target — or, for a null, produces nothing at all (the anti-leak assertion, with the offending key in the failure message).
• 318/318 tests, typecheck, lint, format, build + publint all green.

Follow-ups

• The vue target (feat(vue): Vue 3 integration #33) adopts the same annotations once both land — a two-line diff there.
• A possible next step (discussed, not in scope): a shared web base for the DOM targets — one DOM_EVENT/DOM_ATTRS authority + shared payload adapters, with react/vue keeping only their listener-spelling layer.

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
dunky-state-machine	Ready	Preview	Aug 15, 2026 12:38am