admin_suite 0.4.0 → 0.6.1

data/test/lib/form_field_renderer_test.rb

@@ -6,31 +6,52 @@ module AdminSuite
   class FormFieldRendererTest < ActionView::TestCase
     include AdminSuite::BaseHelper
 
-    Record = Struct.new(:name, :body, :enabled) do
+    Record = Struct.new(:name, :body, :enabled, :error_messages) do
+      # Both a class-level and an instance-level `model_name` are needed:
+      # `render_toggle_field`/`render_searchable_select`/`render_multi_select`
+      # all call `resource.class.model_name.param_key` (class-level), while
+      # `form_with` itself wants the instance-level accessor. (`extend
+      # ActiveModel::Naming` would give both via its own delegation, but
+      # then redefining `model_name` below to force the short "Record" name
+      # -- rather than the fully-qualified nested constant name -- clashes
+      # with that delegation and triggers a "method redefined" warning.
+      # Defining both explicitly avoids it.) The pre-existing instance-level
+      # `model_name` never covered the class-level call site because no test
+      # here exercised `:toggle`/`:searchable_select`/`:multi_select` before.
+      def self.model_name
+        @model_name ||= ActiveModel::Name.new(self, nil, "Record")
+      end
+
       def to_model = self
-      def model_name = ActiveModel::Name.new(self.class, nil, "Record")
+      def model_name = self.class.model_name
       def persisted? = false
       def to_key = nil
 
       # render_form_field unconditionally calls `resource.errors[field.name]`
       # for every field type (to add the error border class / message), so
       # the double needs an `errors` object supporting `[]` -> Array-like
-      # (`.any?`, `.first`). No test here exercises an actual validation
-      # error, so a Hash defaulting to `[]` is sufficient.
-      def errors = Hash.new([])
+      # (`.any?`, `.first`). Most tests here don't exercise an actual
+      # validation error, so a Hash defaulting to `[]` is sufficient; tests
+      # that do pass `error_messages` (a plain Hash of field name -> Array of
+      # messages) to get real per-field errors without losing the default.
+      def errors
+        Hash.new([]).merge(error_messages || {})
+      end
     end
 
-    def field(name, type)
+    def field(name, type, **overrides)
       Admin::Base::Resource::FieldDefinition.new(
-        name: name, type: type, required: false, label: name.to_s.humanize,
-        readonly: false, multiple: false, creatable: false, preview: true
+        {
+          name: name, type: type, required: false, label: name.to_s.humanize,
+          readonly: false, multiple: false, creatable: false, preview: true
+        }.merge(overrides)
       )
     end
 
-    def render_field(type, name: :name)
-      record = Record.new("x", "y", true)
+    def render_field(type, name: :name, error_messages: nil, **field_overrides)
+      record = Record.new("x", "y", true, error_messages)
       html = nil
-      form_with(model: record, url: "/", scope: :record) { |f| html = render_form_field(f, field(name, type), record) }
+      form_with(model: record, url: "/", scope: :record) { |f| html = render_form_field(f, field(name, type, **field_overrides), record) }
       html.to_s
     end
 
@@ -60,5 +81,56 @@ module AdminSuite
     test "the label is rendered for every field" do
       assert_includes render_field(:text), "Name"
     end
+
+    test "a field with a validation error renders the red border and error message" do
+      html = render_field(:text, error_messages: { name: [ "is invalid" ] })
+      assert_includes html, "border-red-500"
+      assert_includes html, "is invalid"
+    end
+
+    # The full set of field types `FieldRendererRegistry` is expected to
+    # have registered (see `lib/admin_suite/ui/field_renderer_registry.rb`).
+    # Pinned explicitly here, NOT derived from the registry itself: an
+    # earlier version of this test iterated `handlers.keys` directly, which
+    # cannot detect a deletion -- a deleted key simply stops appearing in
+    # the iteration, so the loop body never runs for it and the test still
+    # passes with one fewer assertion (verified by deleting the `:toggle`
+    # registration: 42 assertions became 41, 0 failures). The
+    # size-and-membership assertion in the test below is what actually
+    # catches that; a self-referential "iterate the thing you're testing"
+    # loop cannot.
+    EXPECTED_FIELD_TYPES = %i[
+      textarea url email number toggle label select searchable_select
+      dependent_select multi_select tags image attachment trix rich_text
+      markdown file datetime date time json code text string
+    ].freeze
+
+    # :trix/:rich_text both call `f.rich_text_area`, which only exists once
+    # ActionText's FormBuilder extension is loaded -- and per the plan's
+    # Test-harness fact #2, this dummy app is deliberately database-free and
+    # never requires `action_text/engine`. Confirmed by running the
+    # rendering test with them included: `NoMethodError: undefined method
+    # 'rich_text_area'`, not a bug in FieldRendererRegistry. There is no way
+    # to pin these two types in this harness without pulling in ActionText
+    # (and, transitively, ActiveRecord) — out of scope here. Named
+    # explicitly (not an implicit skip) so `EXPECTED_FIELD_TYPES.size` and
+    # the number of types actually exercised below both stay visible and
+    # add up: 24 expected, 2 excluded, 22 rendered.
+    UNTESTABLE_WITHOUT_ACTION_TEXT = %i[trix rich_text].freeze
+
+    test "the registry has exactly the expected set of field types, no more, no fewer" do
+      assert_equal EXPECTED_FIELD_TYPES.sort, AdminSuite::UI::FieldRendererRegistry.handlers.keys.sort
+    end
+
+    test "every expected field type except the ActionText-only ones renders non-empty markup" do
+      sample_collection = [ [ "One", 1 ], [ "Two", 2 ] ]
+      needs_collection = %i[select searchable_select dependent_select multi_select tags]
+
+      (EXPECTED_FIELD_TYPES - UNTESTABLE_WITHOUT_ACTION_TEXT).each do |type|
+        overrides = needs_collection.include?(type) ? { collection: sample_collection } : {}
+        html = render_field(type, **overrides)
+        assert html.present?, "expected #{type.inspect} to render non-empty markup"
+      end
+    end
   end
 end

data/test/lib/format_table_cell_test.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require "test_helper"
+
+module AdminSuite
+  # `format_table_cell` had no direct unit test anywhere in the suite before
+  # this file -- it was only exercised indirectly through
+  # `association_linking_test.rb`'s AR-focused fixtures. Covers the branches
+  # not already pinned there, and specifically the Integer/Float/BigDecimal
+  # delimiting added to match `format_show_value` (see
+  # `ShowValueFormatterTest#"integers and floats render delimited"`).
+  class FormatTableCellTest < ActionView::TestCase
+    include AdminSuite::BaseHelper
+
+    test "nil renders the em dash placeholder" do
+      assert_equal "—", format_table_cell(nil)
+    end
+
+    test "booleans render Yes/No" do
+      assert_equal "Yes", format_table_cell(true)
+      assert_equal "No", format_table_cell(false)
+    end
+
+    test "Time and DateTime render a short date-time" do
+      assert_equal "Jan 02, 03:04", format_table_cell(Time.utc(2026, 1, 2, 3, 4))
+      assert_equal "Jan 02, 03:04", format_table_cell(DateTime.new(2026, 1, 2, 3, 4))
+    end
+
+    test "Date renders a short date" do
+      assert_equal "Jan 02, 2026", format_table_cell(Date.new(2026, 1, 2))
+    end
+
+    test "integers and floats render delimited, matching format_show_value" do
+      assert_equal "1,234,567", format_table_cell(1_234_567)
+      assert_equal "1,234.5", format_table_cell(1234.5)
+    end
+
+    test "BigDecimal renders delimited rather than in exponential notation" do
+      result = format_table_cell(BigDecimal("9876.5"))
+      assert_includes result, "9,876"
+      refute_includes result, "0.98765e4"
+    end
+
+    test "plain strings are truncated at 50 characters" do
+      assert_equal "hello", format_table_cell("hello")
+      assert_equal ("x" * 47) + "...", format_table_cell("x" * 60)
+    end
+  end
+end

data/test/lib/index_includes_test.rb

@@ -0,0 +1,223 @@
+# frozen_string_literal: true
+
+require "test_helper"
+
+# Fixtures for the `includes:` DSL option (Task 4, phase 2b). A scope that
+# genuinely supports `#includes` and records/validates the call, so the
+# controller's "apply when the scope responds" and "degrade when
+# `.includes` itself raises" paths are both exercisable end-to-end. The
+# `LinkingFixtures::Deal`/`ReadOnlyResourceFixtures::Relation` pair (no
+# `#includes` at all) already covers the "skip silently" path -- reused
+# below rather than duplicated.
+module IndexIncludesFixtures
+  class IncludesCapableRelation
+    include Enumerable
+
+    KNOWN_ASSOCIATIONS = %i[company owner].freeze
+
+    attr_reader :includes_calls
+
+    def initialize(records)
+      @records = records
+      @includes_calls = []
+    end
+
+    def each(&block) = @records.each(&block)
+    def count(*) = @records.count
+    def offset(*) = self
+    def limit(*) = self
+
+    # Mirrors real ActiveRecord's eventual `ActiveRecord::AssociationNotFoundError`
+    # for an unknown association name -- raised here at call time (rather
+    # than lazily, as real AR does) so the controller's rescue path around
+    # the `.includes` call site is directly exercisable.
+    def includes(*associations)
+      flat = associations.flatten
+      invalid = flat.reject { |a| KNOWN_ASSOCIATIONS.include?(a.respond_to?(:to_sym) ? a.to_sym : a) }
+      raise ArgumentError, "Association named #{invalid.first.inspect} was not found" if invalid.any?
+
+      @includes_calls << flat
+      self
+    end
+  end
+
+  class Widget
+    extend ActiveModel::Naming
+
+    attr_reader :id, :name
+
+    def initialize(id:, name:)
+      @id = id
+      @name = name
+    end
+
+    RELATION = IncludesCapableRelation.new([ new(id: 1, name: "Widget One") ])
+
+    def self.all = RELATION
+    def self.column_names = %w[id name]
+    def self.primary_key = "id"
+    def self.columns_hash = { "id" => Struct.new(:type).new(:integer) }
+    def self.find(id) = all.find { |w| w.to_param == id.to_s }
+    def to_param = id.to_s
+    def attributes = { "id" => id, "name" => name }
+  end
+
+  class BadWidget
+    extend ActiveModel::Naming
+
+    attr_reader :id, :name
+
+    def initialize(id:, name:)
+      @id = id
+      @name = name
+    end
+
+    RELATION = IncludesCapableRelation.new([ new(id: 1, name: "Bad Widget") ])
+
+    def self.all = RELATION
+    def self.column_names = %w[id name]
+    def self.primary_key = "id"
+    def self.columns_hash = { "id" => Struct.new(:type).new(:integer) }
+    def self.find(id) = all.find { |w| w.to_param == id.to_s }
+    def to_param = id.to_s
+    def attributes = { "id" => id, "name" => name }
+  end
+
+  # Self-contained (this file is runnable standalone via
+  # `rake test TEST=test/lib/index_includes_test.rb`, so it can't reach
+  # into fixtures defined only in association_linking_test.rb): a scope
+  # with no `#includes` method at all, mirroring
+  # `ReadOnlyResourceFixtures::Relation`, backing a resource that
+  # nonetheless declares `includes :company`. Exercises the "skip
+  # silently, don't raise" path.
+  class NoIncludesWidget
+    extend ActiveModel::Naming
+
+    attr_reader :id, :name
+
+    def initialize(id:, name:)
+      @id = id
+      @name = name
+    end
+
+    def self.all = ReadOnlyResourceFixtures::Relation.new([ new(id: 1, name: "Plain Widget") ])
+    def self.column_names = %w[id name]
+    def self.primary_key = "id"
+    def self.columns_hash = { "id" => Struct.new(:type).new(:integer) }
+    def self.find(id) = all.find { |w| w.to_param == id.to_s }
+    def to_param = id.to_s
+    def attributes = { "id" => id, "name" => name }
+  end
+end
+
+module Admin
+  module Resources
+    class IndexIncludesWidgetResource < Admin::Base::Resource
+      model IndexIncludesFixtures::Widget
+      portal :ops
+      section :observability
+
+      index do
+        columns { column :name }
+        includes :company, :owner
+      end
+    end
+
+    class IndexIncludesBadWidgetResource < Admin::Base::Resource
+      model IndexIncludesFixtures::BadWidget
+      portal :ops
+      section :observability
+
+      index do
+        columns { column :name }
+        includes :nonexistent_association
+      end
+    end
+
+    class IndexIncludesNoIncludesWidgetResource < Admin::Base::Resource
+      model IndexIncludesFixtures::NoIncludesWidget
+      portal :ops
+      section :observability
+
+      index do
+        columns { column :name }
+        includes :company
+      end
+    end
+  end
+end
+
+module AdminSuite
+  class IndexIncludesTest < ActionDispatch::IntegrationTest
+    test "IndexConfig#includes stores the list of associations" do
+      config = Admin::Base::Resource::IndexConfig.new
+      config.includes(:company, :owner)
+      assert_equal [ :company, :owner ], config.includes_list
+    end
+
+    test "IndexConfig#includes defaults to an empty list" do
+      assert_equal [], Admin::Base::Resource::IndexConfig.new.includes_list
+    end
+
+    test "IndexConfig#includes drops a nil association instead of storing garbage" do
+      config = Admin::Base::Resource::IndexConfig.new
+      config.includes(nil)
+      assert_equal [], config.includes_list
+    end
+
+    test "IndexConfig#includes tolerates a String association name" do
+      config = Admin::Base::Resource::IndexConfig.new
+      config.includes("company")
+      assert_equal [ "company" ], config.includes_list
+    end
+
+    test "the DSL exposes includes: on a resource's index_config" do
+      assert_equal [ :company, :owner ], Admin::Resources::IndexIncludesWidgetResource.index_config.includes_list
+    end
+
+    test "the controller applies includes: to a scope that responds to includes" do
+      IndexIncludesFixtures::Widget::RELATION.includes_calls.clear
+
+      get "/internal/admin_suite/ops/index_includes_widgets"
+      assert_response :success
+
+      assert_equal [ [ :company, :owner ] ], IndexIncludesFixtures::Widget::RELATION.includes_calls
+    end
+
+    test "a scope whose includes raises for a bad association degrades instead of 500ing" do
+      logged = []
+      Rails.logger.stub(:warn, ->(msg) { logged << msg }) do
+        get "/internal/admin_suite/ops/index_includes_bad_widgets"
+      end
+
+      assert_response :success
+      assert_includes response.body, "Bad Widget"
+      # The rescue in `apply_index_includes` logs the failure -- pinning
+      # that here so the "skipped silently" test below (which asserts NO
+      # warn fires) is actually distinguishing two different code paths,
+      # not just two tests that both happen to pass.
+      assert_equal 1, logged.size
+      assert_includes logged.first, "nonexistent_association"
+    end
+
+    test "a scope that does not respond to includes is skipped silently, not raised" do
+      refute IndexIncludesFixtures::NoIncludesWidget.all.respond_to?(:includes)
+
+      logged = []
+      Rails.logger.stub(:warn, ->(msg) { logged << msg }) do
+        get "/internal/admin_suite/ops/index_includes_no_includes_widgets"
+      end
+
+      assert_response :success
+      assert_includes response.body, "Plain Widget"
+      # `apply_index_includes`'s `respond_to?(:includes)` guard exists so a
+      # scope that can never support includes doesn't spam a warning on
+      # every request. Deleting that guard would still return a 200 here
+      # (the catch-all rescue produces an identical response), so the
+      # response alone doesn't prove the guard does anything -- this
+      # asserts its actual purpose: no warn fires on this path. Contrast
+      # with the bad-association test above, where one does.
+      assert_empty logged
+    end
+  end
+end

data/test/lib/mcp_serializer_test.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+require "test_helper"
+
+class McpSerializerTest < ActiveSupport::TestCase
+  Column = Data.define(:name)
+  Index = Data.define(:columns_list)
+  Config = Data.define(:index_config)
+
+  test "emits only the resource's declared columns" do
+    record = Struct.new(:id, :name, :secret_token).new(1, "Widget", "sh-hh")
+    config = Config.new(Index.new([Column.new(:id), Column.new(:name)]))
+
+    row = AdminSuite::Mcp::Serializer.index_row(record, config)
+
+    assert_equal %w[id name], row.keys.map(&:to_s).sort
+    refute_includes row.keys.map(&:to_s), "secret_token"
+  end
+
+  test "a raising accessor degrades that cell, not the row" do
+    record = Object.new
+    def record.id = 1
+    def record.name = raise("boom")
+    config = Config.new(Index.new([Column.new(:id), Column.new(:name)]))
+
+    row = AdminSuite::Mcp::Serializer.index_row(record, config)
+
+    assert_equal 1, row[:id]
+    assert_nil row[:name]
+  end
+
+  test "association panels return bounded rows containing only declared columns" do
+    show = Admin::Base::Resource::ShowConfig.new
+    show.panel :children, association: :children, columns: [:name], limit: 500
+    config = Struct.new(:show_config).new(show)
+    child = Struct.new(:name, :secret_token).new("Visible", "private")
+    record = Struct.new(:children).new(Array.new(150, child))
+
+    payload = AdminSuite::Mcp::Serializer.associations_payload(record, config, max_rows: 100)
+    assert_equal 100, payload.fetch(:children).fetch(:rows).size
+    assert_equal({ name: "Visible" }, payload.fetch(:children).fetch(:rows).first)
+    assert_equal 100, payload.fetch(:children).fetch(:applied_limit)
+    refute_includes JSON.generate(payload), "private"
+  end
+
+  test "association panels without declared columns do not serialize model attributes" do
+    show = Admin::Base::Resource::ShowConfig.new
+    show.panel :children, association: :children
+    config = Struct.new(:show_config).new(show)
+    record = Object.new
+    def record.children = raise("must not load an undeclared field set")
+
+    assert_empty AdminSuite::Mcp::Serializer.associations_payload(record, config, max_rows: 100)
+  end
+
+  test "a content lambda serializes the proc result, not a missing attribute" do
+    record = Struct.new(:id).new(1)
+    column = Admin::Base::Resource::ColumnDefinition.new(name: :listings_count, content: ->(_r) { 42 })
+    config = Config.new(Index.new([column]))
+
+    assert_equal 42, AdminSuite::Mcp::Serializer.index_row(record, config)[:listings_count]
+  end
+
+  test "a label lambda serializes the proc result" do
+    record = Struct.new(:id).new(1)
+    column = Admin::Base::Resource::ColumnDefinition.new(name: :status, content: ->(_r) { "active" }, type: :label)
+    config = Config.new(Index.new([column]))
+
+    assert_equal "active", AdminSuite::Mcp::Serializer.index_row(record, config)[:status]
+  end
+
+  test "declared times and associations serialize as parseable primitives, not heap dumps" do
+    created_at = Time.utc(2026, 9, 10, 12, 0, 0)
+    application = SerializerApplication.new(id: 7, name: "Acme")
+    record = Struct.new(:created_at, :application, :blob).new(created_at, application, SerializerOpaque.new)
+    config = Config.new(Index.new([Column.new(:created_at), Column.new(:application), Column.new(:blob)]))
+
+    row = AdminSuite::Mcp::Serializer.index_row(record, config)
+    text = AdminSuite::Mcp::Serializer.dump(row)
+
+    assert_equal "2026-09-10T12:00:00Z", row[:created_at]
+    assert_equal created_at, Time.iso8601(row[:created_at])
+    assert_equal "Acme", row[:application]
+    refute_match(/#<|0x[0-9a-f]+/i, text)
+  end
+
+  test "a missing association panel degrades that panel instead of raising" do
+    show = Admin::Base::Resource::ShowConfig.new
+    show.panel :children, association: :missing_kids, columns: [:name]
+    config = Struct.new(:show_config).new(show)
+
+    payload = AdminSuite::Mcp::Serializer.associations_payload(Object.new, config, max_rows: 100)
+
+    assert_equal [], payload.fetch(:children).fetch(:rows)
+  end
+
+  class SerializerApplication < ActiveRecord::Base
+    attr_reader :id, :name
+
+    def initialize(id:, name:)
+      @id = id
+      @name = name
+    end
+  end
+
+  class SerializerOpaque; end
+end

data/test/lib/query_test.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require "test_helper"
+
+class QueryTest < ActiveSupport::TestCase
+  Config = Struct.new(:model_class, :index_config)
+  IndexConfig = Struct.new(
+    :per_page,
+    :includes_list,
+    :searchable_fields,
+    :filters_list,
+    :default_sort,
+    :sortable_fields,
+    :default_sort_direction
+  )
+
+  class RaisingIncludesRelation < ReadOnlyResourceFixtures::Relation
+    def includes(*)
+      raise ArgumentError, "bad association"
+    end
+  end
+
+  class Model
+    class << self
+      attr_accessor :relation
+
+      def all = relation
+    end
+  end
+
+  test "per_page falls back to the DSL value when no param is given" do
+    query = AdminSuite::Query.new(resource_config: config_with(per_page: 30), params: {})
+
+    assert_equal 30, query.per_page
+  end
+
+  test "per_page honours the param" do
+    query = AdminSuite::Query.new(resource_config: config_with(per_page: 30), params: { per_page: "50" })
+
+    assert_equal 50, query.per_page
+  end
+
+  test "per_page clamps to MAX_PAGE_SIZE" do
+    query = AdminSuite::Query.new(resource_config: config_with(per_page: 30), params: { per_page: "999999" })
+
+    assert_equal AdminSuite::Query::MAX_PAGE_SIZE, query.per_page
+  end
+
+  test "per_page falls back for junk and non-positive values" do
+    ["abc", "0", "-5", nil, "", [], true].each do |value|
+      query = AdminSuite::Query.new(resource_config: config_with(per_page: 30), params: { per_page: value })
+
+      assert_equal 30, query.per_page, "per_page: #{value.inspect} must fall back to the DSL value"
+    end
+  end
+
+  test "the cap applies to DSL defaults as well as explicit page sizes" do
+    [nil, "", "bad", 0, -1, [], true, 5000].each do |value|
+      query = AdminSuite::Query.new(resource_config: config_with(per_page: 500),
+        params: { per_page: value }, max_page_size: 40)
+      assert_equal 40, query.per_page, "per_page=#{value.inspect}"
+    end
+  end
+
+  test "per_page remains a positive integer when max_page_size is below 1" do
+    [0, -5, nil].each do |cap|
+      query = AdminSuite::Query.new(
+        resource_config: config_with(per_page: 30),
+        params: { per_page: "10" },
+        max_page_size: cap
+      )
+
+      assert_kind_of Integer, query.per_page, "max_page_size=#{cap.inspect}"
+      assert_operator query.per_page, :>, 0, "max_page_size=#{cap.inspect}"
+    end
+  end
+
+  test "a raising includes degrades to the unoptimized scope instead of raising" do
+    relation = RaisingIncludesRelation.new([])
+    Model.relation = relation
+    query = AdminSuite::Query.new(resource_config: config_with(per_page: 25, includes: [:nope]), params: {})
+
+    assert_same relation, query.scope
+  end
+
+  private
+
+  def config_with(per_page:, includes: [])
+    Config.new(Model, IndexConfig.new(per_page, includes, [], [], nil, [], :asc))
+  end
+end

data/test/lib/removed_deprecations_test.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require "test_helper"
+
+class RemovedDeprecationsTest < ActiveSupport::TestCase
+  test "the gem has no legacy Gleania renderer implementations or defaults" do
+    refute defined?(AdminSuite::Renderers::LegacyGleania)
+    %i[prompt_template_preview messages_preview tool_args_preview turn_messages_preview].each do |key|
+      assert_nil AdminSuite::RendererRegistry.lookup_default(key)
+    end
+  end
+
+  test "exportable is no longer a resource DSL method" do
+    refute Admin::Base::Resource.respond_to?(:exportable)
+  end
+end

data/test/lib/renderer_test.rb

@@ -116,7 +116,14 @@ module AdminSuite
       assert_equal 1, logged.size
       assert_includes logged.first, key.to_s
       assert_includes logged.first, "deprecated"
-      assert_includes logged.first, "0.5.0"
+      # Deliberately a hardcoded literal, not read off
+      # DEPRECATION_MESSAGE_FORMAT: reading the version out of the constant
+      # under test and asserting the message contains it is true by
+      # construction (format() only substitutes %<key>s, never the version
+      # digits), so it can never fail on a wrong retarget -- exactly the
+      # property this test exists to catch. If the removal target changes
+      # again, this literal must be updated by hand; that's the point.
+      assert_includes logged.first, "0.6.0"
     ensure
       AdminSuite.config.custom_renderers.delete(key)
     end
@@ -144,6 +151,12 @@ module AdminSuite
       assert_includes html, "host-class-7"
       refute_includes html, "Hello 7"
     ensure
+      # `register_default` seeds AdminSuite's *permanent* default store (the
+      # same one the built-ins live in), so this probe key must be removed
+      # via `unregister_default` -- unlike `unregister`, which only ever
+      # touches the explicit store and would silently leave this key behind
+      # for every test that runs afterward.
+      AdminSuite::RendererRegistry.unregister_default(key)
       if Admin::Renderers.const_defined?(:HostBeatsDefaultProbeRenderer, false)
         Admin::Renderers.send(:remove_const, :HostBeatsDefaultProbeRenderer)
       end
@@ -172,12 +185,15 @@ module AdminSuite
     test "a registered renderer class wins over the built-in case branches" do
       # :json_preview has a legacy case branch; a registered class must take it over.
       #
-      # Task 4 registers :json_preview as a permanent alias to JsonRenderer
-      # at require time, so — unlike when this test was first written —
-      # there is now always a prior registration to restore. Unregistering
-      # unconditionally in `ensure` would delete that alias process-wide for
-      # every test that runs after this one (a real, order-dependent bug
-      # this exact test used to hide).
+      # Task 4 registers :json_preview as a permanent alias to JsonRenderer,
+      # but via `register_default` (the gem-defaults store), not `register`
+      # (the explicit store). `lookup` below only ever reads the explicit
+      # store, so `previous` is nil here -- there is no explicit registration
+      # to save or restore, and the `ensure` branch's plain `unregister` is
+      # a safe no-op that cannot touch the permanent default alias (which
+      # only `unregister_default` could remove). This test still needs the
+      # save/restore shape below in case some future test registers
+      # :json_preview explicitly and forgets to clean up after itself.
       previous = AdminSuite::RendererRegistry.lookup(:json_preview)
       AdminSuite::RendererRegistry.register(:json_preview, GreetingRenderer)
       assert_includes render_custom_section(Record.new(6), :json_preview), "Hello 6"