plutonium 0.60.1 → 0.60.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 371d9fea402116abc683c5a86c2a23ff54d6e093a5d5d64860a905cd2fb64b72
-  data.tar.gz: 6fc951e3e6ab822ee42c17ee843b0373b185e9e2d54b63c68906391bae04d07b
+  metadata.gz: bf3e52945d9a07683b9af721fd0c00f25d8850a63d7631a8a304135e13484232
+  data.tar.gz: 292591ab6eacc2f3565c9e959d62510e12b6e56d609ede2002372c2869b12cf5
 SHA512:
-  metadata.gz: e3b2bbce710220fe7cdaab63cb0b35c5b271cf4c07fe246fbc6a5a96cc178b1b223947150e547bc763c5adb59454d685e50984e6978a7427813d2f8182f72fdc
-  data.tar.gz: c243e2aa38c0ca4942655791b6a9ed8efc1e037d90ec63c1f07e1051ef4fe7fc8abf1b12af5dcb916632c301eb3eb9bdb3c7d7f4818a347992fac3a5ecc142e2
+  metadata.gz: 0f69cf663aa031cc3073717587c589a74bad312d9a2dad5088cb0798b07d5c3adef879f82f9cf6a25fc0a64a7d0fc996feef5f49048b26c63c6fe6b1178ae23f
+  data.tar.gz: 57495b760f039d03363fab2035726e00f972c581610e1d36048f6610c0a83c6777eaf22a8630d91e8c0fd24c71e171d0604b62fe1bd773f76c66cdd2f0ea4dce

data/.claude/skills/plutonium-ui/SKILL.md

@@ -506,7 +506,15 @@ Plutonium.configure do |config|
 end
 ```
 
-`:plain` keeps the Topbar but drops the icon rail. Override per-controller (and so per-portal, since it's an inherited `class_attribute`) with the `rail` DSL — `rail false` / `rail true`; `rail nil` (default) inherits the shell default, `rail?` reads the resolved value:
+`:plain` keeps the Topbar but drops the icon rail. **Shell resolves global → engine → controller**, each overriding the one above (`nil` falls through); read it with `controller.shell`:
+
+```ruby
+config.shell = :plain                       # 1. global default
+class CustomerPortal::Engine; shell :plain;  # 2. per-engine (lib/engine.rb)
+class DashboardController; shell :modern;     # 3. per-controller (overrides engine/global)
+```
+
+Alongside `shell`, the controller-only `rail` DSL flips just the rail (inherited `class_attribute`, so a portal opts in/out once in its concern) — `rail false` / `rail true`; `rail nil` (default) inherits the resolved shell, `rail?` reads the resolved value:
 
 ```ruby
 module CustomerPortal::Concerns::Controller

data/CHANGELOG.md

@@ -1,3 +1,8 @@
+## [0.60.2] - 2026-06-15
+
+### 🚀 Features
+
+- *(layout)* Resolve shell across global, engine, and controller tiers
 ## [0.60.1] - 2026-06-15
 
 ### 🚀 Features

data/docs/reference/ui/layouts.md

@@ -18,15 +18,39 @@ If you're starting fresh, use `:modern`. `:classic` exists so apps upgrading fro
 
 ## Shell variants & the icon rail
 
-`config.shell` selects the chrome for the whole app:
+The shell variant selects the page chrome:
 
 - `:modern` (default) — Topbar plus the desktop icon rail.
-- `:plain` — Topbar but **no** icon rail. The Topbar is kept; only the rail is removed, so the whole app is rail-less.
+- `:plain` — Topbar but **no** icon rail. The Topbar is kept; only the rail is removed, so the surface is rail-less.
 - `:classic` — legacy Header/Sidebar (upgrade paths only).
 
-### Per-controller / per-portal override
+### Resolving the shell (global → engine → controller)
 
-Any Plutonium resource controller exposes a class-level `rail` DSL that overrides the shell default. It's a `class_attribute`, so it's inherited: a portal opts its entire surface in or out by calling `rail false` (or `rail true`) once in its controller concern.
+The shell resolves across three layers, each overriding the one above it:
+
+```ruby
+# 1. Global default (config/initializers/plutonium.rb)
+Plutonium.configure { |config| config.shell = :modern }
+
+# 2. Per-engine — set it on a portal/package engine (lib/engine.rb)
+module CustomerPortal
+  class Engine < Rails::Engine
+    include Plutonium::Portal::Engine
+    shell :plain   # this whole portal is rail-less
+  end
+end
+
+# 3. Per-controller — overrides the engine/global default for one controller (and subclasses)
+class DashboardController < ResourceController
+  shell :modern   # opt this controller back into the rail
+end
+```
+
+An unset engine/controller value (`nil`) falls through to the next layer. Read the resolved value with the `shell` helper (`controller.shell`).
+
+### `rail` — a controller-level rail toggle
+
+Alongside `shell`, any resource controller exposes a class-level `rail` DSL that flips just the icon rail without changing the shell. It's a `class_attribute`, so it's inherited — a portal opts its entire surface in or out by calling `rail false` (or `rail true`) once in its controller concern:
 
 ```ruby
 module CustomerPortal
@@ -39,7 +63,7 @@ module CustomerPortal
 end
 ```
 
-`rail nil` (the default) inherits the shell default — the rail shows when `config.shell == :modern`. Read the resolved value with the `rail?` predicate.
+`rail nil` (the default) inherits the resolved shell — the rail shows when the resolved `shell == :modern`. Read the resolved value with the `rail?` predicate.
 
 ### Stable CSS hooks
 

data/lib/plutonium/core/controller.rb

@@ -47,7 +47,8 @@ module Plutonium
         helper_method :registered_resources
 
         class_attribute :_rail_enabled, instance_writer: false, default: nil
-        helper_method :rail?
+        class_attribute :_shell, instance_writer: false, default: nil
+        helper_method :rail?, :shell
       end
 
       class_methods do
@@ -56,6 +57,12 @@ module Plutonium
         def rail(enabled)
           self._rail_enabled = enabled
         end
+
+        # Set the shell variant for this controller and its subclasses,
+        # overriding the engine/global default. nil (default) inherits.
+        def shell(value)
+          self._shell = value
+        end
       end
 
       # Whether the modern icon rail is active for this request. Resolves the
@@ -63,7 +70,19 @@ module Plutonium
       # Public: the resource layout calls `controller.rail?`.
       def rail?
         return _rail_enabled unless _rail_enabled.nil?
-        Plutonium.configuration.shell == :modern
+        shell == :modern
+      end
+
+      # Resolved shell variant for this request: controller override, else the
+      # engine's shell, else the global Plutonium.configuration.shell.
+      def shell
+        return _shell unless _shell.nil?
+
+        engine = current_engine
+        engine_shell = engine.shell unless engine == Rails.application.class
+        return engine_shell unless engine_shell.nil?
+
+        Plutonium.configuration.shell
       end
 
       private

data/lib/plutonium/package/engine.rb

@@ -35,6 +35,16 @@ module Plutonium
           end
         end
       end
+
+      class_methods do
+        # Shell variant for this engine's controllers (:modern / :plain /
+        # :classic). Overrides the global Plutonium.configuration.shell and is
+        # itself overridden by a controller's own `shell`. Unset (nil) inherits.
+        def shell(value = nil)
+          @shell = value unless value.nil?
+          @shell
+        end
+      end
     end
   end
 end

data/lib/plutonium/ui/layout/base.rb

@@ -52,7 +52,7 @@ module Plutonium
         #   signal) for non-classic shells, since Turbo Drive does not update
         #   <html> attributes across cross-URL visits.
         def render_pre_paint_scripts
-          manage_no_rail = Plutonium.configuration.shell != :classic
+          manage_no_rail = pre_paint_shell != :classic
           script do
             raw(safe(<<~JS))
               (function () {
@@ -80,6 +80,11 @@ module Plutonium
           end
         end
 
+        # Shell variant used by pre-paint scripts. Base uses the global config
+        # (safe for non-resource layouts whose controllers lack #shell);
+        # ResourceLayout overrides this to the resolved shell.
+        def pre_paint_shell = Plutonium.configuration.shell
+
         def render_body(&)
           body(**body_attributes) {
             render_before_main

data/lib/plutonium/ui/layout/resource_layout.rb

@@ -8,6 +8,12 @@ module Plutonium
         # the controller's resolution (shell default + per-controller `rail`).
         def rail? = controller.rail?
 
+        def shell = controller.shell
+
+        # Override Base's seam so all pre-paint shell logic uses the resolved
+        # (controller/engine/global) shell rather than only the global config.
+        def pre_paint_shell = shell
+
         # Sets pu-rail-pinned immediately on initial page load so the rail
         # renders in its pinned state from the first frame. Turbo navigations
         # are handled by the turbo:before-render listener in Base. Skipped
@@ -34,13 +40,13 @@ module Plutonium
         # Scoped to the modern family — :classic keeps its own offsets.
         def html_attributes
           attrs = super
-          return attrs if Plutonium.configuration.shell == :classic
+          return attrs if shell == :classic
 
           rail? ? attrs : mix(attrs, {class: "pu-no-rail"})
         end
 
         def main_attributes
-          classes = if Plutonium.configuration.shell == :classic
+          classes = if shell == :classic
             "pt-20 lg:ml-64"
           else
             rail? ? "pt-16 pb-6 px-6 lg:pl-20" : "pt-16 pb-6 px-6"

data/lib/plutonium/version.rb

@@ -1,5 +1,5 @@
 module Plutonium
-  VERSION = "0.60.1"
+  VERSION = "0.60.2"
   NEXT_MAJOR_VERSION = VERSION.split(".").tap { |v|
     v[1] = v[1].to_i + 1
     v[2] = 0

data/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@radioactive-labs/plutonium",
-  "version": "0.60.1",
+  "version": "0.60.2",
   "description": "Build production-ready Rails apps in minutes, not days. Convention-driven, fully customizable, AI-ready.",
   "type": "module",
   "main": "src/js/core.js",

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: plutonium
 version: !ruby/object:Gem::Version
-  version: 0.60.1
+  version: 0.60.2
 platform: ruby
 authors:
 - Stefan Froelich