jsx_rosetta 0.3.0 → 0.5.1

data/lib/jsx_rosetta/ir/lowering.rb

@@ -1,29 +1,31 @@
 # frozen_string_literal: true
 
 require_relative "types"
+require_relative "module_shape_classifier"
+require_relative "../ast/inflector"
 
 module JsxRosetta
   module IR
     # Lowers a parsed AST::File into an IR::Component tree.
     #
-    # Phase 2 scope:
-    #   - Single function-declaration component per file.
-    #   - JSX elements with lowercase tags lower to IR::Element; others to
-    #     IR::ComponentInvocation.
-    #   - className attributes lower to IR::StyleBinding; everything else
-    #     to IR::Attribute (event handlers like onClick are passed through
-    #     as Attribute for now and will be re-lowered to EventBinding in
-    #     a later phase).
-    #   - JS expressions are preserved as opaque source text via
-    #     IR::Interpolation. No JS-to-Ruby translation.
-    #   - Pure-whitespace JSXText between elements is dropped (matches
-    #     JSX runtime behavior); other text is preserved verbatim.
+    # Responsibilities:
+    #   - Component discovery — find function/arrow declarations whose
+    #     name and body shape qualify as a function component.
+    #   - Module-shape classification — when no component is found,
+    #     produce a triage-friendly error message via SHAPE_MESSAGES.
+    #   - Function-body lowering — turn return-bearing block statements,
+    #     if-chains, switch/try statements, and bare expression returns
+    #     into IR values (Conditional, Interpolation, Text, etc.).
+    #   - JSX-node lowering — turn JSXElement / JSXFragment / JSXText /
+    #     JSXExpressionContainer trees into IR::Element / Fragment /
+    #     ComponentInvocation / Conditional / Loop / etc.
+    #   - Pattern recognition — `cn()` / `clsx()` className helpers,
+    #     `items.map(...)` loops, `cond ? <A/> : <B/>` polymorphic tags,
+    #     React-hook calls, and onX={...} handlers promotable to
+    #     Stimulus methods.
     #
-    # Phase 4a additions:
-    #   - {children} where `children` is a prop lowers to IR::Slot.
-    #   - {cond && X}, {cond ? X : null}, and {cond ? X : Y} lower to
-    #     IR::Conditional. Other LogicalExpression operators (||, ??) are
-    #     left as opaque interpolations.
+    # Anything outside these patterns is preserved verbatim as a TODO
+    # so the human reviewer sees the original JS at the right spot.
     class Lowering
       # A failure during AST → IR lowering. Carries optional line/column
       # information when the failure can be tied to an AST node.
@@ -66,9 +68,52 @@ module JsxRosetta
         useReducer useImperativeHandle useLayoutEffect useDebugValue
       ].freeze
 
-      EXPORT_TYPES = %w[ExportNamedDeclaration ExportDefaultDeclaration].freeze
+      # Apollo Client hooks. `useQuery` / `useLazyQuery` / `useSubscription`
+      # take a GraphQL document as the first argument; `useMutation` returns
+      # a `[mutate, { loading, ... }]` tuple. None of these have a direct
+      # translation — they encode data fetching, which in Rails lives in
+      # the controller/model. Captured here so the backend can emit a
+      # per-hook TODO with the operation name preserved when extractable.
+      APOLLO_HOOKS = %w[
+        useQuery useLazyQuery useMutation useSubscription useApolloClient
+      ].freeze
+
+      # Next.js navigation hooks (App Router and Pages Router). Each has a
+      # Rails-side analog:
+      #   useRouter        → controller actions / redirect_to
+      #   usePathname      → request.path
+      #   useSearchParams  → params
+      #   useParams        → params (route params)
+      #   useSelectedLayoutSegment(s) → not directly translatable; usually
+      #     used to highlight nav links — the Rails view can pattern-match
+      #     against request.path.
+      NEXT_HOOKS = %w[
+        useRouter usePathname useSearchParams useParams
+        useSelectedLayoutSegment useSelectedLayoutSegments
+      ].freeze
+
+      FRAMEWORK_HOOKS_BY_LIBRARY = {
+        react: REACT_HOOKS,
+        apollo: APOLLO_HOOKS,
+        next_js: NEXT_HOOKS
+      }.freeze
+
       JSX_NODE_TYPES = %w[JSXElement JSXFragment JSXText JSXExpressionContainer].freeze
-      HOC_NAMES = %w[memo forwardRef lazy observer].freeze
+
+      # Mirrors React's `isUnitlessNumber` table — CSS properties that take
+      # a bare number rather than a length. Numeric style values for any
+      # property NOT in this set get a `px` suffix appended at lowering time.
+      UNITLESS_CSS_PROPERTIES = %w[
+        animation-iteration-count aspect-ratio border-image-outset
+        border-image-slice border-image-width box-flex box-flex-group
+        box-ordinal-group column-count columns flex flex-grow flex-negative
+        flex-order flex-positive flex-shrink font-weight grid-area
+        grid-column grid-column-end grid-column-span grid-column-start
+        grid-row grid-row-end grid-row-span grid-row-start line-clamp
+        line-height opacity order orphans scale tab-size widows z-index
+        zoom fill-opacity flood-opacity stop-opacity stroke-dasharray
+        stroke-dashoffset stroke-miterlimit stroke-opacity stroke-width
+      ].to_set.freeze
 
       # Pre-lowering AST scan: maps a node type to a callable returning the
       # AST nodes that contribute return values. Used by body_returns_jsx?.
@@ -106,11 +151,20 @@ module JsxRosetta
         @prop_names = []
         @local_jsx = {}
         @local_bindings = []
+        @local_binding_names = []
         @local_arrows = {}
         @local_polymorphic_tags = {}
+        @local_destructures = {}
         @stimulus_methods = []
         @stimulus_seen_names = {}
         @react_hooks = []
+        @render_methods = []
+        @render_method_seen = {}
+        # Class-component non-render members (constructor, lifecycle hooks,
+        # custom handlers). Keyed by class name; populated by
+        # extract_class_component, drained by lower_component to surface
+        # the verbatim sources as a TODO comment block.
+        @pending_class_other_members = {}
       end
 
       def lower_file(file)
@@ -118,148 +172,79 @@ module JsxRosetta
         raise no_component_error(file.program) if candidates.empty?
 
         name, function = candidates.first
-        lower_component(name, function)
+        module_bindings = capture_module_bindings(file.program, candidates)
+        attach_module_bindings(lower_component(name, function), module_bindings)
       end
 
       def lower_all_components(file)
         candidates = find_component_functions(file.program)
         raise no_component_error(file.program) if candidates.empty?
 
-        candidates.map { |name, function| lower_component(name, function) }
-      end
-
-      private
-
-      def lowering_error(message, node: nil)
-        LoweringError.new(message, node: node, source: @source)
-      end
-
-      def no_component_error(program)
-        shape = classify_module_shape(program)
-        message = SHAPE_MESSAGES[shape]
-        suffix = message ? " — #{message}" : ""
-        lowering_error("no component function found in module#{suffix}")
-      end
-
-      # Heuristic classifier that labels a module whose top-level shape isn't
-      # a function component. Used only for the error message — does not
-      # affect what does or doesn't translate. Order matters: more specific
-      # shapes are checked first.
-      def classify_module_shape(program)
-        ast_shape = classify_ast_shape(program)
-        return ast_shape if ast_shape
-
-        classify_by_export_names(top_level_export_names(program), program)
-      end
-
-      def classify_ast_shape(program)
-        return :class_component if program.body.any? { |stmt| class_component?(stmt) }
-        return :hoc_wrapped if program.body.any? { |stmt| hoc_wrapped_export?(stmt) }
-        return :columns_data if program.body.any? { |stmt| array_literal_export?(stmt) }
-
-        nil
-      end
-
-      def classify_by_export_names(names, program)
-        export_label = classify_by_export_pattern(names)
-        return export_label if export_label
-
-        classify_non_export_module(program)
-      end
-
-      def classify_by_export_pattern(names)
-        any_hooks = names.any? { |n| hook_name?(n) }
-        any_helpers = names.any? { |n| /\A[a-z]/.match?(n) && !hook_name?(n) }
-        return :mixed_exports if any_hooks && any_helpers
-        return :hooks_only if any_hooks
-        return :utils_only if any_helpers
-
-        nil
-      end
-
-      # No function-shaped exports. Distinguish:
-      #   - side-effect-only (top-level calls like `LicenseManager.set(...)`)
-      #   - types-only       (TS types/interfaces and constants)
-      #   - unknown          (nothing top-level to look at)
-      def classify_non_export_module(program)
-        return :side_effects_only if program.body.any? { |s| side_effect_statement?(s) }
-        return :types_only if top_level_has_anything?(program)
-
-        :unknown
-      end
-
-      def side_effect_statement?(stmt)
-        stmt.is_a?(AST::Node) && stmt.type == "ExpressionStatement"
+        module_bindings = capture_module_bindings(file.program, candidates)
+        candidates.map do |name, function|
+          attach_module_bindings(lower_component(name, function), module_bindings)
+        end
       end
 
-      def hook_name?(name)
-        name.start_with?("use") && name.length > 3 && name[3] == name[3].upcase
+      # Walk the program body for top-level `const`/`let` declarations that
+      # aren't component declarations. Capture each as a LocalBinding so
+      # backends can emit them as Ruby constants (or as a TODO comment for
+      # non-literal initializers) before the class definition. Without
+      # this, `const FOO = 400; function X() { return <p>{FOO}</p> }` would
+      # silently drop the FOO declaration and emit an unbacked `foo`
+      # reference inside the view template.
+      def capture_module_bindings(program, candidates)
+        component_names = candidates.to_set(&:first)
+        bindings = []
+        program.body.each do |stmt|
+          walk_module_binding(stmt, component_names, bindings)
+        end
+        bindings
       end
 
-      def class_component?(stmt)
-        decl = EXPORT_TYPES.include?(stmt.type) ? stmt[:declaration] : stmt
-        decl.is_a?(AST::Node) && decl.type == "ClassDeclaration"
+      def walk_module_binding(stmt, component_names, bindings)
+        case stmt.type
+        when "VariableDeclaration"
+          stmt[:declarations].each { |d| record_module_binding(stmt, d, component_names, bindings) }
+        when "ExportNamedDeclaration"
+          decl = stmt[:declaration]
+          walk_module_binding(decl, component_names, bindings) if decl.is_a?(AST::Node)
+        end
       end
 
-      # Recognize `export const X = React.memo(...)` (export wrapper) or a
-      # top-level `const X = lazy(() => ...)` followed by `export default X`
-      # — a VariableDeclaration whose init is a CallExpression to a known HOC.
-      def hoc_wrapped_export?(stmt)
-        decl = EXPORT_TYPES.include?(stmt.type) ? stmt[:declaration] : stmt
-        return false unless decl.is_a?(AST::Node) && decl.type == "VariableDeclaration"
+      def record_module_binding(stmt, declarator, component_names, bindings)
+        init = declarator[:init]
+        return unless init.is_a?(AST::Node)
 
-        decl[:declarations].any? do |d|
-          init = d[:init]
-          init.is_a?(AST::Node) && init.type == "CallExpression" && hoc_callee?(init[:callee])
-        end
-      end
+        # Component declarators (`const Foo = () => ...`) are handled by
+        # the component pipeline; skip them here so the source doesn't
+        # show up twice.
+        return if %w[ArrowFunctionExpression FunctionExpression].include?(init.type) &&
+                  component_names.include?(declarator[:id]&.[](:name))
 
-      def hoc_callee?(callee)
-        return false unless callee.is_a?(AST::Node)
+        name = declarator[:id]&.[](:name)
+        return unless name
 
-        case callee.type
-        when "Identifier" then HOC_NAMES.include?(callee[:name])
-        when "MemberExpression"
-          property = callee[:property]
-          property.is_a?(AST::Node) && property.type == "Identifier" && HOC_NAMES.include?(property[:name])
-        else false
-        end
+        bindings << LocalBinding.new(name: name, source: source_of(stmt).strip)
       end
 
-      def array_literal_export?(stmt)
-        return false unless EXPORT_TYPES.include?(stmt.type)
+      def attach_module_bindings(component, module_bindings)
+        return component if module_bindings.empty?
 
-        decl = stmt[:declaration]
-        return true if decl.is_a?(AST::Node) && decl.type == "ArrayExpression"
-        return false unless decl.is_a?(AST::Node) && decl.type == "VariableDeclaration"
-
-        decl[:declarations].any? { |d| d[:init].is_a?(AST::Node) && d[:init].type == "ArrayExpression" }
+        component.with(module_bindings: module_bindings)
       end
 
-      # Does the program have any top-level non-import statements? Used to
-      # distinguish "types-only / empty module" from "mixed exports."
-      def top_level_has_anything?(program)
-        program.body.any? do |stmt|
-          stmt.is_a?(AST::Node) && stmt.type != "ImportDeclaration"
-        end
-      end
+      private
 
-      def top_level_export_names(program)
-        program.body.flat_map { |stmt| extract_top_level_names(stmt) }.compact
+      def lowering_error(message, node: nil)
+        LoweringError.new(message, node: node, source: @source)
       end
 
-      def extract_top_level_names(stmt)
-        case stmt.type
-        when "FunctionDeclaration"
-          [stmt[:id]&.[](:name)]
-        when "VariableDeclaration"
-          stmt[:declarations].map { |d| d[:id].is_a?(AST::Node) && d[:id].type == "Identifier" ? d[:id][:name] : nil }
-        when "ExportNamedDeclaration", "ExportDefaultDeclaration"
-          decl = stmt[:declaration]
-          decl.is_a?(AST::Node) ? extract_top_level_names(decl) : []
-        else
-          []
-        end
+      def no_component_error(program)
+        shape = ModuleShapeClassifier.classify(program)
+        message = SHAPE_MESSAGES[shape]
+        suffix = message ? " — #{message}" : ""
+        lowering_error("no component function found in module#{suffix}")
       end
 
       def find_component_functions(program)
@@ -278,6 +263,7 @@ module JsxRosetta
         return false if name.nil? || name.empty?
         return true if pascal_case?(name)
         return false if hook_name?(name)
+        return true if extract_data_factory_array(function)
 
         body_returns_jsx?(function[:body])
       end
@@ -287,6 +273,10 @@ module JsxRosetta
         first == first.upcase && first != first.downcase
       end
 
+      def hook_name?(name)
+        name.start_with?("use") && name.length > 3 && name[3] == name[3].upcase
+      end
+
       # Pre-lowering AST scan: does any return path in this body produce a
       # JSX value? Used only as a heuristic for component_function?, so a
       # false positive is a translation attempt that may TODO out, while
@@ -311,6 +301,8 @@ module JsxRosetta
           [[stmt[:id]&.[](:name), stmt]]
         when "VariableDeclaration"
           extract_arrow_components(stmt)
+        when "ClassDeclaration"
+          extract_class_component(stmt)
         when "ExportNamedDeclaration", "ExportDefaultDeclaration"
           extract_exported_components(stmt[:declaration])
         else
@@ -324,10 +316,133 @@ module JsxRosetta
         case declaration.type
         when "FunctionDeclaration" then [[declaration[:id]&.[](:name), declaration]]
         when "VariableDeclaration" then extract_arrow_components(declaration)
+        when "ClassDeclaration" then extract_class_component(declaration)
         else []
         end
       end
 
+      # Recognize a class component by the presence of a `render()` method.
+      # We don't require `extends React.Component` because TypeScript codebases
+      # often declare the parent via an `extends` of a typed alias. The render
+      # method's signature (no args, returns JSX) is the JSX-component signal.
+      #
+      # The render ClassMethod's `[:params]` is always `[]` and `[:body]` is a
+      # BlockStatement — same shape as a function declaration's body, so the
+      # rest of the lowering pipeline works unchanged. Other class members
+      # (constructor, lifecycle hooks, custom handlers) get stashed on
+      # `@pending_class_other_members` keyed by class name, then surfaced as
+      # a LocalBinding-style TODO block by `lower_component`.
+      def extract_class_component(class_decl)
+        name = class_decl[:id]&.[](:name)
+        return [] unless name
+
+        render_method, other_members = partition_class_members(class_decl)
+        return [] unless render_method
+
+        @pending_class_other_members[name] = other_members
+        [[name, render_method]]
+      end
+
+      def partition_class_members(class_decl)
+        body = class_decl.child(:body)
+        return [nil, []] unless body
+
+        render_method = nil
+        others = []
+        body[:body].each do |member|
+          if class_render_method?(member)
+            render_method = member
+          else
+            others << member
+          end
+        end
+        [render_method, others]
+      end
+
+      def class_render_method?(member)
+        return false unless AST::Node.matches?(member, "ClassMethod", "MethodDefinition")
+
+        key = member.child(:key)
+        AST::Node.matches?(key, "Identifier") && key[:name] == "render" && member[:kind] != "constructor"
+      end
+
+      # Surface every non-render class member (constructor, lifecycle
+      # methods like componentDidMount / componentDidCatch / getDerivedStateFromError,
+      # custom event handlers) as a LocalBinding-shaped TODO with the
+      # verbatim JS source preserved. The user either translates each to a
+      # Ruby method by hand or moves the behavior to Stimulus / controllers.
+      def absorb_class_other_members(name)
+        members = @pending_class_other_members.delete(name) || []
+        members.each do |member|
+          source = source_of(member).strip
+          member_name = class_member_label(member)
+          @local_bindings << LocalBinding.new(name: member_name, source: source)
+        end
+      end
+
+      def class_member_label(member)
+        key = member.child(:key)
+        return "<class member>" unless key
+
+        case key.type
+        when "Identifier" then key[:name]
+        when "StringLiteral" then key[:value]
+        else "<class member>"
+        end
+      end
+
+      # Pre-scan the render method body for `this.props.X` member access
+      # patterns. Each unique X becomes a synthesized IR::Prop entry on the
+      # component, so the generated class emits a matching `initialize(x:)`
+      # and the translator (which sees `@x`) resolves cleanly. Without this
+      # scan, render references would land in `unresolved_identifiers` and
+      # the generated initializer would be empty.
+      def absorb_class_render_props(render_method)
+        body = render_method.child(:body)
+        return [] unless body
+
+        prop_names = []
+        scan_this_props(body, prop_names)
+        prop_names.uniq.map { |name| Prop.new(name: name, default: nil, alias_name: nil) }
+      end
+
+      def scan_this_props(node, accumulator)
+        return unless node.is_a?(AST::Node)
+
+        if node.of_type?("MemberExpression") && this_props_access?(node)
+          accumulator << node[:property][:name]
+        elsif node.of_type?("VariableDeclarator") && this_props_destructure?(node)
+          destructured_names_of(node[:id]).each { |name| accumulator << name }
+        end
+        node.each_child { |child| scan_this_props(child, accumulator) }
+      end
+
+      # Match `this.props.X` exactly — `this.props` member access where the
+      # property side is also a MemberExpression. We don't follow deeper
+      # chains here; only the immediate `.X` after `.props` becomes a prop
+      # name. `this.props.foo.bar` still yields prop name `foo`.
+      def this_props_access?(member_expr)
+        object = member_expr.child(:object)
+        return false unless AST::Node.matches?(object, "MemberExpression")
+        return false unless AST::Node.matches?(object.child(:object), "ThisExpression")
+
+        object_prop = object.child(:property)
+        AST::Node.matches?(object_prop, "Identifier") && object_prop[:name] == "props"
+      end
+
+      # `const { foo, bar } = this.props;` — destructure off this.props. Each
+      # destructured name becomes a prop. We don't need to walk the rest of
+      # the chain because the destructure consumes one level of `.props`.
+      def this_props_destructure?(declarator)
+        init = declarator[:init]
+        return false unless AST::Node.matches?(init, "MemberExpression")
+        return false unless AST::Node.matches?(init.child(:object), "ThisExpression")
+        return false unless destructure_pattern?(declarator[:id])
+
+        prop = init.child(:property)
+        AST::Node.matches?(prop, "Identifier") && prop[:name] == "props"
+      end
+
       def extract_arrow_components(variable_declaration)
         variable_declaration[:declarations].filter_map do |declarator|
           init = declarator[:init]
@@ -344,42 +459,129 @@ module JsxRosetta
           raise lowering_error("anonymous component functions are not supported", node: function)
         end
 
+        reset_per_component_state!
         props, rest_prop_name = lower_params(function[:params])
         @prop_names = props.map(&:name)
-        @local_bindings = []
-        @local_arrows = {}
-        @local_polymorphic_tags = {}
-        @stimulus_methods = []
-        @stimulus_seen_names = {}
-        @react_hooks = []
-
-        body = lower_function_body(function[:body])
-
+        absorb_class_metadata(name, function, props) if function.of_type?("ClassMethod", "MethodDefinition")
+
+        body, mode = lower_component_body(function)
+        # Unconsumed local arrows (`const handleClick = () => ...` that didn't
+        # become a Stimulus method or a render-method) are still real bindings
+        # in the source. Add their names here so the translator treats use
+        # sites as known-unresolvable — `on_click: handle_click` (NameError)
+        # becomes `on_click: nil` (file loads, marker visible upstream).
+        unconsumed_arrow_names = @local_arrows.keys
         Component.new(
           name: name,
           props: props,
           body: body,
           rest_prop_name: rest_prop_name,
           local_bindings: @local_bindings,
+          local_binding_names: (@local_binding_names + unconsumed_arrow_names).uniq,
+          module_bindings: [],
           stimulus_methods: @stimulus_methods,
-          react_hooks: @react_hooks
+          react_hooks: @react_hooks,
+          render_methods: @render_methods,
+          mode: mode
         )
       end
 
+      # A "data factory" function — common for AG-Grid / antd column
+      # descriptor modules — is a function whose body just returns an array
+      # of object literals (`export const createColumns = (...) => [{...},
+      # {...}]`). When we recognize this shape, we lower the body via the
+      # recursive ObjectLiteral/ArrayLiteral path (Gap H) and let the
+      # backend emit a snake_case method that returns the data, instead of
+      # a `view_template`. JSX inside object properties still extracts to
+      # private methods on the class via the IR::Lambda extraction.
+      def lower_component_body(function)
+        factory_array = extract_data_factory_array(function)
+        return [lower_value_expression(factory_array), :data_factory] if factory_array
+
+        [lower_function_body(function[:body]), :view]
+      end
+
+      def extract_data_factory_array(function)
+        body = function[:body]
+        return nil unless body.is_a?(AST::Node)
+
+        # Implicit-return arrow: body IS the ArrayExpression.
+        return body if data_factory_candidate_array?(body)
+
+        return nil unless body.of_type?("BlockStatement")
+
+        return_stmt = body[:body].last
+        return nil unless AST::Node.matches?(return_stmt, "ReturnStatement")
+
+        arg = return_stmt[:argument]
+        data_factory_candidate_array?(arg) ? arg : nil
+      end
+
+      def data_factory_candidate_array?(node)
+        return false unless AST::Node.matches?(node, "ArrayExpression")
+
+        # At least one element should be an object literal — otherwise
+        # this is probably a primitive list, which doesn't warrant the
+        # extra emission machinery and can stay as a regular
+        # `body_returns_jsx?` rejection.
+        node[:elements].any? { |el| AST::Node.matches?(el, "ObjectExpression") }
+      end
+
+      def reset_per_component_state!
+        @local_bindings = []
+        @local_binding_names = []
+        @local_arrows = {}
+        @local_polymorphic_tags = {}
+        @local_destructures = {}
+        @stimulus_methods = []
+        @stimulus_seen_names = {}
+        @react_hooks = []
+        @render_methods = []
+        @render_method_seen = {}
+      end
+
+      def absorb_class_metadata(name, render_method, props)
+        absorb_class_other_members(name)
+        props.concat(absorb_class_render_props(render_method))
+        @prop_names = props.map(&:name)
+      end
+
       def lower_params(params)
         return [[], nil] if params.nil? || params.empty?
 
+        # Multi-positional params — typical for data-factory functions
+        # like `createColumns(token, sortedInfo)` and lowercase JSX-helpers
+        # like `getAlertIcon(level, status, token, isSnoozed = false)`.
+        # Each becomes a Prop with no default. We support Identifier and
+        # `AssignmentPattern` (default values get dropped — translating
+        # JS defaults to Ruby isn't worth the risk here). Other shapes
+        # in a multi-param signature fall through to legacy first-param-
+        # only handling so we don't regress files that used to translate.
+        if params.size > 1 && params.all? { |p| multi_param_supported?(p) }
+          return [params.map { |p| Prop.new(name: multi_param_name(p), default: nil, alias_name: nil) }, nil]
+        end
+
         first_param = params.first
         case first_param.type
         when "ObjectPattern"
           lower_object_pattern_params(first_param)
         when "Identifier"
-          [[Prop.new(name: first_param[:name], default: nil)], nil]
+          [[Prop.new(name: first_param[:name], default: nil, alias_name: nil)], nil]
         else
           raise lowering_error("unsupported parameter shape: #{first_param.type}", node: first_param)
         end
       end
 
+      def multi_param_supported?(param)
+        return true if AST::Node.matches?(param, "Identifier")
+
+        AST::Node.matches?(param, "AssignmentPattern") && AST::Node.matches?(param[:left], "Identifier")
+      end
+
+      def multi_param_name(param)
+        param.type == "Identifier" ? param[:name] : param[:left][:name]
+      end
+
       def lower_object_pattern_params(pattern)
         props = []
         rest_name = nil
@@ -401,8 +603,26 @@ module JsxRosetta
         key = property[:key]
         prop_name = key.type == "StringLiteral" ? key[:value] : key[:name]
         value = property[:value]
-        default = (Interpolation.new(expression: source_of(value[:right])) if value.type == "AssignmentPattern")
-        Prop.new(name: prop_name, default: default)
+        # Route prop default expressions through the recursive value
+        # lowering so object/array literals translate cleanly, instead of
+        # producing an opaque Interpolation that the backend would emit as
+        # `nil # TODO: ...`. The trailing `#` comment inside a method
+        # parameter list swallows the closing `)` and breaks Ruby syntax.
+        default = (lower_value_expression(value[:right]) if value.type == "AssignmentPattern")
+        alias_name = destructure_alias_for(prop_name, value)
+        Prop.new(name: prop_name, default: default, alias_name: alias_name)
+      end
+
+      # `{ "data-testid": dataTestId }` — extract the alias so use sites of
+      # `dataTestId` resolve to the prop's `@data_testid` ivar instead of
+      # leaking as a bare snake_case ref. Returns nil for the non-aliased
+      # case (`{ loading }` — key.name == value.name).
+      def destructure_alias_for(prop_name, value)
+        target = value.type == "AssignmentPattern" ? value[:left] : value
+        return nil unless AST::Node.matches?(target, "Identifier")
+        return nil if target[:name] == prop_name
+
+        target[:name]
       end
 
       def lower_function_body(body)
@@ -454,7 +674,7 @@ module JsxRosetta
       # around the base value as outer Conditionals. Returns nil when no shape
       # matches; caller raises.
       def lower_block_returns(statements)
-        return_idx = statements.index { |s| s.is_a?(AST::Node) && s.type == "ReturnStatement" }
+        return_idx = statements.index { |s| AST::Node.matches?(s, "ReturnStatement") }
 
         if return_idx
           return_arg = statements[return_idx][:argument]
@@ -492,20 +712,22 @@ module JsxRosetta
       # behavior of dropping unrepresentable preceding statements rather
       # than failing the whole component.
       def wrap_return_guards(preceding, base_value)
-        preceding.reverse.each do |stmt|
-          next unless stmt.is_a?(AST::Node) && stmt.type == "IfStatement"
-          next if stmt[:alternate]
+        preceding.reverse.reduce(base_value) do |acc, stmt|
+          next acc unless guard_if_statement?(stmt)
 
           branch_value = lower_return_branch(stmt[:consequent])
-          next unless branch_value
+          next acc unless branch_value
 
-          base_value = Conditional.new(
+          Conditional.new(
             test: Interpolation.new(expression: source_of(stmt[:test])),
             consequent: branch_value,
-            alternate: base_value
+            alternate: acc
           )
         end
-        base_value
+      end
+
+      def guard_if_statement?(stmt)
+        AST::Node.matches?(stmt, "IfStatement") && stmt[:alternate].nil?
       end
 
       def lower_if_return_chain(if_stmt)
@@ -547,7 +769,7 @@ module JsxRosetta
 
       def collect_nested_local_bindings(stmts)
         stmts.each do |stmt|
-          next unless stmt.is_a?(AST::Node) && stmt.type == "VariableDeclaration"
+          next unless AST::Node.matches?(stmt, "VariableDeclaration")
 
           seen = {}
           stmt[:declarations].each { |declarator| classify_local_binding(stmt, declarator, seen) }
@@ -625,10 +847,10 @@ module JsxRosetta
       #   case A: if (X) return Y; return Z;  (guard prefix + return)
       # Trailing `break` statements are ignored.
       def lower_switch_case_consequent(stmts)
-        filtered = stmts.reject { |s| s.is_a?(AST::Node) && s.type == "BreakStatement" }
+        filtered = stmts.reject { |s| AST::Node.matches?(s, "BreakStatement") }
         return nil if filtered.empty?
 
-        if filtered.size == 1 && filtered.first.is_a?(AST::Node) && filtered.first.type == "BlockStatement"
+        if filtered.size == 1 && AST::Node.matches?(filtered.first, "BlockStatement")
           return lower_switch_case_consequent(filtered.first[:body])
         end
 
@@ -650,6 +872,7 @@ module JsxRosetta
         @local_jsx = {}
         @local_arrows = {}
         @local_polymorphic_tags = {}
+        @local_destructures = {}
         seen_other_stmts = {}
 
         statements.each do |stmt|
@@ -666,14 +889,54 @@ module JsxRosetta
         init = declarator[:init]
         return unless init.is_a?(AST::Node)
 
-        if hook_call?(init)
-          @react_hooks << ReactHookCall.new(hook: init[:callee][:name], source: source_of(stmt).strip)
-          return
-        end
+        # `const { foo, bar } = this.props` — destructured names already
+        # got synthesized into `props:` by absorb_class_render_props at
+        # class-component setup time. Skip the LocalBinding TODO + the
+        # local_binding_names capture so the translator picks up the prop
+        # form (`@foo`) instead of emitting a `nil` placeholder.
+        return if this_props_destructure?(declarator)
 
-        name = declarator[:id]&.[](:name)
+        library = hook_library_for(init)
+        record_hook_call(stmt, init, library) if library
+
+        id_node = declarator[:id]
+        return handle_destructure_binding(stmt, declarator, init, seen, !library.nil?) if destructure_pattern?(id_node)
+        return handle_identifier_hook_binding(id_node) if library
+
+        name = id_node&.[](:name)
         return unless name
 
+        dispatch_identifier_binding(stmt, init, name, seen)
+      end
+
+      def record_hook_call(stmt, call_expression, library)
+        @react_hooks << ReactHookCall.new(
+          hook: call_expression[:callee][:name],
+          source: source_of(stmt).strip,
+          library: library,
+          operation: apollo_operation_name(call_expression, library)
+        )
+      end
+
+      # `const [a, b] = ...` or `const { a, b } = ...`. Capture every bound
+      # name so the translator recognizes them as known locals. Hook
+      # destructures (`const [open, setOpen] = useState(0)`) contribute
+      # names but not a separate LocalBinding TODO — the hook's source
+      # already shows the binding to the reviewer.
+      def handle_destructure_binding(stmt, declarator, init, seen, is_hook)
+        record_destructured_names(stmt, declarator, init: init, seen: seen, is_hook: is_hook)
+      end
+
+      # Identifier-bound hook result (`const handleChange = useCallback(...)`).
+      # The hook source is already in @react_hooks; just mark the binding
+      # name as known-local so use sites translate to `nil` instead of a
+      # bare snake_case ref that NameErrors at render time.
+      def handle_identifier_hook_binding(id_node)
+        name = id_node&.[](:name)
+        @local_binding_names << name if name
+      end
+
+      def dispatch_identifier_binding(stmt, init, name, seen)
         case init.type
         when "JSXElement", "JSXFragment"
           @local_jsx[name] = init
@@ -687,19 +950,117 @@ module JsxRosetta
         end
       end
 
+      def destructure_pattern?(node)
+        AST::Node.matches?(node, "ArrayPattern", "ObjectPattern")
+      end
+
+      def record_destructured_names(stmt, declarator, init:, seen:, is_hook:)
+        pattern = declarator[:id]
+        names = destructured_names_of(pattern)
+        return if names.empty?
+
+        # Member-expression-style destructuring (Gap J): `const { Content } = Layout`
+        # binds `Content` to `Layout.Content`. Record those so JSX use sites
+        # resolve to the right component.
+        track_member_destructures(pattern, init) if AST::Node.matches?(init, "Identifier")
+
+        @local_binding_names.concat(names)
+        return if is_hook
+
+        seen[stmt.start_pos] ||= source_of(stmt).strip
+        names.each { |name| @local_bindings << LocalBinding.new(name: name, source: seen[stmt.start_pos]) }
+      end
+
+      # Return the flat list of Identifier names bound by a destructuring
+      # pattern. Nested patterns recurse. RestElement / aliased properties
+      # are included; defaults (AssignmentPattern) are followed to their
+      # left-hand identifier.
+      def destructured_names_of(pattern)
+        return [] unless pattern.is_a?(AST::Node)
+
+        case pattern.type
+        when "Identifier" then [pattern[:name]]
+        when "ArrayPattern"
+          pattern[:elements].flat_map { |element| element ? destructured_names_of(element) : [] }
+        when "ObjectPattern"
+          pattern[:properties].flat_map { |prop| destructured_names_from_property(prop) }
+        when "RestElement"
+          destructured_names_of(pattern[:argument])
+        when "AssignmentPattern"
+          destructured_names_of(pattern[:left])
+        else
+          []
+        end
+      end
+
+      def destructured_names_from_property(prop)
+        case prop.type
+        when "ObjectProperty" then destructured_names_of(prop[:value])
+        when "RestElement" then destructured_names_of(prop[:argument])
+        else []
+        end
+      end
+
+      def track_member_destructures(pattern, source_identifier)
+        return unless AST::Node.matches?(pattern, "ObjectPattern")
+
+        source_name = source_identifier[:name]
+        pattern[:properties].each do |prop|
+          next unless prop.type == "ObjectProperty"
+
+          value = prop[:value]
+          next unless AST::Node.matches?(value, "Identifier")
+
+          @local_destructures[value[:name]] = source_name
+        end
+      end
+
       def detect_bare_hook_call(stmt)
-        expr = stmt[:expression]
-        return unless expr.is_a?(AST::Node) && expr.type == "CallExpression"
-        return unless hook_call?(expr)
+        expr = stmt.child(:expression)
+        return unless expr&.of_type?("CallExpression")
+
+        library = hook_library_for(expr)
+        return unless library
 
-        @react_hooks << ReactHookCall.new(hook: expr[:callee][:name], source: source_of(stmt).strip)
+        record_hook_call(stmt, expr, library)
       end
 
       def hook_call?(call_expression)
-        return false unless call_expression.type == "CallExpression"
+        !hook_library_for(call_expression).nil?
+      end
+
+      # Resolve a CallExpression to the library whose hook set its callee
+      # belongs to (`:react`, `:apollo`, `:next_js`), or nil when it isn't
+      # a recognized hook invocation. Lookup is by bare-Identifier callee
+      # only — member-expression callees (`Apollo.useQuery`) aren't
+      # recognized; we follow what production code actually writes.
+      def hook_library_for(call_expression)
+        return nil unless call_expression.is_a?(AST::Node) && call_expression.of_type?("CallExpression")
 
-        callee = call_expression[:callee]
-        callee.is_a?(AST::Node) && callee.type == "Identifier" && REACT_HOOKS.include?(callee[:name])
+        callee = call_expression.child(:callee)
+        return nil unless callee&.of_type?("Identifier")
+
+        name = callee[:name]
+        FRAMEWORK_HOOKS_BY_LIBRARY.each do |library, names|
+          return library if names.include?(name)
+        end
+        nil
+      end
+
+      # For Apollo's document-first hooks (`useQuery(GET_USERS, ...)`),
+      # extract the operation name from a bare-Identifier first argument
+      # so the backend can echo it in the TODO. Returns nil for inline
+      # documents (`gql\`...\``), member-expression args, or non-Apollo
+      # hooks — the caller already has the verbatim source in `source`,
+      # which surfaces those cases to the reviewer.
+      def apollo_operation_name(call_expression, library)
+        return nil unless library == :apollo
+
+        args = call_expression[:arguments]
+        first_arg = args.is_a?(Array) ? args.first : nil
+        return nil unless AST::Node.matches?(first_arg, "Identifier")
+
+        first_arg[:name]
       end
 
       # Recognize the asChild-style polymorphic tag pattern:
@@ -727,6 +1088,7 @@ module JsxRosetta
       def record_local_other_binding(stmt, name, seen)
         seen[stmt.start_pos] ||= source_of(stmt).strip
         @local_bindings << LocalBinding.new(name: name, source: seen[stmt.start_pos])
+        @local_binding_names << name
       end
 
       def lower_jsx(node)
@@ -742,7 +1104,7 @@ module JsxRosetta
 
       def lower_jsx_element(element)
         tag = element.tag_name
-        attributes = element.opening_element.attributes.filter_map { |attr| lower_attribute(attr) }
+        attributes = element.opening_element.attributes.filter_map { |attr| lower_attribute(attr, tag: tag) }
         # `key` is a React-only reconciliation hint; never emit it to the DOM
         # or to ViewComponent invocations.
         attributes = attributes.reject { |attr| attr.is_a?(Attribute) && attr.name == "key" }
@@ -750,6 +1112,10 @@ module JsxRosetta
 
         if (poly = @local_polymorphic_tags[tag])
           lower_polymorphic_tag_use(poly, attributes, children)
+        elsif (parent = @local_destructures[tag])
+          # Gap J: `const { Content } = Layout; <Content/>` should resolve
+          # to `Layout::Content`, not a bare `ContentComponent`.
+          ComponentInvocation.new(name: "#{parent}.#{tag}", props: attributes, children: children)
         elsif html_element?(tag)
           Element.new(tag: tag, attributes: attributes, children: children)
         else
@@ -834,11 +1200,30 @@ module JsxRosetta
         when "ConditionalExpression" then lower_ternary_expression(expression)
         when "Identifier" then lower_identifier_expression(expression)
         when "CallExpression" then lower_call_expression(expression)
+        when "ArrowFunctionExpression", "FunctionExpression" then lower_render_prop(expression)
         else
           Interpolation.new(expression: source_of(expression))
         end
       end
 
+      # Recognize the render-prop / function-as-children pattern:
+      #   <Form.List>{(fields, helpers) => <div>{fields}</div>}</Form.List>
+      # Returns nil (caller falls back to verbatim interpolation) when the
+      # arrow has zero or too many params, or when the body doesn't lower
+      # cleanly to a JSX child.
+      def lower_render_prop(arrow)
+        params = arrow[:params]
+        return Interpolation.new(expression: source_of(arrow)) if params.size > 4
+        unless params.all? { |p| AST::Node.matches?(p, "Identifier") }
+          return Interpolation.new(expression: source_of(arrow))
+        end
+
+        body = lower_arrow_body(arrow[:body])
+        return Interpolation.new(expression: source_of(arrow)) unless body
+
+        RenderProp.new(params: params.map { |p| p[:name] }, body: body)
+      end
+
       def lower_jsx_comment(empty_expression)
         comments = empty_expression.raw["innerComments"]
         return nil if comments.nil? || comments.empty?
@@ -848,35 +1233,112 @@ module JsxRosetta
 
       def lower_call_expression(expression)
         loop_node = try_lower_map_loop(expression)
-        loop_node || Interpolation.new(expression: source_of(expression))
+        return loop_node if loop_node
+
+        local_call = try_lower_local_arrow_call(expression)
+        return local_call if local_call
+
+        Interpolation.new(expression: source_of(expression))
+      end
+
+      # Recognize `{renderHeader()}` where `renderHeader` is a locally-bound
+      # arrow whose body returns JSX. Extract the arrow as a RenderMethod
+      # on the component and emit a LocalRenderCall at this use site so the
+      # backend can call the generated method instead of dropping the
+      # expression as "[untranslated: renderHeader()]". Args must be simple
+      # identifiers (props, locals) since we don't translate arbitrary
+      # argument expressions here — the backend's ExpressionTranslator
+      # handles them via the Interpolation it sees.
+      def try_lower_local_arrow_call(call_expression)
+        match = local_arrow_call_match(call_expression)
+        return nil unless match
+
+        # Consume the arrow so it doesn't ALSO get promoted to a Stimulus
+        # method if it later appears in event-handler position.
+        @local_arrows.delete(match[:callee_name])
+
+        method_name = unique_render_method_name(match[:callee_name])
+        @render_methods << RenderMethod.new(
+          name: method_name,
+          params: match[:arrow][:params].map { |p| p[:name] },
+          body: match[:body]
+        )
+
+        LocalRenderCall.new(
+          method_name: method_name,
+          args: match[:args].map { |arg| Interpolation.new(expression: source_of(arg)) }
+        )
       end
 
-      # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
-      def try_lower_map_loop(call_expression)
-        callee = call_expression[:callee]
-        return nil unless callee.is_a?(AST::Node) && callee.type == "MemberExpression"
-        return nil unless callee[:property].is_a?(AST::Node) && callee[:property][:name] == "map"
+      def local_arrow_call_match(call_expression)
+        callee = call_expression.child(:callee)
+        return nil unless callee&.of_type?("Identifier")
+
+        arrow = @local_arrows[callee[:name]]
+        return nil unless arrow
+        return nil unless arrow[:params].all? { |p| AST::Node.matches?(p, "Identifier") }
 
         args = call_expression[:arguments]
-        return nil if args.size != 1
-        return nil unless args.first.type == "ArrowFunctionExpression"
+        return nil if args.size != arrow[:params].size
+        return nil unless args.all? { |a| AST::Node.matches?(a, "Identifier", "MemberExpression") }
 
-        arrow = args.first
-        params = arrow[:params]
-        return nil if params.empty? || params.size > 2
-        return nil unless params.all? { |p| p.is_a?(AST::Node) && p.type == "Identifier" }
+        body = lower_lambda_body(arrow[:body])
+        return nil unless body
+
+        { callee_name: callee[:name], arrow: arrow, args: args, body: body }
+      end
+
+      def unique_render_method_name(js_name)
+        snake = AST::Inflector.underscore(js_name)
+        @render_method_seen[snake] ||= 0
+        @render_method_seen[snake] += 1
+        @render_method_seen[snake] == 1 ? snake : "#{snake}_#{@render_method_seen[snake]}"
+      end
+
+      def try_lower_map_loop(call_expression)
+        callee = call_expression.child(:callee)
+        return nil unless callee&.of_type?("MemberExpression")
+
+        property = callee.child(:property)
+        return nil unless property && property[:name] == "map"
+
+        arrow = map_loop_arrow(call_expression[:arguments])
+        return nil unless arrow
 
+        params = arrow[:params]
         body = lower_arrow_body(arrow[:body])
         return nil unless body
 
         Loop.new(
-          iterable: Interpolation.new(expression: source_of(callee[:object])),
+          iterable: lower_loop_iterable(callee[:object]),
           item_binding: params[0][:name],
           index_binding: params[1] && params[1][:name],
           body: body
         )
       end
-      # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+
+      # Recognize ArrayExpression/ObjectExpression iterables so a literal-
+      # rooted `.map(...)` doesn't bail at translation time. Falls back to
+      # the verbatim Interpolation for everything else.
+      def lower_loop_iterable(object)
+        case object.type
+        when "ArrayExpression" then lower_array_literal(object)
+        else Interpolation.new(expression: source_of(object))
+        end
+      end
+
+      def map_loop_arrow(args)
+        return nil if args.size != 1
+
+        arrow = args.first
+        return nil unless AST::Node.matches?(arrow, "ArrowFunctionExpression")
+
+        params = arrow[:params]
+        return nil if params.empty? || params.size > 2
+        return nil unless params.all? { |p| AST::Node.matches?(p, "Identifier") }
+
+        arrow
+      end
 
       def lower_arrow_body(body)
         case body.type
@@ -939,21 +1401,27 @@ module JsxRosetta
         end
       end
 
-      def lower_attribute(attr)
+      def lower_attribute(attr, tag:)
         case attr
         when AST::JSXAttribute
-          lower_jsx_attribute(attr)
+          lower_jsx_attribute(attr, tag: tag)
         when AST::JSXSpreadAttribute
           SpreadAttribute.new(expression: source_of(attr.argument))
         end
       end
 
-      def lower_jsx_attribute(attr)
+      # When the JSX tag is a component (PascalCase or member-expression),
+      # `on*` props are NOT DOM events — they're callback props the receiving
+      # Ruby component decides how to handle. Stimulus action descriptors
+      # only fire on real DOM events, so promoting them would generate
+      # never-firing `data-action="change->foo#h"` markup. Pass through as
+      # a regular component-prop kwarg instead.
+      def lower_jsx_attribute(attr, tag:)
         name = attr.attribute_name
 
         return lower_class_name(attr.value) if name == "className"
         return lower_style_attribute_or_fallback(attr.value) if name == "style"
-        if event_attribute?(name) && attr.value.is_a?(AST::JSXExpressionContainer)
+        if event_attribute?(name) && attr.value.is_a?(AST::JSXExpressionContainer) && html_element?(tag)
           return lower_event_attribute(name, attr.value)
         end
 
@@ -968,7 +1436,7 @@ module JsxRosetta
         return nil unless value.is_a?(AST::JSXExpressionContainer)
 
         expression = value.expression
-        return nil unless expression.is_a?(AST::Node) && expression.type == "ObjectExpression"
+        return nil unless AST::Node.matches?(expression, "ObjectExpression")
 
         declarations = expression[:properties].map { |prop| lower_style_property(prop) }
         return nil if declarations.any?(&:nil?)
@@ -986,21 +1454,33 @@ module JsxRosetta
           end
         return nil if property_name.nil?
 
-        value = lower_style_value(property[:value])
+        value = lower_style_value(property[:value], property_name)
         return nil if value.nil?
 
         StyleDeclaration.new(property: property_name, value: value)
       end
 
-      def lower_style_value(value)
+      def lower_style_value(value, property_name)
         case value.type
         when "StringLiteral" then value[:value]
-        when "NumericLiteral" then value[:value].to_s
+        when "NumericLiteral" then numeric_style_value(value[:value], property_name)
         when "Identifier", "MemberExpression"
           Interpolation.new(expression: source_of(value))
         end
       end
 
+      # Mirrors React's `isUnitlessNumber` table: properties that take bare
+      # numbers (`zIndex: 5`) rather than lengths. Everything else gets a
+      # `px` suffix appended when the JSX source provides a unitless number
+      # — `marginBottom: 16` → `margin-bottom: 16px;`. Without this, the
+      # browser silently ignores the declaration as invalid CSS.
+      def numeric_style_value(number, property_name)
+        return number.to_s if number.zero?
+        return number.to_s if UNITLESS_CSS_PROPERTIES.include?(property_name)
+
+        "#{number}px"
+      end
+
       def css_property_from_camel(name)
         name.gsub(/([a-z\d])([A-Z])/, '\1-\2').downcase
       end
@@ -1014,10 +1494,10 @@ module JsxRosetta
       end
 
       def try_lower_class_helper(expression)
-        return nil unless expression.is_a?(AST::Node) && expression.type == "CallExpression"
+        return nil unless AST::Node.matches?(expression, "CallExpression")
 
-        callee = expression[:callee]
-        return nil unless callee.is_a?(AST::Node) && callee.type == "Identifier"
+        callee = expression.child(:callee)
+        return nil unless callee&.of_type?("Identifier")
         return nil unless %w[cn clsx classnames].include?(callee[:name])
 
         segments = expression[:arguments].flat_map { |arg| lower_class_helper_arg(arg) }
@@ -1069,26 +1549,49 @@ module JsxRosetta
         )
       end
 
+      # Promote a JSX event-handler attribute (`onClick={...}`, `onChange={...}`)
+      # to a Stimulus method binding. Three input shapes are recognized:
+      #   - inline arrow / function expression (`onClick={() => doX()}`)
+      #     → method body is the arrow's body source.
+      #   - identifier referring to a local arrow binding
+      #     (`const h = () => doX(); onClick={h}`) → method body is the
+      #     bound arrow's body. The local arrow is consumed.
+      #   - identifier referring to a prop or external (`onClick={onChange}`)
+      #     → synthesizes a method whose body documents the original
+      #     reference. Without this branch, prop-handler bindings used to
+      #     fall through to an EventBinding that rendered as a broken
+      #     `data-action` (a Ruby reference, not a Stimulus action descriptor).
       def try_promote_to_stimulus(attr_name, event, expression)
-        arrow_node, name_hint = stimulus_arrow_for(expression)
-        return nil unless arrow_node
+        case expression.type
+        when "ArrowFunctionExpression", "FunctionExpression"
+          promote_arrow_to_stimulus(attr_name, event, expression, name_hint: nil)
+        when "Identifier"
+          promote_identifier_event(attr_name, event, expression[:name])
+        end
+      end
 
-        method_name = stimulus_method_name(name_hint || default_stimulus_method_name(attr_name))
+      def promote_arrow_to_stimulus(attr_name, event, arrow_node, name_hint:)
+        base = name_hint || default_stimulus_method_name(attr_name)
+        method_name = stimulus_method_name(base)
         body_source = source_of(arrow_node[:body])
-        @stimulus_methods << StimulusMethod.new(name: method_name, body_source: body_source)
+        @stimulus_methods << StimulusMethod.new(
+          name: method_name, body_source: body_source, original_name: base
+        )
         @local_arrows.delete(name_hint) if name_hint
-
         StimulusBinding.new(event: event, method_name: method_name)
       end
 
-      def stimulus_arrow_for(expression)
-        case expression.type
-        when "ArrowFunctionExpression", "FunctionExpression"
-          [expression, nil]
-        when "Identifier"
-          arrow = @local_arrows[expression[:name]]
-          arrow ? [arrow, expression[:name]] : nil
+      def promote_identifier_event(attr_name, event, identifier_name)
+        if (arrow = @local_arrows[identifier_name])
+          return promote_arrow_to_stimulus(attr_name, event, arrow, name_hint: identifier_name)
         end
+
+        method_name = stimulus_method_name(identifier_name)
+        body_source = "// originally bound to: #{identifier_name}"
+        @stimulus_methods << StimulusMethod.new(
+          name: method_name, body_source: body_source, original_name: identifier_name
+        )
+        StimulusBinding.new(event: event, method_name: method_name)
       end
 
       def default_stimulus_method_name(attr_name)
@@ -1108,12 +1611,86 @@ module JsxRosetta
         when nil
           true
         when AST::JSXExpressionContainer
-          Interpolation.new(expression: source_of(value.expression))
+          lower_value_expression(value.expression)
         else
           value.raw["value"]
         end
       end
 
+      # Recursively lower an arbitrary JS expression into structured IR
+      # when possible: ObjectExpression → ObjectLiteral, ArrayExpression
+      # → ArrayLiteral, ArrowFunctionExpression / FunctionExpression →
+      # Lambda. Everything else falls back to the verbatim Interpolation
+      # so simpler ExpressionTranslator paths still get a crack at it.
+      def lower_value_expression(expression)
+        case expression.type
+        when "ObjectExpression" then lower_object_literal(expression)
+        when "ArrayExpression" then lower_array_literal(expression)
+        when "ArrowFunctionExpression", "FunctionExpression" then lower_value_lambda(expression)
+        else
+          Interpolation.new(expression: source_of(expression))
+        end
+      end
+
+      def lower_object_literal(object_expression)
+        properties = []
+        object_expression[:properties].each do |prop|
+          # Spreads inside object literals, computed keys, getters/setters,
+          # methods — fall back to a verbatim Interpolation since we can't
+          # represent them as a simple key-value pair.
+          return Interpolation.new(expression: source_of(object_expression)) unless prop.type == "ObjectProperty"
+          return Interpolation.new(expression: source_of(object_expression)) if prop.raw["computed"]
+
+          key_name = object_property_key_name(prop[:key])
+          return Interpolation.new(expression: source_of(object_expression)) if key_name.nil?
+
+          properties << [key_name, lower_value_expression(prop[:value])]
+        end
+        ObjectLiteral.new(properties: properties)
+      end
+
+      def object_property_key_name(key_node)
+        case key_node.type
+        when "Identifier" then key_node[:name]
+        when "StringLiteral" then key_node[:value]
+        when "NumericLiteral" then key_node[:value].to_s
+        end
+      end
+
+      def lower_array_literal(array_expression)
+        elements = array_expression[:elements].map do |el|
+          next nil if el.nil? # `[1, , 3]` holes — Ruby has no equivalent
+
+          lower_value_expression(el)
+        end
+        ArrayLiteral.new(elements: elements)
+      end
+
+      def lower_value_lambda(arrow)
+        params = arrow[:params]
+        return Interpolation.new(expression: source_of(arrow)) if params.size > 4
+        unless params.all? { |p| AST::Node.matches?(p, "Identifier") }
+          return Interpolation.new(expression: source_of(arrow))
+        end
+
+        body = lower_lambda_body(arrow[:body])
+        return Interpolation.new(expression: source_of(arrow)) unless body
+
+        Lambda.new(params: params.map { |p| p[:name] }, body: body)
+      end
+
+      def lower_lambda_body(body)
+        return lower_jsx(body) if %w[JSXElement JSXFragment].include?(body.type)
+
+        return unless body.type == "BlockStatement"
+
+        return_stmt = body[:body].find { |s| s.type == "ReturnStatement" }
+        return nil unless return_stmt && return_stmt[:argument]
+
+        arg = return_stmt[:argument]
+        %w[JSXElement JSXFragment].include?(arg.type) ? lower_jsx(arg) : nil
+      end
+
       def style_binding_expression(value)
         case value
         when nil then "true"