vocs 2.0.7 → 2.0.10

package/dist/react/internal/CodeToHtml.client.d.ts

@@ -0,0 +1,27 @@
+/**
+ * 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 declare function CodeToHtml(props: CodeToHtml.Props): import("react/jsx-runtime").JSX.Element;
+export declare namespace CodeToHtml {
+    type Props = {
+        code: string;
+        lang: string;
+    };
+}
+/** Returns the highlighted HTML for a snippet if it has already been computed. */
+export declare function getCached(code: string, lang: string): string | undefined;
+/** Highlights a snippet (memoized), loading the Shiki bundle on first use. */
+export declare function highlight(code: string, lang: string): Promise<string>;
+/** Eagerly loads the Shiki bundle so the first real highlight is fast. */
+export declare function prewarm(): void;
+//# sourceMappingURL=CodeToHtml.client.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"CodeToHtml.client.d.ts","sourceRoot":"","sources":["../../../src/react/internal/CodeToHtml.client.tsx"],"names":[],"mappings":"AAKA;;;;;;;;;;;;GAYG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,UAAU,CAAC,KAAK,2CA2BjD;AAmCD,yBAAiB,UAAU,CAAC;IAC1B,KAAY,KAAK,GAAG;QAClB,IAAI,EAAE,MAAM,CAAA;QACZ,IAAI,EAAE,MAAM,CAAA;KACb,CAAA;CACF;AA0DD,kFAAkF;AAClF,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,sBAEnD;AAED,8EAA8E;AAC9E,wBAAsB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,mBAQzD;AAED,0EAA0E;AAC1E,wBAAgB,OAAO,SAEtB"}

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

@@ -0,0 +1,138 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+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) {
+    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(() => 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 _jsx("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 _jsx(Skeleton, { code: code });
+}
+function Skeleton(props) {
+    const lines = props.code.split('\n');
+    return (_jsx("div", { "data-v-code-skeleton": true, "aria-hidden": "true", children: _jsxs("pre", { className: "shiki", "data-v-overflow-fade": true, children: [_jsx("code", { children: lines.map((line, index) => {
+                        const indent = line.length - line.trimStart().length;
+                        const length = line.trim().length;
+                        return (_jsx("span", { className: "line", children: length > 0 && (_jsx("span", { "data-v-skeleton-bar": true, style: {
+                                    marginLeft: `${indent}ch`,
+                                    width: `${Math.min(length, 48)}ch`,
+                                } })) }, index));
+                    }) }), _jsx("div", { "data-v-overflow-sentinel": true })] }) }));
+}
+let highlighterPromise;
+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),
+                langs: [],
+            });
+            return {
+                async codeToHtml(code, lang) {
+                    const base = langAlias[lang] ?? lang;
+                    const resolvedLang = base in bundledLanguages ? base : 'txt';
+                    if (!highlighter.getLoadedLanguages().includes(resolvedLang))
+                        await highlighter.loadLanguage(resolvedLang);
+                    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();
+function cacheKey(code, lang) {
+    return `${lang}\n${code}`;
+}
+/** Returns the highlighted HTML for a snippet if it has already been computed. */
+export function getCached(code, lang) {
+    return cache.get(cacheKey(code, lang));
+}
+/** Highlights a snippet (memoized), loading the Shiki bundle on first use. */
+export async function highlight(code, lang) {
+    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) {
+            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, ' ') };
+        },
+    };
+}
+//# sourceMappingURL=CodeToHtml.client.js.map

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

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

package/dist/react/internal/CodeToHtml.d.ts

@@ -1,8 +1,2 @@
-export declare function CodeToHtml(props: CodeToHtml.Props): Promise<import("react/jsx-runtime").JSX.Element>;
-export declare namespace CodeToHtml {
-    type Props = {
-        code: string;
-        lang: string;
-    };
-}
+export { CodeToHtml } from './CodeToHtml.client.js';
 //# sourceMappingURL=CodeToHtml.d.ts.map

package/dist/react/internal/CodeToHtml.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"CodeToHtml.d.ts","sourceRoot":"","sources":["../../../src/react/internal/CodeToHtml.tsx"],"names":[],"mappings":"AAYA,wBAAsB,UAAU,CAAC,KAAK,EAAE,UAAU,CAAC,KAAK,oDAyCvD;AAED,yBAAiB,UAAU,CAAC;IAC1B,KAAY,KAAK,GAAG;QAClB,IAAI,EAAE,MAAM,CAAA;QACZ,IAAI,EAAE,MAAM,CAAA;KACb,CAAA;CACF"}
+{"version":3,"file":"CodeToHtml.d.ts","sourceRoot":"","sources":["../../../src/react/internal/CodeToHtml.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAA"}

package/dist/react/internal/CodeToHtml.js

@@ -1,57 +1,2 @@
-import { jsx as _jsx } from "react/jsx-runtime";
-import { config } from 'virtual:vocs/config';
-import { langs as virtualLangs } from 'virtual:vocs/langs';
-import { bundledLanguages, createHighlighter, hastToHtml, makeSingletonHighlighter, } from 'shiki/bundle/web';
-const getHighlighter = makeSingletonHighlighter(createHighlighter);
-export async function 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),
-        langs: import.meta.env.DEV
-            ? ['txt']
-            : [...Object.keys(bundledLanguages), ...virtualLangs],
-        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 _jsx("div", { dangerouslySetInnerHTML: { __html: html } });
-}
-function transformerShrinkIndent() {
-    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';
 //# sourceMappingURL=CodeToHtml.js.map

package/dist/react/internal/CodeToHtml.js.map

@@ -1 +1 @@
-{"version":3,"file":"CodeToHtml.js","sourceRoot":"","sources":["../../../src/react/internal/CodeToHtml.tsx"],"names":[],"mappings":"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"}
+{"version":3,"file":"CodeToHtml.js","sourceRoot":"","sources":["../../../src/react/internal/CodeToHtml.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAA"}

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.7",
+  "version": "2.0.10",
   "main": "./dist/index.js",
   "license": "MIT",
   "repository": {

package/src/internal/mdx.ts

@@ -1118,7 +1118,10 @@ function getVirtualFiles(codeNodes: MdAst.Code[]): Map<string, string> {
   for (const node of codeNodes) {
     const fileName = getCodeFileName(node)
     if (!fileName) continue
-    virtualFiles.set(fileName, node.value)
+    // Strip any inline twoslash cache comment so it isn't inlined ahead of a
+    // host block's code when this virtual file is imported/included. The
+    // original node keeps its comment for its own rendering.
+    virtualFiles.set(fileName, InlineCache.stripInlineCacheComments(node.value))
   }
   return virtualFiles
 }

package/src/internal/shiki-transformers.ts

@@ -307,8 +307,13 @@ export function twoslash(options: twoslash.Options): ShikiTransformer {
           executeOptions?: Parameters<TwoslashInstance>[2],
           meta?: Parameters<NonNullable<typeof typesCache.preprocess>>[3],
         ) {
-          const preprocessed = typesCache.preprocess?.(code, lang, executeOptions, meta)
-          return Renderer.normalizeCustomTagBlocks(preprocessed ?? code)
+          // Normalize before the inner preprocess so the cache key hashed on
+          // read matches the code hashed on write (which runs against the
+          // normalized output). Without this, snippets containing consecutive
+          // custom tag lines (`@log`/`@error`/`@warn`/`@annotate`) would never
+          // hit the cache.
+          const normalized = Renderer.normalizeCustomTagBlocks(code)
+          return typesCache.preprocess?.(normalized, lang, executeOptions, meta) ?? normalized
         },
       }
     : undefined

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

@@ -6,6 +6,7 @@ import {
   createInlineTypesCache,
   extractSourceMapComment,
   injectSourceMapComment,
+  stripInlineCacheComments,
 } from './inline-cache.js'
 
 describe('source map codec', () => {
@@ -26,6 +27,21 @@ describe('source map codec', () => {
   })
 })
 
+describe('stripInlineCacheComments', () => {
+  it('removes all cache comments', () => {
+    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)
+  })
+})
+
 describe('inline types cache', () => {
   const tmpFiles: string[] = []
 
@@ -87,6 +103,70 @@ describe('inline types cache', () => {
     }
   })
 
+  it('replaces an existing cache comment in place instead of appending a duplicate', () => {
+    const code = 'const a: string = "x"'
+    const { file, from, to } = createMarkdown(code)
+    const data = { nodes: [], code: 'compiled-output' }
+
+    // --- Pass 1: cold write ---
+    {
+      const { typesCache, patcher } = createInlineTypesCache()
+      const meta = { sourceMap: { path: file, from, to } } as never
+      typesCache.preprocess?.(code, 'ts', {}, meta)
+      typesCache.write(code, data as never, 'ts', {}, meta)
+      patcher.patch(file)
+    }
+
+    const cacheLines = () =>
+      fs
+        .readFileSync(file, 'utf-8')
+        .split('\n')
+        .filter((l) => l.includes('// @twoslash-cache:'))
+    expect(cacheLines()).toHaveLength(1)
+
+    // --- Pass 2: a writer with stale in-memory code (no cache comment, so the
+    // existing comment can't be located via `search`) must still replace the
+    // on-disk comment rather than append a second one. ---
+    {
+      const content = fs.readFileSync(file, 'utf-8')
+      const currentTo = content.lastIndexOf('\n```')
+      const { typesCache, patcher } = createInlineTypesCache()
+      const meta = { sourceMap: { path: file, from, to: currentTo } } as never
+      // Pass the original (comment-free) code to simulate a stale read.
+      typesCache.preprocess?.(code, 'ts', {}, meta)
+      typesCache.write(code, data as never, 'ts', {}, meta)
+      patcher.patch(file)
+    }
+
+    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)

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,8 +72,33 @@ 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')
+/** 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|$)`)
+
+/**
+ * Remove all `// @twoslash-cache: ...` comments from a code string.
+ *
+ * Used when a virtual file's content is injected into another twoslash block
+ * (via `[!include]` or `import` resolution). Without stripping, the included
+ * file's own cache comment would be inlined ahead of the host block's code and
+ * picked up as the host's cache, causing a permanent hash mismatch (and a
+ * spurious cache comment to be re-appended on every build).
+ */
+export function stripInlineCacheComments(code: string): string {
+  return code.replace(CODE_INLINE_CACHE_REGEX, '')
+}
 
 export function createInlineTypesCache(
   options: { remove?: boolean | undefined; ignoreCache?: boolean | undefined } = {},
@@ -82,32 +106,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)
@@ -120,7 +137,7 @@ 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: () => {
@@ -148,12 +165,28 @@ export function createInlineTypesCache(
     const range: { from: number; to?: number } = { from: source.from }
     let linebreak = true
 
+    let located = false
     if (search) {
       const cachePos = file.content.indexOf(search, source.from)
       if (cachePos !== -1 && cachePos < source.to) {
         range.from = cachePos
         range.to = cachePos + search.length
         linebreak = search.endsWith('\n')
+        located = true
+      }
+    }
+
+    // Fallback: if the existing cache comment wasn't located via `search` (e.g.
+    // a concurrent build environment already wrote one, or the in-memory code
+    // was stale), detect a cache comment at the block body start and replace it
+    // in place rather than appending a duplicate.
+    if (!located) {
+      const body = file.content.slice(source.from, source.to)
+      const match = body.match(CODE_INLINE_CACHE_LINE_REGEX)
+      if (match) {
+        range.from = source.from
+        range.to = source.from + match[0].length
+        linebreak = match[0].endsWith('\n')
       }
     }
 
@@ -169,7 +202,7 @@ export function createInlineTypesCache(
   }
 
   const typesCache: TwoslashTypesCache = {
-    preprocess(code, lang, options, meta) {
+    preprocess(code, lang, _options, meta) {
       if (!meta) return
 
       let rawCache = ''
@@ -187,7 +220,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
         }
@@ -203,13 +236,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)
     },
   }