controlled-machine 0.1.0

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs","sources":["../src/index.ts"],"sourcesContent":["/**\n * Controlled Machine\n *\n * A controlled state machine where state lives outside the machine.\n *\n * - input: External data passed in\n * - computed: Derived values from input\n * - context: input + computed (full context available in handlers)\n * - on: Event → conditional actions\n * - effects: Watch-based side effects\n * - always: Auto-evaluated rules on context change\n */\n\n// ============================================\n// Types\n// ============================================\n\nexport type Rule<\n  TContext,\n  TPayload = undefined,\n  TActions extends string = string,\n> = {\n  when?: (context: TContext, payload: TPayload) => boolean\n  do: TActions | TActions[]\n}\n\nexport type Handler<\n  TContext,\n  TPayload = undefined,\n  TActions extends string = string,\n> = TActions | TActions[] | Rule<TContext, TPayload, TActions>[]\n\n// Effect helpers - utilities available in effect callbacks\nexport type EffectHelpers<TEvents extends EventsConfig> = {\n  send: Send<TEvents>\n}\n\nexport type Cleanup = () => void\n\nexport type Effect<\n  TContext,\n  TEvents extends EventsConfig,\n  TWatched = unknown,\n> = {\n  watch: (context: TContext) => TWatched\n  enter?: (\n    context: TContext,\n    helpers: EffectHelpers<TEvents>,\n  ) => void | Cleanup | Promise<void>\n  exit?: (context: TContext, helpers: EffectHelpers<TEvents>) => void | Cleanup\n  change?: (\n    context: TContext,\n    prev: TWatched | undefined,\n    curr: TWatched,\n    helpers: EffectHelpers<TEvents>,\n  ) => void | Cleanup\n}\n\n/** Helper for inferring prev/curr types from watch return type */\nexport function effect<TContext, TEvents extends EventsConfig, TWatched>(\n  config: Effect<TContext, TEvents, TWatched>,\n): Effect<TContext, TEvents, TWatched> {\n  return config\n}\n\nexport type EventsConfig = Record<string, unknown>\nexport type ComputedConfig = Record<string, unknown>\n\n// ============================================\n// Object-based Generic Types\n// ============================================\n\n/**\n * Object-based generic types - specify only needed types in any order\n *\n * @example\n * createMachine<{\n *   input: MyInput\n *   events: MyEvents\n *   actions: 'foo' | 'bar'\n * }>({...})\n */\nexport type MachineTypes = {\n  input?: unknown\n  events?: EventsConfig\n  computed?: ComputedConfig\n  actions?: string\n  state?: string\n}\n\nexport type Input<T extends MachineTypes> = T['input']\nexport type Events<T extends MachineTypes> = T['events'] extends EventsConfig\n  ? T['events']\n  : Record<string, undefined>\nexport type Computed<T extends MachineTypes> = T['computed'] extends ComputedConfig\n  ? T['computed']\n  : Record<string, never>\nexport type Actions<T extends MachineTypes> = T['actions'] extends string\n  ? T['actions']\n  : string\nexport type State<T extends MachineTypes> = T['state'] extends string\n  ? T['state']\n  : string\n\n// Context = Input + Computed (full context available in handlers)\nexport type Context<T extends MachineTypes> = Input<T> & Computed<T>\n\n// State-based handler configuration\nexport type StateConfig<\n  TContext,\n  TEvents extends EventsConfig,\n  TActions extends string = string,\n> = {\n  on?: { [K in keyof TEvents]?: Handler<TContext, TEvents[K], TActions> }\n}\n\nexport type StatesConfig<\n  TState extends string,\n  TContext,\n  TEvents extends EventsConfig,\n  TActions extends string = string,\n> = {\n  [K in TState]?: StateConfig<TContext, TEvents, TActions>\n}\n\nexport type Machine<T extends MachineTypes> = {\n  computed?: {\n    [K in keyof Computed<T>]: (input: Input<T>) => Computed<T>[K]\n  }\n  on?: {\n    [K in keyof Events<T>]?: Handler<Context<T>, Events<T>[K], Actions<T>>\n  }\n  states?: StatesConfig<State<T>, Context<T>, Events<T>, Actions<T>>\n  always?: Rule<Context<T>, undefined, Actions<T>>[]\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  effects?: Effect<Context<T>, Events<T>, any>[]\n  actions?: {\n    // eslint-disable-next-line @typescript-eslint/no-explicit-any\n    [K in Actions<T>]: (context: Context<T>, payload?: any) => void\n  }\n}\n\nexport type Send<TEvents extends EventsConfig> = <K extends keyof TEvents>(\n  event: K,\n  ...args: TEvents[K] extends undefined ? [] : [payload: TEvents[K]]\n) => void\n\n// createMachine return type\nexport type MachineInstance<T extends MachineTypes> = Machine<T> & {\n  send: <K extends keyof Events<T>>(\n    event: K,\n    input: Input<T>,\n    ...args: Events<T>[K] extends undefined ? [] : [payload: Events<T>[K]]\n  ) => void\n  evaluate: (input: Input<T>) => void\n  getComputed: (input: Input<T>) => Computed<T>\n  cleanup: () => void\n}\n\n// ============================================\n// Core Logic (Pure)\n// ============================================\n\nexport function executeActions<TContext, TPayload>(\n  actionNames: string | string[],\n  actions: Record<string, (context: TContext, payload?: TPayload) => void>,\n  context: TContext,\n  payload: TPayload,\n): void {\n  if (typeof actionNames === 'string') {\n    actions[actionNames]?.(context, payload)\n  } else {\n    for (const name of actionNames) {\n      actions[name]?.(context, payload)\n    }\n  }\n}\n\nexport function isRuleArray<TContext, TPayload, TActions extends string>(\n  handler: Handler<TContext, TPayload, TActions>,\n): handler is Rule<TContext, TPayload, TActions>[] {\n  return (\n    Array.isArray(handler) &&\n    handler.length > 0 &&\n    typeof handler[0] === 'object' &&\n    'do' in handler[0]\n  )\n}\n\nexport function executeHandler<TContext, TPayload>(\n  handler: Handler<TContext, TPayload>,\n  actions: Record<string, (context: TContext, payload?: TPayload) => void>,\n  context: TContext,\n  payload: TPayload,\n): void {\n  // Single action or action array\n  if (typeof handler === 'string' || (Array.isArray(handler) && !isRuleArray(handler))) {\n    executeActions(handler as string | string[], actions, context, payload)\n    return\n  }\n\n  // Rule array\n  for (const rule of handler as Rule<TContext, TPayload>[]) {\n    if (!rule.when || rule.when(context, payload)) {\n      executeActions(rule.do, actions, context, payload)\n      break\n    }\n  }\n}\n\nexport function computeValues<TContext, TComputed extends ComputedConfig>(\n  context: TContext,\n  computed?: { [K in keyof TComputed]: (context: TContext) => TComputed[K] },\n): TContext & TComputed {\n  if (!computed) return context as TContext & TComputed\n\n  const values = {} as TComputed\n  for (const key in computed) {\n    values[key] = computed[key](context)\n  }\n  return { ...context, ...values }\n}\n\n/**\n * Shallow comparison function - for composite watch support\n *\n * Arrays: length + === comparison for each element\n * Others: === comparison\n */\nexport function shallowEqual(a: unknown, b: unknown): boolean {\n  if (a === b) return true\n\n  // Array comparison\n  if (Array.isArray(a) && Array.isArray(b)) {\n    if (a.length !== b.length) return false\n    return a.every((v, i) => v === b[i])\n  }\n\n  return false\n}\n\n// Effect store for tracking state\nexport type EffectStore = {\n  watchedValues: Map<number, unknown>\n  enterCleanups: Map<number, () => void>\n  changeCleanups: Map<number, () => void>\n  exitCleanups: Map<number, () => void>\n}\n\nexport function createEffectStore(): EffectStore {\n  return {\n    watchedValues: new Map(),\n    enterCleanups: new Map(),\n    changeCleanups: new Map(),\n    exitCleanups: new Map(),\n  }\n}\n\n/**\n * Common effects processing logic\n */\nexport function processEffects<TContext, TEvents extends EventsConfig>(\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  effects: Effect<TContext, TEvents, any>[] | undefined,\n  context: TContext,\n  effectHelpers: EffectHelpers<TEvents>,\n  store: EffectStore,\n): void {\n  if (!effects) return\n\n  effects.forEach((effect, i) => {\n    const prev = store.watchedValues.get(i)\n    const curr = effect.watch(context)\n\n    if (!shallowEqual(prev, curr)) {\n      // cleanup previous enter\n      const enterCleanup = store.enterCleanups.get(i)\n      if (enterCleanup) {\n        enterCleanup()\n        store.enterCleanups.delete(i)\n      }\n\n      // cleanup previous change\n      const changeCleanup = store.changeCleanups.get(i)\n      if (changeCleanup) {\n        changeCleanup()\n        store.changeCleanups.delete(i)\n      }\n\n      // change callback (can return cleanup)\n      const changeResult = effect.change?.(context, prev, curr, effectHelpers)\n      if (typeof changeResult === 'function') {\n        store.changeCleanups.set(i, changeResult)\n      }\n\n      // enter (falsy → truthy)\n      if (!prev && curr) {\n        // cleanup previous exit\n        const exitCleanup = store.exitCleanups.get(i)\n        if (exitCleanup) {\n          exitCleanup()\n          store.exitCleanups.delete(i)\n        }\n\n        const enterResult = effect.enter?.(context, effectHelpers)\n        if (typeof enterResult === 'function') {\n          store.enterCleanups.set(i, enterResult)\n        }\n      }\n\n      // exit (truthy → falsy)\n      if (prev && !curr) {\n        const exitResult = effect.exit?.(context, effectHelpers)\n        if (typeof exitResult === 'function') {\n          store.exitCleanups.set(i, exitResult)\n        }\n      }\n\n      store.watchedValues.set(i, curr)\n    }\n  })\n}\n\n/**\n * Clear effect store\n */\nexport function clearEffectStore(store: EffectStore): void {\n  store.enterCleanups.forEach((fn) => fn())\n  store.enterCleanups.clear()\n  store.changeCleanups.forEach((fn) => fn())\n  store.changeCleanups.clear()\n  store.exitCleanups.forEach((fn) => fn())\n  store.exitCleanups.clear()\n  store.watchedValues.clear()\n}\n\n// ============================================\n// Vanilla (non-React) + Type inference helper\n// ============================================\n\nexport function createMachine<T extends MachineTypes>(\n  config: Machine<T>,\n): MachineInstance<T> {\n  const effectStore = createEffectStore()\n\n  const send = (<K extends keyof Events<T>>(\n    event: K,\n    input: Input<T>,\n    ...args: Events<T>[K] extends undefined ? [] : [payload: Events<T>[K]]\n  ) => {\n    const context = computeValues(input, config.computed)\n    const payload = args[0] as Events<T>[K]\n\n    // 1. State-specific handler first\n    const state = (context as { state?: State<T> }).state\n    if (state && config.states?.[state]?.on?.[event]) {\n      const stateHandler = config.states[state].on[event]\n      executeHandler(stateHandler, config.actions ?? {}, context, payload)\n    }\n\n    // 2. Global handler\n    const globalHandler = config.on?.[event]\n    if (globalHandler) {\n      executeHandler(globalHandler, config.actions ?? {}, context, payload)\n    }\n  }) as <K extends keyof Events<T>>(\n    event: K,\n    input: Input<T>,\n    ...args: Events<T>[K] extends undefined ? [] : [payload: Events<T>[K]]\n  ) => void\n\n  // vanilla send wrapper (with input binding)\n  const createEffectHelpersWithInput = (input: Input<T>): EffectHelpers<Events<T>> => ({\n    send: (<K extends keyof Events<T>>(\n      event: K,\n      ...args: Events<T>[K] extends undefined ? [] : [payload: Events<T>[K]]\n    ) => {\n      send(event, input, ...args)\n    }) as Send<Events<T>>,\n  })\n\n  const evaluate = (input: Input<T>) => {\n    const context = computeValues(input, config.computed)\n    const effectHelpers = createEffectHelpersWithInput(input)\n\n    // always\n    if (config.always && config.actions) {\n      const actionsMap = config.actions as Record<\n        string,\n        (context: Context<T>) => void\n      >\n      for (const rule of config.always) {\n        if (!rule.when || rule.when(context, undefined)) {\n          executeActions(rule.do, actionsMap, context, undefined)\n          break\n        }\n      }\n    }\n\n    // effects\n    processEffects(config.effects, context, effectHelpers, effectStore)\n  }\n\n  const getComputed = (input: Input<T>): Computed<T> => {\n    const context = computeValues(input, config.computed)\n    if (!config.computed) return {} as Computed<T>\n    const result = {} as Computed<T>\n    for (const key in config.computed) {\n      result[key] = context[key]\n    }\n    return result\n  }\n\n  const cleanup = () => clearEffectStore(effectStore)\n\n  return Object.assign(config, { send, evaluate, getComputed, cleanup })\n}\n"],"names":["effect"],"mappings":"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"}

package/dist/index.d.cts

@@ -0,0 +1,143 @@
+export declare type Actions<T extends MachineTypes> = T['actions'] extends string ? T['actions'] : string;
+
+export declare type Cleanup = () => void;
+
+/**
+ * Clear effect store
+ */
+export declare function clearEffectStore(store: EffectStore): void;
+
+export declare type Computed<T extends MachineTypes> = T['computed'] extends ComputedConfig ? T['computed'] : Record<string, never>;
+
+export declare type ComputedConfig = Record<string, unknown>;
+
+export declare function computeValues<TContext, TComputed extends ComputedConfig>(context: TContext, computed?: {
+    [K in keyof TComputed]: (context: TContext) => TComputed[K];
+}): TContext & TComputed;
+
+export declare type Context<T extends MachineTypes> = Input<T> & Computed<T>;
+
+export declare function createEffectStore(): EffectStore;
+
+export declare function createMachine<T extends MachineTypes>(config: Machine<T>): MachineInstance<T>;
+
+export declare type Effect<TContext, TEvents extends EventsConfig, TWatched = unknown> = {
+    watch: (context: TContext) => TWatched;
+    enter?: (context: TContext, helpers: EffectHelpers<TEvents>) => void | Cleanup | Promise<void>;
+    exit?: (context: TContext, helpers: EffectHelpers<TEvents>) => void | Cleanup;
+    change?: (context: TContext, prev: TWatched | undefined, curr: TWatched, helpers: EffectHelpers<TEvents>) => void | Cleanup;
+};
+
+/** Helper for inferring prev/curr types from watch return type */
+export declare function effect<TContext, TEvents extends EventsConfig, TWatched>(config: Effect<TContext, TEvents, TWatched>): Effect<TContext, TEvents, TWatched>;
+
+export declare type EffectHelpers<TEvents extends EventsConfig> = {
+    send: Send<TEvents>;
+};
+
+export declare type EffectStore = {
+    watchedValues: Map<number, unknown>;
+    enterCleanups: Map<number, () => void>;
+    changeCleanups: Map<number, () => void>;
+    exitCleanups: Map<number, () => void>;
+};
+
+export declare type Events<T extends MachineTypes> = T['events'] extends EventsConfig ? T['events'] : Record<string, undefined>;
+
+export declare type EventsConfig = Record<string, unknown>;
+
+export declare function executeActions<TContext, TPayload>(actionNames: string | string[], actions: Record<string, (context: TContext, payload?: TPayload) => void>, context: TContext, payload: TPayload): void;
+
+export declare function executeHandler<TContext, TPayload>(handler: Handler<TContext, TPayload>, actions: Record<string, (context: TContext, payload?: TPayload) => void>, context: TContext, payload: TPayload): void;
+
+export declare type Handler<TContext, TPayload = undefined, TActions extends string = string> = TActions | TActions[] | Rule<TContext, TPayload, TActions>[];
+
+export declare type Input<T extends MachineTypes> = T['input'];
+
+export declare function isRuleArray<TContext, TPayload, TActions extends string>(handler: Handler<TContext, TPayload, TActions>): handler is Rule<TContext, TPayload, TActions>[];
+
+export declare type Machine<T extends MachineTypes> = {
+    computed?: {
+        [K in keyof Computed<T>]: (input: Input<T>) => Computed<T>[K];
+    };
+    on?: {
+        [K in keyof Events<T>]?: Handler<Context<T>, Events<T>[K], Actions<T>>;
+    };
+    states?: StatesConfig<State<T>, Context<T>, Events<T>, Actions<T>>;
+    always?: Rule<Context<T>, undefined, Actions<T>>[];
+    effects?: Effect<Context<T>, Events<T>, any>[];
+    actions?: {
+        [K in Actions<T>]: (context: Context<T>, payload?: any) => void;
+    };
+};
+
+export declare type MachineInstance<T extends MachineTypes> = Machine<T> & {
+    send: <K extends keyof Events<T>>(event: K, input: Input<T>, ...args: Events<T>[K] extends undefined ? [] : [payload: Events<T>[K]]) => void;
+    evaluate: (input: Input<T>) => void;
+    getComputed: (input: Input<T>) => Computed<T>;
+    cleanup: () => void;
+};
+
+/**
+ * Object-based generic types - specify only needed types in any order
+ *
+ * @example
+ * createMachine<{
+ *   input: MyInput
+ *   events: MyEvents
+ *   actions: 'foo' | 'bar'
+ * }>({...})
+ */
+export declare type MachineTypes = {
+    input?: unknown;
+    events?: EventsConfig;
+    computed?: ComputedConfig;
+    actions?: string;
+    state?: string;
+};
+
+/**
+ * Common effects processing logic
+ */
+export declare function processEffects<TContext, TEvents extends EventsConfig>(effects: Effect<TContext, TEvents, any>[] | undefined, context: TContext, effectHelpers: EffectHelpers<TEvents>, store: EffectStore): void;
+
+/**
+ * Controlled Machine
+ *
+ * A controlled state machine where state lives outside the machine.
+ *
+ * - input: External data passed in
+ * - computed: Derived values from input
+ * - context: input + computed (full context available in handlers)
+ * - on: Event → conditional actions
+ * - effects: Watch-based side effects
+ * - always: Auto-evaluated rules on context change
+ */
+export declare type Rule<TContext, TPayload = undefined, TActions extends string = string> = {
+    when?: (context: TContext, payload: TPayload) => boolean;
+    do: TActions | TActions[];
+};
+
+export declare type Send<TEvents extends EventsConfig> = <K extends keyof TEvents>(event: K, ...args: TEvents[K] extends undefined ? [] : [payload: TEvents[K]]) => void;
+
+/**
+ * Shallow comparison function - for composite watch support
+ *
+ * Arrays: length + === comparison for each element
+ * Others: === comparison
+ */
+export declare function shallowEqual(a: unknown, b: unknown): boolean;
+
+export declare type State<T extends MachineTypes> = T['state'] extends string ? T['state'] : string;
+
+export declare type StateConfig<TContext, TEvents extends EventsConfig, TActions extends string = string> = {
+    on?: {
+        [K in keyof TEvents]?: Handler<TContext, TEvents[K], TActions>;
+    };
+};
+
+export declare type StatesConfig<TState extends string, TContext, TEvents extends EventsConfig, TActions extends string = string> = {
+    [K in TState]?: StateConfig<TContext, TEvents, TActions>;
+};
+
+export { }

package/dist/index.d.ts

@@ -0,0 +1,143 @@
+export declare type Actions<T extends MachineTypes> = T['actions'] extends string ? T['actions'] : string;
+
+export declare type Cleanup = () => void;
+
+/**
+ * Clear effect store
+ */
+export declare function clearEffectStore(store: EffectStore): void;
+
+export declare type Computed<T extends MachineTypes> = T['computed'] extends ComputedConfig ? T['computed'] : Record<string, never>;
+
+export declare type ComputedConfig = Record<string, unknown>;
+
+export declare function computeValues<TContext, TComputed extends ComputedConfig>(context: TContext, computed?: {
+    [K in keyof TComputed]: (context: TContext) => TComputed[K];
+}): TContext & TComputed;
+
+export declare type Context<T extends MachineTypes> = Input<T> & Computed<T>;
+
+export declare function createEffectStore(): EffectStore;
+
+export declare function createMachine<T extends MachineTypes>(config: Machine<T>): MachineInstance<T>;
+
+export declare type Effect<TContext, TEvents extends EventsConfig, TWatched = unknown> = {
+    watch: (context: TContext) => TWatched;
+    enter?: (context: TContext, helpers: EffectHelpers<TEvents>) => void | Cleanup | Promise<void>;
+    exit?: (context: TContext, helpers: EffectHelpers<TEvents>) => void | Cleanup;
+    change?: (context: TContext, prev: TWatched | undefined, curr: TWatched, helpers: EffectHelpers<TEvents>) => void | Cleanup;
+};
+
+/** Helper for inferring prev/curr types from watch return type */
+export declare function effect<TContext, TEvents extends EventsConfig, TWatched>(config: Effect<TContext, TEvents, TWatched>): Effect<TContext, TEvents, TWatched>;
+
+export declare type EffectHelpers<TEvents extends EventsConfig> = {
+    send: Send<TEvents>;
+};
+
+export declare type EffectStore = {
+    watchedValues: Map<number, unknown>;
+    enterCleanups: Map<number, () => void>;
+    changeCleanups: Map<number, () => void>;
+    exitCleanups: Map<number, () => void>;
+};
+
+export declare type Events<T extends MachineTypes> = T['events'] extends EventsConfig ? T['events'] : Record<string, undefined>;
+
+export declare type EventsConfig = Record<string, unknown>;
+
+export declare function executeActions<TContext, TPayload>(actionNames: string | string[], actions: Record<string, (context: TContext, payload?: TPayload) => void>, context: TContext, payload: TPayload): void;
+
+export declare function executeHandler<TContext, TPayload>(handler: Handler<TContext, TPayload>, actions: Record<string, (context: TContext, payload?: TPayload) => void>, context: TContext, payload: TPayload): void;
+
+export declare type Handler<TContext, TPayload = undefined, TActions extends string = string> = TActions | TActions[] | Rule<TContext, TPayload, TActions>[];
+
+export declare type Input<T extends MachineTypes> = T['input'];
+
+export declare function isRuleArray<TContext, TPayload, TActions extends string>(handler: Handler<TContext, TPayload, TActions>): handler is Rule<TContext, TPayload, TActions>[];
+
+export declare type Machine<T extends MachineTypes> = {
+    computed?: {
+        [K in keyof Computed<T>]: (input: Input<T>) => Computed<T>[K];
+    };
+    on?: {
+        [K in keyof Events<T>]?: Handler<Context<T>, Events<T>[K], Actions<T>>;
+    };
+    states?: StatesConfig<State<T>, Context<T>, Events<T>, Actions<T>>;
+    always?: Rule<Context<T>, undefined, Actions<T>>[];
+    effects?: Effect<Context<T>, Events<T>, any>[];
+    actions?: {
+        [K in Actions<T>]: (context: Context<T>, payload?: any) => void;
+    };
+};
+
+export declare type MachineInstance<T extends MachineTypes> = Machine<T> & {
+    send: <K extends keyof Events<T>>(event: K, input: Input<T>, ...args: Events<T>[K] extends undefined ? [] : [payload: Events<T>[K]]) => void;
+    evaluate: (input: Input<T>) => void;
+    getComputed: (input: Input<T>) => Computed<T>;
+    cleanup: () => void;
+};
+
+/**
+ * Object-based generic types - specify only needed types in any order
+ *
+ * @example
+ * createMachine<{
+ *   input: MyInput
+ *   events: MyEvents
+ *   actions: 'foo' | 'bar'
+ * }>({...})
+ */
+export declare type MachineTypes = {
+    input?: unknown;
+    events?: EventsConfig;
+    computed?: ComputedConfig;
+    actions?: string;
+    state?: string;
+};
+
+/**
+ * Common effects processing logic
+ */
+export declare function processEffects<TContext, TEvents extends EventsConfig>(effects: Effect<TContext, TEvents, any>[] | undefined, context: TContext, effectHelpers: EffectHelpers<TEvents>, store: EffectStore): void;
+
+/**
+ * Controlled Machine
+ *
+ * A controlled state machine where state lives outside the machine.
+ *
+ * - input: External data passed in
+ * - computed: Derived values from input
+ * - context: input + computed (full context available in handlers)
+ * - on: Event → conditional actions
+ * - effects: Watch-based side effects
+ * - always: Auto-evaluated rules on context change
+ */
+export declare type Rule<TContext, TPayload = undefined, TActions extends string = string> = {
+    when?: (context: TContext, payload: TPayload) => boolean;
+    do: TActions | TActions[];
+};
+
+export declare type Send<TEvents extends EventsConfig> = <K extends keyof TEvents>(event: K, ...args: TEvents[K] extends undefined ? [] : [payload: TEvents[K]]) => void;
+
+/**
+ * Shallow comparison function - for composite watch support
+ *
+ * Arrays: length + === comparison for each element
+ * Others: === comparison
+ */
+export declare function shallowEqual(a: unknown, b: unknown): boolean;
+
+export declare type State<T extends MachineTypes> = T['state'] extends string ? T['state'] : string;
+
+export declare type StateConfig<TContext, TEvents extends EventsConfig, TActions extends string = string> = {
+    on?: {
+        [K in keyof TEvents]?: Handler<TContext, TEvents[K], TActions>;
+    };
+};
+
+export declare type StatesConfig<TState extends string, TContext, TEvents extends EventsConfig, TActions extends string = string> = {
+    [K in TState]?: StateConfig<TContext, TEvents, TActions>;
+};
+
+export { }

package/dist/index.js

@@ -0,0 +1,160 @@
+function effect(config) {
+  return config;
+}
+function executeActions(actionNames, actions, context, payload) {
+  if (typeof actionNames === "string") {
+    actions[actionNames]?.(context, payload);
+  } else {
+    for (const name of actionNames) {
+      actions[name]?.(context, payload);
+    }
+  }
+}
+function isRuleArray(handler) {
+  return Array.isArray(handler) && handler.length > 0 && typeof handler[0] === "object" && "do" in handler[0];
+}
+function executeHandler(handler, actions, context, payload) {
+  if (typeof handler === "string" || Array.isArray(handler) && !isRuleArray(handler)) {
+    executeActions(handler, actions, context, payload);
+    return;
+  }
+  for (const rule of handler) {
+    if (!rule.when || rule.when(context, payload)) {
+      executeActions(rule.do, actions, context, payload);
+      break;
+    }
+  }
+}
+function computeValues(context, computed) {
+  if (!computed) return context;
+  const values = {};
+  for (const key in computed) {
+    values[key] = computed[key](context);
+  }
+  return { ...context, ...values };
+}
+function shallowEqual(a, b) {
+  if (a === b) return true;
+  if (Array.isArray(a) && Array.isArray(b)) {
+    if (a.length !== b.length) return false;
+    return a.every((v, i) => v === b[i]);
+  }
+  return false;
+}
+function createEffectStore() {
+  return {
+    watchedValues: /* @__PURE__ */ new Map(),
+    enterCleanups: /* @__PURE__ */ new Map(),
+    changeCleanups: /* @__PURE__ */ new Map(),
+    exitCleanups: /* @__PURE__ */ new Map()
+  };
+}
+function processEffects(effects, context, effectHelpers, store) {
+  if (!effects) return;
+  effects.forEach((effect2, i) => {
+    const prev = store.watchedValues.get(i);
+    const curr = effect2.watch(context);
+    if (!shallowEqual(prev, curr)) {
+      const enterCleanup = store.enterCleanups.get(i);
+      if (enterCleanup) {
+        enterCleanup();
+        store.enterCleanups.delete(i);
+      }
+      const changeCleanup = store.changeCleanups.get(i);
+      if (changeCleanup) {
+        changeCleanup();
+        store.changeCleanups.delete(i);
+      }
+      const changeResult = effect2.change?.(context, prev, curr, effectHelpers);
+      if (typeof changeResult === "function") {
+        store.changeCleanups.set(i, changeResult);
+      }
+      if (!prev && curr) {
+        const exitCleanup = store.exitCleanups.get(i);
+        if (exitCleanup) {
+          exitCleanup();
+          store.exitCleanups.delete(i);
+        }
+        const enterResult = effect2.enter?.(context, effectHelpers);
+        if (typeof enterResult === "function") {
+          store.enterCleanups.set(i, enterResult);
+        }
+      }
+      if (prev && !curr) {
+        const exitResult = effect2.exit?.(context, effectHelpers);
+        if (typeof exitResult === "function") {
+          store.exitCleanups.set(i, exitResult);
+        }
+      }
+      store.watchedValues.set(i, curr);
+    }
+  });
+}
+function clearEffectStore(store) {
+  store.enterCleanups.forEach((fn) => fn());
+  store.enterCleanups.clear();
+  store.changeCleanups.forEach((fn) => fn());
+  store.changeCleanups.clear();
+  store.exitCleanups.forEach((fn) => fn());
+  store.exitCleanups.clear();
+  store.watchedValues.clear();
+}
+function createMachine(config) {
+  const effectStore = createEffectStore();
+  const send = ((event, input, ...args) => {
+    const context = computeValues(input, config.computed);
+    const payload = args[0];
+    const state = context.state;
+    if (state && config.states?.[state]?.on?.[event]) {
+      const stateHandler = config.states[state].on[event];
+      executeHandler(stateHandler, config.actions ?? {}, context, payload);
+    }
+    const globalHandler = config.on?.[event];
+    if (globalHandler) {
+      executeHandler(globalHandler, config.actions ?? {}, context, payload);
+    }
+  });
+  const createEffectHelpersWithInput = (input) => ({
+    send: ((event, ...args) => {
+      send(event, input, ...args);
+    })
+  });
+  const evaluate = (input) => {
+    const context = computeValues(input, config.computed);
+    const effectHelpers = createEffectHelpersWithInput(input);
+    if (config.always && config.actions) {
+      const actionsMap = config.actions;
+      for (const rule of config.always) {
+        if (!rule.when || rule.when(context, void 0)) {
+          executeActions(rule.do, actionsMap, context, void 0);
+          break;
+        }
+      }
+    }
+    processEffects(config.effects, context, effectHelpers, effectStore);
+  };
+  const getComputed = (input) => {
+    const context = computeValues(input, config.computed);
+    if (!config.computed) return {};
+    const result = {};
+    for (const key in config.computed) {
+      result[key] = context[key];
+    }
+    return result;
+  };
+  const cleanup = () => clearEffectStore(effectStore);
+  return Object.assign(config, { send, evaluate, getComputed, cleanup });
+}
+export {
+  clearEffectStore,
+  computeValues,
+  createEffectStore,
+  createMachine,
+  effect,
+  executeActions,
+  executeHandler,
+  isRuleArray,
+  processEffects,
+  shallowEqual
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sources":["../src/index.ts"],"sourcesContent":["/**\n * Controlled Machine\n *\n * A controlled state machine where state lives outside the machine.\n *\n * - input: External data passed in\n * - computed: Derived values from input\n * - context: input + computed (full context available in handlers)\n * - on: Event → conditional actions\n * - effects: Watch-based side effects\n * - always: Auto-evaluated rules on context change\n */\n\n// ============================================\n// Types\n// ============================================\n\nexport type Rule<\n  TContext,\n  TPayload = undefined,\n  TActions extends string = string,\n> = {\n  when?: (context: TContext, payload: TPayload) => boolean\n  do: TActions | TActions[]\n}\n\nexport type Handler<\n  TContext,\n  TPayload = undefined,\n  TActions extends string = string,\n> = TActions | TActions[] | Rule<TContext, TPayload, TActions>[]\n\n// Effect helpers - utilities available in effect callbacks\nexport type EffectHelpers<TEvents extends EventsConfig> = {\n  send: Send<TEvents>\n}\n\nexport type Cleanup = () => void\n\nexport type Effect<\n  TContext,\n  TEvents extends EventsConfig,\n  TWatched = unknown,\n> = {\n  watch: (context: TContext) => TWatched\n  enter?: (\n    context: TContext,\n    helpers: EffectHelpers<TEvents>,\n  ) => void | Cleanup | Promise<void>\n  exit?: (context: TContext, helpers: EffectHelpers<TEvents>) => void | Cleanup\n  change?: (\n    context: TContext,\n    prev: TWatched | undefined,\n    curr: TWatched,\n    helpers: EffectHelpers<TEvents>,\n  ) => void | Cleanup\n}\n\n/** Helper for inferring prev/curr types from watch return type */\nexport function effect<TContext, TEvents extends EventsConfig, TWatched>(\n  config: Effect<TContext, TEvents, TWatched>,\n): Effect<TContext, TEvents, TWatched> {\n  return config\n}\n\nexport type EventsConfig = Record<string, unknown>\nexport type ComputedConfig = Record<string, unknown>\n\n// ============================================\n// Object-based Generic Types\n// ============================================\n\n/**\n * Object-based generic types - specify only needed types in any order\n *\n * @example\n * createMachine<{\n *   input: MyInput\n *   events: MyEvents\n *   actions: 'foo' | 'bar'\n * }>({...})\n */\nexport type MachineTypes = {\n  input?: unknown\n  events?: EventsConfig\n  computed?: ComputedConfig\n  actions?: string\n  state?: string\n}\n\nexport type Input<T extends MachineTypes> = T['input']\nexport type Events<T extends MachineTypes> = T['events'] extends EventsConfig\n  ? T['events']\n  : Record<string, undefined>\nexport type Computed<T extends MachineTypes> = T['computed'] extends ComputedConfig\n  ? T['computed']\n  : Record<string, never>\nexport type Actions<T extends MachineTypes> = T['actions'] extends string\n  ? T['actions']\n  : string\nexport type State<T extends MachineTypes> = T['state'] extends string\n  ? T['state']\n  : string\n\n// Context = Input + Computed (full context available in handlers)\nexport type Context<T extends MachineTypes> = Input<T> & Computed<T>\n\n// State-based handler configuration\nexport type StateConfig<\n  TContext,\n  TEvents extends EventsConfig,\n  TActions extends string = string,\n> = {\n  on?: { [K in keyof TEvents]?: Handler<TContext, TEvents[K], TActions> }\n}\n\nexport type StatesConfig<\n  TState extends string,\n  TContext,\n  TEvents extends EventsConfig,\n  TActions extends string = string,\n> = {\n  [K in TState]?: StateConfig<TContext, TEvents, TActions>\n}\n\nexport type Machine<T extends MachineTypes> = {\n  computed?: {\n    [K in keyof Computed<T>]: (input: Input<T>) => Computed<T>[K]\n  }\n  on?: {\n    [K in keyof Events<T>]?: Handler<Context<T>, Events<T>[K], Actions<T>>\n  }\n  states?: StatesConfig<State<T>, Context<T>, Events<T>, Actions<T>>\n  always?: Rule<Context<T>, undefined, Actions<T>>[]\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  effects?: Effect<Context<T>, Events<T>, any>[]\n  actions?: {\n    // eslint-disable-next-line @typescript-eslint/no-explicit-any\n    [K in Actions<T>]: (context: Context<T>, payload?: any) => void\n  }\n}\n\nexport type Send<TEvents extends EventsConfig> = <K extends keyof TEvents>(\n  event: K,\n  ...args: TEvents[K] extends undefined ? [] : [payload: TEvents[K]]\n) => void\n\n// createMachine return type\nexport type MachineInstance<T extends MachineTypes> = Machine<T> & {\n  send: <K extends keyof Events<T>>(\n    event: K,\n    input: Input<T>,\n    ...args: Events<T>[K] extends undefined ? [] : [payload: Events<T>[K]]\n  ) => void\n  evaluate: (input: Input<T>) => void\n  getComputed: (input: Input<T>) => Computed<T>\n  cleanup: () => void\n}\n\n// ============================================\n// Core Logic (Pure)\n// ============================================\n\nexport function executeActions<TContext, TPayload>(\n  actionNames: string | string[],\n  actions: Record<string, (context: TContext, payload?: TPayload) => void>,\n  context: TContext,\n  payload: TPayload,\n): void {\n  if (typeof actionNames === 'string') {\n    actions[actionNames]?.(context, payload)\n  } else {\n    for (const name of actionNames) {\n      actions[name]?.(context, payload)\n    }\n  }\n}\n\nexport function isRuleArray<TContext, TPayload, TActions extends string>(\n  handler: Handler<TContext, TPayload, TActions>,\n): handler is Rule<TContext, TPayload, TActions>[] {\n  return (\n    Array.isArray(handler) &&\n    handler.length > 0 &&\n    typeof handler[0] === 'object' &&\n    'do' in handler[0]\n  )\n}\n\nexport function executeHandler<TContext, TPayload>(\n  handler: Handler<TContext, TPayload>,\n  actions: Record<string, (context: TContext, payload?: TPayload) => void>,\n  context: TContext,\n  payload: TPayload,\n): void {\n  // Single action or action array\n  if (typeof handler === 'string' || (Array.isArray(handler) && !isRuleArray(handler))) {\n    executeActions(handler as string | string[], actions, context, payload)\n    return\n  }\n\n  // Rule array\n  for (const rule of handler as Rule<TContext, TPayload>[]) {\n    if (!rule.when || rule.when(context, payload)) {\n      executeActions(rule.do, actions, context, payload)\n      break\n    }\n  }\n}\n\nexport function computeValues<TContext, TComputed extends ComputedConfig>(\n  context: TContext,\n  computed?: { [K in keyof TComputed]: (context: TContext) => TComputed[K] },\n): TContext & TComputed {\n  if (!computed) return context as TContext & TComputed\n\n  const values = {} as TComputed\n  for (const key in computed) {\n    values[key] = computed[key](context)\n  }\n  return { ...context, ...values }\n}\n\n/**\n * Shallow comparison function - for composite watch support\n *\n * Arrays: length + === comparison for each element\n * Others: === comparison\n */\nexport function shallowEqual(a: unknown, b: unknown): boolean {\n  if (a === b) return true\n\n  // Array comparison\n  if (Array.isArray(a) && Array.isArray(b)) {\n    if (a.length !== b.length) return false\n    return a.every((v, i) => v === b[i])\n  }\n\n  return false\n}\n\n// Effect store for tracking state\nexport type EffectStore = {\n  watchedValues: Map<number, unknown>\n  enterCleanups: Map<number, () => void>\n  changeCleanups: Map<number, () => void>\n  exitCleanups: Map<number, () => void>\n}\n\nexport function createEffectStore(): EffectStore {\n  return {\n    watchedValues: new Map(),\n    enterCleanups: new Map(),\n    changeCleanups: new Map(),\n    exitCleanups: new Map(),\n  }\n}\n\n/**\n * Common effects processing logic\n */\nexport function processEffects<TContext, TEvents extends EventsConfig>(\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  effects: Effect<TContext, TEvents, any>[] | undefined,\n  context: TContext,\n  effectHelpers: EffectHelpers<TEvents>,\n  store: EffectStore,\n): void {\n  if (!effects) return\n\n  effects.forEach((effect, i) => {\n    const prev = store.watchedValues.get(i)\n    const curr = effect.watch(context)\n\n    if (!shallowEqual(prev, curr)) {\n      // cleanup previous enter\n      const enterCleanup = store.enterCleanups.get(i)\n      if (enterCleanup) {\n        enterCleanup()\n        store.enterCleanups.delete(i)\n      }\n\n      // cleanup previous change\n      const changeCleanup = store.changeCleanups.get(i)\n      if (changeCleanup) {\n        changeCleanup()\n        store.changeCleanups.delete(i)\n      }\n\n      // change callback (can return cleanup)\n      const changeResult = effect.change?.(context, prev, curr, effectHelpers)\n      if (typeof changeResult === 'function') {\n        store.changeCleanups.set(i, changeResult)\n      }\n\n      // enter (falsy → truthy)\n      if (!prev && curr) {\n        // cleanup previous exit\n        const exitCleanup = store.exitCleanups.get(i)\n        if (exitCleanup) {\n          exitCleanup()\n          store.exitCleanups.delete(i)\n        }\n\n        const enterResult = effect.enter?.(context, effectHelpers)\n        if (typeof enterResult === 'function') {\n          store.enterCleanups.set(i, enterResult)\n        }\n      }\n\n      // exit (truthy → falsy)\n      if (prev && !curr) {\n        const exitResult = effect.exit?.(context, effectHelpers)\n        if (typeof exitResult === 'function') {\n          store.exitCleanups.set(i, exitResult)\n        }\n      }\n\n      store.watchedValues.set(i, curr)\n    }\n  })\n}\n\n/**\n * Clear effect store\n */\nexport function clearEffectStore(store: EffectStore): void {\n  store.enterCleanups.forEach((fn) => fn())\n  store.enterCleanups.clear()\n  store.changeCleanups.forEach((fn) => fn())\n  store.changeCleanups.clear()\n  store.exitCleanups.forEach((fn) => fn())\n  store.exitCleanups.clear()\n  store.watchedValues.clear()\n}\n\n// ============================================\n// Vanilla (non-React) + Type inference helper\n// ============================================\n\nexport function createMachine<T extends MachineTypes>(\n  config: Machine<T>,\n): MachineInstance<T> {\n  const effectStore = createEffectStore()\n\n  const send = (<K extends keyof Events<T>>(\n    event: K,\n    input: Input<T>,\n    ...args: Events<T>[K] extends undefined ? [] : [payload: Events<T>[K]]\n  ) => {\n    const context = computeValues(input, config.computed)\n    const payload = args[0] as Events<T>[K]\n\n    // 1. State-specific handler first\n    const state = (context as { state?: State<T> }).state\n    if (state && config.states?.[state]?.on?.[event]) {\n      const stateHandler = config.states[state].on[event]\n      executeHandler(stateHandler, config.actions ?? {}, context, payload)\n    }\n\n    // 2. Global handler\n    const globalHandler = config.on?.[event]\n    if (globalHandler) {\n      executeHandler(globalHandler, config.actions ?? {}, context, payload)\n    }\n  }) as <K extends keyof Events<T>>(\n    event: K,\n    input: Input<T>,\n    ...args: Events<T>[K] extends undefined ? [] : [payload: Events<T>[K]]\n  ) => void\n\n  // vanilla send wrapper (with input binding)\n  const createEffectHelpersWithInput = (input: Input<T>): EffectHelpers<Events<T>> => ({\n    send: (<K extends keyof Events<T>>(\n      event: K,\n      ...args: Events<T>[K] extends undefined ? [] : [payload: Events<T>[K]]\n    ) => {\n      send(event, input, ...args)\n    }) as Send<Events<T>>,\n  })\n\n  const evaluate = (input: Input<T>) => {\n    const context = computeValues(input, config.computed)\n    const effectHelpers = createEffectHelpersWithInput(input)\n\n    // always\n    if (config.always && config.actions) {\n      const actionsMap = config.actions as Record<\n        string,\n        (context: Context<T>) => void\n      >\n      for (const rule of config.always) {\n        if (!rule.when || rule.when(context, undefined)) {\n          executeActions(rule.do, actionsMap, context, undefined)\n          break\n        }\n      }\n    }\n\n    // effects\n    processEffects(config.effects, context, effectHelpers, effectStore)\n  }\n\n  const getComputed = (input: Input<T>): Computed<T> => {\n    const context = computeValues(input, config.computed)\n    if (!config.computed) return {} as Computed<T>\n    const result = {} as Computed<T>\n    for (const key in config.computed) {\n      result[key] = context[key]\n    }\n    return result\n  }\n\n  const cleanup = () => clearEffectStore(effectStore)\n\n  return Object.assign(config, { send, evaluate, getComputed, cleanup })\n}\n"],"names":["effect"],"mappings":"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"}

package/dist/react.cjs

@@ -0,0 +1,103 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const react = require("react");
+const index = require("./index.cjs");
+function useMachine(machine, input) {
+  const inputRef = react.useRef(input);
+  const machineRef = react.useRef(machine);
+  const isMountedRef = react.useRef(true);
+  inputRef.current = input;
+  machineRef.current = machine;
+  const { computed: computedDef } = machine;
+  const context = react.useMemo(
+    () => index.computeValues(input, computedDef),
+    [input, computedDef]
+  );
+  const computed = react.useMemo(() => {
+    if (!computedDef) return {};
+    const result = {};
+    for (const key in computedDef) {
+      result[key] = context[key];
+    }
+    return result;
+  }, [context, computedDef]);
+  const contextRef = react.useRef(context);
+  contextRef.current = context;
+  const prevContextRef = react.useRef(context);
+  const effectStoreRef = react.useRef({
+    watchedValues: /* @__PURE__ */ new Map(),
+    enterCleanups: /* @__PURE__ */ new Map(),
+    changeCleanups: /* @__PURE__ */ new Map(),
+    exitCleanups: /* @__PURE__ */ new Map()
+  });
+  const { always, actions } = machine;
+  if (prevContextRef.current !== context && always && actions) {
+    const actionsMap = actions;
+    for (const rule of always) {
+      if (!rule.when || rule.when(context, void 0)) {
+        index.executeActions(rule.do, actionsMap, context, void 0);
+        break;
+      }
+    }
+  }
+  prevContextRef.current = context;
+  const send = react.useCallback(
+    (event, ...args) => {
+      const currentMachine = machineRef.current;
+      const currentInput = inputRef.current;
+      const currentContext = index.computeValues(
+        currentInput,
+        currentMachine.computed
+      );
+      const payload = args[0];
+      const state2 = currentContext.state;
+      if (state2 && currentMachine.states?.[state2]?.on?.[event]) {
+        const stateHandler = currentMachine.states[state2].on[event];
+        index.executeHandler(
+          stateHandler,
+          currentMachine.actions ?? {},
+          currentContext,
+          payload
+        );
+      }
+      const globalHandler = currentMachine.on?.[event];
+      if (globalHandler) {
+        index.executeHandler(
+          globalHandler,
+          currentMachine.actions ?? {},
+          currentContext,
+          payload
+        );
+      }
+    },
+    []
+    // no dependencies - uses refs
+  );
+  const safeSend = react.useCallback(
+    (event, ...args) => {
+      if (!isMountedRef.current) return;
+      send(event, ...args);
+    },
+    [send]
+  );
+  const effectHelpers = react.useMemo(
+    () => ({ send: safeSend }),
+    [safeSend]
+  );
+  const { effects } = machine;
+  react.useEffect(() => {
+    index.processEffects(effects, context, effectHelpers, effectStoreRef.current);
+  }, [context, effects, effectHelpers]);
+  react.useEffect(() => {
+    isMountedRef.current = true;
+    const store = effectStoreRef.current;
+    return () => {
+      isMountedRef.current = false;
+      index.clearEffectStore(store);
+    };
+  }, []);
+  const state = context.state ?? "";
+  return { send, computed, state };
+}
+exports.useMachine = useMachine;
+//# sourceMappingURL=react.cjs.map

package/dist/react.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"react.cjs","sources":["../src/react.ts"],"sourcesContent":["/**\n * Controlled Machine - React Integration\n *\n * React hook for using controlled-machine in React components.\n */\n\nimport { useCallback, useRef, useEffect, useMemo } from 'react'\nimport {\n  type MachineTypes,\n  type Machine,\n  type Events,\n  type Computed,\n  type State,\n  type Send,\n  type EffectHelpers,\n  type EffectStore,\n  type Context,\n  computeValues,\n  executeActions,\n  executeHandler,\n  processEffects,\n  clearEffectStore,\n} from './index'\n\n// ============================================\n// React Hook\n// ============================================\n\nexport function useMachine<T extends MachineTypes>(\n  machine: Machine<T>,\n  input: T['input'],\n): { send: Send<Events<T>>; computed: Computed<T>; state: State<T> } {\n  // refs for stable callbacks\n  const inputRef = useRef(input)\n  const machineRef = useRef(machine)\n  const isMountedRef = useRef(true)\n\n  inputRef.current = input\n  machineRef.current = machine\n\n  // compute values\n  const { computed: computedDef } = machine\n  const context = useMemo(\n    () => computeValues(input, computedDef),\n    [input, computedDef],\n  )\n\n  // extract computed only\n  const computed = useMemo(() => {\n    if (!computedDef) return {} as Computed<T>\n    const result = {} as Computed<T>\n    for (const key in computedDef) {\n      result[key] = context[key]\n    }\n    return result\n  }, [context, computedDef])\n\n  const contextRef = useRef(context)\n  contextRef.current = context\n\n  const prevContextRef = useRef<Context<T>>(context)\n  const effectStoreRef = useRef<EffectStore>({\n    watchedValues: new Map(),\n    enterCleanups: new Map(),\n    changeCleanups: new Map(),\n    exitCleanups: new Map(),\n  })\n\n  // always: auto-evaluate when context changes (synchronous, during render)\n  const { always, actions } = machine\n  if (prevContextRef.current !== context && always && actions) {\n    const actionsMap = actions as Record<string, (context: Context<T>) => void>\n    for (const rule of always) {\n      if (!rule.when || rule.when(context, undefined)) {\n        executeActions(rule.do, actionsMap, context, undefined)\n        break\n      }\n    }\n  }\n  prevContextRef.current = context\n\n  // send: stable function (no deps, uses refs)\n  const send: Send<Events<T>> = useCallback(\n    <K extends keyof Events<T>>(\n      event: K,\n      ...args: Events<T>[K] extends undefined ? [] : [payload: Events<T>[K]]\n    ) => {\n      const currentMachine = machineRef.current\n      const currentInput = inputRef.current\n      const currentContext = computeValues(\n        currentInput,\n        currentMachine.computed,\n      )\n      const payload = args[0] as Events<T>[K]\n\n      // 1. State-specific handler first\n      const state = (currentContext as { state?: State<T> }).state\n      if (state && currentMachine.states?.[state]?.on?.[event]) {\n        const stateHandler = currentMachine.states[state].on![event]!\n        executeHandler(\n          stateHandler,\n          currentMachine.actions ?? {},\n          currentContext,\n          payload,\n        )\n      }\n\n      // 2. Global handler\n      const globalHandler = currentMachine.on?.[event]\n      if (globalHandler) {\n        executeHandler(\n          globalHandler,\n          currentMachine.actions ?? {},\n          currentContext,\n          payload,\n        )\n      }\n    },\n    [], // no dependencies - uses refs\n  )\n\n  // safeSend: won't be called after unmount\n  const safeSend: Send<Events<T>> = useCallback(\n    <K extends keyof Events<T>>(\n      event: K,\n      ...args: Events<T>[K] extends undefined ? [] : [payload: Events<T>[K]]\n    ) => {\n      if (!isMountedRef.current) return\n      send(event, ...args)\n    },\n    [send],\n  )\n\n  // effect helpers\n  const effectHelpers: EffectHelpers<Events<T>> = useMemo(\n    () => ({ send: safeSend }),\n    [safeSend],\n  )\n\n  // effects: detect watch value changes\n  const { effects } = machine\n  useEffect(() => {\n    processEffects(effects, context, effectHelpers, effectStoreRef.current)\n  }, [context, effects, effectHelpers])\n\n  // mount/unmount management\n  useEffect(() => {\n    isMountedRef.current = true\n    const store = effectStoreRef.current\n    return () => {\n      isMountedRef.current = false\n      clearEffectStore(store)\n    }\n  }, [])\n\n  // state from context (default to empty string if not provided)\n  const state = (context as { state?: State<T> }).state ?? ('' as State<T>)\n\n  return { send, computed, state }\n}\n\n// Re-export types for convenience\nexport type { Send } from './index'\n"],"names":["useRef","useMemo","computeValues","executeActions","useCallback","state","executeHandler","useEffect","processEffects","clearEffectStore"],"mappings":"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"}