improvement(docs): clear leftovers from the reverted revisions

A cleanup pass over the final state. Every finding was residue from an approach
this PR tried and abandoned, or a claim that stopped being true when it did.

- Delete the copy-button svg sizing rule: a later rule sets `display: none` on
  that same element ungated, so sizing it was never observable. Superseded by
  the mask approach.
- Drop the paragraph in page.tsx arguing about a custom Shiki factory. The
  factory was deleted; nothing configures one now.
- Correct shiki-curl-json.ts, which still claimed the grammar "reaches the
  client path too". It does not — that was the justification for choosing a
  grammar over a transformer, so leaving it stated the opposite of the truth.
  Now records where it applies, where it does not, and why not to retry.
- Correct the global.css section header, which claimed the component owns the
  shell while the next rule defines it here.
- Qualify the `--copy-glyph` declarations with `:has(> svg[class*="lucide"])`,
  which the group's own comment asserts of every rule in it.
- Correct `getCode`'s TSDoc: the gutter is a `::before`, and pseudo-element
  content never reaches `textContent`, so line numbers were never what the
  clone guards. It guards transformer-emitted `.nd-copy-ignore` nodes.
- Compose `chipGeometryClass` and emcn's `ChipChevronDown` in the API example
  selector instead of restating their literals.
- Merge the duplicated `div[role="region"]` rule. The tablist pair stays split:
  biome's `noDuplicateProperties` reads a nested `@variant` setting the same
  property as a duplicate and fails the build — recorded so it is not remerged.
- Note that fumadocs ships its own gutter for `lines`-meta fences, which cannot
  be suppressed from here and would paint a second column.

Author: waleedlatif1

apps/docs/app/[lang]/[[...slug]]/page.tsx

@@ -78,15 +78,11 @@ function stripLocalePrefix(url: string, lang: string): string {
  * instead of fumadocs' lucide clipboard. Mirrors the default renderer — same `highlight` call,
  * same `Pre` component, same `my-0` — differing only in which shell wraps the result.
  *
- * One asymmetry: `highlight` resolves fumadocs' shared `defaultShikiFactory`, while the renderer
- * this replaces uses whatever `shiki` factory the page was configured with. They are the same
- * object because that factory is also the default; passing a custom one would be honored on API
- * markdown and ignored here.
+ * The `getHighlighter` call registers the JSON-body injection on the shared highlighter
+ * `highlight` resolves. An injection is a property of the highlighter, not a per-call option, and
+ * already-loaded grammars are skipped.
  */
 async function ApiCodeBlock({ lang, code }: { lang: string; code: string }) {
-  // Registers the injection on the shared highlighter `highlight` resolves; an injection is a
-  // property of the highlighter, not a per-call option. Idempotent — already-loaded grammars are
-  // skipped.
   await getHighlighter('js', { langs: [curlJsonBodyGrammar] })
   return (
     <CodeBlock className='my-0'>

apps/docs/app/global.css

@@ -1603,15 +1603,17 @@ main article tbody tr:last-child td {
 
 /* Code blocks — platform field chrome.
 
-   The shell itself (radius, border, fill) is owned by components/ui/code-block.tsx, the way
-   an emcn component owns its chrome. What remains here is the styling of fumadocs internals
-   that component cannot reach: the title row it renders from a `title` prop, the scroll
-   viewport, and the tab strip that `<Tabs>` puts above a fence. */
-
-/* Local aliases, not new design values: each is an existing platform token whose light and
-   dark halves differ. Naming the pair once lets the rules below be written without a `.dark`
-   twin, which would otherwise have to restate their `:has()` selectors — the double-`:has()`
-   the tabbed group is matched by, and the sibling-combinator one the gutter is matched by. */
+   Three renderers emit these figures and only two go through components/ui/code-block.tsx, so
+   the shell and the fumadocs internals that component cannot reach — the title row, the scroll
+   viewport, the tab strip `<Tabs>` puts above a fence — are all defined here. The component
+   keeps only the copy control and the prose margin. */
+
+/* Local aliases, not new design values: each names an existing platform token pair whose light
+   and dark halves differ (`--surface-5`/`--code-bg`, `--text-muted`/`--code-line-number`).
+
+   `--code-surface` has three consumers. `--code-gutter` has one, and is an alias anyway because
+   a `.dark` twin would have to restate the sibling-combinator `:has()` its consumer is matched
+   by — the expensive form, which re-checks on every line insertion. */
 :root {
   --code-surface: var(--surface-5);
   --code-gutter: var(--text-muted);
@@ -1689,10 +1691,9 @@ figure.shiki > div:first-child:has(figcaption) svg {
 
    The `!important` and the viewport selector are belt-and-braces, not strictly required —
    fumadocs' declaration is (0,2,0) and these selectors are (0,3,1) and (0,4,1), so they
-   already win, and nothing declares this property on the viewport. They are kept because
-   getting this wrong puts the line numbers on top of the code, which shipped once already, and
-   because the specificity of `:has()` and `:not()` is easy to miscount in exactly the
-   direction that reintroduces it. Remove them only alongside a visual check.
+   already win, and nothing declares this property on the viewport. They are kept because the
+   specificity of `:has()` and `:not()` is easy to miscount in the direction that puts the line
+   numbers on top of the code. Remove them only alongside a visual check.
  */
 figure.shiki:has(.line ~ .line),
 figure.shiki:has(.line ~ .line) > div[role="region"],
@@ -1733,6 +1734,7 @@ figure.shiki code:has(.line ~ .line) .line::before {
    the code surface. The viewport is the one box all three renderers agree on. */
 figure.shiki > div[role="region"] {
   background-color: var(--code-surface);
+  padding-block: 10px;
 }
 
 /* Shiki emits `--shiki-*-bg` custom properties under `defaultColor: false`; keep the `pre` clear
@@ -1744,10 +1746,6 @@ figure.shiki pre {
 /* Viewport padding — fumadocs ships 14px vertical; the platform's viewer uses 8px. Split the
    difference at 10px, which keeps a single-line fence from looking hollow at the tighter
    21px line box. */
-figure.shiki > div[role="region"] {
-  padding-block: 10px;
-}
-
 /* Untitled blocks float the copy control over the code, so the last column has to clear it:
    an 8px offset plus emcn's 20px icon button, with room to breathe. fumadocs reserves 32px,
    which the glyphs run into.
@@ -1802,12 +1800,6 @@ figure.shiki button[aria-label="Copied Text"]:has(> svg[class*="lucide"]) {
     color 150ms;
 }
 
-figure.shiki button[aria-label="Copy Text"] > svg[class*="lucide"],
-figure.shiki button[aria-label="Copied Text"] > svg[class*="lucide"] {
-  width: 14px;
-  height: 14px;
-}
-
 figure.shiki button[aria-label="Copy Text"]:has(> svg[class*="lucide"]) {
   @variant hover-hover {
     background-color: var(--surface-active);
@@ -1849,11 +1841,11 @@ figure.shiki button[aria-label$="Text"]:has(> svg[class*="lucide"])::before {
   -webkit-mask-size: contain;
 }
 
-figure.shiki button[aria-label="Copy Text"] {
+figure.shiki button[aria-label="Copy Text"]:has(> svg[class*="lucide"]) {
   --copy-glyph: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='-1 -2 24 24' fill='none' stroke='%23000' stroke-width='1.25' stroke-linecap='round' stroke-linejoin='round'%3E%3Cpath d='M14.25 0.75H2.75C1.64543 0.75 0.75 1.64543 0.75 2.75V14.25'/%3E%3Crect x='5.25' y='5.25' width='14' height='14' rx='2'/%3E%3C/svg%3E");
 }
 
-figure.shiki button[aria-label="Copied Text"] {
+figure.shiki button[aria-label="Copied Text"]:has(> svg[class*="lucide"]) {
   --copy-glyph: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='-1 -2 24 24' fill='none' stroke='%23000' stroke-width='1.25' stroke-linecap='round' stroke-linejoin='round'%3E%3Cpath d='M18.25 2.75L7.25 15.75L1.75 10.25'/%3E%3C/svg%3E");
 }
 
@@ -1901,6 +1893,9 @@ div:has(> div > figure.shiki) > [role="tablist"] button {
     color 150ms;
 }
 
+/* Kept as its own rule rather than nested into the block above: biome's
+   `noDuplicateProperties` reads a nested `@variant` setting the same property as a duplicate
+   declaration and fails the build. */
 div:has(> div > figure.shiki) > [role="tablist"] button {
   @variant hover-hover {
     color: var(--text-body);

apps/docs/components/ui/api-example-selector.tsx

@@ -2,8 +2,14 @@
 
 import type { ComponentProps } from 'react'
 import { useId } from 'react'
-import { chipFieldSurfaceClass, chipFieldTextClass, chipHoverSurfaceClass, cn } from '@sim/emcn'
-import { ChevronDown } from '@sim/emcn/icons'
+import {
+  ChipChevronDown,
+  chipFieldSurfaceClass,
+  chipFieldTextClass,
+  chipGeometryClass,
+  chipHoverSurfaceClass,
+  cn,
+} from '@sim/emcn'
 import type { APIPageClientOptions } from 'fumadocs-openapi/ui/client'
 
 type FumadocsAPIExampleSelector = NonNullable<
@@ -35,10 +41,11 @@ export function APIExampleSelector({ items, value, onValueChange }: APIExampleSe
            * screen-reader behavior a custom listbox would have to rebuild.
            */
           className={cn(
+            chipGeometryClass,
             chipFieldSurfaceClass,
             chipFieldTextClass,
             chipHoverSurfaceClass,
-            'h-[30px] w-full appearance-none ps-2 pe-8 text-left'
+            'w-full appearance-none pe-8'
           )}
         >
           {items.map((item) => (
@@ -47,7 +54,7 @@ export function APIExampleSelector({ items, value, onValueChange }: APIExampleSe
             </option>
           ))}
         </select>
-        <ChevronDown className='-translate-y-1/2 pointer-events-none absolute end-2 top-1/2 size-[14px] text-[var(--text-icon)]' />
+        <ChipChevronDown className='-translate-y-1/2 pointer-events-none absolute end-2 top-1/2' />
       </div>
       {selectedItem?.description && (
         <p className='text-[var(--text-muted)] text-caption'>{selectedItem.description}</p>

apps/docs/components/ui/code-block.tsx

@@ -45,9 +45,11 @@ export function CodeBlock({ title, ...props }: React.ComponentProps<typeof Fumad
   const figureRef = useRef<HTMLElement>(null)
 
   /**
-   * Reads the block's text the way fumadocs does: from a clone, with `.nd-copy-ignore` nodes
-   * replaced by newlines. Those nodes carry rendered gutter and diff markers, so copying the
-   * live `textContent` would paste line numbers along with the code.
+   * Reads the block's text the way fumadocs' own `CopyButton` does: from a clone, with
+   * `.nd-copy-ignore` nodes replaced by newlines. Shiki transformers emit those to mark content
+   * that is displayed but is not part of the code, so reading `pre.textContent` directly would
+   * copy it. (The line-number gutter here is a `::before`, and pseudo-element content never
+   * reaches `textContent` — it is not what this guards.)
    */
   function getCode() {
     const pre = figureRef.current?.getElementsByTagName('pre').item(0)
@@ -65,8 +67,9 @@ export function CodeBlock({ title, ...props }: React.ComponentProps<typeof Fumad
       className={cn('my-4', props.className)}
       allowCopy={false}
       /**
-       * fumadocs' own `className` is discarded rather than merged — its untitled-block variant
-       * carries a `backdrop-blur-lg` that goes milky over an opaque fill.
+       * The `className` fumadocs passes this render prop is deliberately neither destructured nor
+       * merged — its untitled-block variant carries a `backdrop-blur-lg` that goes milky over an
+       * opaque fill.
        */
       Actions={() => (
         <div className={cn('flex items-center', title ? '-me-1' : 'absolute top-2 right-2 z-[1]')}>

apps/docs/lib/shiki-curl-json.ts

@@ -14,10 +14,18 @@ import type { LanguageRegistration } from 'shiki'
  *   when it owns the opening brace. Entering mid-string, keys keep `string.quoted.double.json`
  *   and stay string-colored, which is the entire difference this exists to remove. Hence the
  *   hand-written patterns below, which name that scope directly.
- * - **A Shiki transformer.** A transformer can re-tokenize the body correctly, but it is a
- *   function, and the API reference's request tabs highlight in the browser off a `shikiOptions`
- *   object passed through RSC — where "Functions cannot be passed directly to Client
- *   Components". A grammar is plain data, so it reaches the client path too.
+ * - **A Shiki transformer.** A transformer re-tokenizes the body correctly, but it is a function,
+ *   and `shikiOptions` is forwarded into a client component — "Functions cannot be passed
+ *   directly to Client Components" takes down every API reference page. A grammar is plain data,
+ *   so it survives that boundary.
+ *
+ * Where it applies: prose fences, via `langs` on the MDX pipeline, and the API reference's
+ * request/response samples, via the `getHighlighter` call in the docs page. NOT the API
+ * reference's cURL usage tabs — those highlight in the browser off fumadocs' own factory, and
+ * `ClientCodeBlockProvider` sits in a `"use client"` module the package does not expose through
+ * its `exports` map, so reaching it means importing `fumadocs-openapi/ui/base` from client code
+ * and dragging `remark` and `@fumari/json-schema-ts` into the browser bundle. That broke the
+ * deployment once; it is not worth a second attempt.
  *
  * The opening brace requires a `}`, a quoted key, or end-of-line after it. That is what keeps
  * `awk '{print $1}'` out, while still matching a body whose brace ends the line — Oniguruma