vocs 2.0.8 → 2.0.11

package/dist/react/internal/TwoslashHover.client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"TwoslashHover.client.d.ts","sourceRoot":"","sources":["../../../src/react/internal/TwoslashHover.client.tsx"],"names":[],"mappings":"AAGA,OAAO,KAAK,KAAK,KAAK,MAAM,OAAO,CAAA;AAGnC,wBAAgB,aAAa,CAAC,KAAK,EAAE,aAAa,CAAC,KAAK,2CA+BvD;AAED,yBAAiB,aAAa,CAAC;IAC7B,KAAY,KAAK,GAAG;QAClB,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;QAC9B,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAA;QACzB,IAAI,CAAC,EAAE,OAAO,GAAG,SAAS,CAAA;QAC1B,OAAO,EAAE,KAAK,CAAC,SAAS,CAAA;KACzB,CAAA;IAED,SAAgB,eAAe;uBACK,cAAc,GAAG,IAAI;MAwBxD;CACF"}
+{"version":3,"file":"TwoslashHover.client.d.ts","sourceRoot":"","sources":["../../../src/react/internal/TwoslashHover.client.tsx"],"names":[],"mappings":"AAGA,OAAO,KAAK,KAAK,KAAK,MAAM,OAAO,CAAA;AAInC,wBAAgB,aAAa,CAAC,KAAK,EAAE,aAAa,CAAC,KAAK,2CAqCvD;AAED,yBAAiB,aAAa,CAAC;IAC7B,KAAY,KAAK,GAAG;QAClB,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;QAC9B,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAA;QACzB,IAAI,CAAC,EAAE,OAAO,GAAG,SAAS,CAAA;QAC1B,OAAO,EAAE,KAAK,CAAC,SAAS,CAAA;KACzB,CAAA;IAED,SAAgB,eAAe;uBACK,cAAc,GAAG,IAAI;MAwBxD;CACF"}

package/dist/react/internal/TwoslashHover.client.js

@@ -1,11 +1,17 @@
 'use client';
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { Popover } from '@base-ui/react/popover';
-import { useCallback } from 'react';
+import { useCallback, useEffect } from 'react';
+import { prewarm } from './CodeToHtml.client.js';
 export function TwoslashHover(props) {
     const { className = '', children, trigger } = props;
     const { ref } = TwoslashHover.useOverflowFade();
     const open = className?.includes('twoslash-query-persisted');
+    // Warm the highlighter so the code inside the popup highlights as quickly as
+    // possible (the popup shows a skeleton placeholder until then).
+    useEffect(() => {
+        prewarm();
+    }, []);
     return (_jsxs(Popover.Root, { ...(open ? { open } : {}), children: [_jsx(Popover.Trigger, { "data-v-twoslash-trigger": true, openOnHover: true, delay: 0, children: _jsx("span", { children: trigger }) }), _jsx(Popover.Portal, { children: _jsx(Popover.Positioner, { align: "start", side: "bottom", sideOffset: 4, collisionAvoidance: { side: 'none' }, children: _jsxs(Popover.Popup, { className: className, initialFocus: false, children: [_jsx(Popover.Arrow, { className: "vocs:data-[side=bottom]:top-[-8px] vocs:data-[side=left]:right-[-13px] vocs:data-[side=left]:rotate-90 vocs:data-[side=right]:left-[-13px] vocs:data-[side=right]:-rotate-90 vocs:data-[side=top]:bottom-[-8px] vocs:data-[side=top]:rotate-180", children: _jsx(ArrowSvg, {}) }), _jsx("div", { "data-v-content": true, ref: ref, children: children })] }) }) })] }));
 }
 (function (TwoslashHover) {

package/dist/react/internal/TwoslashHover.client.js.map

@@ -1 +1 @@
-{"version":3,"file":"TwoslashHover.client.js","sourceRoot":"","sources":["../../../src/react/internal/TwoslashHover.client.tsx"],"names":[],"mappings":"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"}
+{"version":3,"file":"TwoslashHover.client.js","sourceRoot":"","sources":["../../../src/react/internal/TwoslashHover.client.tsx"],"names":[],"mappings":"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"}

package/dist/styles/twoslash.css

@@ -63,6 +63,38 @@
   }
 }
 
+[data-v-code-skeleton] [data-v-skeleton-bar] {
+  display: inline-block;
+  height: 0.72em;
+  vertical-align: middle;
+  border-radius: 0.1875rem;
+  background-color: var(--vocs-background-color-surfaceTint);
+  background-image: linear-gradient(
+    90deg,
+    transparent 0%,
+    color-mix(in srgb, var(--vocs-color-gray10) 22%, transparent) 50%,
+    transparent 100%
+  );
+  background-repeat: no-repeat;
+  background-size: 200% 100%;
+  animation: vocs-skeleton-shimmer 1.25s ease-in-out infinite;
+}
+
+@keyframes vocs-skeleton-shimmer {
+  from {
+    background-position: 180% 0;
+  }
+  to {
+    background-position: -80% 0;
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  [data-v-code-skeleton] [data-v-skeleton-bar] {
+    animation: none;
+  }
+}
+
 .twoslash-popup-docs {
   @apply vocs:max-h-40 vocs:overflow-y-scroll;
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "vocs",
   "type": "module",
-  "version": "2.0.8",
+  "version": "2.0.11",
   "main": "./dist/index.js",
   "license": "MIT",
   "repository": {

package/src/internal/shiki-transformers.test.ts

@@ -241,6 +241,28 @@ const element = <div />`,
     highlighter.dispose()
   })
 
+  it('should hide committed inline cache comments when inline cache is disabled', async () => {
+    const highlighter = await createHighlighter({
+      themes: ['github-dark'],
+      langs: ['typescript'],
+    })
+
+    const html = highlighter.codeToHtml(
+      `// @twoslash-cache: {"v":1,"hash":"old","data":"x"}
+const value = 1`,
+      {
+        lang: 'typescript',
+        theme: 'github-dark',
+        transformers: [twoslash({ explicitTrigger: false })],
+      },
+    )
+
+    expect(html).toContain('const')
+    expect(html).not.toContain('twoslash-cache')
+
+    highlighter.dispose()
+  })
+
   it('should typecheck virtual json files in check-only mode', async () => {
     const highlighter = await createHighlighter({
       themes: ['github-dark'],

package/src/internal/shiki-transformers.ts

@@ -253,16 +253,22 @@ export function twoslash(options: twoslash.Options): ShikiTransformer {
     renderer = Renderer.rich(),
     throws = true,
     twoslashOptions,
-    typesCache = InlineCache.enabled(inlineCache)
-      ? InlineCache.getOrCreate().typesCache
-      : TypesCache.fs({ dir: cacheDir ? path.join(cacheDir, 'twoslash') : undefined }),
+    typesCache: configuredTypesCache,
   } = options
+  const inlineCacheStore = InlineCache.enabled(inlineCache) ? InlineCache.getOrCreate() : undefined
+  const typesCache =
+    configuredTypesCache ??
+    inlineCacheStore?.typesCache ??
+    TypesCache.fs({ dir: cacheDir ? path.join(cacheDir, 'twoslash') : undefined })
+  const shouldStripInlineCache = typesCache !== inlineCacheStore?.typesCache
 
   const lazyTwoslasher = (
     code: string,
     lang?: string,
     executeOptions?: Parameters<TwoslashInstance>[2],
   ) => {
+    code = InlineCache.stripInlineCacheComments(code)
+
     if (!twoslasher) {
       const tsModule = twoslashOptions?.tsModule ?? getTypeScript()
 
@@ -312,7 +318,10 @@ export function twoslash(options: twoslash.Options): ShikiTransformer {
           // normalized output). Without this, snippets containing consecutive
           // custom tag lines (`@log`/`@error`/`@warn`/`@annotate`) would never
           // hit the cache.
-          const normalized = Renderer.normalizeCustomTagBlocks(code)
+          const stripped = shouldStripInlineCache
+            ? InlineCache.stripInlineCacheComments(code)
+            : code
+          const normalized = Renderer.normalizeCustomTagBlocks(stripped)
           return typesCache.preprocess?.(normalized, lang, executeOptions, meta) ?? normalized
         },
       }
@@ -393,6 +402,8 @@ function checkOnlyTwoslasher(options: {
     executeOptions?: Parameters<TwoslashInstance>[2],
     meta?: { __raw?: string | undefined },
   ) => {
+    code = InlineCache.stripInlineCacheComments(code)
+
     const twoslashOptions = {
       ...options.twoslashOptions,
       ...executeOptions,

package/src/internal/twoslash/inline-cache.test.ts

@@ -36,6 +36,14 @@ describe('stripInlineCacheComments', () => {
     expect(stripInlineCacheComments(code)).toBe('export const client = 1')
   })
 
+  it('removes cache comments without a space after the colon', () => {
+    const code = [
+      '// @twoslash-cache:{"v":1,"hash":"abc","data":"x"}',
+      'export const client = 1',
+    ].join('\n')
+    expect(stripInlineCacheComments(code)).toBe('export const client = 1')
+  })
+
   it('leaves code without cache comments untouched', () => {
     const code = 'export const client = 1\nconst a = 2'
     expect(stripInlineCacheComments(code)).toBe(code)
@@ -141,6 +149,32 @@ describe('inline types cache', () => {
     expect(cacheLines()).toHaveLength(1)
   })
 
+  it('hits regardless of twoslash options (portable across environments)', () => {
+    const code = 'const a: string = "x"'
+    const { file, from, to } = createMarkdown(code)
+    const data = { nodes: [], code: 'compiled-output' }
+
+    // Seed with one set of options (e.g. machine A, with `paths`).
+    {
+      const { typesCache, patcher } = createInlineTypesCache()
+      const meta = { sourceMap: { path: file, from, to } } as never
+      const options = { compilerOptions: { paths: { foo: ['/abs/a'] } } }
+      typesCache.preprocess?.(code, 'ts', options as never, meta)
+      typesCache.write(code, data as never, 'ts', options as never, meta)
+      patcher.patch(file)
+    }
+
+    // Read with different options (e.g. machine B / Vercel, without `paths`).
+    {
+      const { typesCache } = createInlineTypesCache()
+      const body = readBody(file, from)
+      const meta = { sourceMap: { path: file, from, to } } as never
+      const otherOptions = { compilerOptions: {} }
+      typesCache.preprocess?.(body, 'ts', otherOptions as never, meta)
+      expect(typesCache.read(body, 'ts', otherOptions as never, meta)).toEqual(data)
+    }
+  })
+
   it('invalidates the cache when the hash no longer matches', () => {
     const code = 'const a: string = "x"'
     const { file, from, to } = createMarkdown(code)
@@ -165,6 +199,38 @@ describe('inline types cache', () => {
     }
   })
 
+  it('invalidates cached results that would render the cache comment', () => {
+    const code = 'const a: string = "x"'
+    const { file, from, to } = createMarkdown(code)
+
+    {
+      const { typesCache, patcher } = createInlineTypesCache()
+      const meta = { sourceMap: { path: file, from, to } } as never
+      typesCache.preprocess?.(code, 'ts', {}, meta)
+      typesCache.write(
+        code,
+        {
+          nodes: [],
+          code: `// @twoslash-cache: {"v":1,"hash":"old","data":"x"}\n${code}`,
+        } as never,
+        'ts',
+        {},
+        meta,
+      )
+      patcher.patch(file)
+    }
+
+    {
+      const { typesCache } = createInlineTypesCache()
+      const body = readBody(file, from)
+      const meta = { sourceMap: { path: file, from, to } } as never
+
+      const preprocessed = typesCache.preprocess?.(body, 'ts', {}, meta)
+      expect(preprocessed).toBe(code)
+      expect(typesCache.read(body, 'ts', {}, meta)).toBeNull()
+    }
+  })
+
   it('ignoreCache skips reading existing cache', () => {
     const code = 'const a: string = "x"'
     const { file, from, to } = createMarkdown(code)

package/src/internal/twoslash/inline-cache.ts

@@ -1,7 +1,6 @@
 import * as crypto from 'node:crypto'
 import type { TwoslashShikiReturn, TwoslashTypesCache } from '@shikijs/twoslash'
 import LZString from 'lz-string'
-import { getObjectHash, type TwoslashExecuteOptions } from 'twoslash/core'
 import { FilePatcher } from './file-patcher.js'
 
 /**
@@ -73,10 +72,25 @@ type CachePayload = {
   data: string
 }
 
+/**
+ * Cache payload format version. Kept at `1` even though the cache key changed
+ * from `optionsHash:lang:code` to `lang:code` (see `cacheHash`): stale
+ * payloads from the old key naturally fail the hash check on `preprocess` and
+ * are transparently re-seeded on the next write, so a version bump (which
+ * would force a one-shot invalidation of every committed cache comment) is
+ * unnecessary.
+ */
+const CACHE_VERSION = 1
+
 const CODE_INLINE_CACHE_KEY = '@twoslash-cache'
-const CODE_INLINE_CACHE_REGEX = new RegExp(`// ${CODE_INLINE_CACHE_KEY}: (.*)(?:\n|$)`, 'g')
+const CODE_INLINE_CACHE_REGEX = new RegExp(
+  `^// ${CODE_INLINE_CACHE_KEY}:[ \\t]*([^\\r\\n]*)(?:\\r?\\n|$)`,
+  'gm',
+)
 /** Matches a cache comment anchored to the start of a code block body. */
-const CODE_INLINE_CACHE_LINE_REGEX = new RegExp(`^// ${CODE_INLINE_CACHE_KEY}: .*(?:\n|$)`)
+const CODE_INLINE_CACHE_LINE_REGEX = new RegExp(
+  `^// ${CODE_INLINE_CACHE_KEY}:[ \\t]*[^\\r\\n]*(?:\\r?\\n|$)`,
+)
 
 /**
  * Remove all `// @twoslash-cache: ...` comments from a code string.
@@ -97,32 +111,25 @@ export function createInlineTypesCache(
   const { remove, ignoreCache } = options
   const patcher = new FilePatcher()
 
-  const optionsHashCache = new WeakMap<TwoslashExecuteOptions, string>()
-  function getOptionsHash(options: TwoslashExecuteOptions = {}): string {
-    let hash = optionsHashCache.get(options)
-    if (!hash) {
-      hash = getObjectHash(options)
-      optionsHashCache.set(options, hash)
-    }
-    return hash
-  }
-
-  function cacheHash(code: string, lang?: string, options?: TwoslashExecuteOptions): string {
+  // Key the cache on the (already fully-composed) snippet code and language
+  // only — deliberately NOT on the twoslash options. The whole point of the
+  // inline cache is to travel with the repo across machines and CI, but
+  // `twoslashOptions` frequently contain environment-specific or volatile
+  // values (absolute paths, config that branches on whether built `.d.ts`
+  // files exist, etc). Hashing them in makes the committed cache miss on any
+  // machine other than the one that seeded it. This matches the filesystem
+  // types cache, which also keys on code alone.
+  function cacheHash(code: string, lang?: string): string {
     return crypto
       .createHash('sha256')
-      .update(`${getOptionsHash(options)}:${lang ?? ''}:${code}`)
+      .update(`${lang ?? ''}:${code}`)
       .digest('hex')
   }
 
-  function stringifyCachePayload(
-    data: TwoslashShikiReturn,
-    code: string,
-    lang?: string,
-    options?: TwoslashExecuteOptions,
-  ): string {
+  function stringifyCachePayload(data: TwoslashShikiReturn, code: string, lang?: string): string {
     const payload: CachePayload = {
-      v: 1,
-      hash: cacheHash(code, lang, options),
+      v: CACHE_VERSION,
+      hash: cacheHash(code, lang),
       data: LZString.compressToBase64(JSON.stringify(data)),
     }
     return JSON.stringify(payload)
@@ -135,12 +142,20 @@ export function createInlineTypesCache(
     if (!cache) return null
     try {
       const payload = JSON.parse(cache) as CachePayload
-      if (payload.v === 1) {
+      if (payload.v === CACHE_VERSION) {
         return {
           payload,
           twoslash: () => {
             try {
-              return JSON.parse(LZString.decompressFromBase64(payload.data))
+              const twoslash = JSON.parse(
+                LZString.decompressFromBase64(payload.data),
+              ) as TwoslashShikiReturn
+              if (
+                typeof twoslash.code === 'string' &&
+                stripInlineCacheComments(twoslash.code) !== twoslash.code
+              )
+                return null
+              return twoslash
             } catch {
               return null
             }
@@ -200,7 +215,7 @@ export function createInlineTypesCache(
   }
 
   const typesCache: TwoslashTypesCache = {
-    preprocess(code, lang, options, meta) {
+    preprocess(code, lang, _options, meta) {
       if (!meta) return
 
       let rawCache = ''
@@ -218,7 +233,7 @@ export function createInlineTypesCache(
       const shouldLoadCache = !ignoreCache && !remove
       if (shouldLoadCache) {
         const cache = resolveCachePayload(cacheString)
-        if (cache?.payload.hash === cacheHash(code, lang, options)) {
+        if (cache?.payload.hash === cacheHash(code, lang)) {
           const twoslash = cache.twoslash()
           if (twoslash) meta.__cache = twoslash
         }
@@ -234,13 +249,13 @@ export function createInlineTypesCache(
     read(_code, _lang, _options, meta) {
       return meta?.__cache ?? null
     },
-    write(code, data, lang, options, meta) {
+    write(code, data, lang, _options, meta) {
       if (remove) {
         meta?.__patch?.('')
         return
       }
       const twoslashShiki = simplifyTwoslashReturn(data)
-      const cacheStr = `// ${CODE_INLINE_CACHE_KEY}: ${stringifyCachePayload(twoslashShiki, code, lang, options)}`
+      const cacheStr = `// ${CODE_INLINE_CACHE_KEY}: ${stringifyCachePayload(twoslashShiki, code, lang)}`
       meta?.__patch?.(cacheStr)
     },
   }

package/src/react/internal/CodeToHtml.client.tsx

@@ -0,0 +1,176 @@
+'use client'
+
+import { config } from 'virtual:vocs/config'
+import { useEffect, useState } from 'react'
+
+/**
+ * Lazily highlights code on the client.
+ *
+ * Twoslash hover popups embed a code snippet (the resolved type) for every
+ * hoverable token. Highlighting these with Shiki on the server forces RSC to
+ * render and serialize a fully highlighted snippet for every token across every
+ * page at build time — which dominates build memory and time even though the
+ * popups are only ever seen on hover.
+ *
+ * Instead we render the snippet as plain text in the RSC payload and highlight
+ * it on the client. Because the popup only mounts when it opens, the Shiki
+ * bundle is dynamically imported and the snippet highlighted on demand.
+ */
+export function CodeToHtml(props: CodeToHtml.Props) {
+  const { code, lang } = props
+  // Initialize from the cache so a snippet that was already highlighted (e.g.
+  // pre-highlighted by the popover before opening, or shown previously) renders
+  // highlighted immediately without a plain-text flash.
+  const [html, setHtml] = useState<string | null>(() => getCached(code, lang) ?? null)
+
+  useEffect(() => {
+    if (html) return
+    let cancelled = false
+    highlight(code, lang)
+      .then((result) => {
+        if (!cancelled) setHtml(result)
+      })
+      .catch(() => {})
+    return () => {
+      cancelled = true
+    }
+  }, [code, lang, html])
+
+  if (html)
+    // biome-ignore lint/security/noDangerouslySetInnerHtml: highlighted by Shiki
+    return <div dangerouslySetInnerHTML={{ __html: html }} />
+
+  // While highlighting, render a skeleton that mirrors the snippet's line
+  // structure so the popup is shown immediately without a layout shift.
+  return <Skeleton code={code} />
+}
+
+function Skeleton(props: { code: string }) {
+  const lines = props.code.split('\n')
+  return (
+    <div data-v-code-skeleton aria-hidden="true">
+      {/* `shiki` class mirrors the real highlighted markup so shared styles
+          (e.g. code padding) apply identically and there is no layout shift. */}
+      <pre className="shiki" data-v-overflow-fade>
+        <code>
+          {lines.map((line, index) => {
+            const indent = line.length - line.trimStart().length
+            const length = line.trim().length
+            return (
+              // biome-ignore lint/suspicious/noArrayIndexKey: static, never reordered
+              <span className="line" key={index}>
+                {length > 0 && (
+                  <span
+                    data-v-skeleton-bar
+                    style={{
+                      marginLeft: `${indent}ch`,
+                      width: `${Math.min(length, 48)}ch`,
+                    }}
+                  />
+                )}
+              </span>
+            )
+          })}
+        </code>
+        <div data-v-overflow-sentinel />
+      </pre>
+    </div>
+  )
+}
+
+export namespace CodeToHtml {
+  export type Props = {
+    code: string
+    lang: string
+  }
+}
+
+let highlighterPromise:
+  | Promise<{
+      codeToHtml: (code: string, lang: string) => Promise<string>
+    }>
+  | undefined
+
+function getHighlighter() {
+  if (!highlighterPromise)
+    highlighterPromise = (async () => {
+      const { bundledLanguages, createHighlighter, hastToHtml } = await import('shiki/bundle/web')
+      const { codeHighlight } = config
+      const { langAlias = {}, themes } = codeHighlight
+      // Note: `langAlias` is intentionally not passed to the highlighter.
+      // Passing a custom `langAlias` registers languages under their alias name
+      // when lazily loaded (e.g. `loadLanguage('ts')` registers as `ts` instead
+      // of `typescript`), which then makes `codeToHast({ lang })` fail to resolve
+      // the grammar. We resolve aliases to their base language ourselves below.
+      const highlighter = await createHighlighter({
+        themes: Object.values(themes) as never,
+        langs: [],
+      })
+      return {
+        async codeToHtml(code: string, lang: string) {
+          const base = langAlias[lang] ?? lang
+          const resolvedLang = base in bundledLanguages ? base : 'txt'
+          if (!highlighter.getLoadedLanguages().includes(resolvedLang))
+            await highlighter.loadLanguage(resolvedLang as never)
+          const hast = highlighter.codeToHast(code, {
+            defaultColor: 'light-dark()',
+            lang: resolvedLang,
+            rootStyle: false,
+            meta: { 'data-v-overflow-fade': true },
+            themes,
+            transformers: [transformerShrinkIndent()],
+          })
+          const pre = hast.children[0]
+          if (pre && pre.type === 'element' && pre.tagName === 'pre')
+            pre.children.push({
+              type: 'element',
+              tagName: 'div',
+              properties: { 'data-v-overflow-sentinel': true },
+              children: [],
+            })
+          return hastToHtml(hast)
+        },
+      }
+    })()
+  return highlighterPromise
+}
+
+const cache = new Map<string, string>()
+
+function cacheKey(code: string, lang: string) {
+  return `${lang}\n${code}`
+}
+
+/** Returns the highlighted HTML for a snippet if it has already been computed. */
+export function getCached(code: string, lang: string) {
+  return cache.get(cacheKey(code, lang))
+}
+
+/** Highlights a snippet (memoized), loading the Shiki bundle on first use. */
+export async function highlight(code: string, lang: string) {
+  const key = cacheKey(code, lang)
+  const cached = cache.get(key)
+  if (cached !== undefined) return cached
+  const highlighter = await getHighlighter()
+  const html = await highlighter.codeToHtml(code, lang)
+  cache.set(key, html)
+  return html
+}
+
+/** Eagerly loads the Shiki bundle so the first real highlight is fast. */
+export function prewarm() {
+  void getHighlighter()
+}
+
+function transformerShrinkIndent() {
+  return {
+    name: 'indent',
+    span(hast: { children: { type: string; value?: string }[] }) {
+      const child = hast.children[0]
+      if (!child) return
+      if (child.type !== 'text') return
+      if (!child.value) return
+      hast.children[0] = { type: 'text', value: child.value.replace(/\s\s/g, ' ') }
+    },
+  }
+}

package/src/react/internal/CodeToHtml.tsx

@@ -1,74 +1 @@
-import { config } from 'virtual:vocs/config'
-import { langs as virtualLangs } from 'virtual:vocs/langs'
-import {
-  bundledLanguages,
-  createHighlighter,
-  hastToHtml,
-  makeSingletonHighlighter,
-  type ShikiTransformer,
-} from 'shiki/bundle/web'
-
-const getHighlighter = makeSingletonHighlighter(createHighlighter)
-
-export async function CodeToHtml(props: CodeToHtml.Props) {
-  const { code, lang } = props
-  const { codeHighlight } = config
-  const { langAlias = {}, themes } = codeHighlight
-
-  const highlighter = await getHighlighter({
-    themes: import.meta.env.DEV ? ['none'] : (Object.values(themes) as never),
-    langs: import.meta.env.DEV
-      ? ['txt']
-      : ([...Object.keys(bundledLanguages), ...virtualLangs] as never),
-    langAlias,
-  })
-
-  const loadedLangs = highlighter.getLoadedLanguages()
-  const resolvedLang = loadedLangs.includes(lang) ? lang : 'txt'
-
-  const hast = highlighter.codeToHast(code, {
-    defaultColor: 'light-dark()',
-    lang: import.meta.env.DEV ? 'txt' : resolvedLang,
-    rootStyle: false,
-    meta: {
-      'data-v-overflow-fade': true,
-    },
-    ...(import.meta.env.DEV ? { theme: 'none' } : { themes }),
-    transformers: [transformerShrinkIndent()],
-  })
-
-  // Add overflow sentinel
-  const pre = hast.children[0]
-  if (pre && pre.type === 'element' && pre.tagName === 'pre')
-    pre.children.push({
-      type: 'element',
-      tagName: 'div',
-      properties: { 'data-v-overflow-sentinel': true },
-      children: [],
-    })
-
-  const html = hastToHtml(hast)
-
-  // biome-ignore lint/security/noDangerouslySetInnerHtml: _
-  return <div dangerouslySetInnerHTML={{ __html: html }} />
-}
-
-export namespace CodeToHtml {
-  export type Props = {
-    code: string
-    lang: string
-  }
-}
-
-function transformerShrinkIndent(): ShikiTransformer {
-  return {
-    name: 'indent',
-    span(hast) {
-      const child = hast.children[0]
-      if (!child) return
-      if (child.type !== 'text') return
-      if (!child.value) return
-      hast.children[0] = { type: 'text', value: child.value.replace(/\s\s/g, ' ') }
-    },
-  }
-}
+export { CodeToHtml } from './CodeToHtml.client.js'

package/src/react/internal/TwoslashHover.client.tsx

@@ -2,7 +2,8 @@
 
 import { Popover } from '@base-ui/react/popover'
 import type * as React from 'react'
-import { useCallback } from 'react'
+import { useCallback, useEffect } from 'react'
+import { prewarm } from './CodeToHtml.client.js'
 
 export function TwoslashHover(props: TwoslashHover.Props) {
   const { className = '', children, trigger } = props
@@ -11,6 +12,12 @@ export function TwoslashHover(props: TwoslashHover.Props) {
 
   const open = className?.includes('twoslash-query-persisted')
 
+  // Warm the highlighter so the code inside the popup highlights as quickly as
+  // possible (the popup shows a skeleton placeholder until then).
+  useEffect(() => {
+    prewarm()
+  }, [])
+
   return (
     <Popover.Root {...(open ? { open } : {})}>
       <Popover.Trigger data-v-twoslash-trigger openOnHover delay={0}>