jsx_rosetta 0.5.1 → 0.6.0

data/plans/nextjs_pages_to_rails_slice_4.md

@@ -0,0 +1,301 @@
+# Slice 4 — Next.js page-router extensions (umbrella: `translator_widening_and_pages_followups.md`)
+
+Five extensions to the page-router story shipped in slices 1–3. Each item touches either `pages_routing.rb` (route classification) or the Phlex backend's `--rails-routes` plumbing (view placement), and several touch both. Land as one slice so the routes.rb, the view tree, and any controller stubs stay in sync.
+
+Items from the umbrella plan, in landing order:
+
+- **B5** — Route groups `(group)/`. Next.js 13+ convention where paren-wrapped dir segments are invisible to the URL but group files semantically. Skip the segment from URL building; carry through as namespace hint. *Lands first — pure Scanner change, no IR / backend coupling.*
+- **B3** — Namespace nesting for multi-segment dir trees. `pages/admin/users/[id].tsx` → `Admin::UsersController#show` at `/admin/users/:id` (today: `admin#users_show`). **Documented breaking change.**
+- **B4** — Error pages (`_error.tsx` / `404.tsx` / `500.tsx`) → `Views::Errors::<Status>` at `app/views/errors/<status>.rb`. Adds a `config.exceptions_app` comment block at the top of routes.rb.
+- **B2** — `_app.tsx` → `app/views/layouts/application.rb` with class `Views::Layouts::Application < Views::Base`. `_document.tsx` remains skipped (HTML scaffolding is Rails's job).
+- **B1** — `getServerSideProps` / `getStaticProps` capture into new `IR::Component#server_data_source` field. Phlex backend emits the body as a TODO comment block at the top of the rails-view file. The one item in slice 4 where AST/IR meaningfully helps.
+
+## Dependencies
+
+```
+B5 ──┐
+     ├─→ B3 ─→ B4 ─→ B2 ─→ B1
+B3 ──┘
+```
+
+B5 and B3 both reshape `controller_for` / `route_name` in `PagesRouting::Naming`; landing B5 first means B3 doesn't have to re-handle paren-wrapped segments. B4 / B2 / B1 are independent and could ship in any order — sequencing them last keeps the routes.rb regression in one place.
+
+## B5 — Route groups `(group)/`
+
+### Detection
+
+`Scanner.segment_to_path_part` already classifies bracketed segments. Add a `(group)` form: `\A\(([^)]+)\)\z` → `[:route_group, name]`. Two rules follow:
+
+1. `rails_path_for` skips `:route_group` entries entirely (no URL segment).
+2. `controller_for` treats `(group)` dirs as transparent — picks the first *non-group, non-bracket* segment. The group name is collected separately into a new `namespace` array on `Route`.
+
+### Route shape
+
+```ruby
+Route = Data.define(:rails_path, :controller, :action, :source_path, :namespace)
+```
+
+`namespace` is `[]` for everything not under a group. Under `pages/(marketing)/about.tsx` it's `["marketing"]`. Under `pages/(marketing)/(public)/about.tsx` it's `["marketing", "public"]` (rare but valid).
+
+### Naming
+
+`Naming.route_name` prefixes the namespace: `["marketing"] + about` → `marketing_about_path`. URL still `/about`.
+
+### Emitter
+
+routes.rb wraps grouped routes in `namespace :marketing, module: "marketing", path: ""` blocks so Rails picks up the controller path (`Marketing::AboutController`) without affecting the URL. Comment above the block names the source group.
+
+### Files
+
+| Path | Status | Scope |
+|---|---|---|
+| `lib/jsx_rosetta/pages_routing.rb` | modify | `Route` gets `namespace:`. Scanner's `segment_to_path_part` + `controller_for` + `rails_path_for` handle the new form. Emitter renders nested `namespace … path: ""` blocks for grouped routes. Naming prefixes route-name helper. |
+
+### Specs
+
+- `pages/(marketing)/about.tsx` → `get "/about"` with `as: :marketing_about` inside `namespace :marketing, path: ""`.
+- `pages/(marketing)/index.tsx` → `get "/"` with `as: :marketing_index`.
+- `pages/(marketing)/(public)/about.tsx` → nested namespaces.
+- `pages/(group)/users/[id].tsx` → group + bracket dir → `Group::UsersController#show` at `/users/:id`.
+
+## B3 — Namespace nesting for nested dirs
+
+### Trigger
+
+In `controller_for(dir_segments)`, current behavior: first non-bracket segment wins. New rule: when **more than one** non-bracket segment precedes the leaf, treat all but the last as namespaces and the last as the controller.
+
+Examples:
+
+| Source path | Before | After |
+|---|---|---|
+| `users/[id].tsx` | controller=`users`, action=`show` | unchanged |
+| `admin/users/[id].tsx` | controller=`admin`, action=`users_show` | namespace=`["admin"]`, controller=`users`, action=`show` |
+| `admin/users/[id]/edit.tsx` | controller=`admin`, action=`users_edit` | namespace=`["admin"]`, controller=`users`, action=`edit` |
+| `admin/billing/invoices/index.tsx` | controller=`admin`, action=`billing_invoices_index` | namespace=`["admin", "billing"]`, controller=`invoices`, action=`index` |
+
+Bracket dirs *between* the controller and the leaf still flow into the URL as params; they don't break namespacing. `policies/[providerSlug]/[policyId]/edit.tsx` stays controller=`policies` because there's only one non-bracket dir.
+
+### Naming & emission
+
+`Naming.route_name` prepends namespace segments to the existing rule. `Admin::UsersController#show` → `as: :admin_user`. Emitter wraps the controller's route block in `namespace :admin do ... end`.
+
+### Behavioral interaction with B5
+
+B5's namespace (from `(group)`) and B3's namespace (from nested dirs) collapse into the same `namespace` array on Route, in source order. A grouped *and* nested path like `pages/(marketing)/admin/users/index.tsx` produces `namespace = ["marketing", "admin"]`, controller=`users`. Rendered as two nested `namespace` blocks in routes.rb.
+
+### Breaking-change notice
+
+Existing route-name helpers change for any pages tree with multi-segment dirs:
+
+- `admin_users_index_path` → `admin_users_path`
+- `admin_users_show_path` → `admin_user_path(id)`
+- `admin_billing_invoices_index_path` → `admin_billing_invoices_path`
+
+Document in the slice-4 plan and in the CHANGELOG when shipped. Parallel to slice 3's `as:` addition: intentional rename, surfaced clearly.
+
+### Files
+
+| Path | Status | Scope |
+|---|---|---|
+| `lib/jsx_rosetta/pages_routing.rb` | modify | `controller_for` returns `[controller, namespace_array]`. `Naming.route_name` & `url_helper_name` accept namespace. `Emitter.grouped_body` wraps in nested `namespace :foo do` blocks. `HrefRewriter` ignores namespace for path-matching — the rails_path string already contains everything URL-relevant. |
+| `lib/jsx_rosetta/backend/phlex.rb` | modify | `rails_view_class_name` prepends namespace: `Views::Admin::Users::Show`. `ruby_path` prepends: `admin/users/show.rb`. |
+| `lib/jsx_rosetta/cli.rb` | unchanged | The `--rails-routes` flow already plumbs the Route through; the namespace travels along for free. |
+
+### Specs
+
+- Two-segment nesting (`admin/users/[id].tsx`) → emits `namespace :admin do; resources :users, only: [:show]; end`-equivalent flat block.
+- Three-segment nesting → two nested namespace blocks.
+- Bracket dir between named segments doesn't break detection.
+- HrefRewriter: literal `"/admin/users/123"` matches namespaced route, returns `admin_user_path(123)`.
+
+## B4 — Error pages
+
+Stop skipping `_error.tsx` / `404.tsx` / `500.tsx`. Emit as:
+
+```ruby
+Route(
+  rails_path: "/404",  # informational; not actually used as a Rails route
+  controller: "errors",
+  action: "not_found",  # or "internal_server_error" / "fallback"
+  source_path: "404.tsx",
+  namespace: [],
+  kind: :error_page
+)
+```
+
+Add a `:kind` field on `Route` (default `:standard`). Routes with `kind: :error_page` are NOT emitted as `get` lines in routes.rb — instead they get a comment block at the top explaining `config.exceptions_app = routes` wiring:
+
+```ruby
+# Error pages — wire in config/application.rb:
+#   config.exceptions_app = self.routes
+# Then declare these as ordinary routes that resolve to ErrorsController:
+#   match "/404", to: "errors#not_found", via: :all
+#   match "/500", to: "errors#internal_server_error", via: :all
+```
+
+View placement still applies — `_rails_view_route` for an error page points at `app/views/errors/<action>.rb` with class `Views::Errors::<Action>`.
+
+Action name mapping:
+
+| Source | Action |
+|---|---|
+| `404.tsx` | `not_found` |
+| `500.tsx` | `internal_server_error` |
+| `_error.tsx` | `fallback` |
+
+### Files
+
+| Path | Status | Scope |
+|---|---|---|
+| `lib/jsx_rosetta/pages_routing.rb` | modify | `Route` gets `kind:`. `Scanner.build_route` recognizes error leaves; `SKIPPED_LEAVES` loses the error entries. `Emitter` emits the wiring comment block at the top of routes.rb when any error-page route is present; skips them from the `get` list. |
+| `lib/jsx_rosetta/backend/phlex.rb` | unchanged | `rails_view_class_name` already does `Views::<Controller>::<Action>` — `errors/not_found.rb` falls out naturally. |
+
+### Specs
+
+- `404.tsx` → Route(`controller: "errors"`, `action: "not_found"`, `kind: :error_page`).
+- Emitter inserts the wiring comment block when error pages are present.
+- View placement: translating `404.tsx` with `--rails-routes` lands at `errors/not_found.rb` with class `Views::Errors::NotFound < Views::Base`.
+
+## B2 — `_app.tsx` → application layout
+
+Stop skipping `_app.tsx`. Emit as:
+
+```ruby
+Route(
+  rails_path: nil,
+  controller: "layouts",
+  action: "application",
+  source_path: "_app.tsx",
+  namespace: [],
+  kind: :layout
+)
+```
+
+`_document.tsx` stays in `SKIPPED_LEAVES` — Next.js's `_document` exists to override the HTML scaffolding (lang attribute, custom head/body wrappers), and Rails owns that via `app/views/layouts/application.html.erb`. We don't try to translate.
+
+### View placement
+
+The Phlex backend translates layouts to `app/views/layouts/application.rb` with class `Views::Layouts::Application < Views::Base`. Body is the body of the `_app.tsx` component — Next.js's `_app` typically returns `<Component {...pageProps} />` wrapped in providers, so the translation lands as:
+
+```ruby
+# Views::Layouts::Application — generated by jsx_rosetta from _app.tsx
+class Views::Layouts::Application < Views::Base
+  def view_template
+    # TODO: Next.js providers detected — port to Rails initializers / Stimulus:
+    #   <ThemeProvider> ... <Component {...pageProps} /> ... </ThemeProvider>
+    yield if block_given?
+  end
+end
+```
+
+The `<Component {...pageProps} />` invocation in the source lowers to a special marker that the backend emits as `yield if block_given?`. Provider wrappers around it stay as TODO comments — wrapping behavior usually doesn't translate verbatim to Rails.
+
+Detection rule: in lowering, when `mode == :layout` (a new mode), the lowering pass recognizes `<Component {...pageProps} />` (camelCase `Component` referencing the page-props param) and replaces it with an `IR::LayoutYield` node. The backend emits `yield if block_given?`.
+
+### Files
+
+| Path | Status | Scope |
+|---|---|---|
+| `lib/jsx_rosetta/pages_routing.rb` | modify | `Scanner` recognizes `_app` as a layout route, not skipped. `Emitter` lists it in the skipped-block-style comment header but doesn't emit it as a `get` line. |
+| `lib/jsx_rosetta/ir/types.rb` | modify | New `IR::LayoutYield` node (no fields). New `mode: :layout` value on Component. |
+| `lib/jsx_rosetta/ir/lowering.rb` | modify | When the function's body is a JSX element wrapping `<Component {...pageProps} />`, lower the inner `<Component ...>` as `LayoutYield`. The wrapping providers stay as ComponentInvocation TODOs (their children include the LayoutYield). |
+| `lib/jsx_rosetta/backend/phlex.rb` | modify | New rendering branch for `IR::LayoutYield` → `yield if block_given?`. When `@rails_view.kind == :layout`, `rails_view_class_name` → `Views::Layouts::Application`. `ruby_path` → `layouts/application.rb`. |
+
+### Specs
+
+- `_app.tsx` returning bare `<Component {...pageProps} />` → emits `yield if block_given?` body.
+- `_app.tsx` wrapping in providers → providers become ComponentInvocation TODOs, the inner `<Component …>` becomes a yield.
+- Class name and path for layouts.
+
+## B1 — `getServerSideProps` / `getStaticProps` capture
+
+### Detection
+
+After parsing, scan the top-level AST `body` for one of:
+
+- `ExportNamedDeclaration` whose `declaration.type` is `FunctionDeclaration` with `id.name` in `{"getServerSideProps", "getStaticProps"}` (sync or async).
+- `ExportNamedDeclaration` whose `declaration.type` is `VariableDeclaration` and the first declarator's `id.name` is in the same set, with `init` an `ArrowFunctionExpression` or `FunctionExpression`.
+
+Capture the full source range of the export statement verbatim. Attach to the component via a new `server_data_source:` field on `IR::Component`. When multiple sibling components share the same module (rare for pages but possible), the field attaches only to the default-export component.
+
+### Field
+
+```ruby
+# server_data_source : ServerDataSource | nil — capture of an exported
+#                      getServerSideProps / getStaticProps function. Body is
+#                      preserved verbatim so the human reviewer can port it
+#                      to the matching Rails controller action. nil for
+#                      non-page components.
+ServerDataSource = Data.define(:hook_name, :source) do
+  include Node
+end
+```
+
+### Phlex emission
+
+When `@rails_view` is set and `component.server_data_source` is non-nil, prepend a TODO comment block above the class:
+
+```ruby
+# TODO: port this to ClaimsController#show:
+#
+#   export async function getServerSideProps(ctx) {
+#     const { id } = ctx.params;
+#     const claim = await fetchClaim(id);
+#     return { props: { claim } };
+#   }
+#
+# In Rails: load the data in the controller action, set @claim, and the
+# view will read it via the existing props plumbing.
+```
+
+If `@rails_view` is not set (non-rails-routes mode), still emit a similar block but referencing "the host controller" rather than a specific name.
+
+### Files
+
+| Path | Status | Scope |
+|---|---|---|
+| `lib/jsx_rosetta/ir/lowering.rb` | modify | New `extract_server_data_source(program)` scans the AST body for the export shapes above. Threads the result into `Component.new(...)` at lower-time. |
+| `lib/jsx_rosetta/ir/types.rb` | modify | New `ServerDataSource` value type. New `server_data_source:` field on `Component`. |
+| `lib/jsx_rosetta/backend/phlex.rb` | modify | New `render_server_data_source_todo(component)` helper. Prepended to the class output above any cva/module-constant prefix. |
+
+### Specs
+
+- `export async function getServerSideProps(ctx) { ... }` — function declaration form.
+- `export const getServerSideProps = async (ctx) => { ... }` — const-arrow form.
+- `export const getStaticProps = ...` — alternate hook name.
+- Two hooks in the same file — only the first is captured (multi-hook is unusual and overlap is rare; the second still surfaces in module_bindings TODO).
+- View emission prepends the TODO block with the right controller name.
+
+## Verification
+
+```bash
+bundle exec rake                            # rspec + rubocop
+bundle exec exe/jsx_rosetta pages-routes tmp/stress/phlex_out/reserv-web/pages \
+  --ext .rb -o /tmp/slice4_routes.rb
+ruby -c /tmp/slice4_routes.rb               # must succeed
+bash tmp/run_phlex_stress.sh                # full corpus translate
+ruby -c tmp/stress/phlex_out/**/*.rb 2>&1 | grep -v "Syntax OK" | head
+```
+
+Numbers to track:
+
+- routes.rb line count (more lines from namespace blocks, comment headers).
+- Page-component count translating cleanly (currently 82/82 emitted).
+- `ruby -c` pass count (currently 1239/1239).
+- Stress corpus: confirm no regressions on non-page files (B-series is page-router-specific).
+
+## Out of scope (deferred or out of umbrella)
+
+- HOC unwrapping (#1).
+- Anchor / query-string preservation in href rewriter (#10).
+- Slice C (`<form action>` + ViewComponent/RailsView `--rails-routes`) — separate slice in the umbrella.
+- Translating Next.js `Link` props beyond `href` (`prefetch`, `replace`, etc.).
+- Provider-component recognition inside `_app.tsx`. The wrapper stays as a ComponentInvocation TODO around `yield`; the host is expected to port providers to Rails initializers or Stimulus controllers by hand.
+
+## Risks
+
+- **B3 breaks downstream route helpers.** Any host code that already references `admin_users_show_path` after slice 1's `as:` addition will need to update to `admin_user_path`. Mitigation: note in CHANGELOG; the rename happens once.
+- **B5 + B3 stacking gets visually busy.** Two nested `namespace` blocks in routes.rb (group + nested) is supported but unusual. Spec covers, but real corpora rarely hit it.
+- **B1 captures large `getServerSideProps` bodies verbatim.** A 200-line server-side handler ends up as a 200-line comment block above the class. Acceptable: the TODO header is clear, and the alternative (silent drop) loses information. Long blocks are a code-review smell, not a translation bug.
+- **B2 layout heuristic is approximate.** `_app.tsx` files that don't follow the standard `<Component {...pageProps} />` shape (e.g. ones that conditionally swap layouts based on `Component.getLayout`) won't emit a `yield`. Mitigation: fall back to emitting the entire body as a TODO with a note that the layout-yield wasn't detected, and let the user wire it.
+- **B4 error pages aren't real Rails routes.** Some Rails apps wire errors via `public/404.html` instead of `config.exceptions_app`. The wiring comment block names both options.

data/plans/translator_widening_and_pages_followups.md

@@ -0,0 +1,120 @@
+# jsx_rosetta — translator widening + pages-router follow-ups
+
+Umbrella plan for ten follow-up items surfaced by the post-merge stress assessment (covers items #2, #3, #4, #5, #6, #7, #8, #9, #11, #12 from the readiness review). Organized into three slices, ordered by independence and impact-per-LOC.
+
+Parent plans this builds on: `plans/nextjs_pages_to_rails.md` and its slice 2 / slice 3 spinoffs.
+
+Each slice below will get its own implementation plan file when it starts, matching the slice-1/2/3 cadence. This document is the umbrella that organizes the work and locks in the sequencing.
+
+## Inventory
+
+The ten items, grouped by where the work lands. The cross-references like "(former #2)" map back to the original list in the readiness assessment.
+
+### Group A — ExpressionTranslator widening (Slice A)
+
+Reduces TODO surface across **every** generated file. Self-contained; no Next.js-specific surface area.
+
+- **A1. Simple-condition translator widening** (former #2). Conditional-render guards like `{loading && <X/>}` should emit `if @loading`, not `# TODO: translate condition: loading`. The translator already handles bare identifiers, member chains, and unary `!` in attribute-value context — the conditional-rendering path bails on the same shapes for reasons that need diagnosing. **Stress corpus impact**: ~123 TODOs (61 "render guard couldn't translate" + 41 + 21 simple-condition TODOs).
+
+- **A2. Trivial top-level const → Ruby constant** (former #3). Every module-level `const` lands in a TODO block today. Many are `const FOO = "literal"` / `const COLUMNS = [...]` / `const TAGS = {...}` — literal-shaped values that translate cleanly using the same machinery as the merge's cva path. **Stress corpus impact**: ~402 TODO blocks affected.
+
+- **A3. `router.push("/path")` hint outside event-handler bodies** (former #6). When the call appears in a synchronous body (not an event handler), emit `# TODO: redirect_to <helper>` referencing the matched URL helper. Handler bodies stay verbatim per the project rule against speculative JS-to-Ruby translation. Smaller surface (<50 occurrences in this corpus) but a high-signal hint when it fires.
+
+### Group B — Next.js page-router extensions (Slice 4 of the parent series)
+
+Builds on slice 1's `pages-routes` and slice 2's `--rails-routes` view placement. Shipping them together keeps the routes.rb, the view tree, and the controller stubs in sync.
+
+- **B1. `getServerSideProps` / `getStaticProps` detection** (former #4). Capture the body at lowering time into a new field on `IR::Component`; emit a TODO comment block at the top of the rails-view file (and a matching one in the controller action stub) with the body verbatim. The only place in slice 4 where AST/IR meaningfully helps.
+
+- **B2. `_app.tsx` / `_document.tsx` → application-layout class** (former #5). Stop skipping at the `pages-routes` layer. Translate to `app/views/layouts/application.rb` with class `Views::Layouts::Application < Views::Base`. The merge's auto-yield mechanism is exactly the body shape this needs.
+
+- **B3. Namespace nesting for nested dirs** (former #7). `pages/admin/users/[id].tsx` should produce `Admin::UsersController#show` at `/admin/users/:id` (not the current `admin#users_show`). Trigger: more than one non-bracket directory segment before the leaf.
+
+- **B4. Error-page support** (former #8). `_error.tsx` / `404.tsx` / `500.tsx` → `Views::Errors::<Status> < Views::Base` at `app/views/errors/<status>.rb`, plus a comment block at the top of routes.rb explaining `config.exceptions_app` wiring.
+
+- **B5. Route groups `(group)/`** (former #11). Next.js 13+ pattern where paren-wrapped directories are invisible to the URL but group files semantically. Rule: skip the segment from URL building; carry it through as a controller namespace hint.
+
+### Group C — Slice-3 backend expansion (Slice C)
+
+Extends slice 3's link-tag reach and the slice-2/3 `--rails-routes` plumbing to the other backends.
+
+- **C1. `<form action="...">` rewrite** (former #9). Extend slice 3's link-tag set: `form` joins `a` / `Link` / `NavLink` / `RouterLink`, with `action` instead of `href`. Only rewrite when `method` is GET or absent (HTML default). Slice 1 emits GET routes only, so non-GET forms stay verbatim until the route table grows.
+
+- **C2. `--rails-routes` for ViewComponent + RailsView backends** (former #12). The Phlex backend has full slice-2/3 support today; the other two don't. Add equivalent view placement (and href rewriting where it makes sense) to `Backend::ViewComponent` and `Backend::RailsView`.
+
+## Slice plans
+
+### Slice A — translator widening
+
+**Why first**: highest TODO-reduction-per-LOC. Self-contained, no Next.js surface. Lowers visible TODO count on every translation; would lift the stress corpus from ~3.9 TODOs/file mean toward ~2.5.
+
+**Likely files**:
+
+| Path | Status | Scope |
+|---|---|---|
+| `lib/jsx_rosetta/backend/view_component/expression_translator.rb` | modify | Accept conditional-render context; return `@ivar` for simple bucket-4 hits with unary `!` prefix preserved. Investigate why the conditional path bails on shapes the attribute-value path accepts — likely a stricter entry point. |
+| `lib/jsx_rosetta/ir/lowering.rb` | modify | New detector for literal-shaped module-level `const` declarations (string, number, boolean, array of literals, object of literals). Mirror the `try_lower_cva_call_site` pattern. |
+| `lib/jsx_rosetta/ir/types.rb` | modify | New `IR::ModuleConstant` value type (parallel to `IR::CvaBinding`). |
+| `lib/jsx_rosetta/backend/phlex.rb` | modify | Emit `IR::ModuleConstant` as a real Ruby constant above the class — reuses the section/ordering of `render_cva_constants`. Also: `router.push("/...")` hit detection in synchronous bodies, emit comment hint using the `@href_rewriter` when present. |
+
+**Verification**: stress-corpus re-run with before/after TODO counts; new specs for the three behaviors.
+
+### Slice 4 — Next.js page-router extensions
+
+**Why second**: every item depends on slice 1 / slice 2 plumbing that already landed. All five items touch `pages-routes` and `translate --rails-routes` together — shipping them as one slice avoids partial-state where the routes.rb expects namespaces but the view tree doesn't (or vice versa).
+
+**Behavior change to flag in the slice-4 plan**: namespace nesting changes the route table for any pages tree with multi-segment dirs. Parallel to slice 3's `as:` addition — intentional and documented.
+
+**Likely files**:
+
+| Path | Status | Scope |
+|---|---|---|
+| `lib/jsx_rosetta/pages_routing.rb` | modify | (a) Route groups: `Scanner` ignores `(group)` dirs for URL building but stores them in a new `namespace` array on `Route`. (b) Namespace nesting: when more than one non-bracket segment precedes the leaf, treat all but the last as namespaces. `Naming.route_name` and `Emitter.route_line` follow. (c) Stop skipping `_error.tsx` / `404.tsx` / `500.tsx`; emit them as `Route(controller: "errors", action: "<status>", ...)` plus a `config.exceptions_app` comment block at the top of routes.rb. (d) Stop skipping `_app.tsx` / `_document.tsx`; slice 2's view-placement gets a `layout: true` variant. |
+| `lib/jsx_rosetta/backend/phlex.rb` | modify | Accept `layout: true` on the `rails_view:` option (or split into a new `rails_layout:` option — pick at slice-4 plan time). Layout emission uses `Views::Layouts::Application < Views::Base` with the `yield if block_given?` body. |
+| `lib/jsx_rosetta/ir/lowering.rb` + `types.rb` | modify | Capture `export async function getServerSideProps(...)` / `export const getServerSideProps = ...` source verbatim into a new `IR::Component#server_data_source` field. Phlex backend emits as a TODO comment block at the top of the view, pointed at the controller action. |
+
+**Verification**: synthetic pages tree exercising each shape (route group, namespace, error page, `_app`, getServerSideProps); stress-corpus pages re-run to confirm the 82 pages still produce valid routes.
+
+### Slice C — slice-3 backend expansion
+
+**Why third (or interchangeable with slice 4)**: smallest scope. Independent of slice 4 — could ship before, after, or in parallel without conflict.
+
+**Likely files**:
+
+| Path | Status | Scope |
+|---|---|---|
+| `lib/jsx_rosetta/backend/phlex.rb` | modify | Extend `LINK_TAGS` with `form`; restructure `HREF_ATTR_NAMES` so `form` matches `action` rather than `href`. Detect the form's `method` attribute (default GET) and only rewrite when GET. |
+| `lib/jsx_rosetta/backend/view_component.rb` | modify | Accept `rails_view:` + `route_table:` Phlex-style. Output paths follow `app/views/<controller>/<action>.html.erb` (template) + `<action>_component.rb` (class). |
+| `lib/jsx_rosetta/backend/rails_view.rb` | modify | Accept `rails_view:` + `route_table:` Phlex-style. Single-file layout, path becomes `app/views/<controller>/<action>.html.erb`. |
+| `lib/jsx_rosetta.rb` | modify | Allowlist `:rails_view, :route_table` for the ViewComponent and RailsView backends (already there for Phlex). |
+| `lib/jsx_rosetta/cli.rb` | modify | Lift the `--rails-routes requires --as=phlex` guard. |
+
+**Verification**: synthetic TSX with `<form action="/x" method="get">`; CLI tests for `translate --as=view --rails-routes <dir>` and `translate --as=view_component --rails-routes <dir>`.
+
+## Sequencing
+
+```
+slice A ──┐
+          ├─→ (independent) ─→ slice 4
+slice C ──┘                    (only depends on slices 1-3, already landed)
+```
+
+**Recommended order**: A first (highest TODO-reduction-per-LOC and broadest reach), then 4 (Next.js-specific value, ships the page-router story end-to-end), then C (smallest scope, additive). Reorder freely if the user prefers — none of the three blocks any other.
+
+## Out of scope for this umbrella
+
+- **HOC unwrapping** (former #1, deliberately omitted from this plan per user direction). Belongs in its own plan when we're ready to decide on the unwrap rules across `React.memo` / `forwardRef` / `lazy` / `observer` / Redux `connect`.
+- **Anchor / query-string preservation** (former #10, deliberately omitted). Defer until a corpus hits it materially.
+- **User-side gaps** from the readiness assessment — React/Apollo hooks, theme tokens, custom-hooks modules. The gem deliberately doesn't translate these.
+
+## Risks
+
+- **Slice A condition widening false positives.** If the translator accepts a shape it shouldn't, the conditional renders against an `@ivar` that doesn't exist → render-time NameError. Mitigation: only widen to identifiers and member expressions whose root is in `prop_names` / `local_binding_names`; everything else continues to bail with a TODO. Same five-bucket discipline as the existing translator.
+
+- **Slice A const detection over-reaches.** A module-level `const FOO = useSomething()` would emit a Ruby constant referencing a JS expression. Mitigation: only lower constants whose initializer is a *literal* (string / number / boolean / null / array of literals / object of literals). Call expressions, member access, identifiers — all bail to the existing TODO block.
+
+- **Slice 4 routes.rb is a breaking change.** Namespace nesting renames route helpers for any pages tree with multi-segment dirs (`/admin/users` → `admin_users_path` rather than `admin_users_show_path`). Document it in the slice-4 plan as a behavior change, parallel to slice 3's `as:` addition. Users with custom `as:` overrides should regenerate.
+
+- **Slice C ViewComponent surface is bigger than Phlex's.** ViewComponent's sidecar layout (class + ERB template) means two emission paths instead of one. The slice-2 helpers may need extracting to a shared module before they apply cleanly.
+
+- **B1 `getServerSideProps` capture is verbatim, not translated.** Risk: users expect it to "just work" once captured. Mitigation: emit the body explicitly as `# TODO: port this to <controller>#<action>` with a clear header so the expectation is set at the comment level.

data/plans/translator_widening_slice_a.md

@@ -0,0 +1,208 @@
+# Slice A — translator widening (umbrella: `translator_widening_and_pages_followups.md`)
+
+Three independent translator changes that reduce TODO noise across every translated file. Self-contained — no Next.js / pages-routing surface area.
+
+Items from the umbrella plan:
+
+- **A1** — Conditional-render path: simple identifier / member-chain / unary tests over known bindings emit `@ivar` (or a short rendered form) with a single migration TODO, instead of the current `# TODO: translate condition: <expr>` + `if false` fallback. **Stress corpus target: ~123 TODOs (`render guard` ladder collapses + `simple-condition` lines).**
+- **A2** — Literal-shaped module-level `const` declarations (string / number / boolean / null / array of literals / object of literals) lower to `IR::ModuleConstant`. The Phlex backend emits them as real Ruby constants above the class, alongside cva constants. Non-literal initializers still fall through to the existing module-binding TODO block. **Stress corpus target: ~402 TODO blocks affected.**
+- **A3** — `router.push("/path")` references inside `useEffect` / non-handler hook bodies trigger a `# → redirect_to <helper>` annotation above the hook TODO when the route table is present. Handler bodies (`onClick={() => router.push(...)}`) stay verbatim per the project rule. **Stress corpus target: <50 occurrences, high-signal where it fires.**
+
+## A1 — Conditional-render widening
+
+### Diagnosis
+
+`safe_test_expression` in `backend/phlex.rb:894` calls `translator.translate(expression)`. The translator already handles bare identifiers / member chains / unary `!` correctly in *attribute-value* contexts. For *render-condition* contexts the same shapes produce one of two failures:
+
+1. **`"nil"` literal result** — bucket-4 hits (known-but-unresolvable locals from hook destructures, top-level `const`, or imports) translate to `"nil"` at the leaf-identifier position so the file loads in attribute-value contexts. Driving `if nil` silently false-arms the branch, so `safe_test_expression` upgrades that to the `false` fallback + TODO.
+
+2. **Translator bail (`nil` return)** — for `member-chain root`, `unary operand`, `binary operand`, bucket 4 returns `nil` to bail the whole translation. The conditional then emits `if false` + TODO.
+
+In both cases the user reads a verbatim JS expression in a comment and has to wire the Rails side manually.
+
+### Widening rule (render-condition context only)
+
+Add a new `ExpressionTranslator#translate_condition(source)` entry point. Same recursive translator, but identifier resolution differs for **bucket 4** (known-but-unresolvable locals + imports):
+
+| Position | Old behavior | New behavior |
+|---|---|---|
+| Leaf identifier | `"nil"` | `"@snake_case"` + record-as `condition_promoted_to_prop` |
+| Member-chain root | bail (return nil) | `"@snake_case"` + record + recurse into chain |
+| Unary `!` operand | bail | translate as above, prefix `!` |
+| Binary operand | bail | translate as above |
+
+Bucket-3 (props) and bucket-1 (local scope) keep their existing translations. Bucket-2 prop aliases unchanged.
+
+The promoted name set comes back via a new field on `Result` (or a sidecar accessor). `safe_test_expression` surfaces the names as a *single, short* TODO line above the `if`, e.g.:
+
+```ruby
+# TODO: render condition `loading` references binding promoted to @loading — thread it as a controller-passed prop
+if @loading
+  # …
+end
+```
+
+instead of the current
+
+```ruby
+# TODO: translate condition: loading
+if false
+  # …
+end
+```
+
+### Why not just always-widen in attribute-value contexts too
+
+Attribute-value uses (`disabled={loading}`) want the bucket-4 leaf to render *something* even when no migration plan exists (the `nil` placeholder is intentional — the page loads and the reviewer fixes it). Promoting to `@loading` everywhere would silently NameError if the user never threads the prop. Render-condition context is the safe place to widen because the test is *load-bearing* — emitting `if false` already destroys the branch's intent, so promoting beats silence.
+
+### Files
+
+| Path | Status | Scope |
+|---|---|---|
+| `lib/jsx_rosetta/backend/view_component/expression_translator.rb` | modify | New `translate_condition(source)` entry point + a `@condition_mode` flag that flips bucket-4 behavior. Track promoted names in a per-translation accumulator. |
+| `lib/jsx_rosetta/backend/phlex.rb` | modify | `safe_test_expression` calls the new entry point. `emit_conditional_branches` and `render_guard_ladder_collapse` emit a one-line promoted-binding TODO above the branch (or above the ladder) instead of the verbose verbatim-JS TODO. |
+
+### Specs
+
+| Path | Status | Coverage |
+|---|---|---|
+| `spec/backend/view_component/expression_translator_spec.rb` | modify | `translate_condition` results for hook-tuple destructure, top-level import, member-chain over local, unary `!loading`. |
+| `spec/backend/phlex_spec.rb` | modify | Conditional render emits `if @ivar` with TODO header naming the promoted binding. Guard ladder ditto. |
+
+## A2 — Literal module-level const → Ruby constant
+
+### Detector
+
+Mirror `parse_cva_binding` in `lib/jsx_rosetta/ir/lowering.rb`. The detector accepts an `init` node and returns `IR::ModuleConstant` when:
+
+- `init.type` is `StringLiteral`, `NumericLiteral`, `BooleanLiteral`, `NullLiteral` — direct literal.
+- `init.type` is `TemplateLiteral` with no interpolations — same as cva's `extract_cva_string`.
+- `init.type` is `ArrayExpression` where **every** element passes the same check recursively, OR is a `SpreadElement` referencing a known-imported binding (defer to the verbatim fallback if any element fails).
+- `init.type` is `ObjectExpression` where every property key is `Identifier` / `StringLiteral`, and every value passes recursively. Computed keys + spread bail to fallback.
+- `init.type` is `TSAsExpression` / `TSSatisfiesExpression` — recurse on the inner expression. Drop the TS annotation; Ruby has no equivalent.
+- `init.type` is `UnaryExpression` with a single `-` operator and a numeric operand — e.g., `const X = -1`.
+
+Anything else (`CallExpression`, `MemberExpression`, identifier-referencing arrays/objects) bails to the existing `LocalBinding` path → existing module-bindings TODO block.
+
+### IR
+
+New value type next to `IR::CvaBinding`:
+
+```ruby
+# A literal-shaped module-level const that lowers to a real Ruby constant.
+# Distinct from LocalBinding (which is captured verbatim as a TODO block)
+# and CvaBinding (which has structured variants/defaults). Use sites that
+# reference this binding's name are unaffected — the imported_names plumbing
+# in build_translator already bails on the bare reference; the constant
+# value just lives above the class.
+#
+# name           : String — original JS identifier (e.g. "TAGS", "COLUMNS").
+# constant_name  : String — the Ruby constant identifier
+#                  (`AST::Inflector.underscore(name).upcase`). Stored on the
+#                  IR so the backend doesn't recompute and so future
+#                  collision-detection has somewhere to bind.
+# value          : Object — the Ruby-side value as a literal-friendly
+#                  Ruby object (String, Integer, Float, true, false, nil,
+#                  Array of these, Hash with String keys of these). Backends
+#                  call `.inspect.freeze` to emit.
+IR::ModuleConstant = Data.define(:name, :constant_name, :value)
+```
+
+### Phlex emission
+
+Extend `render_module_bindings_prefix` (`backend/phlex.rb:271`) to partition module bindings three ways: `CvaBinding`, `ModuleConstant`, other.
+
+`render_module_constants(bindings)` emits a block parallel to `render_cva_constants`:
+
+```ruby
+TAGS = { "warn" => "...", "error" => "..." }.freeze
+DEFAULT_LIMIT = 50
+```
+
+The block sits above the class. Use-site references already bail to `nil` at runtime via the existing imported_names plumbing — that stays the same; future work can promote bucket-4 refs to the new constant when names match, but that's out of scope for slice A (it'd duplicate the A1 conditional-promotion work in attribute-value context).
+
+### Files
+
+| Path | Status | Scope |
+|---|---|---|
+| `lib/jsx_rosetta/ir/types.rb` | modify | Add `IR::ModuleConstant`. |
+| `lib/jsx_rosetta/ir/lowering.rb` | modify | New `parse_module_constant(init, name)` mirroring `parse_cva_binding`. Plumb into `record_module_binding`. |
+| `lib/jsx_rosetta/backend/phlex.rb` | modify | New `render_module_constants` helper. Three-way partition in `render_module_bindings_prefix`. |
+
+### Specs
+
+| Path | Status | Coverage |
+|---|---|---|
+| `spec/ir/lowering_spec.rb` | modify | Each literal shape (string, number, bool, null, array-of-literals, hash-of-literals, template-literal, TS-cast wrapper, unary minus). Non-literal initializers still produce LocalBinding. |
+| `spec/backend/phlex_spec.rb` | modify | Emitted Ruby constants land above the class with the correct name + value. Use sites still emit the existing nil-bail behavior (so the cohabitation is verified). |
+
+## A3 — `router.push` hint in non-handler bodies
+
+### Detection
+
+After lowering, hooks are captured as `IR::ReactHookCall(source: <verbatim JS>, library: :next_js | :react | …)`. For each call whose source contains a `router.push("…")` or `router.push(\`…\`)` invocation:
+
+1. Parse the JS argument with `PagesRouting::HrefRewriter.parse_template_source` / literal-extract helpers — *not* with a new parser; reuse the slice-3 helper that already classifies literal vs. template-with-holes vs. unrewritable.
+2. If `@href_rewriter` is set AND the parsed shape matches a route, prepend a hint line above the existing hook TODO block:
+
+```
+# → redirect_to claim_path(id) (translated from router.push)
+```
+
+3. If no `@href_rewriter` is set (no route table), still detect the pattern but emit just the descriptive hint:
+
+```
+# → consider redirect_to <helper> (translated from router.push)
+```
+
+4. Multiple `router.push` sites in the same hook block produce multiple hint lines.
+
+### Why scope to hook bodies
+
+`useEffect(() => router.push(...))` is the canonical redirect pattern in Next.js — that's where this fires. Event-handler bodies (extracted to `IR::EventHandler` / `IR::StimulusMethod` body sources) stay verbatim per the project rule against speculative JS-to-Ruby translation. Module-level `if (!user) router.push("/login")` would land in `LocalBinding.source` if it ever appeared at module top-level — out of scope for slice A; the hook-only target covers the realistic cases.
+
+### Files
+
+| Path | Status | Scope |
+|---|---|---|
+| `lib/jsx_rosetta/backend/phlex.rb` | modify | New `router_push_hint_lines(hook_source)` helper. Inject at the top of `hook_todo_block_lines`. |
+| `lib/jsx_rosetta/pages_routing.rb` | (possibly) | Expose a `match_path(path_string) → "<helper>(<args>)"` shortcut alongside `HrefRewriter`. Avoid duplicating the parsing logic. |
+
+### Specs
+
+| Path | Status | Coverage |
+|---|---|---|
+| `spec/backend/phlex_spec.rb` | modify | `useEffect(() => router.push("/x"))` with route table emits the helper hint; without route table emits the generic hint. Event handler with `router.push` stays unannotated (no hint above stimulus method TODO). |
+
+## Sequencing within slice A
+
+A2 → A1 → A3. Reasoning:
+
+- A2 is the largest TODO-reduction (~402 affected blocks) but the most mechanical — new IR type, new detector, new emitter. Land first to derisk.
+- A1 changes the translator's behavior in a load-bearing way (render decisions). Land second so any regressions are visible against the now-cleaner A2 baseline.
+- A3 is the smallest scope and depends only on existing plumbing. Land last.
+
+Each lands as its own commit; the umbrella `Verify Slice A` step at the end runs the full rake + stress suite before patch-level release.
+
+## Verification
+
+```bash
+bundle exec rake                           # rspec + rubocop
+bash tmp/run_phlex_stress.sh                # full corpus translate
+# compare tmp/stress/phlex_results.tsv vs. baseline (v0.5.1 stress numbers)
+ruby -c tmp/stress/phlex_out/**/*.rb 2>&1 | grep -v "Syntax OK" | head
+```
+
+Headline metrics to compare:
+
+- Clean-translation count (currently 895/929).
+- Total TODO count (currently ~3.9/file mean across the corpus).
+- Per-category TODO frequency for `translate condition`, `render guard`, `module-level constants`.
+- `ruby -c` pass count (currently 1239/1239).
+
+## Risks
+
+- **A1 false positives.** Promoting `loading` to `@loading` assumes the user adds the prop; if they don't, render-time NameError. Mitigation: the TODO line names the promoted binding explicitly, so a code review catches it. Existing behavior emits dead `if false` branches that are *also* wrong — A1 trades silent dead code for a NameError with a TODO that points at the fix.
+- **A2 constant-name collisions.** Two siblings in the same file with `const TAGS = …` would emit two `TAGS = …` lines. Lowering already captures module bindings once per program via `lower_all` (each sibling sees the same array by reference), so the existing module-bindings TODO doesn't collide — same property applies here. Spec covers the multi-component-per-file case.
+- **A3 false negatives.** A `router.push` argument we can't classify (`router.push(buildUrl(x))`) silently emits no hint. Acceptable: the existing hook TODO still surfaces the source verbatim; the hint is purely additive.
+- **A2 mutation hazard.** `.freeze` on a hash literal protects the hash, not its values. If a value is itself a mutable array, callers can still mutate the inner array. Not a translation-correctness risk; a Ruby idiom hint at most. Skip deep-freeze.