docs-kit 1.3.0 → 1.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: feed239eb09deeafd1a9dc6e92e91d192c14f927fa562105139f4b16473d1a60
-  data.tar.gz: 6149bf7b9509fb611ce86e9c183a38c027ce77addee69669be41a0ce85fb292d
+  metadata.gz: 29ec90ecec4c794dcfd2f0dfa7254a02844ccafa76019303b2b2bdbaf87c62c3
+  data.tar.gz: 3b8e8d345e6f795d00f44cea26529c9433eeb9ebb60e36cd07ce07541eec0fd5
 SHA512:
-  metadata.gz: 5af123f6815e81ccad67dcb7737836c0a2727fb60e963bfc16d6ff0a6540325ca1a67fa2aaaea2ff824ba3b36f2210d8fb4aaab43f097195ec7f020cbfc8c54e
-  data.tar.gz: 32e24110ca11cfba1c795d60ea93d6ecb2f1e42af912274ebc816718cd235d93e217bb1ac2a6082b08039eaefe162c6b8287f4ed328c685ab3c669c840e2e359
+  metadata.gz: cb1ef7f9d6c3673f48d965b3bdd71c85b38b0f7c053d492078046f8fd37b094a98cb92ace7b6b777e986e00fd1cd2be187f455f591ab23437a9da8dee4ac31a6
+  data.tar.gz: 573e0e3db675e201e7457c8adee993d69e239789d08a3019b89c2409dd1cd6ec154e37fc6977c1a40e95369118ea78fa815e0e1da48ba4d551c6375a81692063

data/CHANGELOG.md

@@ -2,6 +2,100 @@
 
 ## [Unreleased]
 
+### Upgrading from 1.4
+
+Nothing to change for a site that registers the controller with
+`eagerLoadControllersFrom("docs_kit/controllers", application)`, as the
+generated `index.js` does: `docs-nav` still registers on every page. It is no
+longer preloaded, so on docs pages the eager loader's `import()` fetches it
+one request later instead of from the preload cache. To keep the preload, set
+`config.docs_kit.preload = true` in `config/application.rb`.
+
+### Added
+
+- **`config.docs_kit.controllers_under`** (default `"docs_kit/controllers"`)
+  sets the auto-pin's module namespace. `"controllers"` pins the controller as
+  `controllers/docs_nav_controller` (same asset), so the host's own loader for
+  `controllers` finds it, with no docs-kit line in `index.js`; with
+  `lazyLoadControllersFrom("controllers", application)` a page fetches it only
+  if it renders `data-controller="docs-nav"`. Set it in
+  `config/application.rb`. (#107)
+
+### Changed
+
+- **`docs-nav` is no longer preloaded on every page.** The auto-pin took
+  importmap-rails' default `preload: true`, so in a host whose docs share the
+  application's import map every page, docs or not, carried a
+  `<link rel="modulepreload">` for the 24 KB controller, and a host `pin` with
+  `preload: false` could not override it (a `pin_all_from` directory expands
+  over plain pins). `config.docs_kit.preload` (default `false`) is now the
+  pin's `preload:`: `true` restores 1.4's behaviour, an entry-point name
+  (importmap-rails 2.x) preloads it only where that entry point is rendered.
+  (#107)
+
+### Fixed
+
+- **One documented registration.** The README and the pin file's header now
+  point at one "Registering the controller" section. The README no longer
+  recommends `lazyLoadControllersFrom("docs_kit/controllers", application)`,
+  which in a host with its own controllers requests
+  `docs_kit/controllers/<identifier>_controller` for every host
+  `data-controller` and logs a "Failed to autoload controller" error for each,
+  on every page. (#107)
+
+## [1.4.0] — 2026-10-15
+
+### 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
@@ -42,7 +136,15 @@
   `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)
+## [1.2.1] — 2026-09-30
+
+### Changed
+
+- **daisyui 2.x is allowed.** The dependency is now `>= 1.2, < 3`. 1.2.0 was
+  tagged but never reached RubyGems (its release run failed a stale spec), so
+  1.2.1 is the first published 1.2 release.
+
+## [1.2.0] — 2026-09-30 (tagged; never published to RubyGems)
 
 ### Upgrading from 1.1
 
@@ -77,9 +179,6 @@ bundle exec rspec
 
 ### Changed
 
-- **daisyui 2.x is allowed.** The dependency is now `>= 1.2, < 3`. 1.2.0 was
-  tagged but never reached RubyGems (its release run failed a stale spec), so
-  1.2.1 is the first published 1.2 release.
 - **The reusable deploy workflow runs on Node 24 actions.** `deploy.yml` now
   uses `actions/checkout@v7`, `docker/setup-buildx-action@v4`,
   `docker/login-action@v4`, `docker/build-push-action@v7` and
@@ -116,21 +215,68 @@ bundle exec rspec
   `lexer:` still wins, and a block with neither (or an unguessable filename)
   stays Ruby, so existing output is unchanged.
 
-## [1.1.1] and earlier
+## [1.1.1] — 2026-08-27
 
 ### Fixed
 
-- **SEO `og:image` 404.** The og:image tag pointed at the raw config path
-  (`https://site/og/og.png`), which isn't a served URL — Propshaft serves the
-  digested asset under `/assets`. A relative `og_image` is now resolved through
-  the site's asset pipeline (`image_url`) to the digested `/assets/og/og-<digest>.png`
-  URL, and the image is treated as **site content**: the gem ships none,
-  `c.seo.og_image` defaults to **nil** (unset → no og:image tag, never a 404), and
-  the `docs_kit:og` task writes into the *site's* `app/assets/images/`. Added a
-  booted-app integration test in the dogfood site
-  (`docs/test/integration/seo_meta_tags_test.rb`) that asserts og:image resolves
-  to a `/assets` URL that actually returns 200 — the coverage isolated component
-  specs can't provide.
+- **`/llms.txt` sends a public max-age** (`expires_in 300, public: true`), so
+  shared caches such as dash-proxy can store it; ETag revalidation is
+  unchanged. (#75)
+
+## [1.1.0] — 2026-08-27
+
+### Added
+
+- **Docs versions foundation.** `c.versions` (`DocsKit::DocVersion`),
+  `c.repo_url` and `c.snapshots_path`, a request-scoped version
+  (`DocsKit::Scope`) and a snapshot content source. A site that configures no
+  versions renders unchanged. (#67)
+
+### Changed
+
+- **The reusable deploy workflow uses dash 4.** `deploy.yml` installs
+  `dash ~> 4.0` and runs `dash doctor` before deploying; the registry secret is
+  now `DASH_REGISTRY_PASSWORD` (`KAMAL_REGISTRY_PASSWORD` is still exported),
+  and the `docs-kit new` deploy template turns on dash-proxy compression,
+  caching and security headers. (#74)
+
+### Fixed
+
+- **Repointed at the `zoolutions` org.** The reusable deploy workflow, the
+  `docs-kit new` and install templates, the README and the gemspec metadata
+  now reference `zoolutions/docs-kit` (reusable-workflow `uses:` refs don't
+  follow the repo move's redirect). (#70)
+
+## [1.0.8] — 2026-08-04
+
+### Added
+
+- **`c.brand_logo`.** A config-driven brand mark (`svg:`, `paths:`, `markup:`,
+  `file:` or `src:`) rendered by the new `DocsUI::Logo` in the topbar and
+  sidebar brand links, falling back to `c.brand`; `c.landing.logo` accepts the
+  same forms. `c.topbar_brand = :mobile_only` hides the topbar copy where the
+  sidebar brand is already visible. (#68)
+
+### Changed
+
+- **The sidebar's top-level heading is flattened.** With one nav heading it
+  is no longer rendered; with several, each is a static `menu-title` label and
+  only subgroups collapse. The landing doc index follows the same rule. (#66)
+
+## [1.0.7] — 2026-08-03
+
+### Added
+
+- **Version-aware `--sync` migrations.** Install and `--sync` stamp the
+  initializer with `# docs-kit synced: vX.Y.Z`, and `--sync` runs the ordered
+  migrations between that version and the gem's, printing what it can't
+  automate. The migration registry ships empty in 1.0.x. (#56)
+- **Two homes: `c.app_link`.** An opt-in `c.app_link = { href:, label: }`
+  renders a topbar link back to the hosting app, and the page masthead's link
+  now follows `c.brand_href` instead of the host's `root_path` and reads
+  "← Docs home". (#63)
+
+## [1.0.6] — 2026-07-04
 
 ### Added
 
@@ -141,6 +287,11 @@ bundle exec rspec
   site's asset pipeline). nil (the default) omits it, so it's backwards-compatible.
   This closes the gap a mounted docs app hit — a hero with no way to show the
   product's own logo — the first consumer to try `DocsUI::Landing` on a real site.
+
+## [1.0.5] — 2026-07-04
+
+### Added
+
 - **`DocsUI::Landing` — a config-driven marketing landing page.** Every consuming
   site (and this dogfood site) was hand-rolling a home page; now render
   `DocsUI::Landing` and drive it from a new `c.landing` config block
@@ -154,6 +305,48 @@ bundle exec rspec
   now renders it and the initializer documents `c.landing`. This is the first
   landing pattern proven on a **mounted** docs app (a docs section inside a larger
   Rails app whose `/` is already taken), contributed back from that use case.
+
+## [1.0.4] — 2026-07-04
+
+### Changed
+
+- **rouge 5 is allowed.** The dependency is now `>= 4.0, < 6`; the `< 5` cap
+  was downgrading sites already on rouge 5. (#54)
+
+### Fixed
+
+- **`docs_kit:install --sync` no longer re-injects the commented `/mcp` route
+  scaffold** into a site that already draws live MCP routes. (#53)
+
+## [1.0.3] — 2026-07-04
+
+### Added
+
+- **`docs_kit:install` templates a lean multi-stage `Dockerfile` and a
+  `.dockerignore`.** The `Dockerfile` is site-owned (skipped if present) and
+  carries a `# docs-kit Dockerfile vX.Y.Z` marker that `--sync` warns about
+  when it is older than the gem; `docs-kit new` uses the same template. (#52)
+
+## [1.0.2] — 2026-07-03
+
+### Fixed
+
+- **SEO `og:image` 404.** The og:image tag pointed at the raw config path
+  (`https://site/og/og.png`), which isn't a served URL — Propshaft serves the
+  digested asset under `/assets`. A relative `og_image` is now resolved through
+  the site's asset pipeline (`image_url`) to the digested `/assets/og/og-<digest>.png`
+  URL, and the image is treated as **site content**: the gem ships none,
+  `c.seo.og_image` defaults to **nil** (unset → no og:image tag, never a 404), and
+  the `docs_kit:og` task writes into the *site's* `app/assets/images/`. Added a
+  booted-app integration test in the dogfood site
+  (`docs/test/integration/seo_meta_tags_test.rb`) that asserts og:image resolves
+  to a `/assets` URL that actually returns 200 — the coverage isolated component
+  specs can't provide.
+
+## [1.0.1] — 2026-07-03
+
+### Added
+
 - **SEO + social sharing.** Every page now emits a complete SEO `<head>` —
   meta description, Open Graph, Twitter Card, canonical, favicon, robots, and
   theme-color — via the new `DocsUI::MetaTags` component, driven entirely by a
@@ -165,6 +358,11 @@ bundle exec rspec
   Backwards-compatible: a site that sets no `c.seo` renders a valid minimal card
   and its `<head>` is a strict superset of before. The install generator documents
   `c.seo` and installs the task; `docs-kit new` reminds the owner to run it. (#48)
+
+## [1.0.0] — 2026-07-03
+
+### Added
+
 - Release tooling matching the sibling gems (daisyui/phlex-reactive/pgbus): a
   `rake release[X.Y.Z]` task (version bump → lockfile update → build-verify →
   commit → push → GitHub Release; `pre`/`force` supported, `main`-only, clean-tree

data/README.md

@@ -124,7 +124,7 @@ generators:
 |-------|---------------|-----|
 | `ApplicationController#render_page` defined by hand | `DocsKit::Controller#render_page` is included (the generator injects `include DocsKit::Controller`) | Delete the method — keep the `include`. |
 | `app/helpers/icon_helper.rb` | docs-kit renders icons via rails_icons (`DocsUI::Icon`) | Delete the file. |
-| Hand-pinned docs-kit lines in `config/importmap.rb` | the engine auto-pins the `docs-nav` controller and its assets | Delete the manual `pin`/`pin_all_from` lines for docs-kit. |
+| Hand-pinned docs-kit lines in `config/importmap.rb` | the engine auto-pins the `docs-nav` controller and its assets | Delete the manual `pin`/`pin_all_from` lines for docs-kit. A line kept only to change `preload:` or `under:` becomes `config.docs_kit.preload` or `config.docs_kit.controllers_under` in `config/application.rb` (see [Registering the controller](#registering-the-controller)). |
 | `Dockerfile` stamped by an older docs-kit (`# docs-kit Dockerfile vX.Y.Z`) | docs-kit ships an optimized, multi-stage Dockerfile; a stale copy misses image-size wins | Diff yours against the current template (`lib/generators/docs_kit/install/templates/Dockerfile.tt` in the gem), adopt the changes or replace it. See [Upgrading your Dockerfile](#upgrading-your-dockerfile). |
 | `app/assets/stylesheets/tailwind.sources.css` committed to git | `bin/build-css` regenerates it on every build with machine-specific absolute gem paths — the committed copy churns per machine/Ruby and no build consumes it. The generator adds the `.gitignore` entry, but gitignoring doesn't untrack an already-committed copy. | `git rm --cached app/assets/stylesheets/tailwind.sources.css` and commit. |
 
@@ -363,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
@@ -1096,12 +1123,74 @@ server round-trip:
   of three placements, auto-hiding on short pages. No server-side knowledge of
   the headings, no per-page wiring.
 
+### Registering the controller
+
+The engine pins `docs-nav` into the host's import map as
+`docs_kit/controllers/docs_nav_controller`, with no `<link rel="modulepreload">`
+on any page. Register it in `app/javascript/controllers/index.js` one of two
+ways.
+
+**Eager** — what `docs_kit:install` writes, next to the stock eager loader:
+
+```js
+import { eagerLoadControllersFrom } from "@hotwired/stimulus-loading"
+eagerLoadControllersFrom("docs_kit/controllers", application)
+```
+
+It imports the controller on every page that loads the entry point, whether
+the page renders `docs-nav` or not. Right for a docs-only site, where every page
+renders the sidebar.
+
+**Through the host's own loader** — pin `docs-nav` under the host's
+`controllers` namespace instead, and add no docs-kit line to `index.js`:
+
+```ruby
+# config/application.rb
+config.docs_kit.controllers_under = "controllers"
+```
+
+The module becomes `controllers/docs_nav_controller` (same asset), so the
+host's existing `eagerLoadControllersFrom("controllers", application)` or
+`lazyLoadControllersFrom("controllers", application)` finds it by convention.
+With the lazy loader, a page fetches `docs-nav` only if it renders
+`data-controller="docs-nav"`: the setup for a host whose docs share an app with
+other pages. Drop an old `eagerLoadControllersFrom("docs_kit/controllers", ...)`
+line, which no longer matches anything. Don't keep a host file named
+`app/javascript/controllers/docs_nav_controller.js`: it has the same module
+name, and the host's `config/importmap.rb` is drawn after the engine's, so it
+replaces docs-kit's controller.
+
+> **Don't** call `lazyLoadControllersFrom("docs_kit/controllers", application)`
+> in a host with its own controllers. A lazy loader imports
+> `<under>/<identifier>_controller` for *every* `data-controller` on the page
+> that isn't registered yet, so `data-controller="dropdown"` makes it request
+> `docs_kit/controllers/dropdown_controller`, which isn't in the map: one
+> "Failed to autoload controller" console error per host identifier, on every
+> page. A second lazy loader is only safe on a namespace that owns every
+> identifier on the page.
+
+**Preloading.** `config.docs_kit.preload` (default `false`) is the pin's
+`preload:`. `true` puts a modulepreload for `docs-nav` on every page that renders
+the import map (docs-kit 1.4's behaviour). An entry-point name, such as
+`"docs"`, preloads it only on pages that render that entry point; it needs
+importmap-rails 2.x (1.x takes only `true`/`false`, and docs-kit doesn't check).
+
+```ruby
+# config/application.rb — defaults shown
+config.docs_kit.preload = false                         # true | "docs" | %w[docs admin]
+config.docs_kit.controllers_under = "docs_kit/controllers"
+```
+
+importmap-rails draws the pin in its own initializer, before
+`config/initializers/` run, so set both in `config/application.rb`. With
+`config.docs_kit.auto_pin = false` neither applies: the host owns the pin.
+
 ### 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:
+and map:
 
 ```ruby
 # config/application.rb — skip the engine's auto-pin into the shared map
@@ -1123,14 +1212,17 @@ 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"
+# This map only loads on docs pages, so preloading docs-nav here is the point.
 pin_all_from DocsKit::Engine.root.join("app/javascript/docs_kit/controllers"),
-             under: "docs_kit/controllers", to: "docs_kit/controllers"
+             under: "docs_kit/controllers", to: "docs_kit/controllers", preload: true
 ```
 
 `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)`.
+`docs` entry point registers the controller eagerly, as in
+[Registering the controller](#registering-the-controller). With one shared map,
+a `docs` entry point and `config.docs_kit.preload = "docs"` preload `docs-nav`
+on docs pages only, without a second map.
 
 ### On this page (auto-TOC)
 
@@ -1156,13 +1248,7 @@ headings, so they need zero per-page data. A page with fewer than 2 sections
 hides the TOC. Scroll-spy highlights the section you're reading.
 
 `DocsUI::Sidebar` already carries `data-controller="docs-nav"`. Register the
-controller in the host app:
-
-```js
-// app/javascript/controllers/index.js
-import { lazyLoadControllersFrom } from "@hotwired/stimulus-loading"
-lazyLoadControllersFrom("docs_kit/controllers", application)
-```
+controller as in [Registering the controller](#registering-the-controller).
 
 The **active nav item** needs no JS — it's server-rendered from the request path.
 

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/page.rb

@@ -35,15 +35,19 @@ 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 = DocsKit::Shareable.make(value) if value
         @eyebrow || (superclass.eyebrow if parent_page?)
       end
 
@@ -53,7 +57,7 @@ module DocsUI
       # 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 = DocsKit::Shareable.make(value) if value
         @description || (superclass.description if parent_page?)
       end
 
@@ -62,7 +66,7 @@ module DocsUI
       # 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__
+        @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

data/config/importmap.rb

@@ -1,15 +1,17 @@
 # frozen_string_literal: true
 
-# Auto-pins the gem's bundled Stimulus controllers for importmap-rails consumers.
-# Exposes `docs_kit/controllers/docs_nav_controller`. Register it in the host app:
+# Auto-pins the gem's bundled Stimulus controller (docs-nav) for importmap-rails
+# consumers. With the defaults it is `docs_kit/controllers/docs_nav_controller`,
+# preloaded nowhere. Two engine options, set in the host's config/application.rb,
+# shape the pin:
 #
-#   // app/javascript/controllers/index.js
-#   import { eagerLoadControllersFrom } from "@hotwired/stimulus-loading"
-#   eagerLoadControllersFrom("docs_kit/controllers", application)
+#   config.docs_kit.preload = false                         # true, or an entry point ("docs")
+#   config.docs_kit.controllers_under = "docs_kit/controllers"  # "controllers" rides the host's lazy loader
 #
-# Use eagerLoadControllersFrom (already imported in the default index.js), NOT
-# lazyLoadControllersFrom — the latter isn't imported there, so calling it throws
-# a ReferenceError that aborts the module and no controllers register at all.
+# How to register the controller in the host's controllers/index.js, and which
+# loader to avoid: README → "Registering the controller".
+docs_kit = DocsKit::Engine.config.docs_kit
 pin_all_from DocsKit::Engine.root.join("app/javascript/docs_kit/controllers"),
-             under: "docs_kit/controllers",
-             to: "docs_kit/controllers"
+             under: docs_kit.controllers_under,
+             to: "docs_kit/controllers",
+             preload: docs_kit.preload

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

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"
 
@@ -276,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
@@ -347,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 —
@@ -453,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
+
+        DocsKit::OpenApi.load(source).tap do |document|
+          @openapi_memo = { source: source, mtime: mtime, document: document }
+        end
+      end
+    end
 
-      @openapi_document_mtime = mtime
-      @openapi_document = DocsKit::OpenApi.load(@openapi)
+    # 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
@@ -677,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
@@ -687,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
@@ -703,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.

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,16 +31,40 @@ 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.
+    # Host-facing engine options, set in config/application.rb: importmap-rails
+    # draws the auto-pin in its own initializer, before config/initializers run.
+    # `config.docs_kit.auto_pin = false` 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
+    # The auto-pin's `preload:`. false (the default) keeps docs-nav out of every
+    # page's modulepreloads; true preloads it everywhere; an entry-point name (or
+    # an array, importmap-rails 2.x) preloads it only where that entry point loads.
+    config.docs_kit.preload = false
+    # The auto-pin's module namespace. "controllers" pins docs-nav as
+    # `controllers/docs_nav_controller`, so the host's own
+    # `lazyLoadControllersFrom("controllers", application)` loads it by convention
+    # on the pages that render it. The asset path never changes.
+    config.docs_kit.controllers_under = "docs_kit/controllers"
 
     # Auto-pin the controller for importmap-rails consumers, so a host app gets
     # `docs_kit/controllers/docs_nav_controller` with no manual pin.

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.3.0"
+  VERSION = "1.4.1"
 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.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__))

data/lib/generators/docs_kit/install/migration.rb

@@ -14,14 +14,19 @@ module DocsKit
     # and hands back strings for whatever needs a human. A `nil` return means
     # "nothing to warn about".
     class Migration
-      attr_reader :to, :description
+      attr_reader :description
 
+      # Keeps `to` as a frozen String, so a migration list can be made
+      # Ractor-shareable without freezing Gem::Version's process-wide cached
+      # instances; #to hands back the Gem::Version.
       def initialize(to:, description:, &block)
-        @to = Gem::Version.new(to.to_s)
+        @to = -to.to_s
         @description = description
         @block = block
       end
 
+      def to = Gem::Version.new(@to)
+
       # Run the transform against the site. Returns the (possibly empty) list of
       # manual-cleanup warnings — never nil, so callers can flat-map safely.
       def call(root, generator)

data/lib/generators/docs_kit/install/migration_registry.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require_relative "../../../docs_kit/shareable"
 require_relative "migration"
 require_relative "migrations/v1_2_0"
 require_relative "../../../docs_kit/version"
@@ -24,21 +25,25 @@ module DocsKit
     # its transform in migrations/vX_Y_Z.rb.
     class MigrationRegistry
       def initialize(migrations = [])
-        @migrations = migrations.sort_by(&:to)
+        @migrations = migrations.sort_by(&:to).freeze
       end
 
-      # The registry the install generator runs during `--sync`.
-      def self.default
-        @default ||= new(MIGRATIONS)
-      end
+      # The registry the install generator runs during `--sync` (DEFAULT, below).
+      def self.default = DEFAULT
 
       # Ordered `Migration.new(to: "1.x.0", description: "...") { ... }` entries, one
       # per release that changes config knobs, routes, templates, or toolchain.
-      MIGRATIONS = [
-        Migration.new(to: "1.2.0", description: Migrations::V1_2_0::DESCRIPTION) do |root, _generator|
-          Migrations::V1_2_0.call(root)
-        end
-      ].freeze
+      # Shareable: each block is capture-free (its self is this class).
+      MIGRATIONS = DocsKit::Shareable.make(
+        [
+          Migration.new(to: "1.2.0", description: Migrations::V1_2_0::DESCRIPTION) do |root, _generator|
+            Migrations::V1_2_0.call(root)
+          end
+        ]
+      )
+
+      # Built at load from MIGRATIONS, never lazily (no first-call race).
+      DEFAULT = DocsKit::Shareable.make(new(MIGRATIONS))
 
       # The migrations a site last synced at `from_version` still needs, ascending
       # by version — those in `(from_version, upto]`. `upto` defaults to the

data/lib/generators/docs_kit/install/migrations/v1_2_0.rb

@@ -12,12 +12,14 @@ module DocsKit
       # handed back as a warning, and a newer value is left alone.
       module V1_2_0 # rubocop:disable Naming/ClassAndModuleCamelCase -- named after the release
         DESCRIPTION = "docs-kit 1.2: Ruby >= 3.3, Bun 1.4.2, Tailwind 4.3 / daisyUI 5.7 floors, Node 24 deploy"
-        MIN_RUBY = Gem::Version.new("3.3")
+        # A String: Gem::Version.new hands out process-wide cached instances,
+        # which a constant must not freeze. Compared via Gem::Version below.
+        MIN_RUBY = "3.3"
         BUN = { from: "1.3.2", to: "1.4.2" }.freeze
         PACKAGE_FLOORS = {
-          "tailwindcss" => { from: "^4.1.18", to: "^4.3.3" },
-          "@tailwindcss/cli" => { from: "^4.1.18", to: "^4.3.3" },
-          "daisyui" => { from: "^5.6.0", to: "^5.7.47" }
+          "tailwindcss" => { from: "^4.1.18", to: "^4.3.3" }.freeze,
+          "@tailwindcss/cli" => { from: "^4.1.18", to: "^4.3.3" }.freeze,
+          "daisyui" => { from: "^5.6.0", to: "^5.7.47" }.freeze
         }.freeze
         DEPLOY_CALL = %r{zoolutions/docs-kit/\.github/workflows/deploy\.yml@(\S+)}
 
@@ -112,7 +114,7 @@ module DocsKit
 
         def below_min_ruby?(value)
           version = version_of(value)
-          version ? version < MIN_RUBY : false
+          version ? version < Gem::Version.new(MIN_RUBY) : false
         end
       end
     end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: docs-kit
 version: !ruby/object:Gem::Version
-  version: 1.3.0
+  version: 1.4.1
 platform: ruby
 authors:
 - Mikael Henriksson
@@ -235,9 +235,11 @@ files:
 - lib/docs_kit/search_index.rb
 - lib/docs_kit/search_index/snippet.rb
 - lib/docs_kit/seo_config.rb
+- lib/docs_kit/shareable.rb
 - lib/docs_kit/shortcut.rb
 - lib/docs_kit/snapshot.rb
 - lib/docs_kit/snapshot/entry.rb
+- lib/docs_kit/store.rb
 - lib/docs_kit/templates/new_site.rb
 - lib/docs_kit/topbar_link.rb
 - lib/docs_kit/version.rb