docs-kit 1.2.1 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 04c64683910c10c37f660008f8891ca9f87296a0aea1ddc67f9d9a199975cccd
-  data.tar.gz: d357822c1df8899b50008f28366992bde0b9d6f622ec90975b5926f11d2de2d7
+  metadata.gz: 6340fb386df08272f63e525ca81d43baaa1f440a82287e4a34e9a392b220a530
+  data.tar.gz: 3740655d5194976ea25a3ed3cdd6a633bb593c03c288a1c3a069d16d7c522cfe
 SHA512:
-  metadata.gz: a2b905a1b80c5e156ea7e652ba45cb4d2ec54c91ad040754112cdd481644b7698fd5356459faf06f46ac140c0c6562b8989039b69585b3f257a3b5629cfe0d49
-  data.tar.gz: 9837ae7885fb3c6ad358b585853aa7d0dee63b9807c574f15e8543f70ae5de6ecea4f5a2755391588a111fa5d05fcf2456a76b9040a648b86bcf3cf767700171
+  metadata.gz: 01e79925a8f67168a27e898fb13f6a9a5658b331b8a5b1ba854c9481c1afc5256f7ec89fb80a6e762f9ec0fd399425c38be82a1943a8fc9517e5cd0803e32fa4
+  data.tar.gz: a9a74e687605433c9a23069d6760a5a14093e898e0f64b133ede84f951f9f4deead0e98ad7735ca5a87e9f79ba86c9a340993004f1ece46731bda6016e6b9bab

data/CHANGELOG.md

@@ -2,6 +2,101 @@
 
 ## [Unreleased]
 
+## [1.4.0]
+
+### Upgrading from 1.3
+
+Nothing to change for a site whose initializer configures docs-kit in a
+`to_prepare` block, as the generated one does. Three things now fail loudly
+instead of later or never: a broken `brand_logo` raises at boot, in
+development too; mutating a registry DSL or `DocsUI::Page` macro value in place
+raises `FrozenError`; so does mutating one of docs-kit's constants.
+
+### Fixed
+
+- **A cold archived version is built once, however many requests ask.**
+  `DocsKit::Snapshot.for` cached snapshots in an unguarded class ivar, so
+  threads that missed a version together each read and parsed its
+  `manifest.json` and raced to store it. The cache is now per Ractor and its
+  check-then-set runs under a lock; `Configuration#openapi_document`'s
+  mtime-checked memo likewise. (#91)
+- **No per-render constant lookups once the app has booted.** The engine now
+  calls `DocsKit.finalize!` once the host has configured the kit, with no app
+  code: the Rouge code themes and every registered page's view class are
+  resolved once into frozen maps instead of `Object.const_get` /
+  `safe_constantize` on every render, and the brand logo, SEO, landing and
+  optional-mcp memos are filled at boot rather than by whichever request comes
+  first. `DocsKit.configure` re-opens it, and a theme assigned directly
+  afterwards still wins. Outside Rails, call `DocsKit.finalize!` yourself. (#91)
+
+### Changed
+
+- **Finalized after boot in every environment, and after every reload.** The
+  engine finalizes in `after_initialize` in development too. With code
+  reloading on, it finalizes again after each reload, once the host's
+  `to_prepare` configure has re-run and re-opened the configuration, so the
+  resolved page views are the reloaded classes. The host's callables (`brand`,
+  `nav`, `version_badge`, `importmap`, ...) are kept as given, never frozen:
+  they may close over app state, so `DocsKit.configuration` stays
+  main-Ractor-only and finalizing never fails on one. (#91)
+- **Boot-time values are frozen.** The registry DSL (`page`, `path_prefix`,
+  `view_namespace`, `group_by_attribute`) and `DocsUI::Page`'s `title`,
+  `eyebrow`, `description` and `on_page` macros deep-freeze what they are
+  given (Ractor-shareable), as do the gem's own constants, and
+  `DocsKit.configuration` is built at load rather than on first read. Code
+  that mutated one of those values in place after declaring it now raises
+  `FrozenError`. (#91)
+- **A broken `brand_logo` fails at boot.** `DocsKit.finalize!` builds the logo,
+  so a missing file or non-SVG markup raises when the app boots, in every
+  environment, instead of on the first render. (#91)
+- docs-kit is held to [conformance-kit](https://github.com/zoolutions/conformance-kit)
+  0.4 in CI: the rubocop-thread_safety cops, thread and fiber contention specs,
+  a Ruby 4.0 Ractor canary (search index, llms.txt, the sidebar tree) and
+  `conformance-audit --strict`, whose allowlist names Rails' and Thor's class
+  state on the engine, controllers and generators by `ancestor:` rule. (#91)
+
+## [1.3.0] — 2026-10-13
+
+### Fixed
+
+- **Markdown links drop a script-bearing href.** `[text](javascript:…)`,
+  `data:`, `vbscript:` and any other scheme outside http(s), `mailto:` and
+  `tel:` now render the link text with no `<a>` (Phlex already refused
+  `javascript:`; `data:` and the rest slipped through). Scheme-less hrefs are
+  unchanged. The same guard `DocsUI::Markdown` images have.
+
+### Added
+
+- **A per-request `brand` and `title_suffix`.** Both accept a zero-arity
+  callable (`c.brand = -> { Current.tenant_name }`), evaluated on every render:
+  the topbar, sidebar header, `<title>`, `og:site_name`, llms.txt and the MCP
+  server name show that request's value. A callable brand needs an explicit
+  `c.nav_storage_key`; `DocsKit.configure` raises without one. New readers
+  `Configuration#brand_text` / `#title_suffix_text`; a String brand renders
+  exactly as before. (#92)
+- **Markdown images render.** `![alt](path "title")` in an `md` island now
+  renders a lazy-loaded `<img>` (it rendered nothing before). In a Rails view
+  a relative path resolves through the site's asset pipeline (`image_path`;
+  off a request it is kept as written); an absolute,
+  protocol-relative or root-relative URL is kept as written; the alt is the
+  description's plain text. A `javascript:`, `data:` or other non-http(s)
+  scheme renders no image. The page's `.md` twin exports it back to
+  `![alt](src)`. (#94)
+- **A dedicated docs import map.** `c.importmap_entry_point` (default
+  `"application"`) and `c.importmap` (an `Importmap::Map` or a callable
+  returning one, resolved per render) choose what the Shell's
+  `javascript_importmap_tags` loads, and `config.docs_kit.auto_pin = false` (in
+  `config/application.rb`) keeps the gem's `docs-nav` pin out of the host's
+  shared map. Unset, the head is unchanged. (#93)
+- **`DocsUI::Page` title, description and eyebrow per instance.** The page now
+  reads `#title`, `#description` and `#eyebrow`, which default to the class
+  macros, so one page class can render many records (`def title = @widget.name`)
+  without an anonymous subclass per render. The `eyebrow`, `description` and
+  `on_page` macros inherit from a parent page when unset. Pages using only the
+  class macros render byte-identically. (#95)
+
+## [1.2.1] — 2026-09-30 (with 1.2.0, same day)
+
 ### Upgrading from 1.1
 
 ```bash

data/README.md

@@ -193,6 +193,20 @@ DocsKit.configure do |c|
 end
 ```
 
+**One app, several hosts?** `brand` and `title_suffix` also take a zero-arity
+callable, evaluated on every render — the topbar, the sidebar header, `<title>`,
+`og:site_name`, llms.txt and the MCP server name all show that request's value.
+A callable brand can't name the localStorage namespace (it must stay stable per
+browser), so set `nav_storage_key` too; `DocsKit.configure` raises without it.
+
+```ruby
+DocsKit.configure do |c|
+  c.brand           = -> { Current.tenant_name }   # Current < ActiveSupport::CurrentAttributes
+  c.title_suffix    = -> { "#{Current.tenant_name} docs" } # optional; unset follows the brand
+  c.nav_storage_key = "docs"
+end
+```
+
 The nav is **derived from the registry**, so you never hand-write it. Each
 registry maps a heading to its authored pages (`Doc.nav_items`); a page that
 isn't written yet is skipped, so there are no dead links. Register a page with
@@ -349,6 +363,33 @@ c.nav = lambda do
 end
 ```
 
+### After boot: finalized, threads and Ractors
+
+The engine calls `DocsKit.finalize!` once the app has booted (`after_initialize`,
+after your `to_prepare` configure) in every environment, and in development again
+after every code reload. It resolves the code themes and every registered page's
+view class once, into frozen maps, and builds the brand logo, SEO, landing and
+optional-mcp memos up front, so no request races another to fill a memo, or
+looks up a theme or a resolved page view. A page whose view class didn't exist
+at boot is still looked up when it is read, so it turns up once written. That
+is also why a broken `brand_logo` fails at boot.
+
+- `DocsKit.configure` re-opens a finalized configuration, so re-running it (a
+  development reload, a spec) takes effect.
+- Outside Rails (a script or Rack app that renders the chrome), call
+  `DocsKit.finalize!` yourself once the configuration is complete.
+- Your callables (`brand`, `title_suffix`, `nav`, `version_badge`, `importmap`)
+  are kept exactly as given: they may close over app state (`Current`, a
+  tenant), so they are never frozen or copied, and finalizing never fails on
+  one. That makes `DocsKit.configuration` main-Ractor-only. Code that runs in a
+  non-main Ractor builds its own `DocsKit::Configuration` from plain values and
+  passes it in (`DocsKit::LlmsText.index(config, ...)`,
+  `DocsKit::Snapshot.for(version, config:)`).
+- What the registry DSL (`page`, `path_prefix`, `view_namespace`) and
+  `DocsUI::Page`'s macros (`title`, `eyebrow`, `description`, `on_page`) are
+  given is deep-frozen when declared, as are docs-kit's own constants: mutating
+  one in place raises `FrozenError`.
+
 ## Render
 
 ```ruby
@@ -431,6 +472,37 @@ end
 `DocsUI::Page` includes the kit, so inside `#content` you call the components
 directly — `DocsUI::Section(...)`, `DocsUI::Code(...)` — no `render … .new`.
 
+### One page class, many records
+
+`title`, `eyebrow` and `description` are class macros by default, but the page
+reads them through **instance** methods — override those when one page class
+renders many records (one reference page per item):
+
+```ruby
+class Views::Docs::Widget < DocsUI::Page
+  eyebrow "Widgets"
+
+  def initialize(widget:) = @widget = widget
+  def title = @widget.name                # masthead <h1> and <title>
+  def description = @widget.summary       # meta/OG description (default: class macro, then #lead)
+  def content = md(@widget.notes)
+end
+
+# controller
+def show = render_page(Views::Docs::Widget.new(widget: Widget.find(params[:id])))
+```
+
+`eyebrow`, `description` and `on_page` inherit: a subclass that leaves one unset
+uses its parent page's. `title` does not — each page names itself.
+
+Such a page usually lives on its own route, outside the registry. If that route
+has no `(.:format)` segment, the masthead's **Markdown** action (which links
+`request.path + ".md"`) would 404 — hide it for that page:
+
+```ruby
+def markdown_action? = false
+```
+
 ### The authoring convention
 
 One rule covers the whole kit: **the primary argument is positional; modifiers
@@ -1051,6 +1123,42 @@ server round-trip:
   of three placements, auto-hiding on short pages. No server-side knowledge of
   the headings, no per-page wiring.
 
+### A dedicated docs import map
+
+By default the Shell loads the host's `application` entry point from
+`Rails.application.importmap`, and the engine adds the `docs-nav` pin to that
+map. A host with several import maps can give its docs their own entry point
+and map, and keep the docs controller out of every other page's preloads:
+
+```ruby
+# config/application.rb — skip the engine's auto-pin into the shared map
+config.docs_kit.auto_pin = false
+
+# config/initializers/docs_kit.rb — build the second map (importmap-rails has no
+# registry for extra maps; the host owns it) and point the docs chrome at it
+DOCS_IMPORTMAP = Importmap::Map.new.draw(Rails.root.join("config/importmaps/docs.rb"))
+
+DocsKit.configure do |c|
+  c.importmap_entry_point = "docs"          # default "application"
+  c.importmap = -> { DOCS_IMPORTMAP }       # default nil → Rails.application.importmap
+end
+```
+
+```ruby
+# config/importmaps/docs.rb — drawn into the docs Importmap::Map above
+pin "docs"
+pin "@hotwired/turbo-rails", to: "turbo.min.js"
+pin "@hotwired/stimulus", to: "stimulus.min.js"
+pin "@hotwired/stimulus-loading", to: "stimulus-loading.js"
+pin_all_from DocsKit::Engine.root.join("app/javascript/docs_kit/controllers"),
+             under: "docs_kit/controllers", to: "docs_kit/controllers"
+```
+
+`c.importmap` takes an `Importmap::Map` or a callable returning one; a callable
+is resolved on every render, so a map rebuilt on code reload is picked up. The
+`docs` entry point registers the controllers with
+`eagerLoadControllersFrom("docs_kit/controllers", application)`.
+
 ### On this page (auto-TOC)
 
 `DocsUI::Page` renders it automatically. The placement is a strategy — set the

data/app/components/docs_ui/callout.rb

@@ -7,9 +7,9 @@ module DocsUI
   #   render DocsUI::Callout.new(:warning) { "Restart the server after…" }
   class Callout < Phlex::HTML
     LEVELS = {
-      note: { klass: "alert-info", icon: "info" },
-      tip: { klass: "alert-success", icon: "lightbulb" },
-      warning: { klass: "alert-warning", icon: "triangle-alert" }
+      note: { klass: "alert-info", icon: "info" }.freeze,
+      tip: { klass: "alert-success", icon: "lightbulb" }.freeze,
+      warning: { klass: "alert-warning", icon: "triangle-alert" }.freeze
     }.freeze
 
     def initialize(level = :note, title: nil)

data/app/components/docs_ui/code.rb

@@ -24,7 +24,9 @@ module DocsUI
   class Code < Phlex::HTML
     include Phlex::Rails::Helpers::ContentSecurityPolicyNonce
 
-    FORMATTER = Rouge::Formatters::HTML.new
+    # Ractor-shareable (deep-frozen): Rouge's HTML formatter keeps no per-call
+    # state, so one instance serves every render (and every Ractor).
+    FORMATTER = DocsKit::Shareable.make(Rouge::Formatters::HTML.new)
 
     def initialize(source, lexer: nil, filename: nil)
       @source = source.to_s.strip

data/app/components/docs_ui/landing.rb

@@ -33,7 +33,7 @@ module DocsUI
     include Phlex::Rails::Helpers::Request
 
     def view_template
-      render DocsUI::Shell.new(title: landing.eyebrow || config.brand) do
+      render DocsUI::Shell.new(title: landing.eyebrow || config.brand_text) do
         div(class: "mx-auto max-w-5xl") do
           hero
           feature_grid
@@ -78,7 +78,7 @@ module DocsUI
     # (the one bit of markdown we honor, so a site can accent a word without HTML).
     def heading
       h1(class: "text-4xl font-bold tracking-tight md:text-5xl") do
-        (landing.title || config.brand).to_s.split(/\*\*(.+?)\*\*/).each_with_index do |part, index|
+        (landing.title || config.brand_text).to_s.split(/\*\*(.+?)\*\*/).each_with_index do |part, index|
           next if part.empty?
 
           index.odd? ? span(class: "text-primary") { part } : plain(part)

data/app/components/docs_ui/markdown.rb

@@ -34,6 +34,9 @@ module DocsUI
     TABLE_WRAPPER = "not-prose my-4 overflow-x-auto rounded-box border border-base-300"
     TABLE_CLASSES = "table table-sm table-zebra"
 
+    # ![alt](src) → <img>, asset-pipeline resolved (see MarkdownImages).
+    include MarkdownImages
+
     # Render source as INLINE markdown: no Prose wrapper div, and a single
     # top-level paragraph is unwrapped so its inline children (strong/em/code/
     # link) sit directly in the surrounding element. Used for a [:md, "…"] table
@@ -88,9 +91,7 @@ module DocsUI
 
     def node_document(node) = visit_children(node)
 
-    def node_paragraph(node)
-      p { visit_children(node) }
-    end
+    def node_paragraph(node) = p { visit_children(node) }
 
     # Demote so Markdown headings never collide with the page masthead/section
     # headings: h1→h3, h2→h4, anything deeper caps at h4.
@@ -127,8 +128,11 @@ module DocsUI
       render DocsUI::Code.new(node.string_content, lexer:)
     end
 
+    # A link keeps its href only for an allowed scheme (MarkdownImages::
+    # LINK_SCHEMES) or none at all; otherwise the text renders bare.
     def node_link(node)
-      a(href: node.url) { visit_children(node) }
+      href = link_href(node.url)
+      href ? a(href:) { visit_children(node) } : visit_children(node)
     end
 
     def node_list(node)

data/app/components/docs_ui/markdown_images.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module DocsUI
+  # DocsUI::Markdown's image handler: `![alt](src "title")` → a lazy-loaded
+  # <img>. A relative src resolves through the site's asset pipeline
+  # (image_path → the digested /assets URL, Propshaft or Sprockets); an absolute,
+  # protocol-relative or root-relative URL is kept as written. Off a request (an
+  # isolated render) the src is used verbatim — the DocsUI::Logo posture.
+  module MarkdownImages
+    include Phlex::Rails::Helpers::ImagePath
+
+    # A Markdown image sits in the prose like the kit's other bordered boxes.
+    IMAGE_CLASSES = "my-4 rounded-box border border-base-300"
+
+    # An image src kept verbatim: absolute, protocol-relative or root-relative.
+    ABSOLUTE_SRC = %r{\A(?:https?:)?/}i
+
+    # Any URL scheme. An image src may only carry http(s); a link href one of
+    # LINK_SCHEMES. Scheme-less URLs (relative, root-relative, protocol-relative,
+    # #anchor) always pass; javascript:, data:, vbscript: and the rest never do.
+    URL_SCHEME = /\A[a-z][a-z0-9+.-]*:/i
+    LINK_SCHEMES = %w[http https mailto tel].freeze
+
+    # The descendants whose string_content makes up the alt text; a soft or hard
+    # line break between them becomes a space so words don't run together.
+    ALT_TEXT_NODES = %i[text code].freeze
+    ALT_BREAK_NODES = %i[softbreak linebreak].freeze
+
+    private
+
+    # An unsafe scheme renders nothing — the alt text is dropped with it rather
+    # than left behind as stray prose.
+    def node_image(node)
+      src = image_src(node.url)
+      return unless src
+
+      title = node.title.to_s
+      img(src:, alt: alt_text(node), title: (title unless title.empty?),
+          loading: "lazy", class: IMAGE_CLASSES)
+    end
+
+    # Browsers strip ASCII whitespace/control characters before reading a
+    # scheme ("java\tscript:"), so the check does too.
+    def image_src(url)
+      bare = bare_url(url)
+      return url if bare.match?(ABSOLUTE_SRC)
+      return if bare.match?(URL_SCHEME)
+
+      view_context ? image_path(url) : url
+    end
+
+    # A link's href as written, or nil when it carries a scheme outside
+    # LINK_SCHEMES (the same whitespace-stripped scheme read as image_src).
+    def link_href(url)
+      scheme = bare_url(url)[URL_SCHEME]
+      return url if scheme.nil? || LINK_SCHEMES.include?(scheme.chomp(":").downcase)
+
+      nil
+    end
+
+    def bare_url(url) = url.to_s.gsub(/[\x00-\x20]/, "")
+
+    # Commonmarker 2 has no plain-text export, so the alt is the image's text
+    # (and inline code) descendants joined — emphasis markup is dropped.
+    def alt_text(node)
+      node.walk.filter_map do |n|
+        if ALT_TEXT_NODES.include?(n.type) then n.string_content
+        elsif ALT_BREAK_NODES.include?(n.type) then " "
+        end
+      end.join
+    end
+  end
+end

data/app/components/docs_ui/meta_tags.rb

@@ -52,7 +52,7 @@ module DocsUI
     # The full title used for og:title, identical to what Shell puts in <title>:
     # "Page · Suffix", or just the suffix on a title-less page (the home page).
     def full_title
-      [@title, config.title_suffix].compact.join(" · ")
+      [@title, config.title_suffix_text].compact.join(" · ")
     end
 
     def description_meta
@@ -67,7 +67,7 @@ module DocsUI
     def open_graph
       meta(property: "og:title", content: full_title)
       meta(property: "og:type", content: seo.og_type)
-      meta(property: "og:site_name", content: config.brand)
+      meta(property: "og:site_name", content: config.brand_text)
       open_graph_optional
     end
 

data/app/components/docs_ui/page.rb

@@ -14,6 +14,16 @@ module DocsUI
   #       render DocsUI::Section.new("Add the gem") { … }
   #     end
   #   end
+  #
+  # A page class that renders many records overrides the INSTANCE readers
+  # (#title, #description, #eyebrow) instead — they default to the class macros:
+  #
+  #   class Views::Docs::Widget < DocsUI::Page
+  #     eyebrow "Widgets"
+  #     def initialize(widget:) = @widget = widget
+  #     def title = @widget.name
+  #     def content = md(@widget.notes)
+  #   end
   class Page < Phlex::HTML
     include Phlex::Rails::Helpers::Routes
     # #request drives the "Markdown" masthead action's href (request.path + .md).
@@ -25,41 +35,52 @@ module DocsUI
     # friction-free path that never trips the parens-with-blocks gotcha.
     include DocsUI::PageHelpers
 
+    # The page macros run in a page class's body, at load (boot, on the main
+    # Ractor), and make each value shareable on write: request threads only
+    # read them afterwards, and a non-main Ractor can too.
+    # rubocop:disable-next ThreadSafety/ClassInstanceVariable -- written once in the class body at load; values made shareable
     class << self
       def title(value = nil)
-        @title = value if value
+        @title = DocsKit::Shareable.make(value) if value
         @title
       end
 
+      # Inherited: a subclass that sets no eyebrow shows its parent page's.
       def eyebrow(value = nil)
-        @eyebrow = value if value
-        @eyebrow
+        @eyebrow = DocsKit::Shareable.make(value) if value
+        @eyebrow || (superclass.eyebrow if parent_page?)
       end
 
       # The per-page SEO/social description → DocsUI::MetaTags (via Shell). Set it
       # for a hand-tuned description; when unset, Page derives one from #lead, so
       # an existing page gets a sensible description for free. nil (no
       # description, no lead) falls back to config.seo.description in MetaTags.
+      # Inherited from a parent page when unset.
       def description(value = nil)
-        @description = value if value
-        @description
+        @description = DocsKit::Shareable.make(value) if value
+        @description || (superclass.description if parent_page?)
       end
 
       # The "On this page" auto-TOC placement for this page. Defaults to the
       # configured DocsKit.configuration.on_page_default; set false to opt out,
-      # or :panel/:toggle/:sidebar to override per page.
+      # or :panel/:toggle/:sidebar to override per page. Inherited from a parent
+      # page when unset.
       def on_page(value = :__unset__)
-        @on_page = value unless value == :__unset__
-        defined?(@on_page) ? @on_page : DocsKit.configuration.on_page_default
+        @on_page = DocsKit::Shareable.make(value) unless value == :__unset__
+        return @on_page if defined?(@on_page)
+
+        parent_page? ? superclass.on_page : DocsKit.configuration.on_page_default
       end
+
+      private
+
+      # Whether the superclass is a page too (true below DocsUI::Page itself), so
+      # an unset macro falls back to it.
+      def parent_page? = superclass <= DocsUI::Page
     end
 
     def view_template
-      render DocsUI::Shell.new(
-        title: self.class.title,
-        description: self.class.description || lead,
-        on_page: self.class.on_page
-      ) do
+      render DocsUI::Shell.new(title:, description:, on_page: self.class.on_page) do
         # data-md-skip drops this nav from the Markdown export — it's chrome, not
         # page content (DocsKit::MarkdownExport strips [data-md-skip]). The
         # "Markdown" action sits opposite "← Home"; it's chrome too, so it lives
@@ -69,7 +90,7 @@ module DocsUI
           render DocsUI::MarkdownAction.new(request.path) if markdown_action?
         end
 
-        render DocsUI::Header.new(self.class.title, eyebrow: self.class.eyebrow) do
+        render DocsUI::Header.new(title, eyebrow:) do
           plain lead if lead
         end
 
@@ -78,9 +99,19 @@ module DocsUI
     end
 
     # Whether to show the "Markdown" masthead action — the config knob
-    # (DocsKit.configuration.page_markdown_action, default true).
+    # (DocsKit.configuration.page_markdown_action, default true). The action links
+    # request.path + ".md"; override to false on a page whose route has no .md twin.
     def markdown_action? = DocsKit.configuration.page_markdown_action
 
+    # The page title (masthead <h1> and <title>), eyebrow and SEO description.
+    # Each defaults to its class macro; override per instance when one page class
+    # renders many records. #title shadows Phlex's <title> element method, on
+    # pages only — the document <title> is DocsUI::Shell's, never a page body's.
+    def title = self.class.title
+    def eyebrow = self.class.eyebrow
+    # Falls back to #lead, then (in DocsUI::MetaTags) to config.seo.description.
+    def description = self.class.description || lead
+
     # The lowercase authoring helpers md/prose/example come from DocsUI::PageHelpers
     # (included above) — the parens-free path that never hits the constant-reference
     # SyntaxError. The kit forms (DocsUI::Prose(), DocsUI::Example()) stay valid too.

data/app/components/docs_ui/shell.rb

@@ -72,9 +72,13 @@ module DocsUI
     # injected by the controller under the active nav link (no content slot).
     def content_toc? = %i[panel toggle].include?(@on_page)
 
+    # "Page · Suffix", or just the suffix on a title-less page. The suffix is
+    # resolved per render (a callable title_suffix/brand → this request's value).
+    def document_title = [@title, config.title_suffix_text].compact.join(" · ")
+
     def render_head
       head do
-        title { [@title, config.title_suffix].compact.join(" · ") }
+        title { document_title }
         meta(charset: "utf-8")
         meta(name: "viewport", content: "width=device-width,initial-scale=1")
         # SEO / social-share tags (description, Open Graph, Twitter Card,
@@ -90,10 +94,20 @@ module DocsUI
         meta(name: "turbo-refresh-scroll", content: "preserve")
         config.stylesheets.each { |sheet| stylesheet_link_tag(sheet, data: { turbo_track: "reload" }) }
         theme_restore_script
-        javascript_importmap_tags
+        importmap_tags
       end
     end
 
+    # The import map tags for config.importmap_entry_point, from config.importmap
+    # when one is set. With nothing configured this is the helper's own default
+    # call, so the head matches a Shell that predates the knobs.
+    def importmap_tags
+      map = config.resolved_importmap
+      return javascript_importmap_tags(config.importmap_entry_point) if map.nil?
+
+      javascript_importmap_tags(config.importmap_entry_point, importmap: map)
+    end
+
     # Restore the persisted theme BEFORE first paint so there's no flash of the
     # server default before the docs-nav controller runs. Reads the same
     # localStorage key the controller writes (docs-kit:<site>:theme). Runs on
@@ -183,9 +197,9 @@ module DocsUI
     # text brand stays the mark's accessible-name fallback.
     def brand_mark
       if (logo = config.brand_logo)
-        render DocsUI::Logo.new(logo, class: "h-6 w-auto", label: config.brand)
+        render DocsUI::Logo.new(logo, class: "h-6 w-auto", label: config.brand_text)
       else
-        plain config.brand
+        plain config.brand_text
       end
     end
 

data/app/components/docs_ui/sidebar.rb

@@ -59,9 +59,9 @@ module DocsUI
     # Slightly taller than the topbar's h-6: this is the masthead.
     def brand_mark
       if (logo = config.brand_logo)
-        render DocsUI::Logo.new(logo, class: "h-7 w-auto", label: config.brand)
+        render DocsUI::Logo.new(logo, class: "h-7 w-auto", label: config.brand_text)
       else
-        plain config.brand
+        plain config.brand_text
       end
     end
 

data/app/controllers/docs_kit/llms_controller.rb

@@ -71,9 +71,12 @@ module DocsKit
     # Revalidate on the rendered body itself (so any registry/config/page change
     # busts it) plus the gem version as the etag salt. In development, always
     # re-render; production sites deploy immutably so the version etag is stable.
+    # A callable brand (#92) makes the body per-request, so the response is then
+    # `private`: a shared cache must not hand one tenant's llms.txt to another.
     def stale_llms?(body)
-      expires_in LLMS_MAX_AGE, public: true
-      stale?(etag: [DocsKit::VERSION, body], public: true)
+      shared = !docs_config.brand_per_request?
+      expires_in LLMS_MAX_AGE, public: shared
+      stale?(etag: [DocsKit::VERSION, body], public: shared)
     end
 
     # A page's Markdown twin, rendered through this controller's view context so

data/lib/docs_kit/api_client.rb

@@ -31,22 +31,26 @@ module DocsKit
 
   # The four generic-HTTP clients every site starts from. Order is stable
   # (curl → javascript → ruby → python) and preserved when a site merges its own.
-  ApiClient::DEFAULTS = {
-    curl: ApiClient.new(
-      label: "cURL", lexer: :curl, filename: "request.sh",
-      template: ApiTemplates.method(:curl)
-    ),
-    javascript: ApiClient.new(
-      label: "JavaScript", lexer: :javascript, filename: "request.js",
-      template: ApiTemplates.method(:javascript)
-    ),
-    ruby: ApiClient.new(
-      label: "Ruby", lexer: :ruby, filename: "request.rb",
-      template: ApiTemplates.method(:ruby)
-    ),
-    python: ApiClient.new(
-      label: "Python", lexer: :python, filename: "request.py",
-      template: ApiTemplates.method(:python)
-    )
-  }.freeze
+  # Shareable (lambdas, not Method objects, which never are), so a non-main
+  # Ractor can read the defaults.
+  ApiClient::DEFAULTS = DocsKit::Shareable.make(
+    {
+      curl: ApiClient.new(
+        label: "cURL", lexer: :curl, filename: "request.sh",
+        template: ->(request) { ApiTemplates.curl(request) }
+      ),
+      javascript: ApiClient.new(
+        label: "JavaScript", lexer: :javascript, filename: "request.js",
+        template: ->(request) { ApiTemplates.javascript(request) }
+      ),
+      ruby: ApiClient.new(
+        label: "Ruby", lexer: :ruby, filename: "request.rb",
+        template: ->(request) { ApiTemplates.ruby(request) }
+      ),
+      python: ApiClient.new(
+        label: "Python", lexer: :python, filename: "request.py",
+        template: ->(request) { ApiTemplates.python(request) }
+      )
+    }
+  )
 end