haveapi 0.29.12 → 0.30.1

data/lib/haveapi/public/js/highlighter.js

@@ -1,9 +1,19 @@
 importScripts('highlight.pack.js');
 
-onmessage = function (e) {
-	if (e.data.language)
-		postMessage(hljs.highlight(e.data.language, e.data.code).value);
-
-	else
-		postMessage(hljs.highlightAuto(e.data.code).value);
+function plainText(source) {
+	return source.replace(/[&<>"']/g, function (value) {
+		return { '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[value];
+	});
 }
+
+onmessage = function (e) {
+	var source = String(e.data.code || '');
+	var language = e.data.language;
+	try {
+		postMessage(language && hljs.getLanguage(language)
+			? hljs.highlight(source, { language: language, ignoreIllegals: true }).value
+			: plainText(source));
+	} catch (error) {
+		postMessage(plainText(source));
+	}
+};

data/lib/haveapi/public/js/main.js

@@ -19,13 +19,21 @@ $(document).ready(function () {
 
 		worker.onmessage = function (e) {
 			currentElement.innerHTML = e.data;
+			currentElement.classList.add('hljs');
 			highlightNext();
 		};
+		worker.onerror = function () {
+			worker.terminate();
+			// The server's escaped source remains readable if the worker fails.
+		};
 
 		highlightNext();
 
 	} else {
-		hljs.initHighlighting();
+		document.querySelectorAll('pre code').forEach(function (element) {
+			if (hljs.getLanguage(element.classList.item(0)))
+				hljs.highlightElement(element);
+		});
 	}
 });
 

data/lib/haveapi/public/js/nojs-tabs.js

@@ -3,7 +3,9 @@
 		this.opts = opts;
 
 		var ul = this.createElement(document.createElement('UL'));
+		ul.setAttribute('role', 'tablist');
 		var tabNum = opts.tabs.children.length;
+		if (!tabNum) return;
 
 		for (var i = 0; i < tabNum; i++) {
 			var tab = opts.tabs.children[i];
@@ -50,6 +52,11 @@
 		var a_text = document.createTextNode(this.getTitle(tab));
 
 		a.href = '#' + tab.id;
+		a.id = 'tab-button-' + tab.id;
+		a.setAttribute('role', 'tab');
+		a.setAttribute('aria-controls', tab.id);
+		tab.setAttribute('role', 'tabpanel');
+		tab.setAttribute('aria-labelledby', a.id);
 
 		var that = this;
 
@@ -59,6 +66,18 @@
 			if (history.pushState)
 				e.preventDefault();
 		});
+		a.addEventListener('keydown', function (e) {
+			var links = Array.prototype.slice.call(that.opts.tabBar.querySelectorAll('[role="tab"]'));
+			var index = links.indexOf(a);
+			if (e.key === 'ArrowRight') index = (index + 1) % links.length;
+			else if (e.key === 'ArrowLeft') index = (index + links.length - 1) % links.length;
+			else if (e.key === 'Home') index = 0;
+			else if (e.key === 'End') index = links.length - 1;
+			else return;
+			e.preventDefault();
+			links[index].focus();
+			that.switchTab(that.opts.tabs.children[index]);
+		});
 
 		a.appendChild(a_text);
 		li.appendChild(a);
@@ -80,7 +99,7 @@
 
 		if (typeof s === 'string' || s instanceof String) {
 			var el = tab.querySelector(s);
-			var ret = el.innerHTML;
+			var ret = el.textContent;
 			
 			if (this.opts.removeHeading === undefined || this.opts.removeHeading)
 				el.parentElement.removeChild(el);
@@ -167,7 +186,7 @@
 		this.activate([targetTab, targetTab.tabAnchor]);
 		
 		// afterChange
-		if (this.opts.beforeChange !== undefined)
+		if (this.opts.afterChange !== undefined)
 			this.opts.afterChange(targetTab, activeTab);
 	};
 
@@ -177,6 +196,13 @@
 		for (var i = 0; i < len; i++) {
 			elems[i].classList.remove(this.opts.hiddenClass);
 			elems[i].classList.add(this.opts.activeClass);
+			var link = elems[i].querySelector('[role="tab"]');
+			if (link) {
+				link.setAttribute('aria-selected', 'true');
+				link.setAttribute('tabindex', '0');
+			} else if (elems[i].getAttribute('role') === 'tabpanel') {
+				elems[i].setAttribute('aria-hidden', 'false');
+			}
 		}
 	};
 
@@ -185,7 +211,15 @@
 
 		for (var i = 0; i < len; i++) {
 			elems[i].classList.remove(this.opts.activeClass);
-			elems[i].classList.add(this.opts.hiddenClass);
+			if (elems[i].getAttribute('role') === 'tabpanel')
+				elems[i].classList.add(this.opts.hiddenClass);
+			var link = elems[i].querySelector('[role="tab"]');
+			if (link) {
+				link.setAttribute('aria-selected', 'false');
+				link.setAttribute('tabindex', '-1');
+			} else if (elems[i].getAttribute('role') === 'tabpanel') {
+				elems[i].setAttribute('aria-hidden', 'true');
+			}
 		}
 	};
 

data/lib/haveapi/server.rb

@@ -3,6 +3,7 @@ require 'redcarpet'
 require 'tilt'
 require 'cgi'
 require 'haveapi/hooks'
+require 'haveapi/documentation_clients'
 
 module HaveAPI
   class Server
@@ -250,6 +251,29 @@ module HaveAPI
         "#{scheme}://#{request.env['HTTP_HOST']}"
       end
 
+      def documentation_context(client = nil, **changes)
+        @documentation_context ||= HaveAPI::ClientExample::Context.new(
+          version: @v, host:, base_url: "#{base_url}#{root.end_with?('/') ? root : "#{root}/"}",
+          version_url: "#{base_url}#{root.end_with?('/') ? root : "#{root}/"}v#{@v}/",
+          description: @help
+        )
+        profile = if client
+                    settings.api_server.documentation_client_profiles(@v)[client.code&.to_sym]
+                  end
+        @documentation_context.with(profile:, **changes)
+      end
+
+      def documentation_clients
+        HaveAPI::ClientExample.clients.select { |client| client.available?(documentation_context(client)) }
+      end
+
+      def documentation_panels(kind, auth_method: nil, auth_description: nil, **changes)
+        documentation_clients.filter_map do |client|
+          result = client.render(kind, context: documentation_context(client, **changes), auth_method:, auth_description:)
+          [client, result] if result
+        end
+      end
+
       def host
         request.env['HTTP_HOST'].split(':').first
       end
@@ -312,11 +336,20 @@ module HaveAPI
       @extensions = []
       @action_state_auth = :backend
       @validation_error_http_status = nil
+      @documentation_clients = HaveAPI::ClientExample::Profiles.new
       @default_locale = :en
       self.available_locales = HaveAPI::I18n.available_locales
       self.locale_header = 'Accept-Language'
     end
 
+    def documentation_clients(version, **profiles)
+      @documentation_clients.register(version, **profiles)
+    end
+
+    def documentation_client_profiles(version)
+      @documentation_clients.for_version(version)
+    end
+
     def available_locales=(locales)
       @available_locales = Array(locales)
       allow_i18n_locales(@available_locales)
@@ -407,6 +440,7 @@ module HaveAPI
     # All routes are mounted under prefix `path`.
     # If no default version is set, the last included version is used.
     def mount(prefix = '/')
+      @documentation_clients.mount(@versions)
       @root = prefix
 
       @sinatra = Sinatra.new do
@@ -588,6 +622,11 @@ module HaveAPI
       end
 
       call_hooks_for(:post_mount, args: [self, @sinatra])
+      @documentation_clients.finalize(self)
+    rescue StandardError
+      @documentation_clients.abort_mount
+      @sinatra = nil
+      raise
     end
 
     def mount_version(prefix, v)

data/lib/haveapi/version.rb

@@ -1,4 +1,4 @@
 module HaveAPI
   PROTOCOL_VERSION = '2.0'.freeze
-  VERSION = '0.29.12'.freeze
+  VERSION = '0.30.1'.freeze
 end

data/lib/haveapi/views/main_layout.erb

@@ -54,6 +54,17 @@
     .tab-hidden {
       display: none;
     }
+    .nav-tabs {
+      display: flex;
+      flex-wrap: wrap;
+    }
+    .nav-tabs > li {
+      float: none;
+    }
+    .nav-tabs a:focus {
+      outline: 2px solid #337ab7;
+      outline-offset: -2px;
+    }
     pre {
       overflow: auto;
     }

data/lib/haveapi/views/version_page/auth_body.erb

@@ -32,9 +32,9 @@
 <div id="<%= baseid %>-tabbar"></div>
 
 <div id="<%= baseid %>-examples">
-  <% HaveAPI::ClientExample.clients.each_with_index do |client, i| %>
-    <div id="<%= "#{baseid}-#{i}" %>">
-      <%= erb :"version_page/client_auth", locals: {client: client, method: name, desc: info} %>
+  <% documentation_panels(:auth, auth_method: name, auth_description: info).each do |client, result| %>
+    <div id="<%= escape_html("#{baseid}-#{client.id}") %>">
+      <%= erb :"version_page/client_auth", locals: {client: client, result: result} %>
     </div>
   <% end %>
 </div>

data/lib/haveapi/views/version_page/client_auth.erb

@@ -1,2 +1,2 @@
-<h4><%= client.label %></h4>
-<pre><code class="<%= client.code %>"><%= escape_html(client.auth(host, base_url, api_version, method, desc)) %></code></pre>
+<h4><%= escape_html(client.label) %></h4>
+<%= erb :"version_page/client_result", locals: {client: client, result: result} %>

data/lib/haveapi/views/version_page/client_example.erb

@@ -1,11 +1,2 @@
-<h6><%= client.label %></h6>
-<% sample = client.new(host, base_url, api_version, r_name, resource, a_name, action) %>
-<% if sample.respond_to?(:example) %>
-  <pre><code class="<%= client.code %>"><%= escape_html(sample.example(example)) %></code></pre>
-
-<% else %>
-  <h6>Request</h6>
-  <pre><code class="<%= client.code %>"><%= escape_html(sample.request(example)) %></code></pre>
-  <h6>Response</h6>
-  <pre><code class="<%= client.code %>"><%= escape_html(sample.response(example)) %></code></pre>
-<% end %>
+<h6><%= escape_html(client.label) %></h6>
+<%= erb :"version_page/client_result", locals: {client: client, result: result} %>

data/lib/haveapi/views/version_page/client_init.erb

@@ -1,2 +1,2 @@
-<h4><%= client.label %></h4>
-<pre><code class="<%= client.code %>"><%= escape_html(client.init(host, base_url, api_version)) %></code></pre>
+<h4><%= escape_html(client.label) %></h4>
+<%= erb :"version_page/client_result", locals: {client: client, result: result} %>

data/lib/haveapi/views/version_page/client_result.erb

@@ -0,0 +1,5 @@
+<% if result[:status] == :limitation %>
+  <p class="client-limitation"><%= escape_html(result[:reason]) %></p>
+<% else %>
+  <pre><code class="<%= escape_html(client.code) %>"><%= escape_html(result[:code]) %></code></pre>
+<% end %>

data/lib/haveapi/views/version_page/resource_body.erb

@@ -104,16 +104,12 @@
               <div id="<%= "#{baseid}-tabbar" %>"></div>
 
               <div id="<%= "#{baseid}-examples" %>">
-                <% HaveAPI::ClientExample.clients.each_with_index do |client, j| %>
-                  <div id="<%= "#{baseid}-#{j}" %>">
+                <% documentation_panels(:example, resource_path: resource_path, resource: resource_info, action_name: action, action: info, sample: example).each do |client, result| %>
+                  <div id="<%= escape_html("#{baseid}-#{client.id}") %>">
                     <%=
                       erb :"version_page/client_example", locals: {
                         client: client,
-                        r_name: resource_path,
-                        resource: resource_info,
-                        a_name: action,
-                        action: info,
-                        example: example,
+                        result: result,
                       }
                     %>
                   </div>

data/lib/haveapi/views/version_page.erb

@@ -16,19 +16,23 @@
 </p>
 
 <ul>
-  <li><a href="https://github.com/vpsfreecz/haveapi-client" target="_blank">Ruby library and CLI</a></li>
-  <li><a href="https://github.com/vpsfreecz/haveapi-client-js" target="_blank">JavaScript</a></li>
-  <li><a href="https://github.com/vpsfreecz/haveapi-client-php" target="_blank">PHP</a></li>
+  <li><a href="https://github.com/vpsfreecz/haveapi/tree/master/clients/ruby" target="_blank" rel="noopener">Ruby library and CLI</a></li>
+  <li><a href="https://github.com/vpsfreecz/haveapi/tree/master/clients/js" target="_blank" rel="noopener">JavaScript and TypeScript (callback and async)</a></li>
+  <li><a href="https://github.com/vpsfreecz/haveapi/tree/master/clients/python" target="_blank" rel="noopener">Python (sync and async)</a></li>
+  <% settings.api_server.documentation_client_profiles(@v).each do |language, profile| %>
+    <li><a href="https://github.com/vpsfreecz/haveapi/tree/master/clients/<%= escape_html(language) %>" target="_blank" rel="noopener"><%= language == :go ? 'Go' : 'Rust (async and blocking)' %></a>: <code><%= escape_html(profile.package_name) %></code><% if profile.package_version %> <%= escape_html(profile.package_version) %><% end %></li>
+  <% end %>
+  <li><a href="https://github.com/vpsfreecz/haveapi/tree/master/clients/php" target="_blank" rel="noopener">PHP</a></li>
   <li>
     <a href="https://github.com/vpsfreecz/haveapi-webui" target="_blank">Generic web interface</a>
     (<a href="https://webui.haveapi.org/v<%= version %>/#<%= urlescape(base_url) %>" target="_blank">connect to this API</a>)
   </li>
-  <li><a href="https://github.com/vpsfreecz/haveapi-fs" target="_blank">FUSE-based file system</a></li>
 </ul>
 
 <p>
-  The code examples found on this page are for HaveAPI v<%= version %>, so be sure
-  to use clients of the same version.
+  These examples target API v<%= escape_html(@v) %>. The framework and dynamic
+  clients share HaveAPI package versions. Generated Go and Rust SDKs use their
+  own package versions. Their configured SDKs are expected to match this API.
 </p>
 
 <h2>Initialization</h2>
@@ -36,9 +40,9 @@
 <div id="init-tabbar"></div>
 
 <div id="init-examples">
-  <% HaveAPI::ClientExample.clients.each_with_index do |client, i| %>
-    <div id="<%= "init-#{i}" %>">
-      <%= erb :"version_page/client_init", locals: {client: client} %>
+  <% documentation_panels(:init).each do |client, result| %>
+    <div id="<%= escape_html("init-#{client.id}") %>">
+      <%= erb :"version_page/client_init", locals: {client: client, result: result} %>
     </div>
   <% end %>
 </div>

data/spec/client_examples/assets/highlighter_test.cjs

@@ -0,0 +1,26 @@
+'use strict';
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const path = require('node:path');
+const vm = require('node:vm');
+const root = path.resolve(__dirname, '../../../lib/haveapi/public/js');
+const context = vm.createContext({});
+vm.runInContext(fs.readFileSync(path.join(root, 'highlight.pack.js'), 'utf8'), context);
+for (const language of ['bash', 'http', 'xml', 'php', 'json', 'javascript', 'ruby', 'go', 'rust', 'python', 'typescript']) {
+  assert(context.hljs.getLanguage(language), language);
+  const result = context.hljs.highlight('const text = "<script>";', { language, ignoreIllegals: true });
+  assert(!result.value.includes('<script>'), language);
+}
+assert.equal(context.hljs.versionString, '11.12.0');
+const messages = [];
+context.importScripts = name => assert.equal(name, 'highlight.pack.js');
+context.postMessage = value => messages.push(value);
+vm.runInContext(fs.readFileSync(path.join(root, 'highlighter.js'), 'utf8'), context);
+context.onmessage({ data: { language: 'unknown', code: '<script>&"\'' } });
+assert.equal(messages.pop(), '&lt;script&gt;&amp;&quot;&#39;');
+context.onmessage({ data: { language: 'go', code: 'package main' } });
+assert(messages.pop().includes('hljs-keyword'));
+context.hljs.highlight = () => { throw new Error('fixture failure'); };
+context.onmessage({ data: { language: 'rust', code: '<unsafe>' } });
+assert.equal(messages.pop(), '&lt;unsafe&gt;');
+console.log('All bundled languages and safe worker fallbacks passed');

data/spec/client_examples/assets/tabs_test.cjs

@@ -0,0 +1,54 @@
+'use strict';
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const path = require('node:path');
+const vm = require('node:vm');
+class Element {
+  constructor(tag, document) {
+    this.tagName = tag.toUpperCase(); this.document = document;
+    this.children = []; this.attributes = {}; this.listeners = {};
+    const classes = new Set();
+    this.classList = { add: (...values) => values.forEach(value => classes.add(value)), remove: value => classes.delete(value), contains: value => classes.has(value) };
+    this.textContent = '';
+  }
+  setAttribute(name, value) { this.attributes[name] = String(value); }
+  getAttribute(name) { return this.attributes[name]; }
+  appendChild(child) { child.parentElement = this; this.children.push(child); return child; }
+  removeChild(child) { this.children.splice(this.children.indexOf(child), 1); }
+  addEventListener(name, handler) { this.listeners[name] = handler; }
+  querySelectorAll(selector) {
+    const matches = element => selector === '[role="tab"]' ? element.getAttribute('role') === 'tab' : selector[0] === '.' ? element.classList.contains(selector.slice(1)) : element.tagName === selector.toUpperCase();
+    return this.children.flatMap(child => [...(matches(child) ? [child] : []), ...child.querySelectorAll(selector)]);
+  }
+  querySelector(selector) { return this.querySelectorAll(selector)[0]; }
+  getElementsByTagName(name) { return this.querySelectorAll(name); }
+  focus() { this.document.activeElement = this; }
+}
+const document = { createElement: tag => new Element(tag, document), createTextNode: value => Object.assign(new Element('#text', document), { textContent: value }) };
+const page = document.createElement('main');
+document.getElementById = id => [page, ...page.querySelectorAll('div')].find(element => element.id === id);
+const tabs = page.appendChild(document.createElement('div')); tabs.id = 'examples';
+const bar = page.appendChild(document.createElement('div')); bar.id = 'bar';
+for (let index = 0; index < 3; index++) {
+  const panel = tabs.appendChild(document.createElement('div')); panel.id = 'example-' + index;
+  const heading = panel.appendChild(document.createElement('h4')); heading.textContent = 'Language ' + index;
+}
+const context = vm.createContext({ window: {}, document, history: { pushState() {} }, location: { hash: '' } });
+vm.runInContext(fs.readFileSync(path.resolve(__dirname, '../../../lib/haveapi/public/js/nojs-tabs.js'), 'utf8'), context);
+context.window.nojsTabs({ tabs, tabBar: bar, titleSelector: 'h4', hiddenClass: 'tab-hidden', activeClass: 'active' });
+const links = bar.querySelectorAll('[role="tab"]');
+assert.equal(links.length, 3);
+assert.equal(links[0].getAttribute('aria-selected'), 'true');
+assert.equal(links[1].getAttribute('tabindex'), '-1');
+for (const link of links) assert(!link.parentElement.classList.contains('tab-hidden'));
+const key = (index, value) => links[index].listeners.keydown({ key: value, preventDefault() {} });
+key(0, 'ArrowRight');
+assert.equal(document.activeElement, links[1]);
+assert.equal(tabs.children[1].getAttribute('aria-hidden'), 'false');
+assert.equal(tabs.children[0].getAttribute('aria-hidden'), 'true');
+key(1, 'End'); assert.equal(document.activeElement, links[2]);
+key(2, 'ArrowRight'); assert.equal(document.activeElement, links[0]);
+key(0, 'ArrowLeft'); assert.equal(document.activeElement, links[2]);
+key(2, 'Home'); assert.equal(document.activeElement, links[0]);
+context.window.nojsTabs({ tabs: document.createElement('div'), tabBar: document.createElement('div') });
+console.log('Keyboard tabs, accessible state and empty panels passed');

data/spec/client_examples/context_spec.rb

@@ -0,0 +1,68 @@
+require 'spec_helper'
+
+describe HaveAPI::ClientExample::Context do
+  let(:description) { { resources: { widget: { actions: {} } } } }
+  let(:context) do
+    described_class.new(version: '1', host: 'api.test', base_url: 'https://api.test/mount/',
+                        version_url: 'https://api.test/mount/v1/', description:)
+  end
+
+  it 'copies and freezes request data without freezing the source description' do
+    expect(context.description).to be_frozen
+    expect(context.description[:resources]).to be_frozen
+    expect(description[:resources]).not_to be_frozen
+    description[:resources][:secret] = {}
+    expect(context.description[:resources]).not_to have_key(:secret)
+  end
+
+  it 'keeps per-example state independent and leaves the original context intact' do
+    data = { request: { name: 'safe' } }
+    child = context.with(resource_path: ['widget'], action_name: 'show', sample: data)
+    data[:request][:name].replace('changed')
+    expect(child.sample[:request][:name]).to eq('safe')
+    expect(context.sample).to be_nil
+    expect(child.resource_path).to eq(['widget'])
+    expect(child).to be_frozen
+  end
+
+  it 'preserves legacy initialization constructors and wraps plain source' do
+    renderer = Class.new(HaveAPI::ClientExample) do
+      def initialize(host, base_url, version)
+        raise ArgumentError, 'expected API version 1' unless version == '1'
+
+        super
+      end
+
+      def init
+        "#{base_url}v#{version}/"
+      end
+    end
+    result = renderer.render(:init, context:)
+    expect(result).to eq(status: :code, code: 'https://api.test/mount/v1/')
+    expect(result).to be_frozen
+    expect(result[:code]).to be_frozen
+  end
+
+  it 'preserves request/response renderers and nil legacy authentication' do
+    renderer = Class.new(HaveAPI::ClientExample) do
+      def request(_sample)
+        'request'
+      end
+
+      def response(_sample)
+        'response'
+      end
+    end
+    expect(renderer.render(:example, context:)).to eq(status: :code, code: "request\n\nresponse")
+    expect(renderer.render(:auth, context:, auth_method: :basic, auth_description: {})).to be_nil
+  end
+
+  it 'wraps a limitation without allowing HTML or an invalid result contract' do
+    renderer = Class.new(HaveAPI::ClientExample) do
+      def init
+        { status: :limitation, reason: 'Cannot render <this>' }
+      end
+    end
+    expect(renderer.render(:init, context:)).to eq(status: :limitation, reason: 'Cannot render <this>')
+  end
+end

data/spec/client_examples/dynamic_acceptance.md

@@ -0,0 +1,83 @@
+# Dynamic example verification
+
+The six JavaScript, TypeScript and Python variants are ordinary server renderers.
+They require no generated-SDK profile. Their examples use exact public lookups,
+mounted base URLs and explicit API versions. Credentials come from environment
+variables in the example process; no example executes in a documentation request.
+
+Run the focused checks in the prepared top-level Nix environment:
+
+```sh
+cd servers/ruby
+bundle exec rspec spec/client_examples/dynamic_js_spec.rb \
+  spec/client_examples/dynamic_python_spec.rb \
+  spec/client_examples/dynamic_metadata_spec.rb \
+  spec/client_examples/dynamic_acceptance_spec.rb
+```
+
+The unit checks parse the actual generated source and compile both TypeScript
+variants against emitted public declarations. Prepare the JavaScript build and
+its declared development dependencies first. The Rack fixture check renders real
+mounted HTML and verifies the extraction boundary and request/result fixtures;
+it opens no listening socket and does not install packages.
+
+`make test-documentation-python` runs the supplemental native Python request
+builder checks in `test_support/dynamic_protocol_spec.rb` and
+`test_support/dynamic_python_login_spec.rb`. Prepare the locked Python
+component environment with `make release-deps` first; the check uses
+`clients/python/.venv/bin/python` and imports the checkout protocol implementation.
+It cross-checks GET limitations, JSON methods and required input metadata without
+transport. It installs nothing and is separate from ordinary Ruby spec discovery.
+The focused JavaScript specs cross-check the built callback and async query/body
+serializers with a mocked transport. The full `make test` includes both checks.
+
+Python token-login examples read required request fields from JSON values in
+`HAVEAPI_AUTH_*` environment variables. For example, an API that requires
+`lifetime` reads `HAVEAPI_AUTH_lifetime`. The examples omit optional lifetime and
+interval fields. The acceptance fixture explicitly chooses `"fixed"` from its
+advertised lifetime values and omits optional interval. The Python challenge
+object supplies the continuation token.
+
+`dynamic_acceptance.rb` checks the installed packages. Supply the built npm and
+Python artifacts, the compiler and Node declaration directories, and a directory
+for evidence. Paths are absolute because the harness changes to an
+isolated consumer:
+
+```sh
+cd servers/ruby
+bundle exec ruby spec/client_examples/dynamic_acceptance.rb \
+  --npm-artifact /absolute/path/dist/haveapi-client-0.30.0.tgz \
+  --python-artifact /absolute/path/dist/haveapi_client-0.30.0-py3-none-any.whl \
+  --typescript /absolute/path/clients/js/node_modules/typescript/bin/tsc \
+  --node-types /absolute/path/clients/js/node_modules/@types \
+  --output /absolute/path/session/dynamic-acceptance-wheel
+```
+
+Repeat with the retained Python sdist and a separate evidence directory. Replace
+artifact versions with the release being tested. The test installs the supplied
+packages without checkout imports, starts its disposable mounted fixture, extracts
+the code from the served HTML, compiles TypeScript with strict checking and runs
+the snippets with the installed clients. It checks discovery, Basic/existing
+token/OAuth credentials, a deterministic token challenge, success/failure and
+request receipts preserving exact names, path order, Unicode, nested Custom
+values, omission, null, empty strings, false and zero. Output and extracted
+programs remain in the evidence directory. The fixture stops and disposable
+consumer is removed when the operation exits.
+
+Each snippet's output is saved before completion checks, including nonzero
+exits. Token panels have separate `example-N-challenge.log` files for the login
+flow without an existing token. `fixture.log` records request method, path and
+HTTP status; the trace excludes headers, query strings and request bodies.
+
+JavaScript list input and nested GET/OPTIONS query values produce a visible
+limitation; HEAD input retains the client's JSON body behavior. Python GET
+examples use a conservative flat-scalar subset with nonempty, bracket-free
+parameter names and namespaces. Custom values must be strings or nullable nulls;
+structured GET values produce a limitation even when the client supports them.
+Python POST, PUT and DELETE retain supported object/list JSON input; unsupported
+methods produce a limitation. Required global or object input metadata also
+produces a limitation because the sample format has no metadata input channel.
+Optional metadata needs no invented values. Prose-only and incomplete samples do
+not become fabricated calls. Callback examples print the raw response; async
+examples use the actual invocation receipt. Operation waiting is shown only through the client's existing
+API, and a timeout is not a cancellation of the server operation.