feat: wildcard (*) events, internal transitions, Choose conditional actions (#58)

Three more XState-class primitives:

- Wildcard '*' event: catch-all transition matched when no exact event
  handler applies; exact matches keep priority; honors guards and
  hierarchical child-priority bubbling.
- Internal(): transition runs its actions without exiting/re-entering the
  source state — no entry/exit hooks, no state change, no history. Target
  optional (build-validated to be empty or the owning state).
- Choose(): conditional-action combinator returning an Action[C] that runs
  the first branch whose guard passes (nil guard = else). Pure helper.

Wildcard and internal transitions round-trip through the Native JSON and
XState v5 exporters (on["*"], internal: true, targetless = internal).

9 new feature tests + export round-trip tests. Full suite green, lint
clean, coverage gates pass.

Author: felixgeelhaar

README.md

@@ -63,6 +63,7 @@ Step-by-step migration guides:
 - History states (shallow and deep)
 - Delayed transitions and parallel/orthogonal regions
 - Eventless (`Always`) transitions, `Raise` internal events, and state `Tags`
+- Wildcard (`*`) event handlers, internal transitions, and `Choose` conditional actions
 - Guards, actions, entry/exit hooks
 - Reflection DSL — define machines with struct tags
 - Build-time validation
@@ -258,6 +259,37 @@ Key behaviors:
 - `HasTag` matches the active leaf, its ancestors, and active parallel-region leaves.
 - All three round-trip through the Native JSON and XState v5 exporters (`always`, `tags`, and `xstate.raise` action descriptors).
 
+## Wildcard Events, Internal Transitions & Choose
+
+**Wildcard `*`** catches any event not handled by a specific transition (exact
+matches always win; it bubbles like any handler). **`Internal()`** runs a
+transition's actions without exiting or re-entering the state — no entry/exit
+hooks, no state change — in contrast to an external self-transition. **`Choose`**
+is a conditional-action combinator: it runs the first branch whose guard passes.
+
+```go
+machine, _ := statekit.NewMachine[Ctx]("ops").
+    WithInitial("running").
+    WithAction("audit", statekit.Choose(
+        statekit.ChooseBranch[Ctx]{When: isAdmin, Then: logAdmin},
+        statekit.ChooseBranch[Ctx]{Then: logUser}, // else
+    )).
+    State("running").
+        On("TICK").Internal().Do("audit").End().  // no exit/entry, no state change
+        On("*").Target("unknown").End().           // catch-all fallback
+        On("STOP").Target("stopped").End().         // exact match beats "*"
+        Done().
+    State("unknown").Final().Done().
+    State("stopped").Final().Done().
+    Build()
+```
+
+Key behaviors:
+- Wildcard `*` is lowest priority within a state and honors guards; child handlers still take priority over ancestors.
+- Internal transitions accept an empty target (or the owning state); build-time validated.
+- `Choose` is a plain `Action[C]` — register it and reference it anywhere an action is used; a branch with a nil `When` is the else.
+- Wildcard and internal transitions round-trip through both exporters (`on["*"]`, `internal: true`).
+
 ## Reflection DSL
 
 Define machines using struct tags:

builder.go

@@ -117,6 +117,9 @@ type TransitionBuilder[C any] struct {
 
 	// Raised internal events (v1.x)
 	raise []EventType
+
+	// Internal transition flag — run actions without exit/entry (v1.x)
+	internal bool
 }
 
 // NewMachine creates a new MachineBuilder with the given ID
@@ -251,6 +254,7 @@ func buildStateRecursive[C any](sb *StateBuilder[C], parentID ir.StateID, machin
 		trans.Actions = append(trans.Actions, tb.actions...)
 		trans.Delay = tb.delay // Delayed transitions (v2.0)
 		trans.Raise = append(trans.Raise, tb.raise...)
+		trans.Internal = tb.internal // Internal transitions (v1.x)
 		state.Transitions = append(state.Transitions, trans)
 	}
 
@@ -673,6 +677,16 @@ func (b *TransitionBuilder[C]) Raise(events ...EventType) *TransitionBuilder[C]
 	return b
 }
 
+// Internal marks the transition as internal (v1.x): its actions run without
+// exiting or re-entering the source state — entry/exit hooks do not fire and
+// the active state does not change. Target is optional; when set it must be
+// the owning state. Contrast with an external self-transition (a plain
+// Target back to the same state), which does exit and re-enter.
+func (b *TransitionBuilder[C]) Internal() *TransitionBuilder[C] {
+	b.internal = true
+	return b
+}
+
 // On starts a new transition on the same state (chainable)
 func (b *TransitionBuilder[C]) On(event EventType) *TransitionBuilder[C] {
 	return b.state.On(event)

choose.go

@@ -0,0 +1,36 @@
+package statekit
+
+// ChooseBranch is one arm of a Choose action: when When passes (or is nil,
+// acting as an "else"), Then runs and evaluation stops (v1.x).
+type ChooseBranch[C any] struct {
+	// When gates this branch. A nil When always matches — use it as the
+	// final else branch.
+	When Guard[C]
+	// Then is the action executed when this branch is selected. May be nil.
+	Then Action[C]
+}
+
+// Choose builds an Action that runs the Then of the first branch whose When
+// guard passes, then stops — the action equivalent of XState's choose(). A
+// branch with a nil When acts as an else. If no branch matches, it is a no-op.
+//
+// Register it like any named action and reference it from transitions or
+// entry/exit hooks:
+//
+//	WithAction("classify", statekit.Choose(
+//	    statekit.ChooseBranch[Ctx]{When: isGold, Then: tagGold},
+//	    statekit.ChooseBranch[Ctx]{When: isSilver, Then: tagSilver},
+//	    statekit.ChooseBranch[Ctx]{Then: tagBronze}, // else
+//	))
+func Choose[C any](branches ...ChooseBranch[C]) Action[C] {
+	return func(ctx *C, event Event) {
+		for _, b := range branches {
+			if b.When == nil || b.When(*ctx, event) {
+				if b.Then != nil {
+					b.Then(ctx, event)
+				}
+				return
+			}
+		}
+	}
+}

choose_wildcard_internal_test.go

@@ -0,0 +1,226 @@
+package statekit
+
+import "testing"
+
+// --- Choose (conditional action combinator) ---
+
+func TestChoose_RunsFirstMatchingBranch(t *testing.T) {
+	type Ctx struct {
+		N    int
+		Tier string
+	}
+
+	pick := Choose(
+		ChooseBranch[Ctx]{
+			When: func(c Ctx, _ Event) bool { return c.N >= 100 },
+			Then: func(c *Ctx, _ Event) { c.Tier = "gold" },
+		},
+		ChooseBranch[Ctx]{
+			When: func(c Ctx, _ Event) bool { return c.N >= 10 },
+			Then: func(c *Ctx, _ Event) { c.Tier = "silver" },
+		},
+		ChooseBranch[Ctx]{
+			// nil When = else branch
+			Then: func(c *Ctx, _ Event) { c.Tier = "bronze" },
+		},
+	)
+
+	cases := []struct {
+		n    int
+		want string
+	}{
+		{150, "gold"},
+		{50, "silver"},
+		{1, "bronze"},
+	}
+	for _, tc := range cases {
+		c := Ctx{N: tc.n}
+		pick(&c, Event{})
+		if c.Tier != tc.want {
+			t.Errorf("N=%d tier=%q want %q", tc.n, c.Tier, tc.want)
+		}
+	}
+}
+
+func TestChoose_NoBranchMatchesIsNoop(t *testing.T) {
+	type Ctx struct{ Hit bool }
+	pick := Choose(ChooseBranch[Ctx]{
+		When: func(c Ctx, _ Event) bool { return false },
+		Then: func(c *Ctx, _ Event) { c.Hit = true },
+	})
+	c := Ctx{}
+	pick(&c, Event{})
+	if c.Hit {
+		t.Errorf("expected no branch to run")
+	}
+}
+
+func TestChoose_WiresIntoTransition(t *testing.T) {
+	type Ctx struct {
+		Score int
+		Label string
+	}
+	m, err := NewMachine[Ctx]("choose").
+		WithInitial("idle").
+		WithContext(Ctx{Score: 42}).
+		WithAction("classify", Choose(
+			ChooseBranch[Ctx]{
+				When: func(c Ctx, _ Event) bool { return c.Score >= 40 },
+				Then: func(c *Ctx, _ Event) { c.Label = "pass" },
+			},
+			ChooseBranch[Ctx]{Then: func(c *Ctx, _ Event) { c.Label = "fail" }},
+		)).
+		State("idle").On("GRADE").Target("done").Do("classify").End().Done().
+		State("done").Final().Done().
+		Build()
+	if err != nil {
+		t.Fatalf("build: %v", err)
+	}
+	i := NewInterpreter(m)
+	i.Start()
+	i.Send(Event{Type: "GRADE"})
+	if got := i.State().Context.Label; got != "pass" {
+		t.Errorf("label = %q, want pass", got)
+	}
+}
+
+// --- Wildcard event ---
+
+func TestWildcard_MatchesUnhandledEvent(t *testing.T) {
+	m, err := NewMachine[struct{}]("wild").
+		WithInitial("a").
+		State("a").
+		On("KNOWN").Target("known").End().
+		On("*").Target("fallback").End().
+		Done().
+		State("known").Final().Done().
+		State("fallback").Final().Done().
+		Build()
+	if err != nil {
+		t.Fatalf("build: %v", err)
+	}
+	i := NewInterpreter(m)
+	i.Start()
+	i.Send(Event{Type: "SOMETHING_ELSE"})
+	if got := i.State().Value; got != "fallback" {
+		t.Errorf("state = %q, want fallback", got)
+	}
+}
+
+func TestWildcard_ExactMatchTakesPriority(t *testing.T) {
+	m, _ := NewMachine[struct{}]("wild2").
+		WithInitial("a").
+		State("a").
+		On("KNOWN").Target("known").End().
+		On("*").Target("fallback").End().
+		Done().
+		State("known").Final().Done().
+		State("fallback").Final().Done().
+		Build()
+	i := NewInterpreter(m)
+	i.Start()
+	i.Send(Event{Type: "KNOWN"})
+	if got := i.State().Value; got != "known" {
+		t.Errorf("state = %q, want known (exact beats wildcard)", got)
+	}
+}
+
+func TestWildcard_RespectsGuard(t *testing.T) {
+	m, _ := NewMachine[struct{ Allow bool }]("wild3").
+		WithInitial("a").
+		WithGuard("allow", func(c struct{ Allow bool }, _ Event) bool { return c.Allow }).
+		WithContext(struct{ Allow bool }{Allow: false}).
+		State("a").On("*").Target("b").Guard("allow").End().Done().
+		State("b").Final().Done().
+		Build()
+	i := NewInterpreter(m)
+	i.Start()
+	i.Send(Event{Type: "ANY"})
+	if got := i.State().Value; got != "a" {
+		t.Errorf("state = %q, want a (guard blocks wildcard)", got)
+	}
+}
+
+// --- Internal transitions ---
+
+func TestInternal_NoExitEntryOrStateChange(t *testing.T) {
+	type Ctx struct {
+		Entries int
+		Exits   int
+		Pings   int
+	}
+	m, err := NewMachine[Ctx]("internal").
+		WithInitial("active").
+		WithAction("onEntry", func(c *Ctx, _ Event) { c.Entries++ }).
+		WithAction("onExit", func(c *Ctx, _ Event) { c.Exits++ }).
+		WithAction("onPing", func(c *Ctx, _ Event) { c.Pings++ }).
+		State("active").
+		OnEntry("onEntry").
+		OnExit("onExit").
+		On("PING").Internal().Do("onPing").End().
+		Done().
+		Build()
+	if err != nil {
+		t.Fatalf("build: %v", err)
+	}
+	i := NewInterpreter(m)
+	i.Start() // 1 entry
+	i.Send(Event{Type: "PING"})
+	i.Send(Event{Type: "PING"})
+
+	st := i.State()
+	if st.Value != "active" {
+		t.Errorf("state = %q, want active", st.Value)
+	}
+	if st.Context.Pings != 2 {
+		t.Errorf("pings = %d, want 2", st.Context.Pings)
+	}
+	if st.Context.Entries != 1 {
+		t.Errorf("entries = %d, want 1 (internal must not re-enter)", st.Context.Entries)
+	}
+	if st.Context.Exits != 0 {
+		t.Errorf("exits = %d, want 0 (internal must not exit)", st.Context.Exits)
+	}
+}
+
+func TestInternal_ContrastsWithExternalSelfTransition(t *testing.T) {
+	type Ctx struct{ Entries, Exits int }
+	m, _ := NewMachine[Ctx]("ext").
+		WithInitial("active").
+		WithAction("onEntry", func(c *Ctx, _ Event) { c.Entries++ }).
+		WithAction("onExit", func(c *Ctx, _ Event) { c.Exits++ }).
+		State("active").
+		OnEntry("onEntry").
+		OnExit("onExit").
+		On("SELF").Target("active").End(). // external self-transition (re-enters)
+		Done().
+		Build()
+	i := NewInterpreter(m)
+	i.Start()
+	i.Send(Event{Type: "SELF"})
+	st := i.State()
+	if st.Context.Exits != 1 || st.Context.Entries != 2 {
+		t.Errorf("external self: entries=%d exits=%d, want entries=2 exits=1", st.Context.Entries, st.Context.Exits)
+	}
+}
+
+func TestInternal_AllowsEmptyTarget(t *testing.T) {
+	type Ctx struct{ Count int }
+	m, err := NewMachine[Ctx]("internal2").
+		WithInitial("s").
+		WithAction("bump", func(c *Ctx, _ Event) { c.Count++ }).
+		State("s").On("BUMP").Internal().Do("bump").End().Done().
+		Build()
+	if err != nil {
+		t.Fatalf("build: %v", err)
+	}
+	i := NewInterpreter(m)
+	i.Start()
+	i.Send(Event{Type: "BUMP"})
+	if i.State().Context.Count != 1 {
+		t.Errorf("count = %d, want 1", i.State().Context.Count)
+	}
+	if i.State().Value != "s" {
+		t.Errorf("state = %q, want s", i.State().Value)
+	}
+}