From 8f9e92444c83b0695dc3935aa72c789388e077bf Mon Sep 17 00:00:00 2001
From: NullVoxPopuli-ai-agent
 <268630448+NullVoxPopuli-ai-agent@users.noreply.github.com>
Date: Mon, 27 Jul 2026 09:46:59 -0400
Subject: [PATCH 1/4] docs-app: preview the unreleased kolay via the dist
 branch

kolay's next release reworks the plugin API (universal-ember/kolay#323):
the combined kolay() vite plugin is split into docs() + apiDocs(), and
page json configs use "title" instead of "componentName".

To preview those changes before the release, resolve kolay to the built
package contents that kolay pushes to its dist branch on every commit
to main (a pnpm override, so the docs-app and docs-support keep their
semver ranges). When kolay releases, the override goes away and the
ranges get bumped instead.

- vite.config: docs({ ... }) serves the co-located app/templates pages;
  apiDocs([...]) takes over the packages list
- addRoutes(this) and setupKolay() are unchanged for this setup
- otp/otp-input page configs: componentName -> title (side-nav already
  falls back to title)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .../3-ui/one-time-password/otp-input.json     |  2 +-
 .../templates/3-ui/one-time-password/otp.json |  2 +-
 docs-app/vite.config.mjs                      |  7 ++++---
 package.json                                  |  1 +
 pnpm-lock.yaml                                | 20 ++++++++++---------
 5 files changed, 18 insertions(+), 14 deletions(-)

diff --git a/docs-app/app/templates/3-ui/one-time-password/otp-input.json b/docs-app/app/templates/3-ui/one-time-password/otp-input.json
index 1e7a4f337..cd6ec2c05 100644
--- a/docs-app/app/templates/3-ui/one-time-password/otp-input.json
+++ b/docs-app/app/templates/3-ui/one-time-password/otp-input.json
@@ -1,3 +1,3 @@
 {
-  "componentName": "OTPInput"
+  "title": "OTPInput"
 }
diff --git a/docs-app/app/templates/3-ui/one-time-password/otp.json b/docs-app/app/templates/3-ui/one-time-password/otp.json
index 71fa735dc..245f77663 100644
--- a/docs-app/app/templates/3-ui/one-time-password/otp.json
+++ b/docs-app/app/templates/3-ui/one-time-password/otp.json
@@ -1,3 +1,3 @@
 {
-  "componentName": "OTP"
+  "title": "OTP"
 }
diff --git a/docs-app/vite.config.mjs b/docs-app/vite.config.mjs
index cd2dbf56f..4cd676538 100644
--- a/docs-app/vite.config.mjs
+++ b/docs-app/vite.config.mjs
@@ -1,7 +1,7 @@
 import { ember, extensions } from "@embroider/vite";
 
 import { babel } from "@rollup/plugin-babel";
-import { kolay } from "kolay/vite";
+import { apiDocs, docs } from "kolay/vite";
 import { defineConfig } from "vite";
 import { scopedCSS } from "ember-scoped-css/vite";
 import rehypeShiki from "@shikijs/rehype";
@@ -11,8 +11,8 @@ export default defineConfig(async (/* { mode } */) => {
     plugins: [
       scopedCSS(),
       ember(),
-      kolay({
-        packages: ["ember-primitives", "which-heading-do-i-need"],
+      // no group: the docs are the co-located pages in app/templates
+      docs({
         rehypePlugins: [
           [
             rehypeShiki,
@@ -38,6 +38,7 @@ export default defineConfig(async (/* { mode } */) => {
           import { Callout } from '@universal-ember/docs-support';
         `,
       }),
+      apiDocs(["ember-primitives", "which-heading-do-i-need"]),
       babel({
         babelHelpers: "runtime",
         extensions,
diff --git a/package.json b/package.json
index b82966c0d..0d04b8ccb 100644
--- a/package.json
+++ b/package.json
@@ -58,6 +58,7 @@
       "ember-primitives": "workspace:^",
       "ember-repl": "^8.0.0",
       "ember-source": "^7.1.0",
+      "kolay": "github:universal-ember/kolay#dist",
       "reactiveweb": "^1.9.1",
       "tracked-toolbox": "^3.0.0"
     },
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index efbf0a84c..3d1ef18e9 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -17,6 +17,7 @@ overrides:
   ember-primitives: workspace:^
   ember-repl: ^8.0.0
   ember-source: ^7.1.0
+  kolay: github:universal-ember/kolay#dist
   reactiveweb: ^1.9.1
   tracked-toolbox: ^3.0.0
 
@@ -105,8 +106,8 @@ importers:
         specifier: ^2.2.1
         version: 2.2.2(highlight.js@11.11.1)
       kolay:
-        specifier: ^5.1.2
-        version: 5.2.0(a417d88aa35fbfb0591a793939686c8f)
+        specifier: github:universal-ember/kolay#dist
+        version: https://codeload.github.com/universal-ember/kolay/tar.gz/f4a21ade2abe9a0bcdeffa921940664f05774765(a417d88aa35fbfb0591a793939686c8f)
       limber-ui:
         specifier: ^4.1.1
         version: 4.2.1(c8332dc3f90c0e60eb130a3a85f980b9)
@@ -476,8 +477,8 @@ importers:
         specifier: ^4.0.2
         version: 4.1.1
       kolay:
-        specifier: ^5.1.2
-        version: 5.2.0(a417d88aa35fbfb0591a793939686c8f)
+        specifier: github:universal-ember/kolay#dist
+        version: https://codeload.github.com/universal-ember/kolay/tar.gz/f4a21ade2abe9a0bcdeffa921940664f05774765(a417d88aa35fbfb0591a793939686c8f)
       package-up:
         specifier: ^5.0.0
         version: 5.0.0
@@ -5287,8 +5288,9 @@ packages:
     resolution: {integrity: sha512-dcS1ul+9tmeD95T+x28/ehLgd9mENa3LsvDTtzm3vyBEO7RPptvAD+t44WVXaUjTBRcrpFeFlC8WCruUR456hw==}
     engines: {node: '>=0.10.0'}
 
-  kolay@5.2.0:
-    resolution: {integrity: sha512-0ExGdvBmlmitKeL8nAit4GCKZO5T+Ya1FqIOI1c/Qnv64wDLoz0LBFye9iXDH8fTM/BhbT+uw2qadhjsiuxtWQ==}
+  kolay@https://codeload.github.com/universal-ember/kolay/tar.gz/f4a21ade2abe9a0bcdeffa921940664f05774765:
+    resolution: {gitHosted: true, integrity: sha512-hxBAMq65JGlqmcswJrl6T4RnZ0fn4QGpryyaoLTMmwexb0Y6U4Gx16B0htLbyhJvNnChCYJs0uE8DJ8MPzdj8w==, tarball: https://codeload.github.com/universal-ember/kolay/tar.gz/f4a21ade2abe9a0bcdeffa921940664f05774765}
+    version: 5.4.0
     engines: {node: '>= 18'}
 
   ky@1.14.3:
@@ -10128,7 +10130,7 @@ snapshots:
       ember-primitives: file:ember-primitives(5c0eaebf1b4b32661be1beb69576d86a)
       ember-resources: 7.0.7(2935cfb77147881c8250be8c1bb7d0d1)
       inter-ui: 4.1.1
-      kolay: 5.2.0(a417d88aa35fbfb0591a793939686c8f)
+      kolay: https://codeload.github.com/universal-ember/kolay/tar.gz/f4a21ade2abe9a0bcdeffa921940664f05774765(a417d88aa35fbfb0591a793939686c8f)
       package-up: 5.0.0
       read-package-up: 12.0.0
       should-handle-link: 1.3.0
@@ -13196,7 +13198,7 @@ snapshots:
 
   kind-of@6.0.3: {}
 
-  kolay@5.2.0(a417d88aa35fbfb0591a793939686c8f):
+  kolay@https://codeload.github.com/universal-ember/kolay/tar.gz/f4a21ade2abe9a0bcdeffa921940664f05774765(a417d88aa35fbfb0591a793939686c8f):
     dependencies:
       '@ember/test-waiters': 4.1.1(c8332dc3f90c0e60eb130a3a85f980b9)
       '@embroider/addon-shim': 1.10.2
@@ -13204,7 +13206,7 @@ snapshots:
       '@glint/template': 1.7.7
       change-case: 5.4.4
       common-tags: 1.8.2
-      content-tag: 4.1.1
+      content-tag: 4.2.0
       decorator-transforms: 2.3.2(@babel/core@7.29.0)
       ember-modifier: 4.3.0(@babel/core@7.29.0)
       ember-primitives: file:ember-primitives(5c0eaebf1b4b32661be1beb69576d86a)

From 92bc710686613ddcfdb5f64ee872fbef3e48c92f Mon Sep 17 00:00:00 2001
From: NullVoxPopuli-ai-agent
 <268630448+NullVoxPopuli-ai-agent@users.noreply.github.com>
Date: Mon, 27 Jul 2026 10:41:09 -0400
Subject: [PATCH 2/4] Drop the vite config comment

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 docs-app/vite.config.mjs | 1 -
 1 file changed, 1 deletion(-)

diff --git a/docs-app/vite.config.mjs b/docs-app/vite.config.mjs
index 4cd676538..fb4fc6b38 100644
--- a/docs-app/vite.config.mjs
+++ b/docs-app/vite.config.mjs
@@ -11,7 +11,6 @@ export default defineConfig(async (/* { mode } */) => {
     plugins: [
       scopedCSS(),
       ember(),
-      // no group: the docs are the co-located pages in app/templates
       docs({
         rehypePlugins: [
           [

From 58fa96c09deef3b152c5c14ee025eb2ef74d53d6 Mon Sep 17 00:00:00 2001
From: NullVoxPopuli-ai-agent
 <268630448+NullVoxPopuli-ai-agent@users.noreply.github.com>
Date: Mon, 27 Jul 2026 10:52:59 -0400
Subject: [PATCH 3/4] prose: typedoc names are inline code, not code blocks

kolay's typedoc renderer writes names (@arg, <:block>) as
<pre class="typedoc__name">, so the prose code-block treatment
(dark slab background, shadow, block padding) swallowed the
reworked types-read-like-code rendering. Exclude them inside the
existing :where() guards (specificity stays zero).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 packages/docs-support/src/site-css/prose.css | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/packages/docs-support/src/site-css/prose.css b/packages/docs-support/src/site-css/prose.css
index d5ea0a382..a000b8a1e 100644
--- a/packages/docs-support/src/site-css/prose.css
+++ b/packages/docs-support/src/site-css/prose.css
@@ -210,8 +210,9 @@
   color: #f8fafc;
 }
 
-/* Pre (code blocks) */
-.prose :where(pre):not(:where([class~="not-prose"], [class~="not-prose"] *)) {
+/* Pre (code blocks) — kolay's typedoc renderer writes names (@arg, <:block>)
+   as <pre class="typedoc__name">, which are inline code, not code blocks */
+.prose :where(pre):not(:where([class~="not-prose"], [class~="not-prose"] *, .typedoc__name)) {
   color: var(--prose-pre-code);
   background-color: var(--prose-pre-bg);
   overflow-x: auto;
@@ -229,7 +230,7 @@
 
 :is(html[style*="color-scheme: dark"])
   .prose
-  :where(pre):not(:where([class~="not-prose"], [class~="not-prose"] *)) {
+  :where(pre):not(:where([class~="not-prose"], [class~="not-prose"] *, .typedoc__name)) {
   background-color: rgb(30 41 59 / 0.6);
   box-shadow: none;
   outline: 1px solid rgb(203 213 225 / 0.1);

From e95fe505022b2a720af5558bfa7a4135b8ec9e50 Mon Sep 17 00:00:00 2001
From: NullVoxPopuli-ai-agent
 <268630448+NullVoxPopuli-ai-agent@users.noreply.github.com>
Date: Mon, 27 Jul 2026 12:16:11 -0400
Subject: [PATCH 4/4] cssTarget preserves light-dark(): typedoc colors survive
 the prod build
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The deploy preview rendered every typedoc token in the prose body
color while dev builds showed the palette. Vite 8's default cssTarget
predates light-dark(), so lightningcss rewrote kolay's colors into
var(--lightningcss-light/dark) space toggles whose :root definitions
don't survive chunking — both fallbacks resolve, the declaration is
invalid at computed-value time, and the color inherits. The rewrite
would also key theming off prefers-color-scheme instead of our
color-scheme toggle. Target browsers that support light-dark()
natively so it ships as authored.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 docs-app/vite.config.mjs | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/docs-app/vite.config.mjs b/docs-app/vite.config.mjs
index fb4fc6b38..ca0062ff6 100644
--- a/docs-app/vite.config.mjs
+++ b/docs-app/vite.config.mjs
@@ -43,6 +43,18 @@ export default defineConfig(async (/* { mode } */) => {
         extensions,
       }),
     ],
+    build: {
+      /**
+       * Vite's default cssTarget predates light-dark(), so lightningcss
+       * rewrites it into var(--lightningcss-light/dark) space toggles whose
+       * :root definitions don't survive chunking — the declarations then
+       * fail at computed-value time (kolay's typedoc colors, for example).
+       * The rewrite would also key theming off prefers-color-scheme,
+       * ignoring our color-scheme toggle. These targets support
+       * light-dark() natively.
+       */
+      cssTarget: ["chrome123", "firefox120", "safari17.5"],
+    },
     optimizeDeps: {
       exclude: [
         // a wasm-providing dependency