jsx_rosetta 0.4.0 → 0.6.0

data/lib/jsx_rosetta/ir/lowering.rb

@@ -2,6 +2,7 @@
 
 require_relative "types"
 require_relative "module_shape_classifier"
+require_relative "../ast/inflector"
 
 module JsxRosetta
   module IR
@@ -54,12 +55,12 @@ module JsxRosetta
         end
       end
 
-      def self.lower(file, source:)
-        new(source).lower_file(file)
+      def self.lower(file, source:, keep_slot: false)
+        new(source, keep_slot: keep_slot).lower_file(file)
       end
 
-      def self.lower_all(file, source:)
-        new(source).lower_all_components(file)
+      def self.lower_all(file, source:, keep_slot: false)
+        new(source, keep_slot: keep_slot).lower_all_components(file)
       end
 
       REACT_HOOKS = %w[
@@ -67,8 +68,53 @@ module JsxRosetta
         useReducer useImperativeHandle useLayoutEffect useDebugValue
       ].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
 
+      # 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?.
       JSX_RETURN_PROBES = {
@@ -80,6 +126,14 @@ module JsxRosetta
         "LogicalExpression" => ->(n) { [n[:left], n[:right]] }
       }.freeze
 
+      # Known wrapper-call names that lowering peers through to find the
+      # inner component definition. Both bare (`memo(...)`) and React-
+      # namespaced (`React.memo(...)`) forms count. Wrappers we don't
+      # unwrap (e.g. `React.lazy` — different shape, no inline function
+      # body) stay off this list on purpose; declarations using them
+      # won't be recognized as components, same as pre-unwrap behavior.
+      HOC_WRAPPER_NAMES = %w[memo forwardRef observer connect withRouter withTranslation].to_set.freeze
+
       SHAPE_MESSAGES = {
         hoc_wrapped: "looks like a HOC-wrapped component (React.memo / forwardRef / lazy / observer) — " \
                      "this version doesn't peel HOC wrappers; remove the wrapper or upgrade when supported",
@@ -100,8 +154,14 @@ module JsxRosetta
         unknown: nil
       }.freeze
 
-      def initialize(source)
+      def initialize(source, keep_slot: false)
         @source = source
+        # When false (default), the shadcn `<Comp asChild>` pattern that
+        # routes through Radix's Slot.Root gets its Slot branch dropped at
+        # lowering time, leaving only the non-Slot HTML/component branch.
+        # When true, preserve the full polymorphic conditional (legacy
+        # behavior; useful if the consumer shims Components::Slot::Root).
+        @keep_slot = keep_slot
         @prop_names = []
         @local_jsx = {}
         @local_bindings = []
@@ -112,6 +172,18 @@ module JsxRosetta
         @stimulus_methods = []
         @stimulus_seen_names = {}
         @react_hooks = []
+        @render_methods = []
+        @render_method_seen = {}
+        # File-level imports; populated once at lower_file / lower_all_components
+        # entry and consulted by JSX lowering to decide whether a member-chain
+        # tag like `SeparatorPrimitive.Root` should resolve through the Radix
+        # registry into an HTML Element.
+        @module_imports = []
+        # 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)
@@ -119,17 +191,63 @@ module JsxRosetta
         raise no_component_error(file.program) if candidates.empty?
 
         name, function = candidates.first
-        module_bindings = capture_module_bindings(file.program, candidates)
-        attach_module_bindings(lower_component(name, function), module_bindings)
+        @module_bindings = capture_module_bindings(file.program, candidates)
+        @module_imports = capture_module_imports(file.program)
+        @server_data_source = capture_server_data_source(file.program)
+        attach_module_metadata(lower_component(name, function),
+                               @module_bindings, @module_imports, @server_data_source)
       end
 
       def lower_all_components(file)
         candidates = find_component_functions(file.program)
         raise no_component_error(file.program) if candidates.empty?
 
-        module_bindings = capture_module_bindings(file.program, candidates)
-        candidates.map do |name, function|
-          attach_module_bindings(lower_component(name, function), module_bindings)
+        @module_bindings = capture_module_bindings(file.program, candidates)
+        @module_imports = capture_module_imports(file.program)
+        @server_data_source = capture_server_data_source(file.program)
+        candidates.each_with_index.map do |(name, function), idx|
+          # Only the first sibling carries the server_data_source — a page
+          # file has at most one such export, and attaching it to every
+          # sibling would duplicate the TODO block across N files.
+          sds = idx.zero? ? @server_data_source : nil
+          attach_module_metadata(lower_component(name, function),
+                                 @module_bindings, @module_imports, sds)
+        end
+      end
+
+      SERVER_DATA_HOOK_NAMES = %w[getServerSideProps getStaticProps].freeze
+
+      # Capture a top-level `export function getServerSideProps()` or
+      # `export const getServerSideProps = ...` (or getStaticProps) so the
+      # Phlex backend can surface the body as a TODO comment block. Returns
+      # nil when no such export is present (the common case for ordinary
+      # components — only Next.js pages have these).
+      def capture_server_data_source(program)
+        program.body.each do |stmt|
+          next unless stmt.of_type?("ExportNamedDeclaration")
+
+          decl = stmt[:declaration]
+          next unless decl.is_a?(AST::Node)
+
+          name = server_data_hook_name(decl)
+          return ServerDataSource.new(hook_name: name, source: source_of(stmt)) if name
+        end
+        nil
+      end
+
+      def server_data_hook_name(decl)
+        case decl.type
+        when "FunctionDeclaration"
+          id = decl[:id]
+          id&.[](:name) if id.is_a?(AST::Node) && SERVER_DATA_HOOK_NAMES.include?(id[:name])
+        when "VariableDeclaration"
+          first = decl[:declarations].first
+          return nil unless first.is_a?(AST::Node)
+
+          id = first[:id]
+          return nil unless id.is_a?(AST::Node) && id.of_type?("Identifier")
+
+          id[:name] if SERVER_DATA_HOOK_NAMES.include?(id[:name])
         end
       end
 
@@ -153,32 +271,300 @@ module JsxRosetta
         case stmt.type
         when "VariableDeclaration"
           stmt[:declarations].each { |d| record_module_binding(stmt, d, component_names, bindings) }
-        when "ExportNamedDeclaration"
+        when "FunctionDeclaration"
+          record_module_function_binding(stmt, component_names, bindings)
+        when "ExportNamedDeclaration", "ExportDefaultDeclaration"
           decl = stmt[:declaration]
           walk_module_binding(decl, component_names, bindings) if decl.is_a?(AST::Node)
         end
       end
 
+      # Top-level `function onError(){}` helpers — non-component, non-hook
+      # functions declared in the same file as the component. Without
+      # capture, a `<Button onClick={onError}>` use site translates to
+      # `on_click: on_error` which NameErrors at render time because
+      # nothing binds `on_error`. Recording the name here threads it into
+      # the translator's bailout set so the reference becomes `on_click: nil`
+      # plus a visible TODO.
+      def record_module_function_binding(stmt, component_names, bindings)
+        name = stmt[:id]&.[](:name)
+        return unless name
+        return if component_names.include?(name)
+
+        bindings << LocalBinding.new(name: name, source: source_of(stmt).strip)
+      end
+
       def record_module_binding(stmt, declarator, component_names, bindings)
         init = declarator[:init]
         return unless init.is_a?(AST::Node)
 
-        # 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))
-
         name = declarator[:id]&.[](:name)
         return unless name
 
+        # Component declarators (`const Foo = () => ...` and the
+        # HOC-wrapped `const Foo = memo(() => ...)` form) are handled by
+        # the component pipeline; skip them here so the source doesn't
+        # surface twice (once as a TODO, once as the class).
+        return if component_names.include?(name)
+
+        # shadcn-style `const fooVariants = cva(base, { variants, ... })` gets
+        # recognized at lowering and stored as a CvaBinding — the backend
+        # turns it into real Ruby constants and the use-site call collapses
+        # to a string interpolation. Falls through to the generic LocalBinding
+        # path when the cva shape doesn't match exactly.
+        if (cva = parse_cva_binding(init, name))
+          bindings << cva
+          return
+        end
+
+        # Literal-shaped `const FOO = "x"` / `const COLUMNS = [...]` /
+        # `const TAGS = {...}` lowers to a real Ruby constant emitted above
+        # the class. Anything richer (call expressions, identifier refs,
+        # JSX) bails to the LocalBinding TODO-block fallback below.
+        if (constant = parse_module_constant(init, name))
+          bindings << constant
+          return
+        end
+
         bindings << LocalBinding.new(name: name, source: source_of(stmt).strip)
       end
 
-      def attach_module_bindings(component, module_bindings)
-        return component if module_bindings.empty?
+      # Returns an IR::ModuleConstant when `init` reduces to a Ruby-literal-
+      # friendly value, or nil otherwise. Anything that depends on runtime
+      # state (call expressions, identifier references, function expressions,
+      # JSX) bails out so the existing LocalBinding TODO path still surfaces
+      # the original JS source.
+      def parse_module_constant(init, name)
+        value = literal_value(init)
+        return nil if value == :__not_literal__
+
+        ModuleConstant.new(
+          name: name,
+          constant_name: AST::Inflector.underscore(name).upcase,
+          value: value
+        )
+      end
+
+      # Returns the Ruby-literal-friendly value for `node`, or the sentinel
+      # `:__not_literal__` when the node isn't translatable. Sentinel rather
+      # than `nil` so a JS `null` (which legitimately maps to Ruby `nil`)
+      # is distinguishable from "couldn't parse this."
+      def literal_value(node)
+        return :__not_literal__ unless node.is_a?(AST::Node)
+
+        case node.type
+        when "StringLiteral", "NumericLiteral", "BooleanLiteral" then node[:value]
+        when "NullLiteral" then nil
+        when "TemplateLiteral" then literal_value_from_template(node)
+        when "ArrayExpression" then literal_value_from_array(node)
+        when "ObjectExpression" then literal_value_from_object(node)
+        when "UnaryExpression" then literal_value_from_unary(node)
+        when "TSAsExpression", "TSSatisfiesExpression", "TSTypeAssertion"
+          literal_value(node[:expression])
+        else :__not_literal__
+        end
+      end
+
+      def literal_value_from_template(node)
+        return :__not_literal__ unless (node[:expressions] || []).empty?
+
+        # `quasi[:value]` is a plain Hash with String keys ("cooked" / "raw"),
+        # not an AST::Node — Babel's AST wraps Hashes only when they carry a
+        # "type" field. Use the String key directly.
+        (node[:quasis] || []).map { |q| q[:value]["cooked"] }.join
+      end
+
+      def literal_value_from_array(node)
+        elements = node[:elements] || []
+        result = []
+        elements.each do |elem|
+          # Holes in array literals (`[1, , 3]`) come through as nil; map to
+          # Ruby `nil` to preserve length. Spread elements bail — we can't
+          # statically expand the spread target.
+          if elem.nil?
+            result << nil
+            next
+          end
+          return :__not_literal__ if elem.is_a?(AST::Node) && elem.type == "SpreadElement"
+
+          value = literal_value(elem)
+          return :__not_literal__ if value == :__not_literal__
+
+          result << value
+        end
+        result
+      end
+
+      def literal_value_from_object(node)
+        properties = node[:properties] || []
+        result = {}
+        properties.each do |prop|
+          return :__not_literal__ unless prop.is_a?(AST::Node) && prop.type == "ObjectProperty"
+          return :__not_literal__ if prop[:computed]
+          return :__not_literal__ if prop[:shorthand] && prop[:value].is_a?(AST::Node) &&
+                                     prop[:value].type == "Identifier"
+
+          key = property_key(prop)
+          return :__not_literal__ unless key.is_a?(String)
+
+          value = literal_value(prop[:value])
+          return :__not_literal__ if value == :__not_literal__
+
+          result[key] = value
+        end
+        result
+      end
+
+      def literal_value_from_unary(node)
+        return :__not_literal__ unless %w[- +].include?(node[:operator])
+
+        inner = literal_value(node[:argument])
+        return :__not_literal__ unless inner.is_a?(Numeric)
+
+        node[:operator] == "-" ? -inner : inner
+      end
+
+      # Returns a CvaBinding when `init` is a `cva(base, options)` call we
+      # know how to parse, or nil to fall through to LocalBinding.
+      def parse_cva_binding(init, name)
+        return nil unless cva_call?(init)
+
+        args = init[:arguments] || []
+        base_class = extract_cva_string(args[0])
+        return nil unless base_class
+
+        options = args[1]
+        return nil unless options.is_a?(AST::Node) && options.type == "ObjectExpression"
+
+        CvaBinding.new(
+          name: name,
+          base_class: base_class,
+          variants: extract_cva_variants(options),
+          default_variants: extract_cva_default_variants(options),
+          compound_source: extract_cva_compound_source(options)
+        )
+      end
+
+      def cva_call?(node)
+        return false unless node.is_a?(AST::Node) && node.type == "CallExpression"
+
+        callee = node[:callee]
+        callee.is_a?(AST::Node) && callee.type == "Identifier" && callee[:name] == "cva"
+      end
+
+      def extract_cva_string(node)
+        return nil unless node.is_a?(AST::Node)
+
+        case node.type
+        when "StringLiteral"
+          node[:value]
+        when "TemplateLiteral"
+          # Only handle templates with no interpolations — they're effectively
+          # a string literal (shadcn's cva bases sometimes use a template for
+          # multi-line readability).
+          return nil unless (node[:expressions] || []).empty?
+
+          (node[:quasis] || []).map { |q| q[:value][:cooked] }.join
+        end
+      end
+
+      def extract_cva_variants(options_node)
+        prop = find_object_property(options_node, "variants")
+        return {} unless object_expression?(prop&.[](:value))
+
+        prop[:value][:properties].each_with_object({}) do |axis, hash|
+          axis_name = property_key(axis)
+          options = extract_cva_axis_options(axis[:value])
+          hash[axis_name] = options if axis_name && !options.empty?
+        end
+      end
+
+      def extract_cva_axis_options(axis_value_node)
+        return {} unless object_expression?(axis_value_node)
+
+        axis_value_node[:properties].each_with_object({}) do |opt, hash|
+          opt_name = property_key(opt)
+          opt_value = extract_cva_string(opt[:value])
+          hash[opt_name] = opt_value if opt_name && opt_value
+        end
+      end
+
+      def object_expression?(node)
+        node.is_a?(AST::Node) && node.type == "ObjectExpression"
+      end
+
+      def extract_cva_default_variants(options_node)
+        prop = find_object_property(options_node, "defaultVariants")
+        return {} unless prop && prop[:value].is_a?(AST::Node) && prop[:value].type == "ObjectExpression"
+
+        prop[:value][:properties].each_with_object({}) do |p, hash|
+          key = property_key(p)
+          val = extract_cva_string(p[:value])
+          hash[key] = val if key && val
+        end
+      end
+
+      def extract_cva_compound_source(options_node)
+        prop = find_object_property(options_node, "compoundVariants")
+        return nil unless prop
 
-        component.with(module_bindings: module_bindings)
+        source_of(prop[:value]).strip
+      end
+
+      def find_object_property(obj_node, name)
+        (obj_node[:properties] || []).find { |p| property_key(p) == name }
+      end
+
+      def property_key(prop)
+        return nil unless prop.is_a?(AST::Node) && prop[:key].is_a?(AST::Node)
+
+        key = prop[:key]
+        case key.type
+        when "Identifier" then key[:name]
+        when "StringLiteral" then key[:value]
+        end
+      end
+
+      def attach_module_metadata(component, module_bindings, module_imports, server_data_source = nil)
+        component.with(
+          module_bindings: module_bindings,
+          module_imports: module_imports,
+          server_data_source: server_data_source
+        )
+      end
+
+      # Capture every top-level `import` declaration so the translator can
+      # recognize use-site references at expression-context. Without this,
+      # an import like `import styles from "./X.module.css"` lets every
+      # `styles.listContainer` use snake-case to a bare `styles` reference
+      # that NameErrors at render time.
+      def capture_module_imports(program)
+        imports = []
+        program.body.each do |stmt|
+          next unless stmt.is_a?(AST::Node) && stmt.type == "ImportDeclaration"
+
+          source = stmt[:source]&.[](:value).to_s
+          (stmt[:specifiers] || []).each do |spec|
+            name = spec[:local]&.[](:name)
+            next unless name
+
+            imports << ModuleImport.new(
+              name: name,
+              source: source,
+              kind: import_specifier_kind(spec),
+              imported_name: spec[:imported]&.[](:name)
+            )
+          end
+        end
+        imports
+      end
+
+      def import_specifier_kind(spec)
+        case spec.type
+        when "ImportDefaultSpecifier" then :default
+        when "ImportNamespaceSpecifier" then :namespace
+        else :named
+        end
       end
 
       private
@@ -210,6 +596,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
@@ -247,6 +634,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
@@ -260,66 +649,366 @@ 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)
+        when "CallExpression" then extract_hoc_default_export(declaration)
         else []
         end
       end
 
+      # `export default memo(function X() {...})` — the declaration is a
+      # CallExpression whose argument is a named FunctionExpression. Peer
+      # through to the inner function and record the wrapper. Anonymous
+      # forms (`export default memo(function () {...})`) get skipped —
+      # `lower_component` rejects anonymous functions and the pre-unwrap
+      # behavior was the same.
+      def extract_hoc_default_export(call_expression)
+        unwrapped = unwrap_hoc(call_expression)
+        return [] unless unwrapped
+
+        inner = unwrapped[:function]
+        name = inner[:id]&.[](:name) if inner.respond_to?(:[])
+        return [] unless name
+
+        record_hoc_wrappers(name, unwrapped[:wrappers])
+        [[name, inner]]
+      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]
           next nil unless init.is_a?(AST::Node)
-          next nil unless %w[ArrowFunctionExpression FunctionExpression].include?(init.type)
 
           name = declarator[:id]&.[](:name)
-          name ? [name, init] : nil
+          next nil unless name
+
+          if %w[ArrowFunctionExpression FunctionExpression].include?(init.type)
+            [name, init]
+          elsif (unwrapped = unwrap_hoc(init))
+            record_hoc_wrappers(name, unwrapped[:wrappers])
+            [name, unwrapped[:function]]
+          end
         end
       end
 
+      # Peer through a CallExpression initializer to find an inline
+      # function/arrow argument that's the real component definition.
+      # Recurses through nested wrappers so `memo(forwardRef(fn))` flattens
+      # to `["memo", "forwardRef"]` + the innermost `fn`. Returns
+      # `{ function: AST, wrappers: [String] }` or nil when no unwrap
+      # applies (the initializer is a CallExpression but doesn't match
+      # a known wrapper shape).
+      def unwrap_hoc(node)
+        wrappers = []
+        current = node
+        while current.is_a?(AST::Node) && current.type == "CallExpression"
+          callee_name = hoc_callee_name(current[:callee])
+          break unless callee_name
+
+          inner = current[:arguments].first
+          break unless inner.is_a?(AST::Node)
+
+          wrappers << callee_name
+          if %w[ArrowFunctionExpression FunctionExpression].include?(inner.type)
+            return { function: inner, wrappers: wrappers }
+          end
+
+          current = inner
+        end
+        nil
+      end
+
+      # Extract the wrapper name from a CallExpression callee. Accepts the
+      # bare form (`memo(...)`) and the React-namespace form (`React.memo(...)`).
+      # Returns the local name ("memo") in both cases so the wrapper TODO
+      # text doesn't have to handle both spellings.
+      def hoc_callee_name(callee)
+        return nil unless callee.is_a?(AST::Node)
+
+        name =
+          case callee.type
+          when "Identifier"
+            callee[:name]
+          when "MemberExpression"
+            object = callee[:object]
+            property = callee[:property]
+            return nil unless object.is_a?(AST::Node) && object.of_type?("Identifier")
+            return nil unless object[:name] == "React"
+            return nil unless property.is_a?(AST::Node) && property.of_type?("Identifier")
+
+            property[:name]
+          end
+        name if name && HOC_WRAPPER_NAMES.include?(name)
+      end
+
+      def record_hoc_wrappers(name, wrappers)
+        @component_hoc_wrappers ||= {}
+        @component_hoc_wrappers[name] = wrappers
+      end
+
       def lower_component(name, function)
         if name.nil? || name.empty?
           raise lowering_error("anonymous component functions are not supported", node: function)
         end
 
-        props, rest_prop_name = lower_params(function[:params])
+        reset_per_component_state!
+        hoc_wrappers = (@component_hoc_wrappers || {})[name] || []
+        # forwardRef's inner function is `(props, ref) => …` — the second
+        # param has no Rails analog, so drop it before lower_params sees
+        # it (otherwise it'd land as a `ref:` ivar with no use site).
+        params_for_lowering = drop_forward_ref_param(function[:params], hoc_wrappers)
+        props, rest_prop_name = lower_params(params_for_lowering)
         @prop_names = props.map(&:name)
-        @local_bindings = []
-        @local_binding_names = []
-        @local_arrows = {}
-        @local_polymorphic_tags = {}
-        @local_destructures = {}
-        @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.uniq,
+          local_binding_names: (@local_binding_names + unconsumed_arrow_names).uniq,
           module_bindings: [],
+          module_imports: [],
           stimulus_methods: @stimulus_methods,
-          react_hooks: @react_hooks
+          react_hooks: @react_hooks,
+          render_methods: @render_methods,
+          mode: mode,
+          server_data_source: nil,
+          hoc_wrappers: hoc_wrappers
         )
       end
 
+      def drop_forward_ref_param(params, wrappers)
+        return params unless wrappers.include?("forwardRef") && params.size > 1
+
+        params[0..-2]
+      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
@@ -347,7 +1036,20 @@ module JsxRosetta
         # `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")
-        Prop.new(name: prop_name, default: default)
+        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)
@@ -614,29 +1316,54 @@ module JsxRosetta
         init = declarator[:init]
         return unless init.is_a?(AST::Node)
 
-        is_hook = hook_call?(init)
-        @react_hooks << ReactHookCall.new(hook: init[:callee][:name], source: source_of(stmt).strip) if is_hook
+        # `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)
 
-        id_node = declarator[:id]
-        if destructure_pattern?(id_node)
-          # Capture destructured names so the ExpressionTranslator recognizes
-          # them as known-local bindings and emits a `nil` placeholder
-          # instead of a bare unresolved reference (which NameErrors at
-          # render time). 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.
-          # Also track member-expression destructures (Gap J) so
-          # `const { Content } = Layout` lets `<Content/>` resolve to
-          # `Layout::Content`.
-          record_destructured_names(stmt, declarator, init: init, seen: seen, is_hook: is_hook)
-          return
-        end
+        library = hook_library_for(init)
+        record_hook_call(stmt, init, library) if library
 
-        return if is_hook
+        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
@@ -717,16 +1444,50 @@ module JsxRosetta
 
       def detect_bare_hook_call(stmt)
         expr = stmt.child(:expression)
-        return unless expr&.of_type?("CallExpression") && hook_call?(expr)
+        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.of_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.child(:callee)
-        callee&.of_type?("Identifier") && REACT_HOOKS.include?(callee[:name])
+        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:
@@ -782,14 +1543,82 @@ module JsxRosetta
           # 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 next_js_layout_yield?(tag, attributes)
+          # `<Component {...pageProps} />` — the canonical Next.js _app
+          # content slot. Lowering to LayoutYield lets the Phlex backend
+          # emit `yield` (Rails layout convention) instead of trying to
+          # render the prop verbatim.
+          LayoutYield.new
         elsif html_element?(tag)
           Element.new(tag: tag, attributes: attributes, children: children)
+        elsif (radix = radix_primitive_for(tag))
+          # `<SeparatorPrimitive.Root .../>` (imported from radix-ui) lowers
+          # to a plain `<div role="separator">` so the consumer doesn't have
+          # to define a Components::SeparatorPrimitive::Root shim.
+          Element.new(
+            tag: radix[:tag],
+            attributes: merge_radix_attrs(radix[:attrs], attributes),
+            children: children
+          )
         else
           ComponentInvocation.new(name: tag, props: attributes, children: children)
         end
       end
 
+      # Returns the Radix registry entry for `<LocalName.Member />` when:
+      #   - the tag is a two-segment member chain
+      #   - the root segment was imported from a Radix-shaped package
+      #   - the (LocalName, Member) pair is in the registry
+      # Otherwise nil — the caller falls through to a ComponentInvocation.
+      def radix_primitive_for(tag)
+        segments = tag.split(".")
+        return nil if segments.length != 2
+
+        local, member = segments
+        return nil unless imported_from_radix?(local)
+
+        RadixRegistry.lookup(local, member)
+      end
+
+      def imported_from_radix?(local_name)
+        @module_imports.any? do |imp|
+          imp.name == local_name && RADIX_SOURCE_PATTERN.match?(imp.source)
+        end
+      end
+
+      # Combine the registry's fixed attrs (role, type, etc.) with the
+      # consumer's own JSX attributes. Consumer attrs win on collision — the
+      # JSX is the source of truth; the registry just supplies safe defaults.
+      # Collision keys normalize away case + hyphens/underscores so future
+      # registry entries like `data-state` don't slip past a consumer's
+      # `dataState`.
+      def merge_radix_attrs(fixed_attrs, jsx_attrs)
+        user_keys = jsx_attrs.filter_map do |a|
+          a.respond_to?(:name) ? normalize_attr_key(a.name) : nil
+        end.to_set
+        injected = fixed_attrs.filter_map do |name, value|
+          attr_name = name.to_s
+          next if user_keys.include?(normalize_attr_key(attr_name))
+
+          Attribute.new(name: attr_name, value: value.to_s)
+        end
+        injected + jsx_attrs
+      end
+
+      def normalize_attr_key(name)
+        name.to_s.downcase.tr("-_", "")
+      end
+
       def lower_polymorphic_tag_use(poly, attributes, children)
+        if (chosen = drop_slot_branch(poly))
+          # The shadcn `<Comp asChild>` pattern routes through Radix's
+          # Slot.Root, which has no Ruby class on the Phlex side. Drop the
+          # Slot branch and render the underlying HTML/component branch
+          # directly. Pass `--keep-slot` to preserve the conditional if
+          # the consumer is shimming Slot::Root themselves.
+          return build_polymorphic_branch(chosen, attributes, children)
+        end
+
         Conditional.new(
           test: Interpolation.new(expression: source_of(poly[:test])),
           consequent: build_polymorphic_branch(poly[:true_branch], attributes, children),
@@ -806,6 +1635,41 @@ module JsxRosetta
         end
       end
 
+      # Returns the non-Slot branch when exactly one of the polymorphic
+      # branches resolves to a Radix Slot reference (`Slot` or `Slot.Root`
+      # rooted at a `radix-ui` import). Returns nil otherwise — including
+      # when `--keep-slot` is in effect — so the caller emits the full
+      # conditional unchanged.
+      def drop_slot_branch(poly)
+        return nil if @keep_slot
+
+        t = poly[:true_branch]
+        f = poly[:false_branch]
+        t_is_slot = radix_slot_branch?(t)
+        f_is_slot = radix_slot_branch?(f)
+        return f if t_is_slot && !f_is_slot
+        return t if f_is_slot && !t_is_slot
+
+        nil
+      end
+
+      # True iff `branch` references a Slot import from a Radix-shaped
+      # package. The local binding is one of {`Slot`, `SlotPrimitive`} —
+      # both correspond to the canonical "import from radix-ui / @radix-ui/
+      # react-slot" pattern. Anything else (e.g. a user-defined
+      # `SlotMachine` from a random package whose path happens to contain
+      # "radix") falls through and renders the conditional unchanged.
+      def radix_slot_branch?(branch)
+        return false unless branch[:kind] == :component
+
+        root = branch[:tag].split(".").first
+        return false unless root && SLOT_LOCAL_NAME_PATTERN.match?(root)
+
+        @module_imports.any? do |imp|
+          imp.name == root && RADIX_SOURCE_PATTERN.match?(imp.source)
+        end
+      end
+
       def lower_jsx_fragment(fragment)
         Fragment.new(children: lower_children(fragment.jsx_children))
       end
@@ -899,7 +1763,66 @@ 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
+
+      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 != arrow[:params].size
+        return nil unless args.all? { |a| AST::Node.matches?(a, "Identifier", "MemberExpression") }
+
+        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)
@@ -1061,21 +1984,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
@@ -1084,10 +2019,116 @@ module JsxRosetta
         if value.is_a?(AST::JSXExpressionContainer)
           decomposed = try_lower_class_helper(value.expression)
           return decomposed if decomposed
+
+          cva_call = try_lower_cva_call_site(value.expression)
+          return cva_call if cva_call
         end
         StyleBinding.new(expression: style_binding_expression(value))
       end
 
+      # Recognize the cva call shape — `cn(<cvaName>({ axes }), <classArg>)`
+      # or the bare `<cvaName>({ axes })` direct form — against a CvaBinding
+      # captured during module-level lowering. Returns an IR::CvaCallSite,
+      # or nil so the caller falls through to the generic StyleBinding.
+      # AST-driven instead of regexing over verbatim source, which lets us
+      # handle reversed-arg `cn(<classArg>, <cvaName>(...))`, the no-cn
+      # direct form, and literal-pinned axes naturally.
+      def try_lower_cva_call_site(expression)
+        return nil unless expression.respond_to?(:type)
+        return nil unless expression.type == "CallExpression"
+
+        callee = expression.child(:callee)
+        return nil unless callee
+
+        if callee.of_type?("Identifier") && %w[cn clsx classnames].include?(callee[:name])
+          build_cva_call_site_from_class_helper(expression[:arguments] || [])
+        else
+          build_cva_call_site_from_direct(expression)
+        end
+      end
+
+      # `cn(<cvaCall>, <classArg>)` or `cn(<classArg>, <cvaCall>)` — accept
+      # the first argument that resolves to a known cva call; the remaining
+      # argument (if any) becomes the optional `class_arg`. Anything more
+      # complex (3+ args, nested cn, multiple cva calls) bails to nil.
+      def build_cva_call_site_from_class_helper(args)
+        return nil unless args.length.between?(1, 2)
+
+        cva_arg_index = args.find_index { |a| cva_call_against_known_binding?(a) }
+        return nil unless cva_arg_index
+
+        cva_arg = args[cva_arg_index]
+        class_arg = args.length == 2 ? args[1 - cva_arg_index] : nil
+        build_cva_call_site_node(cva_arg, class_arg)
+      end
+
+      # Bare `<cvaName>({ axes })` — same shape with no class_arg.
+      def build_cva_call_site_from_direct(expression)
+        return nil unless cva_call_against_known_binding?(expression)
+
+        build_cva_call_site_node(expression, nil)
+      end
+
+      def build_cva_call_site_node(cva_call, class_arg_node)
+        callee_name = cva_call[:callee][:name]
+        options = cva_call[:arguments]&.first
+        return nil unless options && options.type == "ObjectExpression"
+
+        axes = options[:properties].filter_map { |prop| build_cva_axis_pair(prop) }
+        class_arg = class_arg_node && Interpolation.new(expression: source_of(class_arg_node))
+        CvaCallSite.new(binding_name: callee_name, axes: axes, class_arg: class_arg)
+      end
+
+      # Pull one axis-value pair off the cva options object. Shorthand
+      # (`{ variant }`) and explicit (`{ variant: someExpr }`) both work;
+      # spread (`{ ...rest }`) and computed keys bail to nil so the call
+      # site falls through to the generic translator with a TODO.
+      def build_cva_axis_pair(prop)
+        return nil unless prop.type == "ObjectProperty"
+
+        axis = property_key_name(prop)
+        return nil unless axis
+
+        value_node = prop[:value]
+        kind, source = classify_cva_axis_value(value_node)
+        CvaAxisPair.new(axis: axis, kind: kind, source: source)
+      end
+
+      def property_key_name(prop)
+        case prop[:key].type
+        when "Identifier" then prop[:key][:name]
+        when "StringLiteral" then prop[:key][:value]
+        end
+      end
+
+      def classify_cva_axis_value(node)
+        case node.type
+        when "StringLiteral" then [:literal_string, node[:value]]
+        when "NumericLiteral", "BooleanLiteral" then [:literal_other, source_of(node)]
+        when "NullLiteral" then [:literal_nil, nil]
+        when "Identifier"
+          # Shorthand `{ variant }` and explicit `{ variant: ident }` both
+          # land here; the source is the identifier name itself.
+          node[:name] == "undefined" ? [:literal_nil, nil] : [:prop_ref, node[:name]]
+        else
+          # Member chains, calls, etc. — pass the source through as a
+          # raw expression. The backend re-translates it through
+          # ExpressionTranslator like any other prop reference.
+          [:prop_ref, source_of(node)]
+        end
+      end
+
+      def cva_call_against_known_binding?(node)
+        return false unless node.respond_to?(:type)
+        return false unless node.type == "CallExpression"
+
+        callee = node.child(:callee)
+        return false unless callee&.of_type?("Identifier")
+
+        binding_name = callee[:name]
+        @module_bindings.any? { |b| b.is_a?(CvaBinding) && b.name == binding_name }
+      end
+
       def try_lower_class_helper(expression)
         return nil unless AST::Node.matches?(expression, "CallExpression")
 
@@ -1168,9 +2209,18 @@ module JsxRosetta
       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])
+        body_node = arrow_node[:body]
+        body_source = source_of(body_node)
+        # Preserve nil entries for non-Identifier params (ObjectPattern,
+        # ArrayPattern, RestElement) so emit-time bails to TODO rather
+        # than pasting a body that references undefined locals.
+        params = Array(arrow_node[:params]).map { |p| p.type == "Identifier" ? p[:name] : nil }
         @stimulus_methods << StimulusMethod.new(
-          name: method_name, body_source: body_source, original_name: base
+          name: method_name,
+          body_source: body_source,
+          original_name: base,
+          params: params,
+          body_is_block: body_node.type == "BlockStatement"
         )
         @local_arrows.delete(name_hint) if name_hint
         StimulusBinding.new(event: event, method_name: method_name)
@@ -1184,7 +2234,11 @@ module JsxRosetta
         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
+          name: method_name,
+          body_source: body_source,
+          original_name: identifier_name,
+          params: [],
+          body_is_block: false
         )
         StimulusBinding.new(event: event, method_name: method_name)
       end
@@ -1215,18 +2269,39 @@ module JsxRosetta
       # 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.
+      # Lambda, JSXElement / JSXFragment → the same Element / Fragment /
+      # ComponentInvocation that JSX children lower to. 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)
+        when "JSXElement", "JSXFragment" then lower_jsx_value(expression)
         else
           Interpolation.new(expression: source_of(expression))
         end
       end
 
+      # JSX appearing in a non-child position — typically as an attribute
+      # value (`icon={<Foo/>}`, `fallback={<Loading/>}`). Lowered through
+      # the same `lower_jsx` pipeline as children, so the resulting IR
+      # node (Element / ComponentInvocation / Fragment) carries all the
+      # structure the backend can use to emit a real Phlex render call
+      # in place of the old "[untranslated: …]" drop. Single-child
+      # Fragments (`<><Foo/></>`, often emitted by React idioms or as a
+      # workaround for "one node required") collapse to the inner child
+      # so the kwarg value isn't an awkwardly-wrapped Fragment.
+      def lower_jsx_value(expression)
+        lowered = lower_jsx(expression)
+        if lowered.is_a?(Fragment) && lowered.children.length == 1
+          lowered.children.first
+        else
+          lowered
+        end
+      end
+
       def lower_object_literal(object_expression)
         properties = []
         object_expression[:properties].each do |prop|
@@ -1268,10 +2343,16 @@ module JsxRosetta
           return Interpolation.new(expression: source_of(arrow))
         end
 
+        param_names = params.map { |p| p[:name] }
         body = lower_lambda_body(arrow[:body])
-        return Interpolation.new(expression: source_of(arrow)) unless body
+        # JSX-bearing body → render lambda (translated to a Phlex render
+        # method). Non-JSX body → opaque event handler (the body becomes
+        # a verbatim TODO inside a stub method on the class). Without
+        # this fork, every `onClick={() => doX()}` on a PascalCase tag
+        # used to bail to Interpolation and drop with a TODO.
+        return Lambda.new(params: param_names, body: body) if body
 
-        Lambda.new(params: params.map { |p| p[:name] }, body: body)
+        EventHandler.new(params: param_names, body_source: source_of(arrow[:body]))
       end
 
       def lower_lambda_body(body)
@@ -1302,6 +2383,19 @@ module JsxRosetta
         first == first.downcase
       end
 
+      # `<Component {...pageProps} />` — Next.js _app content slot. Tag must
+      # be exactly "Component" and the props must include a spread of
+      # "pageProps". Strict shape match keeps this from false-firing on
+      # ordinary code that happens to render a prop-named `<Component>` —
+      # the `{...pageProps}` spread is the unambiguous Next.js signal.
+      def next_js_layout_yield?(tag, attributes)
+        return false unless tag == "Component"
+
+        attributes.any? do |attr|
+          attr.is_a?(SpreadAttribute) && attr.expression.strip == "pageProps"
+        end
+      end
+
       def source_of(node)
         @source[node.start_pos...node.end_pos]
       end