haveapi 0.32.1 → 0.32.2

data/spec/client_examples/assets/documentation_test.cjs

@@ -5,9 +5,21 @@ const path = require('node:path');
 const vm = require('node:vm');
 const filename = path.resolve(__dirname, '../../../lib/haveapi/public/js/documentation.js');
 const stylesheet = fs.readFileSync(path.resolve(__dirname, '../../../lib/haveapi/public/css/documentation.css'), 'utf8');
-const { preferences, readPreferences, clientChoice, detailLevels, effectiveDetail, exampleDetail, copyText, exampleCopyControls,
+const { setDocumentationMessages, documentationLanguageURL, documentationMessage, preferences, readPreferences, clientChoice, detailLevels, effectiveDetail, exampleDetail, copyText, exampleCopyControls,
   disclosureMenus, legacyTarget, loginTarget, highlighterTarget, activeSection, navigationTargets, referenceNavigation, searchShortcut,
   searchConfiguration, validateSearchIndex, searchMatcher, searchResultURL, renderSearchResult, searchIndexLoader } = require(filename);
+const catalogs = JSON.parse(require('node:child_process').execFileSync('ruby', ['-ryaml', '-rjson', '-e',
+  'print JSON.generate(YAML.load_file(ARGV[0]).transform_values { |v| v.fetch("haveapi").fetch("documentation").fetch("browser") })',
+  path.resolve(__dirname, '../../../../../i18n/haveapi.yml')], { encoding: 'utf8' }));
+setDocumentationMessages(catalogs.en);
+const localeURL = documentationLanguageURL('https://docs.example/api/v1/?resource=widget&q=a%20b&doc_lang=en#root-widget-show', 'cs');
+assert.equal(localeURL, 'https://docs.example/api/v1/?resource=widget&q=a+b&doc_lang=cs#root-widget-show');
+assert.equal(documentationLanguageURL('https://docs.example/api/v1/?page=authentication', 'auto'), null);
+assert.equal(documentationLanguageURL('javascript:alert(1)', 'cs'), null);
+setDocumentationMessages(catalogs.cs);
+assert.equal(documentationMessage('copy_example'), catalogs.cs.copy_example);
+assert.equal(documentationMessage('saved_example_unavailable', { client: '<Client>' }), catalogs.cs.saved_example_unavailable.replace('%{client}', '<Client>'));
+setDocumentationMessages(catalogs.en);
 const clients = [
   { id: '0', language: 'ruby', language_label: 'Ruby', variant: null },
   { id: 'python-sync', language: 'python', language_label: 'Python', variant: 'Sync' },
@@ -30,6 +42,9 @@ assert(!/padding(?:-top|-block)|margin|line-height|grid/.test(sourceLayout), 'or
 assert(/padding-inline-end:/.test(sourceLayout), 'code can pan into a clear inline-end gutter');
 assert(/position: absolute/.test(buttonLayout) && /width: 2\.75rem/.test(buttonLayout) && /height: 2\.75rem/.test(buttonLayout), 'small visual icon keeps an out-of-flow44px hit area');
 assert(/position: absolute/.test(statusLayout) && /inset-block-start: 100%/.test(statusLayout), 'live status stays outside readable code and does not move it');
+const breadcrumbLayout = cssRule('.docs-main .docs-breadcrumb ol');
+assert(/display: flex/.test(breadcrumbLayout) && /list-style: none/.test(breadcrumbLayout), 'breadcrumbs stay horizontal and unnumbered in both locales');
+assert(!/\[aria-label[\^$*~|]?=/.test(stylesheet), 'documentation style must not depend on translated accessibility labels');
 
 assert.equal(preferences(null).theme, 'auto');
 assert.equal(preferences(null).detail, 'simple');
@@ -309,7 +324,8 @@ function browserFixture(workerMode, blockedStorage, display) {
   const visibleCode = code(true, false);
   const codes = [visibleCode, code(false, false), code(true, true)];
   const root = {
-    querySelector: selector => display && selector === '[data-documentation-clients]' ? { textContent: JSON.stringify(display.metadata) }
+    querySelector: selector => selector === '[data-documentation-messages]' ? { textContent: JSON.stringify(catalogs.en) }
+      : display && selector === '[data-documentation-clients]' ? { textContent: JSON.stringify(display.metadata) }
       : display && selector === '[data-docs-sidebar]' ? display.sidebar
         : display && selector === '[data-nav-toggle]' ? display.toggle : display && selector === '.docs-main' ? display.main : null,
     querySelectorAll: selector => display && display.matches[selector] ? display.matches[selector]
@@ -343,7 +359,7 @@ function browserFixture(workerMode, blockedStorage, display) {
   };
   if (workerMode !== 'missing') window.Worker = Worker;
   vm.runInNewContext(fs.readFileSync(filename, 'utf8'), { window, document, Worker, URL, console });
-  return { attributes, messages, worker, visibleCode, themeButtons, writes, themeMedia, document, documentEvents, windowEvents };
+  return { attributes, messages, worker, visibleCode, themeButtons, writes, themeMedia, document, documentEvents, windowEvents, window };
 }
 for (const mode of ['missing', 'constructor-failure', 'post-failure', 'working']) {
   const fixture = browserFixture(mode, true);
@@ -382,6 +398,48 @@ assert.equal(settingsMenu.summary.getAttribute('aria-label'), 'Documentation set
 assert.equal(settingsMenu.summary.getAttribute('title'), 'Documentation settings');
 assert.equal(menuTheme.themeButtons[2].attributes['aria-pressed'], 'true');
 
+const localeListeners = { form: {}, select: {} };
+const documentationLocale = { value: 'cs', addEventListener(name, listener) { (localeListeners.select[name] ||= []).push(listener); } };
+let localeSubmitHidden = false;
+const localeSubmit = {
+  get hidden() { return localeSubmitHidden; },
+  set hidden(value) {
+    assert.equal(localeListeners.form.submit.length, 1, 'native submit stays available until its enhanced listener is bound');
+    assert.equal(localeListeners.select.change.length, 1, 'native submit stays available until change navigation is bound');
+    localeSubmitHidden = value;
+  }
+};
+const localeForm = {
+  querySelector(selector) {
+    assert(['[name="doc_lang"]', '[data-documentation-language-submit]'].includes(selector));
+    return selector === '[name="doc_lang"]' ? documentationLocale : localeSubmit;
+  },
+  addEventListener(name, listener) { (localeListeners.form[name] ||= []).push(listener); }
+};
+const localeVariant = Object.assign(element('select'), { closest: () => null });
+const localeDetail = Object.assign(element('select'), { closest: () => null });
+const localeFixture = browserFixture('missing', false, {
+  metadata: clients, saved: { language: 'python', clients: { python: 'python-async' } }, geometry: { scroll: 0 },
+  matches: { '[data-documentation-language]': [localeForm], '[data-variant-select]': [localeVariant], '[data-detail-select]': [localeDetail] }
+});
+assert.equal(localeSubmit.hidden, true, 'enhanced language settings show the select without a submit button');
+const localeNavigations = [];
+localeFixture.window.location.href = 'https://docs.example/api/v1/?resource=widget&q=hostname#root-widget-show';
+localeFixture.window.location.assign = destination => localeNavigations.push(destination);
+localeFixture.themeButtons[2].listeners.click();
+localeVariant.value = 'python-sync'; localeVariant.listeners.change();
+localeDetail.value = 'thorough'; localeDetail.listeners.change();
+let localePrevented = 0;
+localeListeners.select.change.forEach(listener => listener({ preventDefault() { localePrevented += 1; } }));
+assert.deepEqual(localeNavigations, ['https://docs.example/api/v1/?resource=widget&q=hostname&doc_lang=cs#root-widget-show'],
+  'changing theme, client and detail must not multiply language navigation handlers');
+assert.equal(localePrevented, 1);
+localeNavigations.length = 0;
+documentationLocale.value = 'en';
+localeListeners.form.submit.forEach(listener => listener({ preventDefault() {} }));
+assert.deepEqual(localeNavigations, ['https://docs.example/api/v1/?resource=widget&q=hostname&doc_lang=en#root-widget-show'],
+  'submitting the native language form is enhanced once and preserves the current location');
+
 const shortcutToggle = element('button');
 const shortcutMain = { inert: false };
 let slashFocusCount = 0;
@@ -438,7 +496,7 @@ assert.equal(detailSelect.value, 'thorough');
 assert.equal(detailWrapper.hidden, false);
 assert.equal(languageSelect.disabled, false, 'Language remains the primary available choice');
 languageSelect.value = 'single'; languageSelect.listeners.change();
-assert.equal(detailWrapper.hidden, false); assert.equal(detailSelect.disabled, true);
+assert.equal(detailWrapper.hidden, true); assert.equal(detailSelect.disabled, true);
 assert.equal(variantWrapper.hidden, true); assert.equal(variantSelect.disabled, true);
 assert.deepEqual(values(variantSelect), ['single'], 'Client contains only renderers for the selected language');
 assert.deepEqual(values(detailSelect), ['simple'], 'Examples contains only the current renderer capabilities');
@@ -466,7 +524,7 @@ detailSelect.value = 'thorough'; detailSelect.listeners.change();
 assert.equal(JSON.parse(detailFixture.writes.at(-1).value).clients.capable, 'capable-other');
 detailDisplay.metadata[2].details = null;
 browserFixture('missing', false, { ...detailDisplay, saved: { language: 'single', detail: 'thorough' } });
-assert.equal(detailSelect.disabled, true); assert.equal(detailWrapper.hidden, false);
+assert.equal(detailSelect.disabled, true); assert.equal(detailWrapper.hidden, true);
 assert.deepEqual(values(detailSelect), ['simple']);
 assert.equal(detailPanels.find(panel => !panel.hidden).client, 'single', 'malformed metadata must not discard the renderer');
 assert.equal(detailPanels.find(panel => !panel.hidden).detail, 'simple');
@@ -476,6 +534,38 @@ assert.equal(detailSelect.disabled, false); assert.equal(detailWrapper.hidden, f
 assert.deepEqual(values(detailSelect), ['simple', 'thorough']);
 assert.equal(detailPanels.find(panel => !panel.hidden).detail, 'thorough', 'missing metadata keeps legacy two-level markup');
 
+function examplePreferenceDisplay(selection) {
+  const apply = element('button');
+  const form = Object.assign(element('form'), {
+    getAttribute: name => name === 'data-example-selection' ? selection : null,
+    querySelector: selector => selector === '[data-apply-examples]' ? apply : null
+  });
+  const language = Object.assign(element('select'), { closest: () => null });
+  const variant = Object.assign(element('select'), { closest: () => null });
+  const detail = Object.assign(element('select'), { closest: () => null });
+  const fixture = browserFixture('missing', false, { metadata: clients,
+    saved: { theme: 'dark', language: 'python', clients: { python: 'python-async' }, detail: 'simple' },
+    matches: { '[data-example-preferences]': [form], '[data-language-select]': [language],
+      '[data-variant-select]': [variant], '[data-detail-select]': [detail] } });
+  return { apply, form, language, variant, detail, fixture };
+}
+const nativeChoices = examplePreferenceDisplay(JSON.stringify({ language: 'python', client: 'python-sync', detail: 'thorough' }));
+assert.equal(nativeChoices.variant.value, 'python-sync', 'explicit native selection initializes ahead of saved client');
+assert.equal(nativeChoices.detail.value, 'thorough');
+assert.equal(nativeChoices.fixture.attributes['data-docs-theme'], 'dark', 'native example choices preserve saved theme');
+assert.equal(nativeChoices.fixture.writes.length, 0, 'native query initialization never persists preferences');
+assert.equal(nativeChoices.apply.hidden, true, 'Apply is hidden after its real native form is enhanced');
+let nativeSubmitPrevented = false;
+nativeChoices.form.listeners.submit({ preventDefault() { nativeSubmitPrevented = true; } });
+assert(nativeSubmitPrevented, 'enhanced Enter submission keeps immediate selection and does not navigate');
+nativeChoices.variant.value = 'python-async'; nativeChoices.variant.listeners.change();
+assert.equal(JSON.parse(nativeChoices.fixture.writes.at(-1).value).clients.python, 'python-async', 'actual JS changes still persist immediately');
+const savedChoices = examplePreferenceDisplay(null);
+assert.equal(savedChoices.variant.value, 'python-async', 'without native query the saved client retains precedence');
+assert.equal(savedChoices.detail.value, 'simple');
+assert.equal(savedChoices.fixture.writes.length, 0);
+assert(!stylesheet.includes('[data-docs]:not([data-docs-enhanced]) .docs-preferences'), 'native example controls remain visible without enhancement');
+
 function declaredGroup(levels, panels) {
   const unavailable = { hidden: true };
   return { isConnected: true, getAttribute: () => levels,
@@ -508,7 +598,7 @@ const singletonPage = browserFixture('missing', false, { metadata: [{ id: 'callb
   saved: JSON.parse(mixedFixture.writes.at(-1).value), geometry: { scroll: 0 },
   matches: { '[data-detail-select]': [singletonPageSelect] } });
 assert.deepEqual(values(singletonPageSelect), ['simple'], 'a no-example page consumes its emitted Simple-only union');
-assert.equal(singletonPageSelect.disabled, true); assert.equal(singletonPageSelect.hidden, false);
+assert.equal(singletonPageSelect.disabled, true); assert.equal(singletonPageSelect.hidden, true);
 singletonPageSelect.listeners.change();
 assert.equal(singletonPage.writes.length, 0, 'singleton pages/events never persist over the preferred thorough choice');
 const restoredPageSelect = Object.assign(element('select'), { closest: () => null });
@@ -525,7 +615,7 @@ const oneChoice = browserFixture('missing', false, { saved: { language: 'only',
   matches: { '[data-language-select]': [oneLanguage], '[data-variant-select]': [oneClient], '[data-detail-select]': [oneDetail] } });
 assert.deepEqual(values(oneLanguage), ['only']); assert.equal(oneLanguage.disabled, true);
 assert.equal(oneClientWrapper.hidden, true); assert.equal(oneClient.disabled, true);
-assert.equal(oneDetail.hidden, false); assert.equal(oneDetail.disabled, true); assert.equal(oneDetail.value, 'simple');
+assert.equal(oneDetail.hidden, true); assert.equal(oneDetail.disabled, true); assert.equal(oneDetail.value, 'simple');
 oneDetail.listeners.change(); assert.equal(oneChoice.writes.length, 0, 'no-example singleton controls do not erase a saved thorough preference');
 
 const fixture = JSON.parse(fs.readFileSync(path.resolve(__dirname, '../../documentation/fixtures/search_index.json'), 'utf8'));
@@ -541,6 +631,13 @@ assert.equal(searchConfiguration(action, 'https://foreign.example/api/v1/?page=r
 assert.equal(searchConfiguration(action, indexURL + '&q=secret', key, '1', current, false), null);
 assert.equal(searchConfiguration(action, indexURL, '', '1', current, false), null);
 assert.equal(searchConfiguration(action, indexURL.replace(key, 'b'.repeat(64)), key, '1', current, false), null);
+const localizedConfig = searchConfiguration(action, indexURL + '&doc_lang=cs', key, fixture.index.version, current, false);
+assert.equal(localizedConfig.locale, 'cs');
+assert.equal(new URL(searchConfiguration(action, indexURL + '&doc_lang=cs', key, fixture.index.version, current, true).url).searchParams.get('doc_lang'), 'cs');
+for (const suffix of ['&doc_lang=auto', '&doc_lang=cs&doc_lang=en', '&doc_lang[]=cs']) {
+  assert.equal(searchConfiguration(action, indexURL + suffix, key, fixture.index.version, current, false), null);
+}
+assert.throws(() => validateSearchIndex({ key, index: { ...fixture.index, locale: 'en' } }, localizedConfig));
 const index = validateSearchIndex({ key, index: fixture.index }, config);
 const matchIndex = searchMatcher(index);
 for (const example of fixture.queries) {
@@ -740,7 +837,8 @@ function clipboardFixture(secure, nativeResult) {
   // copy controls share the same state rather than a second selection model.
   const copyLanguage = Object.assign(element('select'), { closest: () => null });
   const copyVariant = Object.assign(element('select'), { closest: selector => selector === '[data-variant-control]' ? { hidden: false } : null });
-  const copyDetail = Object.assign(element('select'), { closest: selector => selector === '[data-detail-control]' ? { hidden: false } : null });
+  const copyDetailWrapper = { hidden: false };
+  const copyDetail = Object.assign(element('select'), { closest: selector => selector === '[data-detail-control]' ? copyDetailWrapper : null });
   const copyPanels = ['capable', 'single'].flatMap(client => ['simple', 'thorough'].map(detail => {
     const pair = copyPanel('  ' + client + ' ' + detail + '\n', false);
     pair.panel.setAttribute('data-client', client); pair.panel.setAttribute('data-detail', detail);
@@ -765,7 +863,7 @@ function clipboardFixture(secure, nativeResult) {
   assert.equal(status(copyPanels[1]).textContent, '', 'changing selected client clears stale copied status');
   assert.deepEqual(values(copyVariant), ['single']); assert.deepEqual(values(copyDetail), ['simple']);
   assert.equal(copyVariant.disabled, true); assert.equal(copyDetail.disabled, true);
-  assert.equal(copyDetail.hidden, false);
+  assert.equal(copyDetailWrapper.hidden, true);
   button(selectedPair()).listeners.click(); await flush();
   assert.equal(actualCopies.at(-1), '  single simple\n', 'copy uses the actual Simple panel while its singleton selector is disabled');
   assert.equal(JSON.parse(copyControls.writes.at(-1).value).detail, 'thorough');

data/spec/client_examples/comment_capture.rb

@@ -0,0 +1,72 @@
+# Test only the authored prose emission boundary. No parsing or stripping of
+# source literals, transcript data or commented commands takes place here.
+module ExampleCommentCapture
+  def comment_capture_class(base)
+    emissions = []
+    captured = Class.new(base) do
+      define_method(:comment_lines) do |text, prefix|
+        block = super(text, prefix)
+        marker = "__HAVEAPI_COMMENT_EMISSION_#{emissions.length}__"
+        emissions << { marker:, block:, prefix: }
+        marker
+      end
+    end
+    [captured, emissions]
+  end
+
+  def restore_comment_emissions(template, emissions)
+    restored = template.dup
+    emissions.each do |emission|
+      marker = emission.fetch(:marker)
+      count = restored.scan(marker).length
+      next if count == 0 # Some renderers prepare a fragment before selecting another branch.
+
+      expect(count).to eq(1)
+      offset = restored.index(marker)
+      line_start = restored.rindex("\n", offset) || -1
+      indentation = restored[(line_start + 1)...offset]
+      indentation = '' unless indentation.match?(/\A[ \t]*\z/)
+      restored = restored.sub(marker) { emission.fetch(:block).gsub("\n", "\n#{indentation}") }
+    end
+    restored
+  end
+end
+
+module ExampleCommentCapture
+  # Standalone adapters consume a duck-typed context and need no server gem.
+  def localized_comment_context(context, locale)
+    require 'yaml'
+    catalog = YAML.load_file(File.expand_path('../../../../i18n/haveapi.yml', __dir__))
+                  .fetch(locale.to_s).fetch('haveapi').fetch('documentation')
+    localized = context.dup
+    localized.define_singleton_method(:documentation_message) do |key, default:, **values|
+      message = key.split('.').reduce(catalog) { |tree, part| tree.is_a?(Hash) ? tree[part] : nil } || default
+      values.empty? ? message : format(message, values)
+    end
+    localized.define_singleton_method(:example_comment) do |key, default:, **values|
+      documentation_message("comments.#{key}", default:, **values)
+    end
+    localized
+  end
+
+  def expect_adapter_comment_parity(base, context, **arguments, &factory)
+    actual = []
+    templates = []
+    traces = []
+    %i[en cs].each do |locale|
+      localized = localized_comment_context(context, locale)
+      rendered = factory.call(base).freeze.render(context: localized, **arguments)
+      expect(rendered[:status]).to eq(:code), "#{arguments.inspect}: #{rendered.inspect}"
+      actual << rendered.fetch(:code)
+      capture, emissions = comment_capture_class(base)
+      templates << factory.call(capture).freeze.render(context: localized, **arguments).fetch(:code)
+      traces << emissions
+      expect(restore_comment_emissions(templates.last, emissions)).to eq(actual.last)
+    end
+    expect(templates[1]).to eq(templates[0])
+    expect(traces[1].map { |item| item[:prefix] }).to eq(traces[0].map { |item| item[:prefix] })
+    # The same adapter used with an old context retains the original English.
+    expect(factory.call(base).freeze.render(context:, **arguments).fetch(:code)).to eq(actual[0])
+    actual
+  end
+end

data/spec/client_examples/comments_spec.rb

@@ -0,0 +1,162 @@
+require 'spec_helper'
+require 'ripper'
+require 'open3'
+require 'tempfile'
+require_relative 'dynamic_fixture'
+require_relative 'comment_capture'
+
+RSpec.describe HaveAPI::ClientExample do
+  include DynamicExampleFixture
+  include ExampleCommentCapture
+
+  let(:renderers) do
+    described_class.clients.reject { |renderer| %w[go rust typescript-generated].include?(renderer.code.to_s) }
+  end
+
+  def render_comments(renderer, context, kind, method = nil)
+    renderer.render(kind, context:, auth_method: method, auth_description: token_description.merge(
+      authorize_path: '/authorize', token_path: '/token', http_header: 'X-Token'
+    )).fetch(:code)
+  end
+
+  def context_for_comments(detail)
+    dynamic_context(detail:, resource_path: ['widget'], action_name: 'show',
+                    action: dynamic_action.merge(blocking: true),
+                    sample: dynamic_sample.merge(path_params: [], request: { name: 'literal // # komentář', enabled: false,
+                                                                             count: 0, nullable: nil }))
+  end
+
+  it 'varies only authored prose boundaries across all native renderers, kinds and detail levels' do
+    differences = 0
+    renderers.each do |renderer|
+      %i[simple thorough].each do |detail|
+        [[:init, nil], %i[auth basic], %i[auth token], %i[auth oauth2], [:example, nil]].each do |kind, method|
+          context = context_for_comments(detail)
+          # HTTP needs sample status metadata; action outputs remain literal data.
+          context = context.with(sample: context.sample.merge(http_status: 200))
+          actual = []
+          traced = []
+          traces = []
+          %i[en cs].each do |locale|
+            localized = context.with(locale:)
+            result = renderer.render(kind, context: localized, auth_method: method, auth_description: token_description.merge(
+              authorize_path: '/authorize', token_path: '/token', http_header: 'X-Token'
+            ))
+            next unless result[:status] == :code
+
+            actual << result.fetch(:code)
+            capture, emissions = comment_capture_class(renderer)
+            traced << render_comments(capture, localized, kind, method)
+            traces << emissions
+            expect(restore_comment_emissions(traced.last, emissions)).to eq(actual.last)
+          end
+          next if actual.empty?
+
+          expect(actual.length).to eq(2)
+          expect(traced[1]).to eq(traced[0]), "Noncomment source changed for #{renderer} #{kind}/#{method}/#{detail}"
+          expect(traces[1].map { |item| item[:prefix] }).to eq(traces[0].map { |item| item[:prefix] })
+          differences += 1 if actual[0] != actual[1]
+        end
+      end
+    end
+    expect(differences).to be > 20
+  end
+
+  it 'preserves response data and failure semantics across every Ruby and PHP layout' do
+    [HaveAPI::ClientExamples::RubyClient, HaveAPI::ClientExamples::PhpClient].each do |renderer|
+      %i[hash hash_list object object_list].product([true, false]).each do |layout, success|
+        context = context_for_comments(:simple)
+        output = { layout:, namespace: :widget, parameters: {
+          name: { type: 'String' }, custom: { type: 'Custom' },
+          relation: { type: 'Resource', resource: ['owner'] }
+        } }
+        response = { name: 'literal // # komentář', custom: false, relation: { id: 0 } }
+        response = [response] if %i[hash_list object_list].include?(layout)
+        context = context.with(action: context.action.merge(output:), sample: context.sample.merge(status: success, response:))
+        templates = []
+        %i[en cs].each do |locale|
+          localized = context.with(locale:)
+          actual = renderer.render(:example, context: localized).fetch(:code)
+          capture, emissions = comment_capture_class(renderer)
+          templates << capture.render(:example, context: localized).fetch(:code)
+          expect(restore_comment_emissions(templates.last, emissions)).to eq(actual)
+        end
+        expect(templates[1]).to eq(templates[0])
+      end
+    end
+  end
+
+  it 'translates Ruby token reuse and leaves direct legacy renderer calls English' do
+    context = context_for_comments(:simple)
+    renderer = HaveAPI::ClientExamples::RubyClient
+    czech = render_comments(renderer, context.with(locale: :cs), :auth, :token)
+    english = render_comments(renderer, context, :auth, :token)
+    expect(czech).to include(::I18n.t('haveapi.documentation.comments.reuse_token', locale: :cs))
+    expect(czech).not_to include('# Reuse an existing token')
+    direct = renderer.new(context.host, context.base_url, context.version).auth(:token, token_description)
+    expect(direct).to include('# Reuse an existing token')
+    [english, czech].each { |source| expect(Ripper.sexp(source)).not_to be_nil }
+  end
+
+  it 'keeps Czech comments syntactically inert in native programs and async fragments' do
+    renderers.select { |renderer| %i[ruby php javascript typescript python].include?(renderer.code) }.each do |renderer|
+      %i[simple thorough].each do |detail|
+        [[:init, nil], %i[auth token], %i[auth oauth2], [:example, nil]].each do |kind, method|
+          context = context_for_comments(detail).with(locale: :cs)
+          result = renderer.render(kind, context:, auth_method: method, auth_description: token_description)
+          next unless result[:status] == :code
+
+          source = result.fetch(:code)
+          case renderer.code
+          when :ruby
+            expect(Ripper.sexp(source)).not_to be_nil
+          when :php
+            output, status = Open3.capture2e('php', '-l', stdin_data: "<?php\n#{source}")
+            expect(status).to be_success, output
+          when :javascript
+            Tempfile.create(['haveapi-comment-', '.mjs']) do |file|
+              file.write(source)
+              file.flush
+              output, status = Open3.capture2e('node', '--check', file.path)
+              expect(status).to be_success, output
+            end
+          when :python
+            if kind == :example && detail == :simple && renderer == HaveAPI::ClientExamples::PythonAsyncClient
+              source = "async def example():\n#{source.lines.map { |line| "    #{line}" }.join}"
+            end
+            output, status = Open3.capture2e('python', '-c', 'import ast, sys; ast.parse(sys.stdin.read())', stdin_data: source)
+            expect(status).to be_success, output
+          when :typescript
+            compiler = File.expand_path('../../../../clients/js/node_modules/typescript', __dir__)
+            script = 'const ts = require(process.argv[1]); let src = ""; process.stdin.on("data", x => src += x); process.stdin.on("end", () => { const result = ts.transpileModule(src, { reportDiagnostics: true, compilerOptions: { target: ts.ScriptTarget.ES2022, module: ts.ModuleKind.ESNext } }); if ((result.diagnostics || []).length) { process.stderr.write(JSON.stringify(result.diagnostics)); process.exitCode = 1; } });'
+            output, status = Open3.capture2e('node', '-e', script, compiler, stdin_data: source)
+            expect(status).to be_success, output
+          end
+        end
+      end
+    end
+  end
+
+  it 'keeps interpolated multiline translations inside actual Ruby comment tokens' do
+    localized_context = Class.new(HaveAPI::ClientExample::Context) do
+      def example_comment(*)
+        "first\r\nputs(:unexpected)\nlast"
+      end
+    end
+    context = context_for_comments(:simple)
+    localized = localized_context.new(**HaveAPI::ClientExample::Context::FIELDS.to_h { |field| [field, context.public_send(field)] })
+    source = render_comments(HaveAPI::ClientExamples::RubyClient, localized, :auth, :token)
+    expect(source).to include("# first\n# puts(:unexpected)\n# last")
+    tokens = Ripper.lex(source)
+    expect(tokens.reject { |(_, type, _, _)| type == :on_comment }.map { |(_, _, token, _)| token }.join)
+      .not_to include('unexpected')
+    expect(Ripper.sexp(source)).not_to be_nil
+  end
+
+  it 'prefixes every physical translated prose line, including interpolated newlines' do
+    renderer = HaveAPI::ClientExamples::RubyClient.new('api.test', '/', '1')
+    expect(renderer.comment_lines("first\r\nsecond\rthird\n", '  # ')).to eq("  # first\n  # second\n  # third\n  # ")
+    expect(renderer.comment_lines("first\nsecond", '    // ')).to eq("    // first\n    // second")
+    expect(renderer.example_comment('missing', default: 'Type %{value}', value: "A\nB")).to eq("Type A\nB")
+  end
+end

data/spec/client_examples/context_spec.rb

@@ -46,6 +46,22 @@ describe HaveAPI::ClientExample::Context do
     end
   end
 
+  it 'captures locale independently of ambient state and retains English defaults' do
+    czech = context.with(locale: :cs)
+    expect(context.locale).to eq(:en)
+    expect(czech.with(detail: :thorough).locale).to eq(:cs)
+    ::I18n.with_locale(:en) do
+      expect(czech.example_comment('reuse_token', default: 'Reuse an existing token')).to eq('Použití existujícího tokenu')
+    end
+    ::I18n.with_locale(:cs) do
+      expect(context.example_comment('reuse_token', default: 'Reuse an existing token')).to eq('Reuse an existing token')
+      expect(context.example_comment('missing_comment', default: 'Keep %{value}', value: 'literal')).to eq('Keep literal')
+    end
+    expect(czech.example_comment('instance_of', default: '%{variable} is an instance of %{type}', variable: 'reply', type: 'Type'))
+      .to eq('reply je instance Type')
+    expect(context).to be_frozen
+  end
+
   describe '#with' do
     let(:fields) do
       {
@@ -54,7 +70,7 @@ describe HaveAPI::ClientExample::Context do
         description: { 'resources' => { 'widget' => { 'label' => 'Widget' } } },
         resource_path: [:widget, 2], resource: { 'label' => 'Widget' },
         action_name: :show, action: { 'method' => 'GET' },
-        sample: { 'request' => { 'values' => [0, false, '', nil] } }, profile: Object.new, detail: :simple
+        sample: { 'request' => { 'values' => [0, false, '', nil] } }, profile: Object.new, detail: :simple, locale: :en
       }
     end
     let(:parent) { described_class.new(**fields) }
@@ -66,7 +82,7 @@ describe HaveAPI::ClientExample::Context do
         resource_path: [:other, 3], resource: { 'label' => 'Other' },
         action_name: :update, action: { 'method' => 'POST' },
         sample: { 'request' => { 'values' => [false, 0, nil, ''] } },
-        profile: Object.new, detail: :thorough
+        profile: Object.new, detail: :thorough, locale: 'cs'
       }
     end
 

data/spec/client_examples/detail_spec.rb

@@ -1,5 +1,6 @@
 require 'spec_helper'
 require 'open3'
+require 'ripper'
 require_relative 'dynamic_fixture'
 
 RSpec.describe HaveAPI::ClientExample, '.render' do
@@ -57,6 +58,19 @@ RSpec.describe HaveAPI::ClientExample, '.render' do
     end
   end
 
+  it 'localizes built-in limitation prose while preserving executable code' do
+    translated = %i[en cs].map do |locale|
+      ::I18n.with_locale(locale) do
+        renderer = HaveAPI::ClientExamples::JsClient
+        { code: renderer.render(:example, context: dynamic_context).fetch(:code),
+          reason: renderer.render(:example, context: dynamic_context(sample: { request: nil, response: nil })).fetch(:reason) }
+      end
+    end
+    expect(translated.last[:code]).to eq(translated.first[:code])
+    expect(translated.last[:reason]).to eq(::I18n.t('haveapi.documentation.limitations.prose_only', locale: :cs))
+    expect(translated.last[:reason]).not_to eq(translated.first[:reason])
+  end
+
   it 'keeps Python async fragments in an explicit async context without adding executable wrappers' do
     source = HaveAPI::ClientExamples::PythonAsyncClient.render(:example, context: dynamic_context).fetch(:code)
     script = 'import ast, sys; ast.parse("async def example():\n" + "".join("    " + line for line in sys.stdin))'
@@ -143,6 +157,60 @@ RSpec.describe HaveAPI::ClientExample, '.render' do
     end
   end
 
+  it 'loads Ruby before initialization and authentication handlers in both documentation languages' do
+    renderer = HaveAPI::ClientExamples::RubyClient
+    %i[en cs].product([[:init, nil], %i[auth basic], %i[auth token]]).each do |locale, (kind, method)|
+      %i[simple thorough].each do |detail|
+        context = dynamic_context(locale:, detail:)
+        source = renderer.render(kind, context:, auth_method: method, auth_description: token_description).fetch(:code)
+        expect(Ripper.sexp(source)).not_to be_nil
+        expect(source.scan("require 'haveapi/client'").length).to eq(1)
+        if detail == :thorough
+          expect(source).to start_with("require 'haveapi/client'\n\nbegin\n  api = HaveAPI::Client.new")
+          expect(source.index('api.setup')).to be < source.index('rescue HaveAPI::Client::ValidationError')
+        else
+          expect(source).to start_with("require 'haveapi/client'\n\napi = HaveAPI::Client.new")
+          expect(source).not_to include('begin', 'api.setup', 'rescue ')
+        end
+        next unless method == :token
+
+        expect(source).to include('continuations.fetch', "token: 'example-token'",
+                                  ::I18n.t('haveapi.documentation.comments.reuse_token', locale:))
+      end
+    end
+  end
+
+  it 'loads Ruby before handlers for public and protected actions in every response layout' do
+    %i[hash hash_list object object_list].product([true, false], [true, false]).each do |layout, success, authenticated|
+      context = dynamic_context(detail: :thorough, resource_path: ['widget'], action_name: 'show')
+      context = context.with(action: context.action.merge(auth: authenticated, output: context.action[:output].merge(layout:)),
+                             sample: context.sample.merge(status: success, path_params: [7]))
+      source = HaveAPI::ClientExamples::RubyClient.render(:example, context:).fetch(:code)
+      expect(Ripper.sexp(source)).not_to be_nil
+      expect(source).to start_with("require 'haveapi/client'\n\nbegin\n  api = HaveAPI::Client.new")
+      expect(source.scan("require 'haveapi/client'").length).to eq(1)
+      expect(source.index('api.setup')).to be < source.index('reply = api.widget.show')
+      expect(source.index('reply = api.widget.show')).to be < source.index('rescue HaveAPI::Client::ValidationError')
+      expect(source.include?("api.authenticate(:token, token: 'example-token')")).to eq(authenticated)
+    end
+  end
+
+  it 'propagates a Ruby client load failure before evaluating application rescue constants' do
+    context = dynamic_context(detail: :thorough)
+    source = HaveAPI::ClientExamples::RubyClient.render(:auth, context:, auth_method: :token, auth_description: token_description).fetch(:code)
+    missing_library = <<~RUBY
+      module Kernel
+        def require(name)
+          raise LoadError, "missing fixture library: \#{name}"
+        end
+      end
+    RUBY
+    output, status = Open3.capture2e(RbConfig.ruby, '-e', missing_library + source)
+    expect(status).not_to be_success
+    expect(output).to include('missing fixture library: haveapi/client', 'LoadError')
+    expect(output).not_to include('NameError', 'uninitialized constant')
+  end
+
   it 'advertises only Simple for built-in limitations without probing another render' do
     context = dynamic_context(sample: dynamic_sample.merge(path_params: [7]))
     results = renderers.to_h { |renderer| [renderer, renderer.render(:example, context:)] }

data/spec/documentation/client_overview_spec.rb

@@ -142,4 +142,64 @@ describe HaveAPI::DocumentationHelpers, '#render_version_documentation' do
     expect(body).to include('href="/rack/mounted/api/v1/?page=resources">HTTP</a>')
     expect(body).to include('href="https://github.com/vpsfreecz/haveapi/tree/master/clients/ruby#client-library">library</a>')
   end
+
+  it 'checks each registered renderer availability once for the complete request' do
+    HaveAPI::ClientExample.clients.each { |client| allow(client).to receive(:available?).and_call_original }
+    get '/v1/'
+    expect(last_response.status).to eq(200)
+    expect(HaveAPI::ClientExample.clients).to all(have_received(:available?).once)
+    metadata = JSON.parse(last_response.body.match(%r{data-documentation-clients>(.*?)</script>}m)[1])
+    expect(metadata.map { |client| client['id'] }).to eq(HaveAPI::ClientExample.clients.reject do |client|
+      %w[go rust-async rust-blocking typescript-generated].include?(client.id)
+    end.map(&:id))
+  end
+
+  it 'retains an empty available list for one request and evaluates it afresh on the next' do
+    HaveAPI::ClientExample.clients.each { |client| allow(client).to receive(:available?).and_return(false) }
+    2.times do
+      get '/v1/'
+      expect(last_response.status).to eq(200)
+      expect(last_response.body).to include('data-documentation-clients>[]</script>')
+      expect(last_response.body).not_to include('data-example-preferences')
+    end
+    expect(HaveAPI::ClientExample.clients).to all(have_received(:available?).twice)
+  end
+
+  it 'uses fresh identity, version, locale, description and profiles on consecutive requests' do
+    require_relative '../../test_support/documentation_oauth_fixture'
+    server = HaveAPI::Server.new(get_opt(:api_module))
+    server.use_version([1, 2])
+    users = %w[admin member].to_h { |name| [name, Struct.new(:login).new(name)] }
+    fixture = DocumentationOAuthFixture.configure(server, users: { 1 => users, 2 => users })
+    server.mount('/')
+    allow(server).to receive(:describe_version).and_wrap_original do |method, context|
+      method.call(context).merge(probe_user: context.current_user&.login)
+    end
+    configured_profiles = {}
+    allow(server).to receive(:documentation_client_profiles) { |_version| configured_profiles }
+    observed = []
+    allow(HaveAPI::ClientExamples::PythonAsyncClient).to receive(:available?) do |context|
+      observed << [context.description[:probe_user], context.version, context.locale]
+      context.description[:probe_user] == 'admin' && context.version == '1' && context.locale == :en
+    end
+    request = lambda do |version, user, locale|
+      Rack::MockRequest.new(server.app).get("#{fixture.origin}/v#{version}/",
+                                            'HTTP_HOST' => URI(fixture.origin).host, 'HTTP_ACCEPT_LANGUAGE' => locale,
+                                            'HTTP_COOKIE' => fixture.header_for(server, version:, token: user))
+    end
+    english = request.call(1, 'admin', 'en')
+    expect(english.status).to eq(200)
+    expect(english.body).to include('data-client="python-async"')
+    czech = request.call(1, 'admin', 'cs')
+    expect(czech.status).to eq(200)
+    expect(czech.body).not_to include('data-client="python-async"')
+    member = request.call(2, 'member', 'en')
+    expect(member.status).to eq(200)
+    expect(member.body).not_to include('data-client="python-async"', 'data-client="go"')
+    configured_profiles[:go] = profile(:go, 'example.test/new-profile')
+    with_profile = request.call(2, 'member', 'en')
+    expect(with_profile.status).to eq(200)
+    expect(with_profile.body).to include('data-client="go"', 'example.test/new-profile')
+    expect(observed).to eq([['admin', '1', :en], ['admin', '1', :cs], ['member', '2', :en], ['member', '2', :en]])
+  end
 end