docs-kit 1.2.1 → 1.4.0

data/lib/docs_kit/configuration.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require_relative "shareable"
 require_relative "seo_config"
 require_relative "landing_config"
 
@@ -78,6 +79,17 @@ module DocsKit
     # stylesheets (e.g. a separate rouge theme) lists them here.
     attr_accessor :stylesheets
 
+    # The import map entry point the Shell loads. Defaults to "application"
+    # (javascript_importmap_tags' own default). A host with a dedicated docs
+    # import map names its entry point here, e.g. "docs".
+    attr_accessor :importmap_entry_point
+
+    # The import map the Shell renders: nil (the default → the host's
+    # Rails.application.importmap), an Importmap::Map, or a zero-arity callable
+    # returning one, resolved per render so a map rebuilt on code reload is
+    # picked up. Read via #resolved_importmap.
+    attr_accessor :importmap
+
     # The Rouge theme class used by DocsUI::Code for inline syntax-highlight CSS.
     # This is the BASE (light) theme, emitted un-scoped so it applies to every
     # theme unless a dark override wins (see #code_theme_dark).
@@ -265,7 +277,7 @@ module DocsKit
 
     # The sentinel "no explicit nav" lambda. #nav_groups compares against this
     # identity to decide whether to derive the sidebar from #nav_registries.
-    DEFAULT_NAV = -> { {} }
+    DEFAULT_NAV = DocsKit::Shareable.make(-> { {} })
 
     # The search-palette shortcuts before this was configurable — "/" and the
     # platform command chord — so a site that never sets #search_shortcuts keeps
@@ -307,6 +319,8 @@ module DocsKit
       @nav_registries = {}
       @version_badge = nil
       @stylesheets = %w[application]
+      @importmap_entry_point = "application"
+      @importmap = nil
       @code_theme = "Rouge::Themes::Monokai"
       @code_theme_dark = nil
       @dark_themes = DEFAULT_DARK_THEMES
@@ -334,6 +348,8 @@ module DocsKit
       @versions = []
       @repo_url = nil
       @snapshots_path = nil
+      @openapi_memo = nil
+      @finalized = nil
     end
 
     # The normalized App Home link (a DocsKit::TopbarLink), or nil when unset —
@@ -440,16 +456,60 @@ module DocsKit
     # spec in development is picked up without a server restart. Raises a
     # DocsKit::Error naming the knob when read while #openapi is unset — a missing
     # spec has nothing useful to degrade to.
+    #
+    # The memo lives on this configuration, so a replaced one takes its
+    # Document with it, and its mtime check-then-set runs under a per-Ractor
+    # lock (DocsKit::Store): threads that miss together load the spec once and
+    # read the same Document. A configuration is only ever read in the Ractor
+    # that built it, so that Ractor's lock is the one that matters.
     def openapi_document
       raise DocsKit::Error, "no OpenAPI spec configured — set c.openapi to a path or Hash" if @openapi.nil?
 
+      source = @openapi
       mtime = openapi_source_mtime
-      return @openapi_document if defined?(@openapi_document) && @openapi_document_mtime == mtime
+      DocsKit::Store.fetch(:docs_kit_openapi_lock) { Mutex.new }.synchronize do
+        memo = @openapi_memo
+        next memo.fetch(:document) if memo && memo.fetch(:source).equal?(source) && memo.fetch(:mtime) == mtime
 
-      @openapi_document_mtime = mtime
-      @openapi_document = DocsKit::OpenApi.load(@openapi)
+        DocsKit::OpenApi.load(source).tap do |document|
+          @openapi_memo = { source: source, mtime: mtime, document: document }
+        end
+      end
     end
 
+    # Resolves, once at boot, what a render would otherwise look up per call:
+    # the Rouge theme classes and every registered page's view class (frozen,
+    # so a non-main Ractor can read them), and fills the lazy memos (brand logo,
+    # SEO, landing, the optional-mcp probe) so no request races to fill them.
+    # Called by DocsKit.finalize! (the engine's after_initialize, and after every
+    # code reload); DocsKit.configure re-opens it (#reopen!). The host's
+    # callables (brand, nav, version_badge, importmap, ...) are kept as they are:
+    # they can close over app state, so the configuration itself stays
+    # main-Ractor-only. A theme assigned directly afterwards still wins:
+    # the resolved class is only used while its source setting is unchanged.
+    def finalize!
+      brand_logo
+      seo
+      landing
+      mcp_gem_present?
+      each_registry { |registry| registry.finalize! if registry.respond_to?(:finalize!) }
+      @finalized = DocsKit::Shareable.make(
+        code_theme: @code_theme, code_theme_class: resolve_code_theme_class,
+        code_theme_dark: @code_theme_dark, code_theme_dark_class: resolve_code_theme_dark_class
+      )
+      self
+    end
+
+    # Drops what #finalize! resolved (and the registries' resolved view classes),
+    # so the next reads resolve lazily against the current settings.
+    def reopen!
+      @finalized = nil
+      each_registry { |registry| registry.reopen! if registry.respond_to?(:reopen!) }
+      self
+    end
+
+    def finalized? = !@finalized.nil?
+
     # The effective client map for DocsUI::RequestExample: the four shipped
     # defaults with site overrides/extensions merged over them. Hash#merge keeps
     # a reused token in its original position and appends new tokens in
@@ -544,14 +604,54 @@ module DocsKit
 
     public
 
+    # The localStorage namespace. A callable brand can't be slugged: the key must
+    # be stable per browser, not per request, so a callable brand needs an
+    # explicit c.nav_storage_key (checked again by DocsKit.configure).
     def nav_storage_key
-      @nav_storage_key || @brand.to_s.downcase.gsub(/[^a-z0-9]+/, "-").gsub(/\A-+|-+\z/, "")
+      return @nav_storage_key if @nav_storage_key
+      if @brand.respond_to?(:call)
+        raise DocsKit::Error,
+              "c.brand is a callable, so set c.nav_storage_key to a stable key " \
+              "(the sidebar/theme localStorage namespace must not change per request)"
+      end
+
+      @brand.to_s.downcase.gsub(/[^a-z0-9]+/, "-").gsub(/\A-+|-+\z/, "")
     end
 
+    # The raw configured suffix (or the raw brand when unset). The chrome reads
+    # #title_suffix_text, which resolves a callable.
     def title_suffix
       @title_suffix || @brand
     end
 
+    # The rendered brand. A String is returned as-is; a zero-arity callable is
+    # invoked on every read (never memoize it — the point is a per-request
+    # value, e.g. -> { Current.tenant_name }).
+    def brand_text
+      resolve_text(@brand).to_s
+    end
+
+    # True when the brand is a callable, i.e. anything that embeds the brand
+    # (the chrome, llms.txt) may differ per request and must not be stored in a
+    # shared cache.
+    def brand_per_request?
+      @brand.respond_to?(:call)
+    end
+
+    # The rendered <title>/og:title suffix: #title_suffix resolved like
+    # #brand_text, falling back to the resolved brand. nil only when both are nil,
+    # so the title join drops it instead of leaving a dangling separator.
+    def title_suffix_text
+      resolve_text(@title_suffix.nil? ? @brand : @title_suffix)
+    end
+
+    # Raises at configure time for a config the chrome can't render (today: a
+    # callable brand without a stable nav_storage_key). Called by DocsKit.configure.
+    def validate!
+      nav_storage_key
+      self
+    end
+
     # Whether the built-in MCP endpoint is active: the #mcp toggle is on AND the
     # optional `mcp` gem is loadable — the same "toggle AND capability" shape as
     # #search_enabled?. Read by DocsKit::LlmsText (to advertise /mcp in llms.txt)
@@ -609,6 +709,12 @@ module DocsKit
       @version_badge.to_s
     end
 
+    # The import map the Shell renders, or nil for the host's default map. A
+    # callable is invoked on every read (once per render).
+    def resolved_importmap
+      @importmap.respond_to?(:call) ? @importmap.call : @importmap
+    end
+
     # The default Rouge theme both #code_theme_class and #code_theme_dark_class
     # fall back to when a configured theme name can't be resolved — so a typo'd
     # theme name degrades gracefully instead of raising on every code block.
@@ -618,9 +724,7 @@ module DocsKit
     # name that doesn't resolve degrades to the default theme rather than raising
     # NameError on every DocsUI::Code render.
     def code_theme_class
-      return @code_theme if @code_theme.is_a?(Class)
-
-      resolve_theme(@code_theme) || Object.const_get(DEFAULT_CODE_THEME)
+      resolved(:code_theme_class, :code_theme, @code_theme) { resolve_code_theme_class }
     end
 
     # The dark Rouge theme class resolved from #code_theme_dark (String or
@@ -628,10 +732,7 @@ module DocsKit
     # dark code CSS only when this is non-nil, so an unresolvable name degrades to
     # nil (no dark restyle) rather than raising.
     def code_theme_dark_class
-      return if @code_theme_dark.nil?
-      return @code_theme_dark if @code_theme_dark.is_a?(Class)
-
-      resolve_theme(@code_theme_dark)
+      resolved(:code_theme_dark_class, :code_theme_dark, @code_theme_dark) { resolve_code_theme_dark_class }
     end
 
     # The dark themes the site actually ships: #dark_themes intersected with
@@ -644,6 +745,33 @@ module DocsKit
 
     private
 
+    def resolve_code_theme_class
+      return @code_theme if @code_theme.is_a?(Class)
+
+      resolve_theme(@code_theme) || Object.const_get(DEFAULT_CODE_THEME)
+    end
+
+    def resolve_code_theme_dark_class
+      return if @code_theme_dark.nil?
+      return @code_theme_dark if @code_theme_dark.is_a?(Class)
+
+      resolve_theme(@code_theme_dark)
+    end
+
+    # What #finalize! resolved for key, while the setting it came from is still
+    # the same object; otherwise the block resolves it now (never finalized,
+    # re-opened, or the setting was reassigned since).
+    def resolved(key, setting, current)
+      finalized = @finalized
+      return yield unless finalized && finalized.fetch(setting).equal?(current)
+
+      finalized.fetch(key)
+    end
+
+    def each_registry(&)
+      (@nav_registries || {}).each_value(&)
+    end
+
     # Resolve a Rouge theme constant from its String name, returning nil (not
     # raising) when the name doesn't resolve — a typo'd or unloaded theme must
     # not crash every code block on the page.
@@ -652,5 +780,12 @@ module DocsKit
     rescue NameError
       nil
     end
+
+    # A String-or-callable knob's value for this render: a callable is invoked
+    # and stringified, nil stays nil, anything else is stringified.
+    def resolve_text(value)
+      value = value.call if value.respond_to?(:call)
+      value&.to_s
+    end
   end
 end

data/lib/docs_kit/engine.rb

@@ -15,7 +15,7 @@ module DocsKit
     config.eager_load_paths = []
     config.paths["app"].skip_eager_load!
 
-    JAVASCRIPT_PATH = root.join("app/javascript")
+    JAVASCRIPT_PATH = root.join("app/javascript").freeze
 
     initializer "docs_kit.controller_helper" do
       ActiveSupport.on_load(:action_controller_base) do
@@ -31,15 +31,35 @@ module DocsKit
       Mime::Type.register("text/markdown", :md) unless Mime::Type.lookup_by_extension(:md)
     end
 
+    # Resolve the configuration's per-render lookups once (DocsKit.finalize!)
+    # after the host has configured the kit: its to_prepare DocsKit.configure
+    # runs before after_initialize at boot. With code reloading on, every
+    # reload re-runs that configure (which re-opens the configuration) against
+    # the reloaded classes, so finalize again after it: a to_prepare added
+    # here, after boot, runs after every to_prepare the host registered.
+    initializer "docs_kit.finalize" do |app|
+      app.config.after_initialize do
+        DocsKit.finalize!
+        app.reloader.to_prepare { DocsKit.finalize! } if app.config.reloading_enabled?
+      end
+    end
+
     # Serve the bundled Stimulus controller (docs_nav) as an asset.
     initializer "docs_kit.assets" do |app|
       app.config.assets.paths << JAVASCRIPT_PATH.to_s if app.config.respond_to?(:assets)
     end
 
+    # Host-facing engine options. `config.docs_kit.auto_pin = false` (in
+    # config/application.rb) keeps the gem's pin out of the host's shared import
+    # map, for a host that pins `docs_kit/controllers` in a dedicated docs map.
+    config.docs_kit = ActiveSupport::OrderedOptions.new
+    config.docs_kit.auto_pin = true
+
     # Auto-pin the controller for importmap-rails consumers, so a host app gets
     # `docs_kit/controllers/docs_nav_controller` with no manual pin.
     initializer "docs_kit.importmap", before: "importmap" do |app|
       next unless app.config.respond_to?(:importmap)
+      next unless app.config.docs_kit.auto_pin
 
       importmap = app.config.importmap
       importmap.paths << root.join("config/importmap.rb") if importmap.respond_to?(:paths)

data/lib/docs_kit/llms_text.rb

@@ -33,7 +33,7 @@ module DocsKit
     # single tight list (no blank lines between bullets), per the llmstxt.org
     # convention.
     def index(config, base_url: nil)
-      blocks = ["# #{config.brand}"]
+      blocks = ["# #{config.brand_text}"]
       tagline = config.tagline
       blocks << "> #{tagline}" if tagline && !tagline.to_s.empty?
       blocks.concat(section_blocks(config, base_url))

data/lib/docs_kit/mcp_server.rb

@@ -28,7 +28,7 @@ module DocsKit
       return unless mcp_available?
 
       server = MCP::Server.new(
-        name: config.brand.to_s,
+        name: config.brand_text,
         version: DocsKit::VERSION,
         instructions: instructions_for(config, base_url),
         server_context: { config:, base_url:, view_context: }
@@ -54,7 +54,7 @@ module DocsKit
       lines = []
       tagline = config.tagline
       lines << tagline.to_s if tagline && !tagline.to_s.empty?
-      lines << "Read-only documentation tools for #{config.brand}. " \
+      lines << "Read-only documentation tools for #{config.brand_text}. " \
                "Use search_docs to find sections, get_page to read a page's Markdown, " \
                "and list_pages to enumerate the docs. Full index: #{llms}."
       lines.join(" ")

data/lib/docs_kit/og_generator.rb

@@ -106,7 +106,9 @@ module DocsKit
 
       port = free_port
       app = Rails.application
-      server_thread = Thread.new do
+      # The docs_kit:og rake task's one-shot local server (a CLI, never a request
+      # path): one thread, killed in the ensure below.
+      server_thread = Thread.new do # rubocop:disable ThreadSafety/NewThread
         Rackup::Handler.get("webrick").run(app, Port: port, Host: "127.0.0.1", Logger: null_logger, AccessLog: [])
       rescue LoadError
         Rack::Handler.get("webrick").run(app, Port: port, Host: "127.0.0.1", Logger: null_logger, AccessLog: [])

data/lib/docs_kit/registry.rb

@@ -62,34 +62,44 @@ module DocsKit
     # given. Appends to the registry in declaration order (== sidebar order).
     #
     #   page "Getting started", group: "Guide", icon: "rocket", slug: "start", view: "Start"
+    #
+    # The DSL runs in the registry's class body, at load. Each value is made
+    # Ractor-shareable on write (the page list is replaced, never appended to
+    # in place), so a non-main Ractor can read a registry and no thread can
+    # mutate it afterwards.
     def page(title, group:, slug: nil, view: nil, icon: nil)
       raise Error, "cannot mix `page` and `entries` in one registry" if defined?(@entries) && @entries
 
-      (@pages ||= []) << {
+      entry = {
         title: title,
         group: group,
         slug: slug || title.parameterize,
         view: view || title.parameterize(separator: "_").camelize,
         icon: icon
-      }.freeze
+      }
+      @pages = DocsKit::Shareable.make([*(defined?(@pages) && @pages), entry])
     end
 
     # href = "#{path_prefix}/#{slug}". Defaults to "/docs".
     def path_prefix(value = nil)
-      @path_prefix = value if value
+      @path_prefix = DocsKit::Shareable.make(value) if value
       @path_prefix || "/docs"
     end
 
     # The namespace a page's view_class resolves under (v2 pages only), e.g.
     # "Views::Docs::Pages". Required to resolve views via the default Entry.
+    # Setting it drops the views #finalize! resolved under the old namespace.
     def view_namespace(value = nil)
-      @view_namespace = value if value
+      if value
+        @view_namespace = DocsKit::Shareable.make(value)
+        @view_classes = nil
+      end
       @view_namespace
     end
 
     # The attribute used by #grouped (default :group).
     def group_by_attribute(attr = nil)
-      @group_by_attribute = attr if attr
+      @group_by_attribute = DocsKit::Shareable.make(attr) if attr
       @group_by_attribute || :group
     end
 
@@ -98,12 +108,32 @@ module DocsKit
     # v2 pages are wrapped in the default Entry; hash entries in the site's class.
     def all
       if defined?(@pages) && @pages
-        @pages.map { |attrs| Entry.new(attrs, path_prefix, view_namespace) }
+        views = @view_classes || Entry::NO_VIEWS
+        @pages.map { |attrs| Entry.new(attrs, path_prefix, view_namespace, views) }
       else
         (entries || []).map { |entry| new(entry) }
       end
     end
 
+    # Resolves every `page`'s view class once (DocsKit.finalize!, at boot) into
+    # a frozen { view name => class } map the entries read instead of
+    # constantizing on every call. Only views that resolve are kept, so a page
+    # written later still turns up. An `entries` registry resolves its own views.
+    def finalize!
+      resolved = Array(defined?(@pages) && @pages).each_with_object({}) do |attrs, map|
+        view_class = Entry.resolve(view_namespace, attrs[:view])
+        map[attrs[:view]] = view_class if view_class
+      end
+      @view_classes = DocsKit::Shareable.make(resolved)
+      self
+    end
+
+    # Drops the resolved view classes: entries constantize again (DocsKit.configure).
+    def reopen!
+      @view_classes = nil
+      self
+    end
+
     # The instance whose slug matches, or nil.
     def from_slug(slug)
       all.find { |item| item.slug.to_s == slug.to_s }
@@ -129,15 +159,26 @@ module DocsKit
     # resolved under the registry's view_namespace (nil until the class exists,
     # preserving the no-dead-links behavior).
     class Entry
+      NO_VIEWS = {}.freeze
+
+      # The page class `view_name` names under `view_namespace`, or nil.
+      def self.resolve(view_namespace, view_name)
+        return unless view_namespace
+
+        "#{view_namespace}::#{view_name}".safe_constantize
+      end
+
       attr_reader :slug, :title, :group, :icon, :view_name, :href
 
-      def initialize(attrs, path_prefix, view_namespace)
+      # view_classes: the registry's finalized { view name => class } map.
+      def initialize(attrs, path_prefix, view_namespace, view_classes = NO_VIEWS)
         @slug = attrs[:slug]
         @title = attrs[:title]
         @group = attrs[:group]
         @icon = attrs[:icon]
         @view_name = attrs[:view]
         @view_namespace = view_namespace
+        @view_classes = view_classes
         @href = "#{path_prefix}/#{@slug}"
       end
 
@@ -145,7 +186,7 @@ module DocsKit
       def view_class
         return unless @view_namespace
 
-        "#{@view_namespace}::#{@view_name}".safe_constantize
+        @view_classes.fetch(@view_name) { self.class.resolve(@view_namespace, @view_name) }
       end
 
       # The renderable instance for this page (nil when unauthored) — the seam

data/lib/docs_kit/shareable.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module DocsKit
+  # Makes a boot-time value Ractor-shareable: Ractor.make_shareable (a deep
+  # freeze; a capture-free Proc becomes an isolated one) where the engine has
+  # Ractors, a plain #freeze where it has none (TruffleRuby, JRuby). For
+  # constants and DSL values written once at load, so a non-main Ractor can read
+  # them and no thread can mutate them afterwards.
+  module Shareable
+    def self.make(value)
+      defined?(::Ractor) && ::Ractor.respond_to?(:make_shareable) ? ::Ractor.make_shareable(value) : value.freeze
+    end
+  end
+end

data/lib/docs_kit/snapshot.rb

@@ -28,27 +28,41 @@ module DocsKit
       # invalidated when manifest.json's mtime changes — the same
       # reload-on-change posture as Configuration#openapi_document, so editing
       # a snapshot in development is picked up without a server restart.
+      #
+      # The cache is per Ractor (DocsKit::Store) and its check-then-set runs
+      # under that Ractor's lock, so threads that miss a cold key together
+      # build it once and all get the same instance.
       def for(version, config: DocsKit.configuration)
         version = DocVersion.from(version)
         root = root_for(version, config)
         mtime = manifest_mtime(root)
-        key = [version.id.to_s, root.to_s]
-
-        @cache ||= {}
-        cached = @cache[key]
-        return cached.fetch(:snapshot) if cached && cached.fetch(:mtime) == mtime
-
-        new(version: version, root: root).tap do |snapshot|
-          @cache[key] = { snapshot: snapshot, mtime: mtime }
-        end
+        memoize([version.id.to_s, root.to_s], mtime) { new(version: version, root: root) }
       end
 
       def reset_cache!
-        @cache = {}
+        cache = cache_store
+        cache.fetch(:lock).synchronize { cache.fetch(:entries).clear }
       end
 
       private
 
+      def cache_store
+        DocsKit::Store.fetch(:docs_kit_snapshots) { { lock: Mutex.new, entries: {} } }
+      end
+
+      # The cached snapshot for key while its manifest mtime is unchanged, else
+      # the block's fresh one (stored) — the whole check-then-set under the lock.
+      def memoize(key, mtime)
+        cache = cache_store
+        cache.fetch(:lock).synchronize do
+          entries = cache.fetch(:entries)
+          cached = entries[key]
+          next cached.fetch(:snapshot) if cached && cached.fetch(:mtime) == mtime
+
+          yield.tap { |snapshot| entries[key] = { snapshot: snapshot, mtime: mtime } }
+        end
+      end
+
       # <snapshots_path>/<id>, or nil when no snapshots path resolves (no
       # config, no Rails) — which reads back as an empty snapshot.
       def root_for(version, config)
@@ -70,10 +84,13 @@ module DocsKit
 
     attr_reader :version, :root
 
+    # Built whole here, never lazily: a cached Snapshot is shared by every
+    # server thread, so it carries no memo a reader could race to fill.
     def initialize(version:, root:)
       @version = version
       @root = root
       @manifest = read_manifest
+      @registries = build_registries
     end
 
     # Every snapshot page across the manifest's registries, in manifest order —
@@ -116,8 +133,10 @@ module DocsKit
     private
 
     # The manifest's registries as { heading:, entries: [Snapshot::Entry] }.
-    def registries
-      @registries ||= Array(@manifest && @manifest["registries"]).map do |registry|
+    attr_reader :registries
+
+    def build_registries
+      Array(@manifest && @manifest["registries"]).map do |registry|
         prefix = registry["path_prefix"] || "/docs"
         {
           heading: registry["heading"],

data/lib/docs_kit/store.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module DocsKit
+  # Per-Ractor lazy storage for docs-kit's caches: `Store.fetch(:docs_kit_x) { {} }`.
+  # A copy of conformance-kit's ConformanceKit::Store (MIT, same author): the kit
+  # is a development dependency only, so the gem carries its own.
+  #
+  # On Ruby 3.4+ this is `Ractor.store_if_absent`, atomic and per-Ractor. Below
+  # 3.4 (and on engines without Ractor) the main Ractor uses one Hash guarded by
+  # a Mutex, created at load (never lazily, so there is no check-then-set race);
+  # it is allowlisted main-only in .conformance.yml. A non-main Ractor on 3.3
+  # cannot read it, so it keeps its own values in Ractor-local storage instead.
+  # That path has no lock (none is shareable): threads of one Ractor that miss
+  # together may each build a value, but only the first one stored is kept and
+  # returned to all of them.
+  module Store
+    # rubocop:disable ThreadSafety/MutableClassInstanceVariable -- main-only fallback, guarded by @fallback_lock
+    @fallback_lock = Mutex.new
+    @fallback_values = {}
+    # rubocop:enable ThreadSafety/MutableClassInstanceVariable
+
+    class << self
+      def fetch(key, &init)
+        raise ArgumentError, "DocsKit::Store.fetch(#{key.inspect}) needs an initializer block" unless init
+        return ::Ractor.store_if_absent(key, &init) if native?
+        return ractor_local(key, &init) unless main_ractor?
+
+        @fallback_lock.synchronize do
+          @fallback_values.fetch(key) { @fallback_values[key] = yield }
+        end
+      end
+
+      private
+
+      def main_ractor? = !defined?(::Ractor) || ::Ractor.current == ::Ractor.main
+
+      # Boxed, so a nil or false value is cached rather than rebuilt on every fetch.
+      # The value is built before the check-then-store, which runs no Ruby code
+      # between the read and the write, so a thread that built a value after
+      # another stored one gets the stored one.
+      def ractor_local(key)
+        slot = :"docs_kit_store/#{key}"
+        stored = ::Ractor.current[slot]
+        return stored.first if stored
+
+        built = [yield]
+        (::Ractor.current[slot] ||= built).first
+      end
+
+      public
+
+      def native?
+        defined?(::Ractor) ? ::Ractor.respond_to?(:store_if_absent) : false
+      end
+    end
+  end
+end

data/lib/docs_kit/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module DocsKit
-  VERSION = "1.2.1"
+  VERSION = "1.4.0"
 end

data/lib/docs_kit.rb

@@ -5,6 +5,7 @@ require "rouge"
 require "zeitwerk"
 
 require_relative "docs_kit/version"
+require_relative "docs_kit/shareable"
 require_relative "docs_kit/configuration"
 
 # DocsKit — a reusable docs-site component library: the shared Phlex chrome
@@ -17,19 +18,36 @@ require_relative "docs_kit/configuration"
 module DocsKit
   class Error < StandardError; end
 
+  # Built at load, never lazily: no first-request race to build two.
+  @configuration = Configuration.new
+
   class << self
-    # The current configuration, memoized. Reset with DocsKit.reset_configuration!.
-    def configuration
-      @configuration ||= Configuration.new
-    end
+    # The current configuration. Reset with DocsKit.reset_configuration!.
+    # Assigned at load and by reset_configuration! (boot, specs) on the main
+    # Ractor; request threads only read it. Main-only (.conformance.yml): it
+    # holds the host's per-request callables (brand, nav, version_badge, ...).
+    attr_reader :configuration
 
+    # Re-opens a finalized configuration first (a development reload re-runs
+    # the host's to_prepare configure), so every setting takes effect.
     def configure
+      configuration.reopen!
       yield(configuration)
-      configuration
+      configuration.validate!
+    end
+
+    # Resolves the configuration's per-render lookups once (see
+    # Configuration#finalize!). In a Rails app the engine calls it after the
+    # host has configured the kit, and again after every code reload; outside
+    # Rails, call it once the configuration is complete.
+    def finalize!
+      configuration.finalize!
     end
 
+    # A fresh default configuration (specs; a host that re-boots its config).
+    # Runs at boot or between examples, never on a request.
     def reset_configuration!
-      @configuration = Configuration.new
+      @configuration = Configuration.new # rubocop:disable ThreadSafety/ClassInstanceVariable
     end
   end
 end
@@ -54,6 +72,8 @@ loader.push_dir(File.expand_path("docs_kit", __dir__), namespace: DocsKit)
 loader.push_dir(File.expand_path("../app/components/docs_ui", __dir__), namespace: DocsUI)
 loader.ignore(File.expand_path("docs_kit/version.rb", __dir__))
 loader.ignore(File.expand_path("docs_kit/configuration.rb", __dir__))
+# Required eagerly above (configuration.rb's constants use it at load).
+loader.ignore(File.expand_path("docs_kit/shareable.rb", __dir__))
 # Required eagerly by configuration.rb (a plain-Ruby value object, no Rails), so
 # ignore it here too or zeitwerk double-manages the constant.
 loader.ignore(File.expand_path("docs_kit/seo_config.rb", __dir__))