jsx_rosetta 0.4.0 → 0.6.0

data/lib/jsx_rosetta/backend/phlex.rb

@@ -2,6 +2,7 @@
 
 require_relative "../ast/inflector"
 require_relative "../ir/types"
+require_relative "../pages_routing"
 require_relative "base"
 require_relative "view_component/expression_translator"
 
@@ -31,37 +32,198 @@ module JsxRosetta
       VALID_IDENTIFIER = /\A[a-z_][a-z0-9_]*\z/i
       VOID_ELEMENTS = %w[area base br col embed hr img input link meta param source track wbr].freeze
 
+      # Inline budget for object/array literal rendering. When the
+      # single-line rendering of a literal exceeds this width — measured
+      # from the opening bracket — it switches to a multi-line layout
+      # with one entry per line, indented two spaces past the parent's
+      # line indent. Closing bracket re-aligns to the parent indent.
+      # Chosen to keep typical attr lines under ~120 chars after the
+      # kwarg name and surrounding `render Foo.new(...)` wrapper.
+      LITERAL_INLINE_BUDGET = 80
+
+      # Per-library TODO header lines surfaced above the verbatim hook
+      # source. Each library has a different Rails analog, so we don't
+      # collapse them into a single generic block. Keys must mirror the
+      # `:library` values produced by IR::Lowering.
+      HOOK_TODO_HEADERS = {
+        react: [
+          "TODO: React hooks detected. None translate automatically.",
+          "Hotwire/Stimulus handles behavior; controllers/views handle state;",
+          "turbo-frames handle async loading. Original source:"
+        ].freeze,
+        apollo: [
+          "TODO: Apollo data-fetching hooks detected. None translate automatically.",
+          "Move the fetch to the Rails controller (or a model/service); pass the",
+          "result in as a prop. For useMutation, use a form POST + redirect or a",
+          "Turbo Stream response. Original source:"
+        ].freeze,
+        next_js: [
+          "TODO: Next.js navigation hooks detected. None translate automatically.",
+          "Rails analogs: useRouter -> redirect_to / form actions;",
+          "usePathname -> request.path; useSearchParams / useParams -> params;",
+          "useSelectedLayoutSegment(s) -> match against request.path in the view.",
+          "Original source:"
+        ].freeze
+      }.freeze
+
       # Structured intermediate for the data-action attribute — mirrors the
       # ViewComponent backend pattern (lib/jsx_rosetta/backend/view_component.rb).
       EventDescriptor = Data.define(:kind, :body)
 
-      def initialize(suffix: nil, namespace: nil)
+      RAILS_VIEW_BASE_CLASS = "Views::Base"
+
+      # Per-tag map of which attribute names carry a URL that the href
+      # rewriter should attempt to rewrite. Most link tags use `href`/`to`;
+      # `<form action="...">` uses `action`. Slice C1 added the `form`
+      # entry — non-GET forms are skipped at format_attributes time
+      # before they reach try_rewrite_href.
+      LINK_TAG_ATTRS = {
+        "a" => %w[href].freeze,
+        "Link" => %w[href to].freeze,
+        "NavLink" => %w[href to].freeze,
+        "RouterLink" => %w[href to].freeze,
+        "form" => %w[action].freeze
+      }.freeze
+      # Matches `router.push("…")` / `router.push('…')` / `router.push(\`…\`)`
+      # in verbatim hook source, capturing the quoted argument (including the
+      # surrounding quote/backtick). A3: only fires for sync hook bodies —
+      # event-handler bodies live in IR::EventHandler / IR::StimulusMethod
+      # sources, not in react_hooks, so they're naturally out of scope.
+      ROUTER_PUSH_PATTERN = /router\.push\(\s*("(?:[^"\\]|\\.)*"|'(?:[^'\\]|\\.)*'|`(?:[^`\\]|\\.)*`)\s*[,)]/
+
+      # Per-wrapper TODO header text. Each HOC that lowering peeled off the
+      # source (recorded on IR::Component#hoc_wrappers) gets one short line
+      # above the class explaining the Rails analog. Falls back to a
+      # generic line for wrappers not in this map.
+      HOC_WRAPPER_TODO_LINES = {
+        "memo" => "TODO: original component was wrapped in memo(...). React's memo memoizes " \
+                  "by shallow prop equality. Rails analog: fragment caching (`cache @model do …`) " \
+                  "when the view is expensive.",
+        "forwardRef" => "TODO: original component was wrapped in forwardRef(...). The second " \
+                        "arg (`ref`) was dropped — Rails has no view-side ref-forwarding analog; " \
+                        "use Stimulus targets / DOM ids if the host needs a handle.",
+        "observer" => "TODO: original component was wrapped in observer(...) (mobx). React's " \
+                      "observer auto-subscribes to observable state. Rails analog: the controller " \
+                      "loads data and sets @ivars; reactivity moves to Turbo Streams / Hotwire.",
+        "connect" => "TODO: original component was wrapped in connect(...)(X) (redux). Props " \
+                     "injected by mapState/mapDispatch in the source — in Rails, expect those as " \
+                     "controller-passed instance variables instead.",
+        "withRouter" => "TODO: original component was wrapped in withRouter(...) (React Router). " \
+                        "Injected router props (location, history, match) map to Rails: request.path, " \
+                        "redirect_to / form actions, and params.",
+        "withTranslation" => "TODO: original component was wrapped in withTranslation()(X) (i18n). " \
+                             "Injected `t` translator function maps to Rails I18n: `I18n.t(\"…\")` " \
+                             "or the `t` view helper."
+      }.freeze
+
+      def initialize(suffix: nil, namespace: nil, rails_view: nil, route_table: nil)
         super()
         raise ArgumentError, "Phlex backend: pass either suffix: or namespace:, not both" if suffix && namespace
+        if rails_view && (suffix || namespace)
+          raise ArgumentError, "Phlex backend: rails_view: cannot be combined with suffix: or namespace:"
+        end
 
         @suffix = suffix.is_a?(String) ? suffix : (DEFAULT_SUFFIX if suffix == true)
         @namespace = namespace
+        @rails_view = rails_view
+        @href_rewriter = route_table && PagesRouting::HrefRewriter.new(route_table)
       end
 
-      def emit(component)
-        prop_names = component.props.map(&:name)
-        prop_names << component.rest_prop_name if component.rest_prop_name
-        translator = ViewComponent::ExpressionTranslator.new(
-          prop_names: prop_names, local_binding_names: component.local_binding_names
-        )
-
+      def emit(component, source_filename: nil)
+        @current_component = component
+        translator = build_translator(component)
         @stimulus_identifier = component.stimulus_methods.any? ? stimulus_identifier(component) : nil
         @lambda_methods = []
         @lambda_method_counts = {}
+        @event_handler_methods = []
+        @emit_module_prefix = first_emit_for_module_bindings?(component)
+        @source_filename = source_filename
 
-        files = [File.new(path: ruby_path(component), contents: render_ruby_class(component, translator))]
+        files = [File.new(path: ruby_path(component), contents: clean_output(render_ruby_class(component, translator)))]
         if component.stimulus_methods.any?
           files << File.new(
             path: stimulus_path(component),
             contents: render_stimulus_controller_js(component)
           )
         end
+        files.concat(lucide_icon_files(component))
         files
+      ensure
+        # Drop the per-emit IR reference so a long-running emitter
+        # instance doesn't pin the entire component tree until the
+        # next emit() call.
+        @current_component = nil
+      end
+
+      # When a source file lowers to multiple sibling components, lower_all
+      # attaches the *same* module_bindings array to every sibling. Emitting
+      # the constants TODO block on each one duplicates 40-line GraphQL
+      # blocks across every emitted .rb file. Track the array identities
+      # we've seen and only emit the prefix the first time.
+      def first_emit_for_module_bindings?(component)
+        return true if component.module_bindings.empty?
+
+        @seen_module_bindings ||= Set.new
+        key = component.module_bindings.object_id
+        return false if @seen_module_bindings.include?(key)
+
+        @seen_module_bindings << key
+        true
+      end
+
+      def build_translator(component)
+        prop_names = component.props.map(&:name)
+        prop_names << component.rest_prop_name if component.rest_prop_name
+        prop_aliases = component.props.each_with_object({}) do |prop, hash|
+          hash[prop.alias_name] = prop.name if prop.alias_name
+        end
+        # `imported_names` covers both top-level `import` declarations AND
+        # top-level helper bindings (`function onError(){}`, `const FOO = …`).
+        # They behave identically at the use site — the translator bails out
+        # to `nil` rather than emitting a bare snake_case ref that NameErrors.
+        ViewComponent::ExpressionTranslator.new(
+          prop_names: prop_names,
+          local_binding_names: component.local_binding_names,
+          prop_aliases: prop_aliases,
+          imported_names: component.module_imports.map(&:name) + component.module_bindings.map(&:name)
+        )
+      end
+
+      # Strip trailing whitespace from each emitted line — easier than
+      # threading rstrip through every formatting helper, and a single
+      # source of truth keeps Layout/TrailingWhitespace at zero. Preserve
+      # the trailing newline of the file as-is. Also suppresses the
+      # intentional-`if false` cops file-wide so the user's rubocop
+      # doesn't drown out actionable findings.
+      def clean_output(source)
+        cleaned = "#{source.split("\n").map(&:rstrip).join("\n")}\n".sub(/\n\n+\z/, "\n")
+        suppress_intentional_if_false_cops(cleaned)
+      end
+
+      # When the file contains any `if false` / `elsif false` branch (the
+      # fallback we emit when a JSX condition can't be translated to Ruby),
+      # disable the cops that flag those at file scope. The corresponding
+      # `# TODO: translate condition:` comment already names the issue, so
+      # the cop's report is redundant noise. Only emits when needed.
+      def suppress_intentional_if_false_cops(source)
+        cops = []
+        cops << "Lint/LiteralAsCondition" if source.match?(/^\s*(?:if|elsif) false$/m)
+        # An elsif-false adjacent to its leading `if false` is the only
+        # configuration that triggers DuplicateElsifCondition — multiple
+        # `if false`s in separate scopes don't qualify. The pattern below
+        # matches an `if false` directly followed (after consequent lines)
+        # by an `elsif false` at the same indent.
+        cops << "Lint/DuplicateElsifCondition" if source.match?(/^(\s*)if false\b[\s\S]*?^\1elsif false\b/m)
+        return source if cops.empty?
+
+        disable = "# rubocop:disable #{cops.join(", ")}\n\n"
+        enable = "# rubocop:enable #{cops.join(", ")}\n"
+        # Magic comment must be followed by a blank line before any other
+        # comment (Layout/EmptyLineAfterMagicComment), and every file-level
+        # disable needs a matching enable (Lint/MissingCopEnableDirective).
+        with_disable = source.sub(/^# frozen_string_literal: true\n\n/,
+                                  "# frozen_string_literal: true\n\n#{disable}")
+        "#{with_disable.chomp}\n#{enable}"
       end
 
       private
@@ -72,42 +234,234 @@ module JsxRosetta
       # letter when forming the class name. Pure-PascalCase names pass
       # through unchanged.
       def class_name(component)
+        return rails_view_class_name if @rails_view
+
         base = "#{component.name[0].upcase}#{component.name[1..]}"
-        @suffix ? "#{base}#{@suffix}" : base
+        suffix = effective_suffix_for(base, source_filename: @source_filename)
+        suffix ? "#{base}#{suffix}" : base
+      end
+
+      def rails_view_class_name
+        return rails_layout_class_name if @rails_view.kind == :layout
+
+        namespace_parts = (@rails_view.namespace || []).map { |ns| AST::Inflector.upper_camelize(ns) }
+        controller = AST::Inflector.upper_camelize(@rails_view.controller)
+        action = AST::Inflector.upper_camelize(@rails_view.action)
+        (["Views"] + namespace_parts + [controller, action]).join("::")
+      end
+
+      # Layouts land under Views::Layouts:: regardless of source path —
+      # `_app.tsx` → Views::Layouts::Application. There's only ever one
+      # "controller" for layouts (`layouts`), so the controller segment
+      # is collapsed into the namespace.
+      def rails_layout_class_name
+        action = AST::Inflector.upper_camelize(@rails_view.action)
+        "Views::Layouts::#{action}"
+      end
+
+      def parent_class
+        @rails_view ? RAILS_VIEW_BASE_CLASS : PHLEX_BASE_CLASS
+      end
+
+      # Pick the suffix to append to a class name, applying two rules in
+      # order:
+      #
+      # 1. **Page detection.** Source name ends in `Page` OR the source
+      #    file path contains `/pages/` (Next.js / Nuxt convention) →
+      #    use the literal `Page` suffix, regardless of the configured
+      #    `@suffix`. Lets the gem keep `<HomePage>` / `pages/home.tsx`
+      #    landing as `HomePage` / `home_page.rb` even when the user
+      #    passes `--phlex-suffix=Component` for the rest of the codebase.
+      # 2. **No double-suffix.** When the name already ends with the
+      #    chosen suffix (e.g. source `HomePage` with the `Page` suffix,
+      #    or source `FooComponent` with the `Component` suffix), skip
+      #    the append. Returns nil so callers don't concatenate.
+      #
+      # `source_filename` is the absolute or repo-relative path of the
+      # JSX source; nil when callers translate raw source strings
+      # without filename context (then only the name-based signal fires).
+      def effective_suffix_for(name, source_filename: nil)
+        suffix = page?(name, source_filename) ? "Page" : @suffix
+        return nil unless suffix
+        return nil if name.end_with?(suffix)
+
+        suffix
+      end
+
+      def page?(name, source_filename)
+        return true if name.end_with?("Page")
+        return false unless source_filename
+
+        source_filename.include?("/pages/")
       end
 
       def ruby_path(component)
+        return "#{rails_view_dir}/#{@rails_view.action}.rb" if @rails_view
+
         "#{AST::Inflector.underscore(class_name(component))}.rb"
       end
 
       def stimulus_path(component)
+        return "#{rails_view_dir}/#{@rails_view.action}_controller.js" if @rails_view
+
         "#{AST::Inflector.underscore(class_name(component))}_controller.js"
       end
 
+      def rails_view_dir
+        ((@rails_view.namespace || []) + [@rails_view.controller]).join("/")
+      end
+
       def stimulus_identifier(component)
         AST::Inflector.underscore(component.name).tr("_", "-")
       end
 
       def render_ruby_class(component, translator)
         class_body = render_class_body(component, translator)
-        prefix = render_module_bindings_prefix(component)
+        prefix = "#{render_hoc_wrappers_prefix(component)}" \
+                 "#{render_server_data_source_prefix(component)}" \
+                 "#{render_module_bindings_prefix(component)}"
         wrap_in_namespace("#{prefix}#{class_body}")
       end
 
+      def render_hoc_wrappers_prefix(component)
+        return "" if component.hoc_wrappers.empty?
+
+        lines = component.hoc_wrappers.map do |wrapper|
+          "# #{HOC_WRAPPER_TODO_LINES[wrapper] ||
+               "TODO: original component was wrapped in #{wrapper}(...). " \
+               "Verify the Rails-side equivalent (or absence) and adjust before shipping."}"
+        end
+        "#{lines.join("\n")}\n"
+      end
+
+      # When the source file exports `getServerSideProps` /
+      # `getStaticProps`, emit a TODO block above the class with the
+      # body verbatim. The block names the matching Rails controller
+      # action when `@rails_view` is set; otherwise it points at "the
+      # host controller" generically.
+      def render_server_data_source_prefix(component)
+        return "" unless component.server_data_source
+
+        sds = component.server_data_source
+        target = if @rails_view
+                   "#{AST::Inflector.upper_camelize(@rails_view.controller)}Controller##{@rails_view.action}"
+                 else
+                   "the host controller action"
+                 end
+        body_lines = comment_lines(sds.source)
+        lines = [
+          "# TODO: port the original Next.js `#{sds.hook_name}` to #{target}:",
+          "#",
+          *body_lines,
+          "#",
+          "# In Rails: load the data in the controller (set @ivars), and read",
+          "# them in this view via the standard props plumbing."
+        ]
+        "#{lines.join("\n")}\n"
+      end
+
       # Top-level `const`/`let` declarations outside the component
-      # function — captured at lowering time and surfaced here as a TODO
-      # comment block above the class definition. We don't try to
-      # translate the JS; the human reviewer either copies the value as
-      # a Ruby constant or moves it to a Rails initializer.
+      # function — captured at lowering time. Cva-shaped bindings get
+      # emitted as real Ruby constants (FOO_BASE_CLASS, etc.); generic
+      # local bindings still surface as a TODO comment block.
       def render_module_bindings_prefix(component)
         return "" if component.module_bindings.empty?
 
+        groups = component.module_bindings.group_by { |b| binding_group(b) }
+        cva_bindings = groups[:cva] || []
+        module_constants = groups[:module_constant] || []
+        other_bindings = groups[:other] || []
+        sections = []
+        # cva constants are *referenced* by every sibling's class body via
+        # FOO_BASE_CLASS / FOO_VARIANT_CLASSES — they have to land in every
+        # sibling's file or non-first siblings NameError at render. The
+        # non-cva TODO block is informational only, so it suppresses on
+        # later siblings to avoid duplicating 40-line GraphQL blocks.
+        sections << render_cva_constants(cva_bindings) unless cva_bindings.empty?
+        sections << render_module_constants(module_constants) unless module_constants.empty?
+        emit_todo_block = @emit_module_prefix && !other_bindings.empty?
+        sections << render_module_local_bindings_todo(other_bindings) if emit_todo_block
+        sections.compact.join("\n")
+      end
+
+      def binding_group(binding)
+        case binding
+        when IR::CvaBinding then :cva
+        when IR::ModuleConstant then :module_constant
+        else :other
+        end
+      end
+
+      # Emit each literal-shaped module-level const as a real Ruby constant.
+      # Hash and array values are emitted via Ruby's `inspect` and frozen so
+      # accidental mutation surfaces immediately. Scalars (string / number /
+      # bool / nil) skip the `.freeze` since they're already immutable in
+      # Ruby — keeps the output terse for the common `const TITLE = "X"` case.
+      def render_module_constants(constants)
+        lines = constants.map do |constant|
+          literal = constant.value.inspect
+          literal += ".freeze" if constant.value.is_a?(Hash) || constant.value.is_a?(Array) ||
+                                  constant.value.is_a?(String)
+          "#{constant.constant_name} = #{literal}"
+        end
+        "#{lines.join("\n")}\n"
+      end
+
+      # Emit one cva binding as a triplet of Ruby constants —
+      # FOO_BASE_CLASS, FOO_VARIANT_CLASSES, FOO_DEFAULT_VARIANTS — that
+      # the call-site interpolation in the class body references.
+      def render_cva_constants(cva_bindings)
+        lines = []
+        cva_bindings.each do |cva|
+          prefix = cva_constant_prefix(cva.name)
+          lines << "#{prefix}_BASE_CLASS = #{cva.base_class.inspect}"
+          lines << "#{prefix}_VARIANT_CLASSES = #{format_variants_literal(cva.variants)}.freeze"
+          unless cva.default_variants.empty?
+            lines << "#{prefix}_DEFAULT_VARIANTS = #{cva.default_variants.inspect}.freeze"
+          end
+          if cva.compound_source
+            lines << "# TODO: compoundVariants from #{cva.name} aren't translated — port by hand:"
+            lines.concat(comment_lines(cva.compound_source))
+          end
+          lines << ""
+        end
+        "#{lines.join("\n").rstrip}\n"
+      end
+
+      # Non-cva module bindings — the original Gap E pre-class TODO block.
+      # Distinct from the body-level `render_local_bindings_todo` further
+      # below in this file.
+      def render_module_local_bindings_todo(bindings)
         lines = ["# TODO: module-level constants — translate to Ruby constants " \
                  "or move to a Rails initializer:"]
-        component.module_bindings.each { |b| lines.concat(comment_lines(b.source)) }
+        bindings.each { |b| lines.concat(comment_lines(b.source)) }
         "#{lines.join("\n")}\n"
       end
 
+      # buttonVariants → BUTTON, alertVariants → ALERT. The degenerate
+      # name `"Variants"` would strip to `""` (a Ruby SyntaxError when
+      # used as a `_BASE_CLASS` prefix) — fall back to the raw name in
+      # that case. Two cva bindings whose names collapse to the same
+      # prefix (`fooVariant` and `fooVariants` → `FOO`) keep both forms
+      # disambiguated by upcasing the unstripped name as the fallback.
+      def cva_constant_prefix(cva_name)
+        stripped = cva_name.sub(/Variants?\z/, "")
+        base = stripped.empty? ? cva_name : stripped
+        AST::Inflector.underscore(base).upcase
+      end
+
+      def format_variants_literal(variants)
+        return "{}" if variants.empty?
+
+        lines = ["{"]
+        variants.each do |axis, options|
+          opts_pairs = options.map { |k, v| "#{k.inspect} => #{v.inspect}" }.join(", ")
+          lines << "  #{axis.inspect} => { #{opts_pairs} },"
+        end
+        lines << "}"
+        lines.join("\n")
+      end
+
       def wrap_in_namespace(body)
         return "# frozen_string_literal: true\n\n#{body}" unless @namespace
 
@@ -117,22 +471,98 @@ module JsxRosetta
 
       def render_class_body(component, translator)
         initializer = render_initializer(component, translator)
-        template = render_view_template(component, translator)
-        # Render lambdas only AFTER the template — `@lambda_methods` is
-        # populated as attribute values are rendered.
-        lambda_methods = render_lambda_method_definitions(translator)
-
-        sections = [initializer, template, lambda_methods].compact.join("\n\n")
-        "class #{class_name(component)} < #{PHLEX_BASE_CLASS}\n#{sections}\nend\n"
+        template = if component.mode == :data_factory
+                     render_data_factory_method(component, translator)
+                   else
+                     render_view_template(component, translator)
+                   end
+        # Render private methods (render_methods + lambdas) AFTER the
+        # template — `@lambda_methods` is populated during attribute-value
+        # rendering, and render_methods bodies share the same indent.
+        private_section = render_private_methods(component, translator)
+
+        sections = [initializer, template, private_section].compact.join("\n\n")
+        cls = class_name(component)
+        # One-line docstring above the class — pacifies Style/Documentation
+        # without forcing the host project to disable the cop globally. The
+        # body is intentionally minimal so it doesn't drift from the source
+        # over time; a richer comment belongs in the host repo's review.
+        "# #{cls} — generated by jsx_rosetta from JSX. Review before shipping.\n" \
+          "class #{cls} < #{parent_class}\n#{sections}\nend\n"
+      end
+
+      # For data-factory components (`export const createColumns = (args)
+      # => [{...}, {...}]`) emit a public method that returns the
+      # translated data array. The method name is the snake_case of the
+      # original JS identifier (`createColumns` → `create_columns`).
+      # Param names come from the regular `props:` list so callers can
+      # invoke with keyword arguments matching the JS signature.
+      def render_data_factory_method(component, translator)
+        method_name = AST::Inflector.underscore(component.name)
+        param_names = component.props.map(&:name)
+        signature = data_factory_signature(method_name, param_names)
+        # Param refs translate as locals (`token`) inside the body rather
+        # than as ivars (`@token`) — the factory params are method-local,
+        # not constructor-stored. `with_locals` pushes the JS names onto
+        # the translator's local stack for the duration of the body.
+        body = translator.with_locals(param_names) do
+          render_inline_value(component.body, translator, todos: [], attr_name: nil, indent: 4)
+        end
+        "  def #{signature}\n    #{body}\n  end"
       end
 
-      def render_lambda_method_definitions(translator)
-        return nil if @lambda_methods.nil? || @lambda_methods.empty?
+      def data_factory_signature(method_name, param_names)
+        return method_name if param_names.empty?
 
-        defs = @lambda_methods.map do |entry|
+        kwargs = param_names.map { |name| "#{AST::Inflector.underscore(name)}: nil" }
+        "#{method_name}(#{kwargs.join(", ")})"
+      end
+
+      # Coalesce RenderMethod (from local-arrow extraction) and Lambda
+      # (from Gap H object-literal extraction) into one `private` section.
+      # Emitting `private` twice is harmless but ugly; one block reads
+      # cleaner.
+      def render_private_methods(component, translator)
+        render_methods = component.render_methods.map { |rm| render_render_method_definition(rm, translator) }
+        lambda_methods = (@lambda_methods || []).map do |entry|
           render_lambda_method_definition(entry[:method_name], entry[:lambda], translator)
         end
-        "  private\n\n#{defs.join("\n\n")}"
+        event_handlers = (@event_handler_methods || []).map do |entry|
+          render_event_handler_method_definition(entry[:method_name], entry[:handler], entry[:attr_name])
+        end
+        all = render_methods + lambda_methods + event_handlers
+        return nil if all.empty?
+
+        "  private\n\n#{all.join("\n\n")}"
+      end
+
+      # Emit one EventHandler as a stub method on the class. The JS body
+      # is preserved verbatim as a TODO comment; the method itself is a
+      # no-op so the file loads and the receiving component sees a real
+      # `Method` object via `method(:name)`. Parameter names snake_case
+      # from JS conventions to Ruby identifiers.
+      def render_event_handler_method_definition(method_name, handler, attr_name)
+        snake_params = handler.params.map { |p| AST::Inflector.underscore(p) }
+        signature = snake_params.empty? ? method_name : "#{method_name}(#{snake_params.join(", ")})"
+        body_lines = comment_lines(handler.body_source).map { |l| "    #{l}" }
+        [
+          "  def #{signature}",
+          "    # TODO: translate the original JSX `#{attr_name}` handler:",
+          *body_lines,
+          "  end"
+        ].join("\n")
+      end
+
+      # Emit one RenderMethod as a private method on the class. Params are
+      # pushed into the translator scope so identifier references inside
+      # the body resolve to method-local arguments.
+      def render_render_method_definition(render_method, translator)
+        snake_params = render_method.params.map { |p| AST::Inflector.underscore(p) }
+        signature = snake_params.empty? ? render_method.name : "#{render_method.name}(#{snake_params.join(", ")})"
+        body = translator.with_locals(render_method.params) do
+          render_ir_node(render_method.body, translator, indent: 4)
+        end
+        "  def #{signature}\n#{body}\n  end"
       end
 
       def render_lambda_method_definition(method_name, lambda, translator)
@@ -145,20 +575,30 @@ module JsxRosetta
       end
 
       def render_initializer(component, translator)
+        # Data-factory components consume their params as method args, not
+        # as constructor props — skip the initializer entirely.
+        return nil if component.mode == :data_factory
+
         props = initializable_props(component)
         rest_name = component.rest_prop_name
         return nil if props.empty? && rest_name.nil?
 
+        # Snake-case the rest-name kwarg so it matches the snake_case ivar
+        # the body uses (`**(@description_props || {})`). Emitting the
+        # camelCase JS name straight to the kwarg would create a different
+        # ivar than the body reads, silently dropping the splat's contents.
+        rest_snake = rest_name && AST::Inflector.underscore(rest_name)
         kwargs = props.map { |prop| ruby_kwarg(prop, translator) }
-        kwargs << "**#{rest_name}" if rest_name
+        kwargs << "**#{rest_snake}" if rest_snake
 
-        assignments = props.map do |prop|
+        body = ["    super()"]
+        body.concat(props.map do |prop|
           snake = AST::Inflector.underscore(prop.name)
           "    @#{snake} = #{snake}"
-        end
-        assignments << "    @#{rest_name} = #{rest_name}" if rest_name
+        end)
+        body << "    @#{rest_snake} = #{rest_snake}" if rest_snake
 
-        "  def initialize(#{kwargs.join(", ")})\n#{assignments.join("\n")}\n  end"
+        "  def initialize(#{kwargs.join(", ")})\n#{body.join("\n")}\n  end"
       end
 
       def initializable_props(component)
@@ -172,6 +612,15 @@ module JsxRosetta
       end
 
       def ruby_default_for(prop, translator)
+        # Use the cva defaultVariants entry as the initializer default when
+        # the prop name matches a cva axis and the JSX didn't already
+        # specify its own default. So `variant: 'default'` flows from the
+        # cva binding's defaultVariants, even though the React function
+        # signature took it as an undefaulted prop.
+        if prop.default.nil? && (cva_default = cva_axis_default_for(prop.name))
+          return cva_default.inspect
+        end
+
         return "nil" if prop.default.nil?
 
         case prop.default
@@ -179,43 +628,117 @@ module JsxRosetta
           translated = translator.translate(prop.default.expression)
           translated ? translated.ruby : "nil"
         when IR::ObjectLiteral, IR::ArrayLiteral, IR::Lambda
-          # Inline values: route through the recursive renderer. Pass an
-          # empty todos array — TODO markers wouldn't be safe inside a
-          # parameter-list anyway.
-          render_inline_value(prop.default, translator, todos: [], attr_name: prop.name)
+          # Inline values: route through the recursive renderer with
+          # `force_inline: true`. A wrapped multi-line default inside the
+          # `initialize(...)` parameter list would put the `{` at one
+          # column and the children at the indent-aligned column —
+          # legal Ruby but trips Layout/FirstHashElementIndentation. Empty
+          # todos array — TODO markers wouldn't survive a parameter list.
+          render_inline_value(prop.default, translator, todos: [], attr_name: prop.name, force_inline: true)
         else
           "nil"
         end
       end
 
+      # Look up `prop_name` (e.g. "variant") across every CvaBinding on the
+      # current component. Returns the cva default value (e.g. "default") or
+      # nil when no cva binding declares that axis with a default.
+      def cva_axis_default_for(prop_name)
+        return nil unless @current_component
+
+        @current_component.module_bindings.each do |b|
+          next unless b.is_a?(IR::CvaBinding)
+          next unless b.default_variants.key?(prop_name)
+
+          return b.default_variants[prop_name]
+        end
+        nil
+      end
+
       def render_view_template(component, translator)
         body = render_template_body(component, translator)
-        prefix = render_template_prefix(component)
+        prefix = render_template_prefix(component, translator)
         body_with_prefix = prefix.empty? ? body : "#{prefix}#{body}"
         "  def view_template\n#{body_with_prefix}\n  end"
       end
 
-      def render_template_prefix(component)
+      def render_template_prefix(component, translator)
         lines = []
-        lines.concat(render_react_hooks_todo(component.react_hooks))
+        lines.concat(render_react_hooks_todo(component.react_hooks, translator))
         lines.concat(render_local_bindings_todo(component.local_bindings))
         return "" if lines.empty?
 
         "#{lines.map { |l| "    #{l}" }.join("\n")}\n"
       end
 
-      def render_react_hooks_todo(hooks)
+      def render_react_hooks_todo(hooks, translator)
         return [] if hooks.empty?
 
-        lines = [
-          "# TODO: React hooks detected. None translate automatically.",
-          "# Hotwire/Stimulus handles behavior; controllers/views handle state;",
-          "# turbo-frames handle async loading. Original source:"
-        ]
-        hooks.each { |hook| lines.concat(comment_lines(hook.source)) }
+        # Preserve the source order of the first occurrence per library so
+        # the React block (typical) lands before Apollo/Next.js blocks when
+        # all three are present. group_by preserves first-seen order.
+        hooks.group_by(&:library).flat_map { |library, calls| hook_todo_block_lines(library, calls, translator) }
+      end
+
+      def hook_todo_block_lines(library, calls, translator)
+        header_lines = HOOK_TODO_HEADERS.fetch(library, HOOK_TODO_HEADERS[:react])
+        lines = header_lines.map { |line| "# #{line}" }
+        calls.each do |call|
+          lines.concat(router_push_hint_lines(call.source, translator))
+          lines << "#   operation: #{call.operation}" if call.operation
+          lines.concat(comment_lines(call.source))
+        end
         lines
       end
 
+      # Scan a hook's verbatim source for `router.push("…")` invocations and
+      # emit a one-line hint per match. With a route table the hint names
+      # the matching URL helper (`redirect_to user_path(@id)`); without one,
+      # it suggests adding the helper. See ROUTER_PUSH_PATTERN for the
+      # accepted shapes and why event-handler bodies are out of scope.
+      def router_push_hint_lines(source, translator)
+        source.scan(ROUTER_PUSH_PATTERN).flat_map do |(arg)|
+          hint = router_push_hint(arg, translator)
+          hint ? ["# #{hint}"] : []
+        end
+      end
+
+      def router_push_hint(arg, translator)
+        if arg.start_with?("`")
+          template_router_push_hint(arg, translator)
+        else
+          path = arg[1..-2]
+          literal_router_push_hint(path)
+        end
+      end
+
+      def literal_router_push_hint(path)
+        helper = @href_rewriter&.rewrite_literal(path)
+        return "→ redirect_to #{helper} (translated from router.push(#{path.inspect}))" if helper
+
+        "→ consider redirect_to <helper> for router.push(#{path.inspect}) (not in route table)"
+      end
+
+      def template_router_push_hint(template_src, translator)
+        segments = PagesRouting::HrefRewriter.parse_template_source(template_src)
+        return "→ consider redirect_to <helper> for router.push(#{template_src})" unless segments
+
+        translated = segments.map { |kind, value| kind == :hole ? translate_hole(value, translator) : [kind, value] }
+        return "→ consider redirect_to <helper> for router.push(#{template_src})" if translated.any?(&:nil?)
+
+        helper = @href_rewriter&.rewrite_template(translated)
+        return "→ redirect_to #{helper} (translated from router.push(#{template_src}))" if helper
+
+        "→ consider redirect_to <helper> for router.push(#{template_src}) (path not in route table)"
+      end
+
+      def translate_hole(js_source, translator)
+        translated = translator.translate(js_source)
+        return nil unless translated && translated.ruby != "nil"
+
+        [:hole, translated.ruby]
+      end
+
       def render_local_bindings_todo(bindings)
         return [] if bindings.empty?
 
@@ -249,10 +772,29 @@ module JsxRosetta
         when IR::Conditional then render_conditional(node, translator, indent: indent)
         when IR::Loop then render_loop(node, translator, indent: indent)
         when IR::RenderProp then render_orphan_render_prop(node, translator, indent: indent)
+        when IR::LocalRenderCall then render_local_render_call(node, translator, indent: indent)
         when IR::Slot then render_slot(node, indent: indent)
         when IR::Text then render_text(node, indent: indent)
         when IR::Interpolation then render_interpolation(node, translator, indent: indent)
         when IR::Comment then render_comment(node, indent: indent)
+        when IR::LayoutYield then "#{" " * indent}yield"
+        end
+      end
+
+      # Emit a call to a previously-extracted RenderMethod. The method body
+      # uses `tag.*`/`render` helpers (Phlex executes inside the view), so
+      # invoking it inline produces output at the right place in the
+      # template. Arg expressions are translated; any that fail translation
+      # fall back to verbatim source.
+      def render_local_render_call(call, translator, indent:)
+        if call.args.empty?
+          "#{spaces(indent)}#{call.method_name}"
+        else
+          arg_sources = call.args.map do |arg|
+            translated = translator.translate(arg.expression)
+            translated ? translated.ruby : arg.expression
+          end
+          "#{spaces(indent)}#{call.method_name}(#{arg_sources.join(", ")})"
         end
       end
 
@@ -268,36 +810,81 @@ module JsxRosetta
 
       def render_element(element, translator, indent:)
         todos = []
-        attrs_source = format_attributes(element.attributes, translator, context: :html, todos: todos)
+        attrs_source = format_attributes(element.attributes, translator,
+                                         context: :html, tag: element.tag, todos: todos, indent: indent)
         method_call = "#{element.tag}#{attrs_source}"
+        body = element_body(element, method_call, translator, indent)
+        prepend_attribute_todos(todos, indent, body)
+      end
 
-        body = if VOID_ELEMENTS.include?(element.tag) || element.children.empty?
-                 "#{spaces(indent)}#{method_call}"
-               else
-                 inner = element.children.map { |c| render_ir_node(c, translator, indent: indent + 2) }.join("\n")
-                 "#{spaces(indent)}#{method_call} do\n#{inner}\n#{spaces(indent)}end"
-               end
+      # Decide whether the HTML tag is blockless, yield-only (auto-yield for
+      # self-closing-with-spread), or full do/end (explicit children).
+      def element_body(element, method_call, translator, indent)
+        return "#{spaces(indent)}#{method_call}" if blockless_element?(element)
 
-        prepend_attribute_todos(todos, indent, body)
+        if element.children.empty?
+          # `<tag {...rest} />` — the rest-spread carries React `children`,
+          # but JSX self-closes so there are no explicit IR children. Yield
+          # to the Phlex caller's block so `Component.new { ... }` nesting
+          # actually renders; guard with `block_given?` so callers who pass
+          # no block don't blow up.
+          yield_only_block(method_call, indent)
+        else
+          inner = element.children.map { |c| render_ir_node(c, translator, indent: indent + 2) }.join("\n")
+          "#{spaces(indent)}#{method_call} do\n#{inner}\n#{spaces(indent)}end"
+        end
+      end
+
+      def blockless_element?(element)
+        return true if VOID_ELEMENTS.include?(element.tag)
+
+        element.children.empty? && !spreads_children?(element)
       end
 
       def render_component_invocation(invocation, translator, indent:)
         todos = []
-        kwargs = component_invocation_kwargs(invocation.props, translator, todos: todos)
+        kwargs = component_invocation_kwargs(invocation.props, translator,
+                                             todos: todos, indent: indent, tag: invocation.name)
         class_ref = component_class_reference(invocation.name)
         new_call = kwargs.empty? ? "#{class_ref}.new" : "#{class_ref}.new(#{kwargs})"
+        body = component_invocation_body(invocation, new_call, translator, indent)
+        prepend_attribute_todos(todos, indent, body)
+      end
 
+      def component_invocation_body(invocation, new_call, translator, indent)
         render_prop = invocation.children.find { |c| c.is_a?(IR::RenderProp) }
-        body = if render_prop
-                 render_with_render_prop(new_call, render_prop, translator, indent)
-               elsif invocation.children.empty?
-                 "#{spaces(indent)}render #{new_call}"
-               else
-                 inner = invocation.children.map { |c| render_ir_node(c, translator, indent: indent + 2) }.join("\n")
-                 "#{spaces(indent)}render #{new_call} do\n#{inner}\n#{spaces(indent)}end"
-               end
+        return render_with_render_prop(new_call, render_prop, translator, indent) if render_prop
 
-        prepend_attribute_todos(todos, indent, body)
+        call = "render #{new_call}"
+        return "#{spaces(indent)}#{call}" if blockless_invocation?(invocation)
+
+        if invocation.children.empty?
+          # `<Component {...rest} />` — same idiom as element_body. The
+          # spread carries `children`; yield to the caller's block.
+          yield_only_block(call, indent)
+        else
+          inner = invocation.children.map { |c| render_ir_node(c, translator, indent: indent + 2) }.join("\n")
+          "#{spaces(indent)}#{call} do\n#{inner}\n#{spaces(indent)}end"
+        end
+      end
+
+      def blockless_invocation?(invocation)
+        invocation.children.empty? && !spreads_children?(invocation)
+      end
+
+      def yield_only_block(call, indent)
+        outer = spaces(indent)
+        inner = spaces(indent + 2)
+        "#{outer}#{call} do\n#{inner}yield if block_given?\n#{outer}end"
+      end
+
+      # Does this Element/ComponentInvocation carry a JSX rest-spread
+      # (`{...props}`) that may transport React `children` we can't see in
+      # the IR? Used to decide whether a self-closing JSX tag should still
+      # yield to the Phlex caller's block.
+      def spreads_children?(node)
+        attrs = node.respond_to?(:attributes) ? node.attributes : node.props
+        attrs.any?(IR::SpreadAttribute)
       end
 
       # Emit a render-prop child as a Ruby block on the parent `render` call.
@@ -324,9 +911,14 @@ module JsxRosetta
       # JSX `<Foo>` → `Foo` (default), `FooComponent` (suffix), or just
       # `Foo` again under namespace (Ruby's constant lookup finds the
       # peer class). JSX `<Foo.Bar>` → `Foo::Bar` (plus suffix when set).
+      # `<HomePage>` keeps the `Page` suffix without doubling (no
+      # `HomePageComponent`) — see effective_suffix_for. The path-based
+      # page detection doesn't apply here: an invocation only carries
+      # the JSX tag name, not the target file's path.
       def component_class_reference(jsx_tag)
         segments = jsx_tag.split(".")
-        segments[-1] = "#{segments.last}#{@suffix}" if @suffix
+        suffix = effective_suffix_for(segments.last)
+        segments[-1] = "#{segments.last}#{suffix}" if suffix
         segments.join("::")
       end
 
@@ -335,17 +927,107 @@ module JsxRosetta
       end
 
       def render_conditional(conditional, translator, indent:)
-        test_ruby, todo = safe_test_expression(conditional.test.expression, translator, fallback: "false")
+        if guard_ladder?(conditional, translator)
+          return render_guard_ladder_collapse(conditional, translator, indent: indent)
+        end
+
         lines = []
-        lines << "#{spaces(indent)}# TODO: translate condition: #{todo}" if todo
-        lines << "#{spaces(indent)}if #{test_ruby}"
+        emit_conditional_branches(conditional, translator, indent, lines, leading_keyword: "if")
+        lines << "#{spaces(indent)}end"
+        lines.join("\n")
+      end
+
+      # A guard ladder is a chain of `if/elsif` branches whose tests are all
+      # untranslatable AND whose consequents are all "render nothing" (the
+      # lowered form of `return null` in a guard), terminating in a real
+      # else branch. Emitted naively as `if false / elsif false / .../ else
+      # <main>`, the else *always* fires — silently inverting the source
+      # semantic ("render nothing when any guard hits") into "render main
+      # unconditionally." Collapse to a single TODO block + just the else
+      # so the reviewer sees what guards used to gate the render, and the
+      # main render is at least visible without the misleading `if false`s.
+      def guard_ladder?(conditional, translator)
+        branches, else_branch = walk_conditional_chain(conditional)
+        return false unless else_branch
+        return false if branches.empty?
+
+        branches.all? do |b|
+          test_translates_to_untranslatable?(b[:test], translator) && empty_consequent?(b[:consequent])
+        end
+      end
+
+      def render_guard_ladder_collapse(conditional, translator, indent:)
+        branches, else_branch = walk_conditional_chain(conditional)
+        lines = ["#{spaces(indent)}# TODO: #{branches.length} render guard(s) couldn't translate; wire up Rails-side:"]
+        branches.each do |b|
+          compact = b[:test].tr("\n", " ").squeeze(" ")
+          lines << "#{spaces(indent)}#   #{compact}"
+        end
+        lines << render_ir_node(else_branch, translator, indent: indent)
+        lines.join("\n")
+      end
+
+      def walk_conditional_chain(conditional)
+        branches = []
+        node = conditional
+        while node.is_a?(IR::Conditional)
+          branches << { test: node.test.expression, consequent: node.consequent }
+          node = node.alternate
+        end
+        [branches, node]
+      end
+
+      def test_translates_to_untranslatable?(expression, translator)
+        # Use condition-mode translation so bucket-4 hits (hook-tuple
+        # destructures, top-level imports) count as translatable. When a
+        # guard ladder's tests *do* translate under widening, the ladder
+        # collapses to nothing — render_conditional emits the real
+        # `if @ivar / elsif @ivar / else <main>` form, which correctly
+        # short-circuits to render nothing when any guard fires. Only
+        # untranslatable tests (verbatim JS we can't ivar-promote) still
+        # trip the collapse-to-TODO path.
+        translated = translator.translate_condition(expression)
+        translated.nil? || translated.ruby == "nil"
+      end
+
+      # An empty consequent is what `return null` (the JS guard idiom) lowers
+      # to. Detected as either a literal empty Text node or a Fragment whose
+      # children are all empty.
+      def empty_consequent?(node)
+        case node
+        when IR::Text then node.value.to_s.empty?
+        when IR::Fragment then node.children.all? { |c| empty_consequent?(c) }
+        else false
+        end
+      end
+
+      # Walk a Conditional and its `alternate` chain, emitting `if` for the
+      # first test, `elsif` for each alternate that is itself a Conditional,
+      # and a final `else` for a non-Conditional alternate. Flattens the
+      # `if X / else / if Y / end / end` shape that JS `else if` chains
+      # produce into idiomatic Ruby `if X / elsif Y / else / end`. Without
+      # this, deeply nested conditional chains explode the file's
+      # indentation and trip Style/IfInsideElse + Metrics/BlockNesting.
+      def emit_conditional_branches(conditional, translator, indent, lines, leading_keyword:)
+        test_ruby, todo, promoted = safe_test_expression(conditional.test.expression, translator, fallback: "false")
+        if todo
+          lines << "#{spaces(indent)}# TODO: translate condition: #{todo}"
+        elsif promoted && !promoted.empty?
+          lines << "#{spaces(indent)}# TODO: render condition references binding(s) promoted to @ivar — " \
+                   "thread as controller-passed prop(s): #{promoted.join(", ")}"
+        end
+        lines << "#{spaces(indent)}#{leading_keyword} #{test_ruby}"
         lines << render_ir_node(conditional.consequent, translator, indent: indent + 2)
-        if conditional.alternate
+
+        alt = conditional.alternate
+        return unless alt
+
+        if alt.is_a?(IR::Conditional)
+          emit_conditional_branches(alt, translator, indent, lines, leading_keyword: "elsif")
+        else
           lines << "#{spaces(indent)}else"
-          lines << render_ir_node(conditional.alternate, translator, indent: indent + 2)
+          lines << render_ir_node(alt, translator, indent: indent + 2)
         end
-        lines << "#{spaces(indent)}end"
-        lines.join("\n")
       end
 
       def render_loop(loop_node, translator, indent:)
@@ -375,26 +1057,51 @@ module JsxRosetta
         when IR::ArrayLiteral
           [render_array_literal_value(iterable, translator, todos: []), nil]
         when IR::Interpolation
-          safe_test_expression(iterable.expression, translator, fallback: "[]")
+          safe_iterable_expression(iterable.expression, translator)
         else
           ["[]", iterable.inspect]
         end
       end
 
+      # Iterable variant of safe_test_expression. Uses narrow (non-condition)
+      # translation: a hook-tuple `items` translates to `nil` here rather than
+      # being promoted to `@items`. Rationale: `nil.each` would crash at
+      # render time; `[].each` renders nothing while the accompanying TODO
+      # documents what didn't translate. Render-condition contexts (A1)
+      # take the opposite trade-off because driving `if nil` silently
+      # disables a load-bearing decision.
+      def safe_iterable_expression(expression, translator)
+        translated = translator.translate(expression)
+        return [translated.ruby, nil] if translated && translated.ruby != "nil"
+
+        compact = expression.tr("\n", " ").squeeze(" ")
+        ["[]", compact]
+      end
+
       # Translate an expression intended to drive an `if` or `.each` call.
-      # Returns `[ruby_source, todo_text]`. When the translator can parse
-      # the expression, `todo_text` is nil. When it can't, the caller's
-      # `fallback` (e.g. `"false"` for conditions, `"[]"` for iterables)
-      # is returned along with the original expression so a TODO comment
-      # can be emitted above the call. Without this, JS operators like
-      # `!==`, `===`, optional chaining, and `in` would leak into the
-      # emitted Ruby and produce SyntaxError on load.
+      # Returns `[ruby_source, todo_text, promoted_locals]`:
+      #   - When the translator can parse the expression cleanly, `todo_text`
+      #     is nil. `promoted_locals` carries any bucket-4 names the
+      #     condition-mode translator promoted to `@ivar` — the caller
+      #     surfaces these in a TODO so a reviewer knows which bindings need
+      #     to become controller-passed props.
+      #   - When the translator can't, the caller's `fallback` (`"false"` for
+      #     conditions, `"[]"` for iterables) is returned with the verbatim
+      #     expression in `todo_text` so a TODO comment can be emitted. Without
+      #     this, JS operators like `!==`, `===`, optional chaining, and `in`
+      #     would leak into Ruby and produce SyntaxError on load.
+      #
+      # Condition-mode translation (`translate_condition`) is used for both
+      # branches — it widens bucket-4 hits to `@ivar` so `if loading; …`
+      # becomes `if @loading; …` instead of the dead `if false` fallback.
+      # The promoted list separates that path from full-clean translation,
+      # which has nothing to flag.
       def safe_test_expression(expression, translator, fallback:)
-        translated = translator.translate(expression)
-        return [translated.ruby, nil] if translated
+        translated = translator.translate_condition(expression)
+        return [translated.ruby, nil, translated.promoted_locals] if translated && translated.ruby != "nil"
 
         compact = expression.tr("\n", " ").squeeze(" ")
-        [fallback, compact]
+        [fallback, compact, []]
       end
 
       def render_slot(slot, indent:)
@@ -406,7 +1113,7 @@ module JsxRosetta
       end
 
       def render_text(text, indent:)
-        "#{spaces(indent)}plain #{text.value.inspect}"
+        "#{spaces(indent)}plain #{AST::Inflector.ruby_string_literal(text.value)}"
       end
 
       def render_interpolation(interpolation, translator, indent:)
@@ -443,8 +1150,9 @@ module JsxRosetta
       # renders something visible at runtime.
       def render_untranslated_interpolation(expression, indent)
         compact = expression.tr("\n", " ").squeeze(" ")
+        placeholder = AST::Inflector.ruby_string_literal("[untranslated: #{compact}]")
         "#{spaces(indent)}# TODO: translate #{compact.inspect}\n" \
-          "#{spaces(indent)}plain #{"[untranslated: #{compact}]".inspect}"
+          "#{spaces(indent)}plain #{placeholder}"
       end
 
       def render_comment(comment, indent:)
@@ -459,53 +1167,141 @@ module JsxRosetta
       # of `h1()`). The `context:` param selects naming convention:
       #   - :html       (HTML element attrs — preserve camelCase for SVG)
       #   - :component  (Ruby method args — snake_case via Inflector.underscore)
-      def format_attributes(attributes, translator, context: :html, todos: [])
+      def format_attributes(attributes, translator, context: :html, tag: nil, todos: [], indent: 0)
         events, others = attributes.partition { |a| a.is_a?(IR::EventBinding) || a.is_a?(IR::StimulusBinding) }
         spreads, plain_attrs = others.partition { |a| a.is_a?(IR::SpreadAttribute) }
 
-        sym_parts = []
-        str_parts = []
+        # Per-element form-method check. Set before any attribute renders
+        # so try_rewrite_href can consult it. Scoped per element via a
+        # local backup/restore around the iteration — nested forms are
+        # rare but legal HTML.
+        prev_form_rewritable = @form_action_rewritable
+        @form_action_rewritable = tag == "form" ? form_action_rewritable?(plain_attrs) : false
+
+        parts = { sym: [], str: [] }
         plain_attrs.each do |a|
-          append_attribute_part(a, translator, sym_parts, str_parts, context: context, todos: todos)
+          append_attribute_part(a, translator, parts, context: context, tag: tag, todos: todos, indent: indent)
         end
-        sym_parts << data_action_entry(events, translator) if events.any?
+        parts[:sym] << data_action_entry(events, translator) if events.any?
 
-        joined = build_attribute_list(sym_parts, str_parts, spreads, translator)
+        joined = build_attribute_list(parts, spreads, translator)
         joined.empty? ? "" : "(#{joined})"
+      ensure
+        @form_action_rewritable = prev_form_rewritable
       end
 
-      def append_attribute_part(attribute, translator, sym_parts, str_parts, context:, todos:)
-        part = phlex_attribute_part(attribute, translator, context: context, todos: todos)
+      def append_attribute_part(attribute, translator, parts, context:, todos:, indent: 0, tag: nil)
+        part = phlex_attribute_part(attribute, translator, context: context, tag: tag, todos: todos, indent: indent)
         return unless part
 
-        (part[:string_key] ? str_parts : sym_parts) << part[:source]
+        (part[:string_key] ? parts[:str] : parts[:sym]) << part[:source]
       end
 
-      def build_attribute_list(sym_parts, str_parts, spreads, translator)
-        pieces = sym_parts.dup
-        pieces << "**{ #{str_parts.join(", ")} }" if str_parts.any?
+      def build_attribute_list(parts, spreads, translator)
+        pieces = parts[:sym].dup
+        pieces << "**{ #{parts[:str].join(", ")} }" if parts[:str].any?
         pieces.concat(spreads.map { |s| "**#{render_spread(s.expression, translator)}" })
         pieces.join(", ")
       end
 
       # Emit one attribute as either a {string_key: false, source: "id: @x"}
       # (Ruby-kwarg-safe name) or {string_key: true, source: '"xml:lang" => @x'}
-      # (rare; non-identifier name — goes into a **{ ... } splat).
-      def phlex_attribute_part(attribute, translator, context:, todos:)
+      # (rare; non-identifier name — goes into a **{ ... } splat). Returns
+      # nil to signal "drop this attribute entirely" — used when every style
+      # declaration dropped (would emit `style: ''`) or every plain-attribute
+      # value bailed (would emit `attr: nil`); the TODO comment above the
+      # element already describes what was lost.
+      def phlex_attribute_part(attribute, translator, context:, todos:, indent: 0, tag: nil)
         case attribute
+        when IR::CvaCallSite then cva_call_site_attribute_part(attribute, translator)
         when IR::StyleBinding then class_attribute_part(attribute.expression, translator)
         when IR::ClassList then { string_key: false, source: "class: #{class_list_to_ruby_string(attribute, translator)}" }
-        when IR::Style then { string_key: false, source: "style: #{style_to_ruby_string(attribute, translator)}" }
-        when IR::Attribute then plain_attribute_part(attribute, translator, context: context, todos: todos)
+        when IR::Style then style_attribute_part(attribute, translator, todos: todos)
+        when IR::Attribute
+          plain_attribute_part(attribute, translator, context: context, tag: tag, todos: todos, indent: indent)
         end
       end
 
+      # Skip the `style:` kwarg entirely when every declaration failed to
+      # translate — `style: ''` is invalid HTML output and pure noise; the
+      # per-declaration TODO comments above the element preserve what was
+      # there.
+      def style_attribute_part(style, translator, todos:)
+        ruby = style_to_ruby_string(style, translator, todos: todos)
+        return nil if empty_style_ruby?(ruby)
+
+        { string_key: false, source: "style: #{ruby}" }
+      end
+
+      def empty_style_ruby?(ruby)
+        ["''", '""'].include?(ruby)
+      end
+
+      # A "dropped" attribute is one where translation failed AND the
+      # fallback was the literal `nil` string. We detect this by watching
+      # whether a TODO was appended during the value computation: a real
+      # `attr={null}` in the source produces `nil` *without* a TODO and
+      # should still emit (preserves intent); a failed translation
+      # produces `nil` *with* a TODO and we drop the kwarg to keep output
+      # clean — the TODO above the element already describes the loss.
+      def dropped_value?(value_ruby, todos_before, todos_after)
+        value_ruby == "nil" && todos_after.length > todos_before
+      end
+
       def class_attribute_part(expression, translator)
         translated = translator.translate(expression)
         ruby = translated ? translated.ruby : expression.inspect
         { string_key: false, source: "class: #{ruby}" }
       end
 
+      # Render an IR::CvaCallSite as the `class:` kwarg. Always produces
+      # a single Ruby string-interpolation literal that references the
+      # backend-emitted constants for the cva binding. The detection
+      # happened at lowering time (in `try_lower_cva_call_site`), so the
+      # node already carries the binding name, axes, and optional
+      # class_arg — no regex over verbatim JS source here.
+      def cva_call_site_attribute_part(node, translator)
+        cva = find_cva_binding(node.binding_name)
+        return { string_key: false, source: "class: nil" } unless cva
+
+        parts = cva_call_site_parts(node, cva, translator)
+        { string_key: false, source: %(class: "#{parts.join(" ")}") }
+      end
+
+      def find_cva_binding(binding_name)
+        @current_component&.module_bindings&.find do |b|
+          b.is_a?(IR::CvaBinding) && b.name == binding_name
+        end
+      end
+
+      def cva_call_site_parts(node, cva, translator)
+        prefix = cva_constant_prefix(cva.name)
+        parts = ["\#{#{prefix}_BASE_CLASS}"]
+        node.axes.each do |pair|
+          next unless cva.variants.key?(pair.axis)
+
+          parts << "\#{#{prefix}_VARIANT_CLASSES[#{pair.axis.inspect}][#{cva_axis_ruby_value(pair)}]}"
+        end
+        parts << "\#{#{cva_class_arg_ruby(node.class_arg, translator)}}" if node.class_arg
+        parts
+      end
+
+      def cva_class_arg_ruby(class_arg, translator)
+        translated = translator.translate(class_arg.expression)
+        return translated.ruby if translated
+
+        "@#{AST::Inflector.underscore(class_arg.expression)}"
+      end
+
+      def cva_axis_ruby_value(pair)
+        case pair.kind
+        when :literal_string then pair.source.inspect
+        when :literal_other then pair.source
+        when :literal_nil then "nil"
+        when :prop_ref then "@#{AST::Inflector.underscore(pair.source)}"
+        end
+      end
+
       # Map a JSX attribute name to its Ruby kwarg form. For HTML element
       # attrs (`context: :html`), only hyphens convert to underscores —
       # camelCase (`viewBox`, `preserveAspectRatio`) preserves verbatim
@@ -515,8 +1311,12 @@ module JsxRosetta
       # follow snake_case convention (`defaultValue` → `default_value`).
       # Names that aren't valid Ruby identifiers after conversion (rare:
       # `xml:lang` and friends) fall back to a quoted string key.
-      def plain_attribute_part(attribute, translator, context:, todos:)
-        value_ruby = attribute_value_to_ruby(attribute.name, attribute.value, translator, todos: todos)
+      def plain_attribute_part(attribute, translator, context:, todos:, indent: 0, tag: nil)
+        todos_before = todos.length
+        value_ruby = attribute_value_to_ruby(attribute.name, attribute.value, translator,
+                                             todos: todos, indent: indent, tag: tag)
+        return nil if dropped_value?(value_ruby, todos_before, todos)
+
         ruby_name = case context
                     when :component then AST::Inflector.underscore(attribute.name)
                     else attribute.name.tr("-", "_")
@@ -524,59 +1324,182 @@ module JsxRosetta
         if ruby_name.match?(VALID_IDENTIFIER)
           { string_key: false, source: "#{ruby_name}: #{value_ruby}" }
         else
-          { string_key: true, source: "#{attribute.name.inspect} => #{value_ruby}" }
+          { string_key: true, source: "#{AST::Inflector.ruby_string_literal(attribute.name)} => #{value_ruby}" }
         end
       end
 
-      def attribute_value_to_ruby(name, value, translator, todos:)
+      def attribute_value_to_ruby(name, value, translator, todos:, indent: 0, tag: nil)
+        if (rewrite = try_rewrite_href(name, value, translator, tag: tag))
+          return rewrite
+        end
+
         case value
         when true then "true"
-        when String then value.inspect
+        when String then AST::Inflector.ruby_string_literal(value)
         when IR::Interpolation then interpolated_attribute_value(name, value, translator, todos: todos)
-        when IR::ObjectLiteral then render_object_literal_value(value, translator, todos: todos)
-        when IR::ArrayLiteral then render_array_literal_value(value, translator, todos: todos)
+        when IR::ObjectLiteral then render_object_literal_value(value, translator, todos: todos, indent: indent)
+        when IR::ArrayLiteral then render_array_literal_value(value, translator, todos: todos, indent: indent)
         when IR::Lambda then render_lambda_method_reference(value, translator, attr_name: name)
+        when IR::EventHandler then render_event_handler_method_reference(value, attr_name: name)
+        when IR::ComponentInvocation
+          component_invocation_value(value, translator, todos: todos, attr_name: name)
+        when IR::Element, IR::Fragment
+          # An HTML tag (`title={<span>x</span>}`) or a multi-element
+          # Fragment as an attribute value needs a Phlex execution context
+          # the receiver might not provide. Drop with a TODO rather than
+          # emit a broken kwarg or a speculative method reference.
+          drop_jsx_value_with_todo(name, value, todos: todos)
+        end
+      end
+
+      # Slice 3: rewrite `href`/`to` on link-shaped tags to a Rails URL
+      # helper call when the literal/template-literal path matches a
+      # route in the scanned table. Returns nil to fall through to the
+      # default emission path. Slice C1 added `<form action>` — see
+      # form_action_rewritable? for the method-attribute check.
+      def try_rewrite_href(name, value, translator, tag:)
+        return nil unless @href_rewriter
+        return nil unless tag
+
+        allowed_attrs = LINK_TAG_ATTRS[tag]
+        return nil unless allowed_attrs&.include?(name)
+        return nil if tag == "form" && !@form_action_rewritable
+
+        case value
+        when String
+          @href_rewriter.rewrite_literal(value)
+        when IR::Interpolation
+          rewrite_interpolation_href(value.expression, translator)
+        end
+      end
+
+      # `<form action="…">` only rewrites for safe (GET) submissions —
+      # slice-1 routes are GET-only, so POST/PUT/DELETE forms must stay
+      # verbatim until the route table supports non-GET routes. Returns
+      # true when no method attr is set (HTML default = GET) or when the
+      # method is a literal GET; false otherwise (including interpolated
+      # / TODO methods where we can't statically prove GET).
+      def form_action_rewritable?(attributes)
+        method_attr = attributes.find { |a| a.is_a?(IR::Attribute) && a.name == "method" }
+        return true unless method_attr
+
+        case method_attr.value
+        when nil, true then true
+        when String then method_attr.value.casecmp("get").zero?
+        else false
         end
       end
 
+      def rewrite_interpolation_href(js_source, translator)
+        if (literal = string_literal_path(js_source))
+          return @href_rewriter.rewrite_literal(literal)
+        end
+
+        segments = PagesRouting::HrefRewriter.parse_template_source(js_source)
+        return nil unless segments
+
+        translated = segments.map do |kind, val|
+          next [:literal, val] if kind == :literal
+
+          result = translator.translate(val)
+          return nil unless result && result.ruby != "nil"
+
+          [:hole, result.ruby]
+        end
+        @href_rewriter.rewrite_template(translated)
+      end
+
+      def string_literal_path(js_source)
+        return nil unless js_source.is_a?(String)
+        return nil unless js_source.length >= 2
+
+        first = js_source[0]
+        return nil unless ['"', "'"].include?(first)
+        return nil unless js_source[-1] == first
+
+        body = js_source[1..-2]
+        return nil if body.include?(first) || body.include?("\\")
+
+        body
+      end
+
       # Render an ObjectLiteral as a Ruby hash literal. Identifier-keyed
       # entries become Ruby kwargs (snake_cased to match Ruby convention);
       # non-identifier keys (numeric, hyphenated) fall back to string keys.
-      def render_object_literal_value(object_literal, translator, todos:)
+      # When the single-line rendering exceeds LITERAL_INLINE_BUDGET, or
+      # when any rendered child value spans multiple lines, the layout
+      # switches to one entry per line, indented two spaces past `indent`.
+      def render_object_literal_value(object_literal, translator, todos:, indent: 0, force_inline: false)
+        child_indent = indent + 2
         parts = object_literal.properties.map do |(key, value)|
-          render_object_property(key, value, translator, todos: todos)
+          render_object_property(key, value, translator, todos: todos, indent: child_indent, force_inline: force_inline)
         end
-        "{ #{parts.join(", ")} }"
+        wrap_literal_parts(parts, open: "{", close: "}", indent: indent, inline_sep: ", ", inline_pad: " ",
+                                  force_inline: force_inline)
       end
 
-      def render_object_property(key, value, translator, todos:)
-        value_ruby = render_inline_value(value, translator, todos: todos, attr_name: key)
+      def render_object_property(key, value, translator, todos:, indent: 0, force_inline: false)
+        value_ruby = render_inline_value(value, translator, todos: todos, attr_name: key, indent: indent,
+                                                            force_inline: force_inline)
         snake = AST::Inflector.underscore(key)
         if snake.match?(VALID_IDENTIFIER)
           "#{snake}: #{value_ruby}"
         else
-          "#{key.inspect} => #{value_ruby}"
+          "#{AST::Inflector.ruby_string_literal(key)} => #{value_ruby}"
         end
       end
 
-      def render_array_literal_value(array_literal, translator, todos:)
+      def render_array_literal_value(array_literal, translator, todos:, indent: 0, force_inline: false)
+        child_indent = indent + 2
         parts = array_literal.elements.map do |el|
-          el.nil? ? "nil" : render_inline_value(el, translator, todos: todos, attr_name: nil)
+          if el.nil?
+            "nil"
+          else
+            render_inline_value(el, translator, todos: todos, attr_name: nil, indent: child_indent,
+                                                force_inline: force_inline)
+          end
         end
-        "[#{parts.join(", ")}]"
+        wrap_literal_parts(parts, open: "[", close: "]", indent: indent, inline_sep: ", ", inline_pad: "",
+                                  force_inline: force_inline)
+      end
+
+      # Pick single-line vs multi-line layout for a rendered literal.
+      # Multi-line is forced when any rendered part already contains a
+      # newline (a nested literal that wrapped); otherwise we wrap only
+      # when the single-line form exceeds LITERAL_INLINE_BUDGET.
+      def wrap_literal_parts(parts, **opts)
+        open = opts[:open]
+        close = opts[:close]
+        return "#{open}#{close}" if parts.empty?
+
+        inline = "#{open}#{opts[:inline_pad]}#{parts.join(opts[:inline_sep])}#{opts[:inline_pad]}#{close}"
+        any_multiline = parts.any? { |p| p.include?("\n") }
+        return inline if opts[:force_inline]
+        return inline if !any_multiline && inline.length <= LITERAL_INLINE_BUDGET
+
+        child_pad = " " * (opts[:indent] + 2)
+        close_pad = " " * opts[:indent]
+        "#{open}\n#{child_pad}#{parts.join(",\n#{child_pad}")}\n#{close_pad}#{close}"
       end
 
       # An inline value can appear as a kwarg value, an array element, or a
       # hash property value. Recursive shapes route back through the new IR
       # types; primitives fall through the same paths as attribute_value_to_ruby.
-      def render_inline_value(value, translator, todos:, attr_name:)
+      def render_inline_value(value, translator, todos:, attr_name:, indent: 0, force_inline: false)
         case value
-        when IR::ObjectLiteral then render_object_literal_value(value, translator, todos: todos)
-        when IR::ArrayLiteral then render_array_literal_value(value, translator, todos: todos)
+        when IR::ObjectLiteral
+          render_object_literal_value(value, translator, todos: todos, indent: indent, force_inline: force_inline)
+        when IR::ArrayLiteral
+          render_array_literal_value(value, translator, todos: todos, indent: indent, force_inline: force_inline)
         when IR::Lambda then render_lambda_method_reference(value, translator, attr_name: attr_name)
+        when IR::EventHandler then render_event_handler_method_reference(value, attr_name: attr_name)
         when IR::Interpolation then interpolated_attribute_value(attr_name || "<element>", value, translator,
                                                                  todos: todos)
-        when String then value.inspect
+        when IR::ComponentInvocation
+          component_invocation_value(value, translator, todos: todos, attr_name: attr_name)
+        when IR::Element, IR::Fragment
+          drop_jsx_value_with_todo(attr_name, value, todos: todos)
+        when String then AST::Inflector.ruby_string_literal(value)
         when true then "true"
         else
           "nil"
@@ -612,43 +1535,145 @@ module JsxRosetta
         @lambda_method_counts[base] == 1 ? base : "#{base}#{@lambda_method_counts[base]}"
       end
 
-      # Attribute-position interpolation. Two failure modes:
-      #   1. Translator returns non-nil but with unresolved identifiers —
-      #      the Ruby reference is fine to emit (it'll surface as a
-      #      NameError at render time if it's wrong). Inline TODO comments
-      #      aren't safe in attribute position (would break hash splat or
-      #      method-call syntax), so the marker is suppressed.
-      #   2. Translator returns nil — the original JS expression couldn't
+      # Inline arrow event handler on a PascalCase tag — `onClick={() =>
+      # doX()}` on `<Button>`. Extract to a stub method on the class and
+      # reference via `method(:handle_click)` at the kwarg position so the
+      # receiving component has a callable. The body translation is left
+      # to the human reviewer (the JS source is preserved as a TODO
+      # comment inside the method), but the structural wiring is intact.
+      def render_event_handler_method_reference(handler, attr_name:)
+        @event_handler_methods ||= []
+        base = event_handler_method_base(attr_name)
+        method_name = unique_lambda_method_name(base)
+        @event_handler_methods << { handler: handler, method_name: method_name, attr_name: attr_name }
+        "method(:#{method_name})"
+      end
+
+      # Map a JSX attribute name to an idiomatic Ruby handler-method name.
+      # `onClick` → `handle_click` (mirrors React's `handleClick` convention,
+      # snake_cased). Non-event attrs (rare — a callback prop with no `on`
+      # prefix) fall back to `<attr>_handler`.
+      def event_handler_method_base(attr_name)
+        return "anonymous_handler" if attr_name.nil? || attr_name.empty?
+
+        snake = AST::Inflector.underscore(attr_name)
+        snake.start_with?("on_") ? "handle_#{snake.delete_prefix("on_")}" : "#{snake}_handler"
+      end
+
+      # Attribute-position interpolation. Three failure modes:
+      #   1. Translator returns non-nil, no unresolved identifiers — emit
+      #      the Ruby reference directly. Common case.
+      #   2. Translator returns non-nil but with unresolved identifiers
+      #      starting with uppercase (PascalCase / SCREAMING_SNAKE_CASE —
+      #      almost always imported constants or enums) — emitting bare
+      #      `default_page_size` from `DEFAULT_PAGE_SIZE` produces a
+      #      runtime NameError with no marker. Drop the value to `nil`
+      #      and surface a TODO with the verbatim source. Lowercase
+      #      unresolved identifiers may be Rails helpers (`current_user`)
+      #      and are passed through as before.
+      #   3. Translator returns nil — the original JS expression couldn't
       #      be parsed at all (e.g. `<LeftOutlined .../>`, array literals,
-      #      template literals with method calls). We emit `nil` for the
-      #      kwarg AND record the original expression in `todos` so the
-      #      caller can prepend a `# TODO:` comment line above the element.
+      #      template literals with method calls). Same TODO + nil path.
       def interpolated_attribute_value(name, value, translator, todos:)
         translated = translator.translate(value.expression)
-        return translated.ruby if translated
+        return translated.ruby if translated && !uppercase_unresolved?(translated.unresolved_identifiers)
 
         compact = value.expression.tr("\n", " ").squeeze(" ")
         todos << "attribute #{name.inspect} dropped — couldn't translate: #{compact}"
         "nil"
       end
 
-      def component_invocation_kwargs(props, translator, todos: [])
+      def uppercase_unresolved?(unresolved_identifiers)
+        unresolved_identifiers.any? { |name| name[0] == name[0].upcase }
+      end
+
+      # JSX appearing as an attribute value — typically `icon={<Foo/>}` or
+      # `fallback={<Loading/>}` on antd/MUI components. Emitted as a
+      # component-instance value: `icon: FooComponent.new`. The receiving
+      # Phlex component can render it directly via `render @icon`. Closes
+      # the largest single category of attribute-value drops we were
+      # silently emitting as `attr: nil` + TODO.
+      #
+      # Three child-handling tiers:
+      #   1. No children — `ClassRef.new(kwargs)` on one line.
+      #   2. Children whose rendered Phlex body fits a single line — emit
+      #      as a block: `ClassRef.new(kwargs) { plain "x" }`. The block
+      #      runs in the child component's render context, so HTML helpers
+      #      resolve correctly.
+      #   3. Children that need multiple lines, or any IR::Element /
+      #      IR::Fragment we can't represent inline — fall back to the
+      #      existing TODO drop. Out of MVP scope; expand later if the
+      #      stress numbers warrant it.
+      def component_invocation_value(invocation, translator, todos:, attr_name:)
+        return drop_attribute_with_todo(attr_name, invocation, todos: todos) if invocation_has_render_prop?(invocation)
+
+        kwargs = component_invocation_kwargs(invocation.props, translator, todos: todos, indent: 0)
+        class_ref = component_class_reference(invocation.name)
+        new_call = kwargs.empty? ? "#{class_ref}.new" : "#{class_ref}.new(#{kwargs})"
+
+        return new_call if invocation.children.empty?
+
+        block_body = render_inline_children(invocation.children, translator)
+        return drop_attribute_with_todo(attr_name, invocation, todos: todos) unless block_body
+
+        "#{new_call} { #{block_body} }"
+      end
+
+      def invocation_has_render_prop?(invocation)
+        invocation.children.any?(IR::RenderProp)
+      end
+
+      # Render children to a single-line Phlex block body. Returns nil when
+      # any child needs multiple lines or isn't representable inline — the
+      # caller falls back to the TODO drop.
+      def render_inline_children(children, translator)
+        rendered = children.map { |c| render_ir_node(c, translator, indent: 0) }
+        return nil if rendered.any? { |line| line.include?("\n") }
+
+        joined = rendered.join("; ")
+        joined.length <= LITERAL_INLINE_BUDGET ? joined : nil
+      end
+
+      def drop_attribute_with_todo(attr_name, invocation, todos:)
+        label = attr_name || "<element>"
+        compact = invocation_source_summary(invocation)
+        todos << "attribute #{label.inspect} dropped — couldn't inline JSX value: #{compact}"
+        "nil"
+      end
+
+      def invocation_source_summary(invocation)
+        tag = invocation.name
+        suffix = invocation.children.empty? ? "/" : "...>"
+        "<#{tag}#{suffix}"
+      end
+
+      def drop_jsx_value_with_todo(attr_name, value, todos:)
+        label = attr_name || "<element>"
+        summary = case value
+                  when IR::Element then "<#{value.tag}...>"
+                  when IR::Fragment then "<>...</>"
+                  else "<JSX>"
+                  end
+        todos << "attribute #{label.inspect} dropped — couldn't inline JSX value: #{summary}"
+        "nil"
+      end
+
+      def component_invocation_kwargs(props, translator, todos: [], indent: 0, tag: nil)
         events, others = props.partition { |a| a.is_a?(IR::EventBinding) || a.is_a?(IR::StimulusBinding) }
         spreads, plain_attrs = others.partition { |a| a.is_a?(IR::SpreadAttribute) }
 
-        sym_parts = []
-        str_parts = []
+        parts = { sym: [], str: [] }
         plain_attrs.each do |a|
-          append_attribute_part(a, translator, sym_parts, str_parts, context: :component, todos: todos)
+          append_attribute_part(a, translator, parts, context: :component, tag: tag, todos: todos, indent: indent)
         end
-        sym_parts << data_action_entry(events, translator) if events.any?
+        parts[:sym] << data_action_entry(events, translator) if events.any?
 
-        build_attribute_list(sym_parts, str_parts, spreads, translator)
+        build_attribute_list(parts, spreads, translator)
       end
 
       def class_list_to_ruby_string(class_list, translator)
         parts = class_list.segments.map { |seg| class_segment_to_ruby(seg, translator) }
-        %("#{parts.join(" ")}")
+        wrap_concatenated_string(parts.join(" "))
       end
 
       def class_segment_to_ruby(segment, translator)
@@ -660,23 +1685,46 @@ module JsxRosetta
         when IR::ConditionalSegment
           cond_translated = translator.translate(segment.condition.expression)
           cond_ruby = cond_translated&.ruby || segment.condition.expression
-          %(\#{#{cond_ruby} ? #{segment.class_name.inspect} : ""})
+          %(\#{#{cond_ruby} ? #{AST::Inflector.ruby_string_literal(segment.class_name)} : ''})
         end
       end
 
-      def style_to_ruby_string(style, translator)
-        parts = style.declarations.map { |decl| style_declaration_to_ruby(decl, translator) }
-        %("#{parts.join(" ")}")
+      def style_to_ruby_string(style, translator, todos: [])
+        parts = style.declarations.filter_map { |decl| style_declaration_to_ruby(decl, translator, todos: todos) }
+        wrap_concatenated_string(parts.join(" "))
       end
 
-      def style_declaration_to_ruby(decl, translator)
-        value = case decl.value
-                when String then decl.value
-                when IR::Interpolation
-                  translated = translator.translate(decl.value.expression)
-                  "\#{#{translated&.ruby || decl.value.expression}}"
-                end
-        "#{decl.property}: #{value};"
+      # Wrap a built-up Ruby string body in single quotes when it contains
+      # no interpolation (`\#{...}`) and no escaping pitfalls; otherwise
+      # use double quotes so the interpolation is honored. Keeps class /
+      # style attribute output passing Style/StringLiterals when no
+      # dynamic segments are present (the common case for hardcoded
+      # `style="margin-bottom: 16px"`).
+      def wrap_concatenated_string(body)
+        return %("#{body}") if body.include?("\#{") || body.include?("'") || body.include?("\\")
+
+        "'#{body}'"
+      end
+
+      def style_declaration_to_ruby(decl, translator, todos: [])
+        case decl.value
+        when String
+          "#{decl.property}: #{decl.value};"
+        when IR::Interpolation
+          translated = translator.translate(decl.value.expression)
+          # Translation failed (e.g., interpolation rooted at an
+          # unresolvable local). Emitting the verbatim JS source inside
+          # `\#{}` would render valid Ruby that NameErrors at runtime.
+          # Drop the declaration and surface a TODO above the element so
+          # the reviewer sees what was lost.
+          if translated.nil?
+            todos << "style declaration #{decl.property.inspect} dropped — " \
+                     "couldn't translate: #{decl.value.expression}"
+            nil
+          else
+            "#{decl.property}: \#{#{translated.ruby}};"
+          end
+        end
       end
 
       # Wrap the spread expression in `(… || {})` so a nil-valued prop
@@ -712,7 +1760,7 @@ module JsxRosetta
       end
 
       def render_single_event_descriptor(descriptor)
-        descriptor.kind == :literal ? %("#{descriptor.body}") : descriptor.body
+        descriptor.kind == :literal ? AST::Inflector.ruby_string_literal(descriptor.body) : descriptor.body
       end
 
       def descriptor_in_string(descriptor)
@@ -733,15 +1781,77 @@ module JsxRosetta
         "#{lines.join("\n")}\n"
       end
 
+      # Stimulus method emission. JSX inline arrow bodies are valid JS already;
+      # for DOM-driven handlers (the common shadcn shape) we just paste the body
+      # verbatim into the method, naming the JS parameter to match the original
+      # arrow's parameter so identifier references in the body still resolve.
+      #
+      # When the body references React-state setters or hooks we can't run in
+      # the browser, fall back to the previous TODO-comment behavior so the
+      # human reviewer ports it by hand.
       def stimulus_method_lines(method)
-        body_lines = method.body_source.strip.split("\n")
-        commented = body_lines.map { |line| "  //   #{line}" }
-        header = ["  // TODO: translate from the original JSX handler:"]
+        lines = []
         if method.name != method.original_name
-          header.unshift("  // NOTE: method renamed from #{method.original_name.inspect} " \
-                         "to avoid collision with an earlier handler")
+          lines << "  // NOTE: method renamed from #{method.original_name.inspect} " \
+                   "to avoid collision with an earlier handler"
         end
-        header + commented + [
+
+        if safe_to_paste_handler?(method)
+          lines.concat(pasted_handler_lines(method))
+        else
+          lines.concat(todo_handler_lines(method))
+        end
+
+        lines
+      end
+
+      # Heuristic for "this JS body is safe to drop into a Stimulus method
+      # verbatim." Bails out when:
+      #   - any arrow param wasn't a plain Identifier (destructured / rest) —
+      #     pasting would reference an undefined local at runtime;
+      #   - the body is the identifier-bound pseudo-comment we synthesize
+      #     when an `onClick={onChange}` reference resolved to no arrow;
+      #   - the body calls a top-level React state setter (`setX(`) or hook
+      #     (`useX(`) — the negative lookbehind on `[.\w]` makes sure DOM
+      #     methods like `e.setAttribute(` / `el.setPointerCapture(` don't
+      #     trip the guard.
+      def safe_to_paste_handler?(method)
+        return false unless method.params.all?
+
+        body = method.body_source
+        return false if body.lstrip.start_with?("//")
+        return false if body =~ /(?<![.\w])set[A-Z]\w*\(/
+        return false if body =~ /(?<![.\w])use[A-Z]\w*\(/
+
+        true
+      end
+
+      # Paste the JS body into the method, using the original arrow's first
+      # parameter name (so the body's references still resolve). Strip the
+      # outer `{ … }` wrapper only when the body was an arrow BlockStatement
+      # (`(e) => { … }`), not an expression-form body like `(e) => ({ x: 1 })`
+      # which Babel hands back as `{ x: 1 }` already — stripping would yield
+      # `x: 1`, a JS label statement (no-op).
+      def pasted_handler_lines(method)
+        param = method.params.first || "event"
+        body = method.body_source.strip
+        body = body[1..-2].strip if method.body_is_block
+        inner_lines = body.split("\n").map { |l| "    #{l.lstrip}" }
+        [
+          "  #{method.name}(#{param}) {",
+          *inner_lines,
+          "  }"
+        ]
+      end
+
+      # Fallback for handlers that aren't safe to paste verbatim — preserve
+      # the original body as a comment and emit an empty method body.
+      def todo_handler_lines(method)
+        body_lines = method.body_source.strip.split("\n")
+        commented = body_lines.map { |line| "  //   #{line}" }
+        [
+          "  // TODO: translate from the original JSX handler:",
+          *commented,
           "  #{method.name}(event) {",
           "    // ...",
           "  }"
@@ -751,6 +1861,159 @@ module JsxRosetta
       def spaces(count)
         " " * count
       end
+
+      # ----------------------------------------------------------------------
+      # Lucide icon sidecars
+      # ----------------------------------------------------------------------
+      #
+      # When a translated component references `<ChevronRight />` after
+      # `import { ChevronRight } from "lucide-react"`, the consumer ends up
+      # with a `render ChevronRight.new(...)` call against a Ruby class that
+      # doesn't exist. To close that NameError, we emit one Phlex class per
+      # referenced icon as a sidecar file (`chevron_right.rb` etc.) plus a
+      # shared `lucide_icon.rb` base. Each file follows Zeitwerk's
+      # one-constant-per-file convention so it drops straight into
+      # `app/components/` without further configuration.
+
+      def lucide_icon_files(component)
+        usages = referenced_lucide_icons(component)
+        return [] if usages.empty?
+
+        @seen_lucide_icons ||= Set.new
+        files = []
+        unless @seen_lucide_icons.include?(:base)
+          files << File.new(path: "lucide_icon.rb", contents: render_lucide_icon_base_rb)
+          @seen_lucide_icons << :base
+        end
+
+        usages.sort_by { |u| u[:local_name] }.each do |usage|
+          next if @seen_lucide_icons.include?(usage[:local_name])
+
+          path = "#{AST::Inflector.underscore(usage[:local_name])}.rb"
+          files << File.new(
+            path: path,
+            contents: render_lucide_icon_class_rb(usage[:local_name], canonical: usage[:canonical_name])
+          )
+          @seen_lucide_icons << usage[:local_name]
+        end
+        files
+      end
+
+      # Lucide imports used as JSX tags, each carrying both the local
+      # binding (what the emitted file/class is named after) and the
+      # canonical export (used to look up the vendored SVG path data).
+      # The two diverge under aliased imports — `import { ChevronRight as
+      # CR }` should still resolve `ChevronRight`'s SVG while emitting a
+      # `cr.rb` defining `class CR < LucideIcon`. Names not in the
+      # vendored data still emit, but the class falls back to a TODO
+      # `inner_svg` instead of NameError-ing at render.
+      def referenced_lucide_icons(component)
+        lucide_by_local = component.module_imports
+                                   .select { |i| Icons.lucide_source?(i.source) }
+                                   .to_h { |i| [i.name, i.imported_name || i.name] }
+        return [] if lucide_by_local.empty?
+
+        invocations = Set.new
+        collect_component_invocations(component.body, invocations)
+        invocations.intersection(lucide_by_local.keys).map do |local_name|
+          { local_name: local_name, canonical_name: lucide_by_local.fetch(local_name) }
+        end
+      end
+
+      # Walk an IR subtree and collect every ComponentInvocation tag name we
+      # see. Recurses through any field that holds an IR node or array of
+      # nodes. Conservative — visits every container; cost is proportional
+      # to IR size.
+      def collect_component_invocations(node, acc)
+        return if node.nil?
+
+        acc << node.name if node.is_a?(IR::ComponentInvocation)
+        return unless node.respond_to?(:members)
+
+        node.members.each do |field|
+          value = node.public_send(field)
+          if value.is_a?(Array)
+            value.each { |child| collect_component_invocations(child, acc) }
+          elsif value.respond_to?(:members)
+            collect_component_invocations(value, acc)
+          end
+        end
+      end
+
+      def render_lucide_icon_base_rb
+        mod_open, mod_close, indent = lucide_module_wrap
+        <<~RUBY
+          # frozen_string_literal: true
+
+          # Generated by jsx_rosetta. Don't edit by hand — re-translate the source
+          # to refresh. Shared SVG-wrapper base for Lucide icon shims; one subclass
+          # per icon (e.g. ChevronRight, Search) sits alongside this file.
+          #{mod_open}#{indent}class LucideIcon < Phlex::HTML
+          #{indent}  BASE_ATTRS = %{xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"}.freeze
+
+          #{indent}  def initialize(class_name: nil, **)
+          #{indent}    super()
+          #{indent}    @class_name = class_name
+          #{indent}  end
+
+          #{indent}  def view_template
+          #{indent}    cls = @class_name.to_s.empty? ? "" : %{ class="\#{@class_name}"}
+          #{indent}    raw safe("<svg \#{BASE_ATTRS}\#{cls}>\#{inner_svg}</svg>")
+          #{indent}  end
+
+          #{indent}  def inner_svg
+          #{indent}    raise NotImplementedError
+          #{indent}  end
+          #{indent}end
+          #{mod_close}
+        RUBY
+      end
+
+      # `name` is the local binding (the Ruby class name we emit), `canonical`
+      # is the original Lucide export — they diverge under aliased imports.
+      # SVG lookup keys on `canonical`; the class definition keys on `name`.
+      def render_lucide_icon_class_rb(name, canonical: name)
+        inner = Icons.lucide_for(canonical)
+        mod_open, mod_close, indent = lucide_module_wrap
+        body = if inner
+                 "#{indent}  def inner_svg = #{format_svg_string(inner)}"
+               else
+                 "#{indent}  # TODO: #{canonical.inspect} isn't in jsx_rosetta's vendored lucide.json.\n" \
+                   "#{indent}  # Fill in inner_svg with the SVG path data from lucide.dev, or refresh\n" \
+                   "#{indent}  # `lib/jsx_rosetta/icons/lucide.json`.\n" \
+                   "#{indent}  def inner_svg = \"\""
+               end
+        <<~RUBY
+          # frozen_string_literal: true
+
+          # Generated by jsx_rosetta from a "lucide-react" import. Refresh with
+          # a re-translate; don't edit by hand.
+          #{mod_open}#{indent}class #{name} < LucideIcon
+          #{body}
+          #{indent}end
+          #{mod_close}
+        RUBY
+      end
+
+      # Match the namespace wrapping we use for the main component class.
+      # Returns ["module Foo\n", "end\n", "  "] when a namespace is set,
+      # or ["", "", ""] for the top-level case.
+      def lucide_module_wrap
+        return ["", "", ""] unless @namespace
+
+        ["module #{@namespace}\n", "end\n", "  "]
+      end
+
+      # Wrap an SVG inner-markup snippet in a Ruby string literal that
+      # preserves its embedded double quotes. Single-quoted when the markup
+      # contains no single quotes (most cases), otherwise %q delimited.
+      def format_svg_string(svg)
+        if svg.include?("'")
+          %(%q{#{svg}})
+        else
+          "'#{svg}'"
+        end
+      end
     end
   end
 end