haveapi 0.31.1 → 0.32.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 61839695eb2b83a98b003c909eeee8de4dd571cdf4b17a519f3ae4519dfcd4cf
-  data.tar.gz: 98f3dbf9483db43feba421bd33a24a3efe1951228dd3cad41b1219e9e881661a
+  metadata.gz: 543db42b7a86f64548fb4b06cc9b7aec1fedaad147de9814a43860f4a2333e14
+  data.tar.gz: 4cdf30eb588b0ab495391fe5bc93f630e272b5f3a1f73187c16a293030e5de00
 SHA512:
-  metadata.gz: d01b884188cbed69ce4078ba790912ec7de535d30fc9647515288f17447375fb46778c142b0d3546ebd078d9c169a17a352668dec0a021e399c46cefecd0e3b7
-  data.tar.gz: 9587c018e899a4d0fd3a320f38b1fddf02f2cdde37c845bf16e6e6052ad88f67e0d4020c5267f9a940f92f25bf941ac9225579c327d509b24e768336a4ba868a
+  metadata.gz: 835dda07aaea82261a29912c7d03270811053dcb16113b2d80b388b8a4c24b848438a9cd7c7ac6866867940501e5bfe35abf62f39eb34f6a66a47fc14c4376a2
+  data.tar.gz: 359f066b2dae8e27c3a2918606cd7aafe5b671e9098d379ee98fb8761df069a49335cd0966cfad715d4a94267e6c01b300e5e213e20f297fd2bcb22735926096

data/.gitignore

@@ -2,5 +2,7 @@ doc/protocol.*
 doc/create-client.md
 doc/typed-input-validation.md
 doc/client-examples.md
+doc/documentation-ui.md
+doc/documentation-oauth.md
 doc/performance.md
 doc/json-schema.html

data/benchmarks/documentation.rb

@@ -152,11 +152,22 @@ module HaveAPI
         end
       end
       if @options[:lanes].include?('html')
-        lanes << trial_lane('html', 1, method(:html_output)) { request.get(URL, **headers) }
+        if Server.method_defined?(:documentation_oauth)
+          html_server, html_setup = measure { DocumentationPerformanceFixture.build(**dimensions, rust: @options[:rust], documentation_oauth: true) }
+          html_request = Rack::MockRequest.new(html_server.app)
+          html_url = "#{html_server.fixture_documentation_oauth.origin}/benchmark/api/v1/"
+          html_headers = headers.except('HTTP_AUTHORIZATION')
+          html_headers['HTTP_COOKIE'] = html_server.fixture_documentation_cookie(@options[:user])
+        else
+          html_request = request
+          html_url = URL
+          html_headers = headers
+        end
+        lanes << trial_lane('html', 1, ->(result) { html_output(result, dimensions) }) { html_request.get(html_url, **html_headers) }
       end
       lanes.concat(rust_lanes(parent, profile)) if @options[:lanes].include?('rust')
       { shape:, dimensions:, profile_mode: @options[:rust] ? 'rust' : 'dynamic', renderers:,
-        description: body_identity(JSON.generate(description)), setup:, lanes: }
+        description: body_identity(JSON.generate(description)), setup:, html_setup:, lanes: }
     end
 
     def rust_lanes(parent, profile)
@@ -218,12 +229,24 @@ module HaveAPI
         **body_identity(JSON.generate(description: child.description, sample: child.sample)) }
     end
 
-    def html_output(response)
+    def html_output(response, dimensions)
       output = { status: response.status, **body_identity(response.body) }
-      unless response.status == 200 && response.body.include?('PUBLIC_SAMPLE_0') && response.body.include?('init-examples')
-        raise InvalidOutput.new('HTML request failed or missing sample panels', output)
-      end
+      raise InvalidOutput.new('HTML request failed', output) unless response.status == 200
 
+      body = response.body
+      if body.match?(/\bdata-docs(?:\s|=|>)/)
+        roots = body.scan(/<[^>]+\bdata-docs(?:\s|=|>)[^>]*>/)
+        links = body.scan(/<a\b([^>]*\bdata-resource-directory-link[^>]*)>/).map do |attributes|
+          attributes.first[/\bhref="([^"]*)"/, 1]
+        end
+        initialization = body.match(%r{<details\b[^>]*\bid="init-python-sync"[^>]*>(.*?)</details>}m)
+        valid = roots.length == 1 && roots.first.scan(/\bdata-page="([^"]*)"/).flatten == ['overview'] && !links.empty? && links.all? { |href| href == '/benchmark/api/v1/?page=resources' } &&
+                initialization && initialization[1].include?('<pre><code') &&
+                !body.match?(/id="example-|PUBLIC_SAMPLE_|ADMIN_ONLY_(?:REQUEST|RESPONSE|DEFAULT)|admin_field/)
+        raise InvalidOutput.new('HTML overview is incomplete or contains action data', output) unless valid
+      elsif !body.include?('PUBLIC_SAMPLE_0') || !body.include?('init-examples')
+        raise InvalidOutput.new('HTML request is missing sample panels', output)
+      end
       output
     end
 

data/benchmarks/endpoints.rb

@@ -1,5 +1,6 @@
 require_relative 'performance_compare'
 require 'base64'
+require 'cgi'
 require 'fileutils'
 require 'etc'
 require 'open3'
@@ -11,7 +12,7 @@ require 'io/wait'
 module HaveAPI
   module Performance
     ROOT = File.expand_path('../../..', __dir__)
-    FIXTURE_PATHS = %w[performance_endpoint_fixture.rb performance_sqlite_fixture.rb documentation_performance_fixture.rb].freeze
+    FIXTURE_PATHS = %w[performance_endpoint_fixture.rb performance_sqlite_fixture.rb documentation_performance_fixture.rb documentation_oauth_fixture.rb].freeze
 
     class WorkerTimeout < ContractError
       attr_reader :details
@@ -23,6 +24,8 @@ module HaveAPI
     end
 
     class DocumentationScenario
+      attr_reader :documentation_identity
+
       # Only benchmark processes install this observer. It does not change the
       # authorization result or retain a request beyond its timed call.
       module AuthorizationObserver
@@ -51,23 +54,36 @@ module HaveAPI
         size = dimensions.fetch(:size, 1)
         @user = dimensions.fetch(:user, 'admin')
         resources, actions = @id == 'docs.html_actions' ? [1, size] : [size, 1]
+        # Only HTML on a source owning the optional docs client uses a cookie.
+        # The historical f6 source keeps real Basic; API/OPTIONS/direct lanes
+        # retain their original provider path and calibrated fixture setup.
+        cookie_identity = @id.start_with?('docs.html_') && Server.method_defined?(:documentation_oauth)
         @server = DocumentationPerformanceFixture.build(resource_count: dimensions.fetch(:resources, resources),
                                                         actions_per_resource: dimensions.fetch(:actions, actions),
                                                         samples_per_action: dimensions.fetch(:samples, 1),
                                                         parameters_per_action: dimensions.fetch(:parameters, 2),
-                                                        rust: @id.start_with?('rust.') || @id == 'docs.html_rust')
+                                                        rust: @id.start_with?('rust.') || @id == 'docs.html_rust',
+                                                        documentation_oauth: cookie_identity)
         @dimensions = dimensions
         Authorization.prepend(AuthorizationObserver) unless Authorization.ancestors.include?(AuthorizationObserver)
         @request = Rack::MockRequest.new(@server.app)
         @headers = { 'HTTP_HOST' => 'example.test', 'HTTP_ACCEPT_LANGUAGE' => 'en',
                      'HTTP_AUTHORIZATION' => "Basic #{Base64.strict_encode64("#{@user}:fixture-only")}" }
         @url = 'http://example.test/benchmark/api/v1/'
+        if cookie_identity
+          @documentation_fixture = @server.fixture_documentation_oauth
+          @headers.delete('HTTP_AUTHORIZATION')
+          @headers['HTTP_COOKIE'] = @server.fixture_documentation_cookie(@user)
+          @url = "#{@documentation_fixture.origin}/benchmark/api/v1/"
+        end
+        @documentation_identity = { mode: cookie_identity ? 'documentation_oauth_cookie' : 'basic', role: @user }
         prepare_rust if @id.start_with?('rust.')
       end
 
       def reset!(iterations:)
         @operations = Array.new(iterations) { { queries: 0, authorizations: 0, executions: 0 } }
         @index = 0
+        @lookup_start = @documentation_fixture&.lookups&.length
       end
 
       def call
@@ -93,6 +109,12 @@ module HaveAPI
         end
         raise ContractError, 'Documentation response failed' unless response.status == 200
 
+        if @documentation_fixture
+          actual = @documentation_fixture.lookups.drop(@lookup_start)
+          expected = Array.new(@index) { [1, "documentation-#{@user}"] }
+          raise ContractError, 'Documentation cookie token validation count differs' unless actual == expected
+        end
+
         content_type = @id.start_with?('rust.') || @id == 'docs.options' ? 'application/json' : 'text/html'
         raise ContractError, 'Documentation content type differs' unless response['content-type']&.start_with?(content_type)
 
@@ -126,38 +148,134 @@ module HaveAPI
 
           return identity
         end
-        unless response.body.include?('PUBLIC_SAMPLE_0') && response.body.include?('init-python-sync') && response.body.include?('init-examples')
+        if response.body.match?(/\bdata-docs(?:\s|=|>)/)
+          validate_overview!(response.body)
+        else
+          validate_monolith!(response.body)
+        end
+        { http_status: 200, envelope_status: nil, body_bytes: response.body.bytesize,
+          body_sha256: Digest::SHA256.hexdigest(response.body), canonical_sha256: Digest::SHA256.hexdigest(response.body) }.tap do |identity|
+          identity[:page] = @page if @page
+        end
+      end
+
+      def validate_monolith!(body)
+        @page = { shape: 'monolithic' }
+        unless body.include?('PUBLIC_SAMPLE_0') && body.include?('init-python-sync') && body.include?('init-examples')
           raise ContractError, 'Documentation panels missing'
         end
-        if response.body.include?('ADMIN_ONLY_REQUEST') != (@user == 'admin')
+        if body.include?('ADMIN_ONLY_REQUEST') != (@user == 'admin')
           raise ContractError, 'Documentation authorization mismatch'
         end
 
-        if @id == 'docs.html_rust'
-          actions = @dimensions.fetch(:resources) * @dimensions.fetch(:actions)
-          unless response.body.include?('init-rust-async') && response.body.include?('init-rust-blocking') &&
-                 response.body.include?("example-resource#{@dimensions.fetch(:resources) - 1}-action3-1")
-            raise ContractError, 'Full Rust documentation page missing panels/actions/examples'
-          end
+        return unless @id == 'docs.html_rust'
 
-          markers = %w[ADMIN_ONLY_ACTION ADMIN_ONLY_DEFAULT ADMIN_ONLY_REQUEST ADMIN_ONLY_RESPONSE ADMIN_ONLY_ACTION_SAMPLE admin_field admin_only]
-          unless markers.all? { |marker| response.body.include?(marker) == (@user == 'admin') }
-            raise ContractError, 'Full Rust documentation authorization mismatch'
-          end
+        actions = @dimensions.fetch(:resources) * @dimensions.fetch(:actions)
+        unless body.include?('init-rust-async') && body.include?('init-rust-blocking') &&
+               body.include?("example-resource#{@dimensions.fetch(:resources) - 1}-action3-1")
+          raise ContractError, 'Full Rust documentation page missing panels/actions/examples'
+        end
+
+        markers = %w[ADMIN_ONLY_ACTION ADMIN_ONLY_DEFAULT ADMIN_ONLY_REQUEST ADMIN_ONLY_RESPONSE ADMIN_ONLY_ACTION_SAMPLE admin_field admin_only]
+        unless markers.all? { |marker| body.include?(marker) == (@user == 'admin') }
+          raise ContractError, 'Full Rust documentation authorization mismatch'
+        end
+
+        examples = body.scan(/id="example-resource\d+-(?:action\d+|admin_only)-\d+-examples"/).uniq.length
+        expected_examples = (actions * (@dimensions.fetch(:samples) + (@user == 'admin' ? 1 : 0))) + (@user == 'admin' ? 1 : 0)
+        unless examples == expected_examples && body.include?('documentation_performance_client')
+          raise ContractError, 'Full Rust documentation example inventory mismatch'
+        end
+
+        @page = { shape: 'monolithic', actual_examples: examples, resources: @dimensions.fetch(:resources), actions: actions + (@user == 'admin' ? 1 : 0),
+                  public_examples: actions * @dimensions.fetch(:samples), user: @user }
+      end
+
+      def validate_overview!(body)
+        roots = body.scan(/<[^>]+\bdata-docs(?:\s|=|>)[^>]*>/)
+        unless body.scan(/\sdata-docs(?=[\s=>])/).length == 1 && roots.length == 1 && roots.first.scan(/\bdata-page="([^"]*)"/).flatten == ['overview']
+          raise ContractError, 'Documentation overview root differs'
+        end
+
+        forbidden = /id="(?:example-|root-)|PUBLIC_SAMPLE_|ADMIN_ONLY_|admin_field|admin_result/
+        raise ContractError, 'Documentation overview contains action data' if body.match?(forbidden)
+
+        resources, actions = documentation_dimensions
+        expected = resources.times.map { |index| "resource#{index}" }
+        links = body.scan(/<a\b([^>]*\bdata-resource-directory-link[^>]*)>/).map do |attributes|
+          href = attributes.first[/\bhref="([^"]*)"/, 1]
+          href && CGI.unescapeHTML(href)
+        end
+        unless !links.empty? && links.all? { |href| href == '/benchmark/api/v1/?page=resources' } &&
+               !body.include?('data-resource-link=')
+          raise ContractError, 'Documentation overview directory navigation differs'
+        end
+
+        %w[0 2 3 5 6 javascript-callback javascript-async typescript-callback typescript-async python-sync python-async].tap do |clients|
+          clients.push('rust-async', 'rust-blocking') if @id == 'docs.html_rust'
+          group = body.match(/data-example-details="([^"]*)" id="init-examples"/)
+          declared = group && JSON.parse(CGI.unescapeHTML(group[1]))
+          clients.each do |client|
+            levels = declared ? declared[client] : %w[simple thorough]
+            unless [['simple'], %w[simple thorough]].include?(levels)
+              raise ContractError, 'Documentation overview initialization detail declaration invalid'
+            end
 
-          examples = response.body.scan(/id="example-resource\d+-(?:action\d+|admin_only)-\d+-examples"/).uniq.length
-          expected_examples = (actions * (@dimensions.fetch(:samples) + (@user == 'admin' ? 1 : 0))) + (@user == 'admin' ? 1 : 0)
-          unless examples == expected_examples && response.body.include?('documentation_performance_client')
-            raise ContractError, 'Full Rust documentation example inventory mismatch'
+            levels.each do |detail|
+              suffix = detail == 'thorough' ? '-thorough' : ''
+              pattern = %r{<details\b(?=[^>]*\bdata-example-panel\b)(?=[^>]*\bdata-client="#{client}")(?=[^>]*\bdata-detail="#{detail}")(?=[^>]*\bid="init-#{client}#{suffix}")[^>]*>(.*?)</details>}m
+              panel = body.match(pattern)
+              code = panel && panel[1].match(%r{<pre><code[^>]*>(.*?)</code></pre>}m)
+              unless code && !code[1].strip.empty?
+                raise ContractError, 'Documentation overview initialization panel missing'
+              end
+            end
           end
+        end
+        if @id == 'docs.html_rust' && !body.include?('documentation_performance_client')
+          raise ContractError, 'Documentation overview Rust package missing'
+        end
+
+        maps = body.scan(%r{<script\b[^>]*\bdata-legacy-anchors\b[^>]*>(.*?)</script>}m)
+        raise ContractError, 'Documentation overview legacy map missing' unless maps.length == 1
+
+        anchors = JSON.parse(maps.first.first)
+        raise ContractError, 'Documentation overview legacy map invalid' unless anchors.is_a?(Hash)
 
-          @page = { actual_examples: examples, resources: @dimensions.fetch(:resources), actions: actions + (@user == 'admin' ? 1 : 0),
-                    public_examples: actions * @dimensions.fetch(:samples), user: @user }
+        expected_anchors = {}
+        expected.each do |key|
+          destination = "/benchmark/api/v1/?resource=#{key}"
+          expected_anchors["root-#{key}"] = destination
+          actions.times do |index|
+            expected_anchors["root-#{key}-action#{index}"] = destination
+            expected_anchors["example-#{key}-action#{index}-"] = destination
+          end
         end
-        { http_status: 200, envelope_status: nil, body_bytes: response.body.bytesize,
-          body_sha256: Digest::SHA256.hexdigest(response.body), canonical_sha256: Digest::SHA256.hexdigest(response.body) }.tap do |identity|
-          identity[:page] = @page if @page
+        if @user == 'admin'
+          expected_anchors['root-resource0-admin_only'] = '/benchmark/api/v1/?resource=resource0'
+          expected_anchors['example-resource0-admin_only-'] = '/benchmark/api/v1/?resource=resource0'
+        end
+        allowed_destinations = expected.map { |key| "/benchmark/api/v1/?resource=#{key}" } +
+                               ['/benchmark/api/v1/', '/benchmark/api/v1/?page=resources', '/benchmark/api/v1/?page=authentication']
+        unless anchors.values.all? { |destination| allowed_destinations.include?(destination) }
+          raise ContractError, 'Documentation overview legacy targets differ'
+        end
+
+        actual = anchors.select { |key, _| key.start_with?('root-', 'example-') }
+        unless actual == expected_anchors
+          raise ContractError, 'Documentation overview authorization or legacy targets differ'
         end
+
+        @page = { shape: 'overview', actual_examples: 0, resources:, actions: (resources * actions) + (@user == 'admin' ? 1 : 0),
+                  public_examples: 0, user: @user }
+      rescue JSON::ParserError
+        raise ContractError, 'Documentation overview legacy map invalid'
+      end
+
+      def documentation_dimensions
+        size = @dimensions.fetch(:size, 1)
+        resources, actions = @id == 'docs.html_actions' ? [1, size] : [size, 1]
+        [@dimensions.fetch(:resources, resources), @dimensions.fetch(:actions, actions)]
       end
 
       def counters
@@ -199,6 +317,7 @@ module HaveAPI
                                       'rjit' => (defined?(RubyVM::RJIT) && RubyVM::RJIT.enabled?) || false)
         raise ContractError, 'JIT must be disabled before worker startup' unless policy == RUNTIME_POLICY
 
+        activate_benchmark_console
         source = File.realpath(@request.fetch('source_root'))
         %w[servers/ruby clients/ruby clients/rust].reverse_each { |component| $:.unshift(File.join(source, component, 'lib')) }
         require 'active_record'
@@ -236,7 +355,9 @@ module HaveAPI
             scenario.close
             stages[:close_seconds] = monotonic - close_started
           end
-          result.merge(spec).merge(stages:)
+          result.merge(spec).merge(stages:).tap do |record|
+            record[:documentation_identity] = scenario.documentation_identity if scenario.respond_to?(:documentation_identity)
+          end
         end
         inputs = if @request['benchmark'] == true
                    self.class.inputs(source, @request.fetch('profile'), release: @request['release_versions'] == true, benchmark: true)
@@ -252,6 +373,14 @@ module HaveAPI
           stages: { require_load_seconds: load_seconds, worker_seconds: monotonic - started } }
       end
 
+      def activate_benchmark_console
+        return unless @request['benchmark'] == true
+
+        gem 'io-console', '= 0.9.4'
+        require 'io/console'
+      end
+      private :activate_benchmark_console
+
       def monotonic
         Process.clock_gettime(Process::CLOCK_MONOTONIC)
       end

data/benchmarks/spec/client_examples_spec.rb

@@ -26,6 +26,7 @@ RSpec.describe HaveAPI::ClientExample, '.render' do
     'typescript-generated' => :typescript
   }.freeze
   lanes = %i[init basic token oauth2 public protected failure].freeze
+  details = %i[simple thorough].freeze
   let(:matrix) { profiles }
 
   before(:all) do
@@ -39,12 +40,12 @@ RSpec.describe HaveAPI::ClientExample, '.render' do
   end
 
   after(:all) do
-    RSpec.configuration.reporter.message("ALL_CLIENT_PERFORMANCE #{JSON.generate(registry: profiles.keys.sort, lanes:, measurements: @measurements)}")
+    RSpec.configuration.reporter.message("ALL_CLIENT_PERFORMANCE #{JSON.generate(registry: profiles.keys.sort, lanes:, details:, measurements: @measurements)}")
   end
 
-  def headers(user)
+  def headers(server, user)
     { 'HTTP_HOST' => 'example.test', 'HTTP_ACCEPT_LANGUAGE' => 'en',
-      'HTTP_AUTHORIZATION' => "Basic #{Base64.strict_encode64("#{user}:fixture-only")}" }
+      'HTTP_COOKIE' => server.fixture_documentation_cookie(user) }
   end
 
   def description(server, user)
@@ -52,13 +53,13 @@ RSpec.describe HaveAPI::ClientExample, '.render' do
                                                          user: HaveAPI::DocumentationPerformanceFixture::User.new(user), params: {}))
   end
 
-  def context(description, profile, action_name: 'protected', sample_index: 0, resource_name: 'resource0')
+  def context(description, profile, action_name: 'protected', sample_index: 0, resource_name: 'resource0', detail: :simple, origin: 'http://example.test')
     resource = description.fetch(:resources).fetch(resource_name)
     action = resource.fetch(:actions).fetch(action_name)
     HaveAPI::ClientExample::Context.new(version: 1, host: 'example.test',
-                                        base_url: 'http://example.test/benchmark/api/',
-                                        version_url: 'http://example.test/benchmark/api/v1/',
-                                        description:, profile:, resource_path: [resource_name.to_s],
+                                        base_url: "#{origin}/benchmark/api/",
+                                        version_url: "#{origin}/benchmark/api/v1/",
+                                        description:, profile:, detail:, resource_path: [resource_name.to_s],
                                         resource:, action_name:, action:, sample: action.fetch(:examples).fetch(sample_index))
   end
 
@@ -113,12 +114,12 @@ RSpec.describe HaveAPI::ClientExample, '.render' do
   end
 
   profiles.each do |id, language|
-    lanes.each do |lane|
-      it "bounds #{id}/#{lane} work and allocations with unrelated descendants" do
+    lanes.product(details).each do |lane, detail|
+      it "bounds #{id}/#{lane}/#{detail} work and allocations with unrelated descendants" do
         client = described_class.clients.find { |item| item.id == id }
         expect(client).not_to be_nil
         profile = language && @profiles.fetch(language)
-        options = { action_name: lane == :public ? 'public' : 'protected', sample_index: lane == :failure ? 1 : 0 }
+        options = { action_name: lane == :public ? 'public' : 'protected', sample_index: lane == :failure ? 1 : 0, detail: }
         small = context(@description, profile, **options)
         large = context(@large_description, profile, **options)
         expect(client.available?(small)).to be(true)
@@ -131,7 +132,7 @@ RSpec.describe HaveAPI::ClientExample, '.render' do
         large_calls = calls { render(client, lane, large) }
         small_allocations = allocations { render(client, lane, small) }
         large_allocations = allocations { render(client, lane, large) }
-        @measurements << { id:, lane:, allocations: [small_allocations, large_allocations], calls: [small_calls, large_calls] }
+        @measurements << { id:, lane:, detail:, allocations: [small_allocations, large_allocations], calls: [small_calls, large_calls] }
         # Selected action/provider/sample is unchanged. Allow fixed VM/lookup
         # slack, while recursive walks of the 128 unrelated subtrees must fail.
         expect(large_calls).to be <= small_calls + 32
@@ -142,74 +143,145 @@ RSpec.describe HaveAPI::ClientExample, '.render' do
   end
 
   def expect_panel(body, anchor, result)
-    panel = body.match(%r{<div id="#{Regexp.escape(anchor)}">\s*(.*?)</div>}m)
+    panel = body.match(%r{<details\b[^>]*\bdata-example-panel\b[^>]*\bid="#{Regexp.escape(anchor)}"[^>]*>(.*?)</details>}m)
     expect(panel).not_to be_nil, "Missing #{anchor}"
     text = result.fetch(result[:status] == :code ? :code : :reason)
     expect(panel[1]).to include(CGI.escapeHTML(text))
     expect(panel[1]).to include(result[:status] == :code ? '<pre><code' : 'client-limitation')
   end
 
-  def expect_complete_page(server, user, resources)
-    desc = description(server, user)
-    response = Rack::MockRequest.new(server.app).get('/benchmark/api/v1/', **headers(user))
+  def expect_meaningful_group(body, base, client, kind, ctx, auth_method: nil, auth_description: nil)
+    simple = client.render(kind, context: ctx, auth_method:, auth_description:)
+    expect(simple).not_to be_nil
+    levels = client.detail_levels_for(kind, context: ctx, result: simple, auth_method:, auth_description:)
+    group = body.match(%r{<div class="docs-example" data-example data-example-details="([^"]*)" id="#{Regexp.escape(base)}-examples">(.*?)</div>}m)
+    expect(group).not_to be_nil, base
+    declared = JSON.parse(CGI.unescapeHTML(group[1]))
+    expect(declared.fetch(client.id)).to eq(levels.map(&:to_s))
+    actual = group[2].scan(/data-example-panel[^>]*data-client="#{Regexp.escape(client.id)}"[^>]*data-detail="([^"]+)"/).flatten
+    expect(actual).to eq(levels.map(&:to_s))
+    levels.each do |detail|
+      result = detail == :simple ? simple : client.render(kind, context: ctx.with(detail:), auth_method:, auth_description:)
+      expect_result(result, client.id, kind == :auth ? auth_method : kind)
+      expect_panel(body, "#{base}-#{client.id}#{'-thorough' if detail == :thorough}", result)
+    end
+    return unless levels == [:simple]
+
+    expect(body).to include("id=\"#{base}-#{client.id}-thorough\"")
+  end
+
+  def request_page(server, user, query = '')
+    response = Rack::MockRequest.new(server.app).get("#{server.fixture_documentation_oauth.origin}/benchmark/api/v1/#{query}", **headers(server, user))
     expect(response.status).to eq(200)
     expect(response['content-type']).to start_with('text/html')
-    expect(response.body).to include('PUBLIC_SAMPLE')
+    response.body
+  end
+
+  def expect_complete_page(server, user, resources, actions: 2)
+    desc = description(server, user)
+    overview = request_page(server, user)
+    authentication = request_page(server, user, '?page=authentication')
+    directory = request_page(server, user, '?page=resources')
+    links = directory.scan(/data-resource-link="([^"]*)"/).flatten
+    expect(links.sort).to eq(resources.times.map { |index| "resource#{index}" }.sort)
+    expect(directory).not_to include('PUBLIC_SAMPLE', 'ADMIN_ONLY_REQUEST', 'ADMIN_ONLY_RESPONSE', 'id="example-')
+    expect(overview).to include('data-resource-directory-link')
+    expect(overview).not_to include('data-resource-link=')
+    pages = resources.times.to_h do |index|
+      name = "resource#{index}"
+      [name, request_page(server, user, "?resource=#{name}")]
+    end
+    expect(overview).not_to include('id="example-')
+    expect(overview).not_to include('PUBLIC_SAMPLE', 'ADMIN_ONLY_REQUEST', 'ADMIN_ONLY_RESPONSE')
+    pages.each do |name, body|
+      expect(body).to include('PUBLIC_SAMPLE')
+      expect(body).not_to include('id="init-examples"')
+      pages.each_key do |other|
+        next if other == name
+
+        expect(body).not_to include("id=\"example-#{other}-")
+      end
+    end
+    combined = [overview, authentication, directory, *pages.values].join
     %w[ADMIN_ONLY_ACTION ADMIN_ONLY_DEFAULT ADMIN_ONLY_REQUEST ADMIN_ONLY_RESPONSE ADMIN_ONLY_ACTION_SAMPLE admin_field admin_only].each do |marker|
-      expect(response.body.include?(marker)).to eq(user == 'admin'), marker
+      expect(combined.include?(marker)).to eq(user == 'admin'), marker
     end
     example_count = 0
     HaveAPI::ClientExample.clients.each do |client|
       language = matrix.fetch(client.id)
       profile = language && server.documentation_client_profiles(1).fetch(language)
-      ctx = context(desc, profile)
+      ctx = context(desc, profile, origin: server.fixture_documentation_oauth.origin)
       expect(client.available?(ctx)).to be(true)
-      expect_panel(response.body, "init-#{client.id}", render(client, :init, ctx))
-      desc.fetch(:authentication).each_key do |method|
-        result = render(client, method, ctx)
-        expect_result(result, client.id, method)
-        expect_panel(response.body, "auth-#{method}-#{client.id}", result)
+      expect_meaningful_group(overview, 'init', client, :init, ctx)
+      desc.fetch(:authentication).each do |method, auth|
+        expect_meaningful_group(authentication, "auth-#{method}", client, :auth, ctx, auth_method: method, auth_description: auth)
       end
-      resources.times do |index|
-        resource_name = "resource#{index}"
+      pages.each do |resource_name, body|
         desc.fetch(:resources).fetch(resource_name).fetch(:actions).each do |action_name, action|
           action.fetch(:examples).each_index do |sample_index|
-            selected = context(desc, profile, action_name: action_name.to_s, sample_index:, resource_name:)
-            result = client.render(:example, context: selected)
-            expect_result(result, client.id, :example)
-            expect_panel(response.body, "example-#{resource_name}-#{action_name}-#{sample_index}-#{client.id}", result)
+            selected = context(desc, profile, action_name: action_name.to_s, sample_index:, resource_name:,
+                                              origin: server.fixture_documentation_oauth.origin)
+            expect_meaningful_group(body, "example-#{resource_name}-#{action_name}-#{sample_index}", client, :example, selected)
             example_count += 1
           end
         end
       end
     end
-    expected_samples = (resources * 2 * (user == 'admin' ? 3 : 2)) + (user == 'admin' ? 1 : 0)
+    expected_samples = (resources * actions * (user == 'admin' ? 3 : 2)) + (user == 'admin' ? 1 : 0)
     expect(example_count).to eq(expected_samples * matrix.length)
-    response
+    combined
   end
 
   it 'renders every real panel and isolates admin/member/admin pages through the same adapters' do
     first = expect_complete_page(@server, 'admin', 2)
     expect_complete_page(@server, 'member', 2)
     last = expect_complete_page(@server, 'admin', 2)
-    expect(last.body).to eq(first.body)
+    expect(last).to eq(first)
   end
 
   it 'bounds complete all-profile page allocations by linear output growth' do
     measurements = [2, 4, 8].map do |resources|
       server = HaveAPI::AllClientPerformanceFixture.build(resources:)
-      response = expect_complete_page(server, 'admin', resources)
+      correctness = expect_complete_page(server, 'admin', resources)
       request = Rack::MockRequest.new(server.app)
-      allocated = allocations(count: 1) { request.get('/benchmark/api/v1/', **headers('admin')) }
-      { resources:, bytes: response.body.bytesize, allocations: allocated }
+      # Measure the four page kinds with one selected resource. Correctness
+      # above still checks every resource and both details; adding unrelated
+      # resources must grow navigation, not action rendering on the selected page.
+      paths = ['', '?page=authentication', '?page=resources', '?resource=resource0']
+      bytes = paths.sum { |query| request.get("#{server.fixture_documentation_oauth.origin}/benchmark/api/v1/#{query}", **headers(server, 'admin')).body.bytesize }
+      allocated = allocations(count: 1) do
+        paths.each { |query| request.get("#{server.fixture_documentation_oauth.origin}/benchmark/api/v1/#{query}", **headers(server, 'admin')) }
+      end
+      { resources:, bytes:, correctness_bytes: correctness.bytesize, allocations: allocated }
     end
     @measurements << { pages: measurements }
     small, medium, large = measurements
     expect(large[:bytes]).to be > medium[:bytes]
     expect(medium[:bytes]).to be > small[:bytes]
     expect(medium[:allocations]).to be > small[:allocations]
-    # Doubling the added resources doubles actual panels/output. A 2.5x
-    # incremental allowance covers bookkeeping; quadratic copying approaches 4x.
+    # The same page kinds retain their panel count; added resources grow only
+    # authorized descriptions/navigation. Keep the existing 2.5x growth budget.
+    expect(large[:allocations] - medium[:allocations]).to be <= 2.5 * (medium[:allocations] - small[:allocations])
+  end
+
+  it 'bounds one resource page allocations as its own action panels grow' do
+    measurements = [2, 4, 8].map do |actions|
+      server = HaveAPI::AllClientPerformanceFixture.build(resources: 1, actions:)
+      expect_complete_page(server, 'admin', 1, actions:)
+      request = Rack::MockRequest.new(server.app)
+      response = request.get("#{server.fixture_documentation_oauth.origin}/benchmark/api/v1/?resource=resource0", **headers(server, 'admin'))
+      allocated = allocations(count: 1) do
+        request.get("#{server.fixture_documentation_oauth.origin}/benchmark/api/v1/?resource=resource0", **headers(server, 'admin'))
+      end
+      { actions:, bytes: response.body.bytesize, allocations: allocated }
+    end
+    @measurements << { action_pages: measurements }
+    small, medium, large = measurements
+    expect(large[:bytes]).to be > medium[:bytes]
+    expect(medium[:bytes]).to be > small[:bytes]
+    expect(medium[:allocations]).to be > small[:allocations]
+    # Both selected panels and description grow here. Repeated whole-description
+    # copying per panel approaches quadratic growth and violates the same budget.
     expect(large[:allocations] - medium[:allocations]).to be <= 2.5 * (medium[:allocations] - small[:allocations])
   end
 end