shikijs · antfu · Feb 26, 2026 · Feb 25, 2026 · Feb 25, 2026 · Feb 26, 2026
diff --git a/bench/bundle-test/index-lite.ts b/bench/bundle-test/index-lite.ts
@@ -1,7 +1,7 @@
-import { codeToHtml, createShikiInternal } from '@shikijs/core'
+import { codeToHtml, createShikiPrimitiveAsync } from '@shikijs/core'
 import { createJavaScriptRawEngine } from '@shikijs/engine-javascript/raw'
 
-const shiki = createShikiInternal(
+const shiki = createShikiPrimitiveAsync(
   {
     langs: [
       import('@shikijs/langs-precompiled/ts'),

diff --git a/bench/bundle-test/index-wasm.ts b/bench/bundle-test/index-wasm.ts
@@ -1,7 +1,7 @@
-import { codeToHtml, createShikiInternal } from '@shikijs/core'
+import { codeToHtml, createShikiPrimitiveAsync } from '@shikijs/core'
 import { createOnigurumaEngine } from '@shikijs/engine-oniguruma'
 
-const shiki = createShikiInternal(
+const shiki = createShikiPrimitiveAsync(
   {
     langs: [
       import('@shikijs/langs/ts'),

diff --git a/packages/core/package.json b/packages/core/package.json
@@ -52,6 +52,7 @@
     "test": "vitest"
   },
   "dependencies": {
+    "@shikijs/primitive": "workspace:*",
     "@shikijs/types": "workspace:*",
     "@shikijs/vscode-textmate": "catalog:prod",
     "@types/hast": "catalog:types",

diff --git a/packages/core/src/constructors/highlighter.ts b/packages/core/src/constructors/highlighter.ts
@@ -1,13 +1,10 @@
 import type { HighlighterCore, HighlighterCoreOptions } from '@shikijs/types'
 
+import { codeToTokensWithThemes, createShikiPrimitive, createShikiPrimitiveAsync } from '@shikijs/primitive'
 import { codeToHast } from '../highlight/code-to-hast'
 import { codeToHtml } from '../highlight/code-to-html'
 import { codeToTokens } from '../highlight/code-to-tokens'
 import { codeToTokensBase, getLastGrammarState } from '../highlight/code-to-tokens-base'
-import { codeToTokensWithThemes } from '../highlight/code-to-tokens-themes'
-
-import { createShikiInternal } from './internal'
-import { createShikiInternalSync } from './internal-sync'
 
 /**
  * Create a Shiki core highlighter instance, with no languages or themes bundled.
@@ -16,19 +13,19 @@ import { createShikiInternalSync } from './internal-sync'
  * @see http://shiki.style/guide/bundles#fine-grained-bundle
  */
 export async function createHighlighterCore(options: HighlighterCoreOptions<false>): Promise<HighlighterCore> {
-  const internal = await createShikiInternal(options)
+  const primitive = await createShikiPrimitiveAsync(options)
 
   return {
-    getLastGrammarState: (...args: any[]) => getLastGrammarState(internal, ...args as [any])!,
-    codeToTokensBase: (code, options) => codeToTokensBase(internal, code, options),
-    codeToTokensWithThemes: (code, options) => codeToTokensWithThemes(internal, code, options),
-    codeToTokens: (code, options) => codeToTokens(internal, code, options),
-    codeToHast: (code, options) => codeToHast(internal, code, options),
-    codeToHtml: (code, options) => codeToHtml(internal, code, options),
+    getLastGrammarState: (...args: any[]) => getLastGrammarState(primitive, ...args as [any])!,
+    codeToTokensBase: (code, options) => codeToTokensBase(primitive, code, options),
+    codeToTokensWithThemes: (code, options) => codeToTokensWithThemes(primitive, code, options),
+    codeToTokens: (code, options) => codeToTokens(primitive, code, options),
+    codeToHast: (code, options) => codeToHast(primitive, code, options),
+    codeToHtml: (code, options) => codeToHtml(primitive, code, options),
     getBundledLanguages: () => ({}),
     getBundledThemes: () => ({}),
-    ...internal,
-    getInternalContext: () => internal,
+    ...primitive,
+    getInternalContext: () => primitive,
   }
 }
 
@@ -41,7 +38,7 @@ export async function createHighlighterCore(options: HighlighterCoreOptions<fals
  * @see http://shiki.style/guide/bundles#fine-grained-bundle
  */
 export function createHighlighterCoreSync(options: HighlighterCoreOptions<true>): HighlighterCore {
-  const internal = createShikiInternalSync(options)
+  const internal = createShikiPrimitive(options)
 
   return {
     getLastGrammarState: (...args: any[]) => getLastGrammarState(internal, ...args as [any, any]),

diff --git a/packages/core/src/constructors/internal.ts b/packages/core/src/constructors/internal.ts
diff --git a/packages/core/src/highlight/code-to-hast.ts b/packages/core/src/highlight/code-to-hast.ts
@@ -2,7 +2,7 @@ import type {
   CodeToHastOptions,
   CodeToHastRenderOptions,
   GrammarState,
-  ShikiInternal,
+  ShikiPrimitive,
   ShikiTransformerContext,
   ShikiTransformerContextCommon,
   ShikiTransformerContextSource,
@@ -14,21 +14,21 @@ import type {
   Text,
 } from 'hast'
 
+import { getLastGrammarStateFromMap, setLastGrammarStateToMap } from '@shikijs/primitive'
 import { FontStyle } from '@shikijs/vscode-textmate'
-import { getLastGrammarStateFromMap, setLastGrammarStateToMap } from '../textmate/grammar-state'
 import { addClassToHast, getTokenStyleObject, stringifyTokenStyle } from '../utils'
 import { getTransformers } from './_get-transformers'
 import { codeToTokens } from './code-to-tokens'
 
 export function codeToHast(
-  internal: ShikiInternal,
+  primitive: ShikiPrimitive,
   code: string,
   options: CodeToHastOptions,
   transformerContext: ShikiTransformerContextCommon = {
     meta: {},
     options,
-    codeToHast: (_code, _options) => codeToHast(internal, _code, _options),
-    codeToTokens: (_code, _options) => codeToTokens(internal, _code, _options),
+    codeToHast: (_code, _options) => codeToHast(primitive, _code, _options),
+    codeToTokens: (_code, _options) => codeToTokens(primitive, _code, _options),
   },
 ): Root {
   let input = code
@@ -43,7 +43,7 @@ export function codeToHast(
     themeName,
     rootStyle,
     grammarState,
-  } = codeToTokens(internal, input, options)
+  } = codeToTokens(primitive, input, options)
 
   const {
     mergeWhitespaces = true,

diff --git a/packages/core/src/highlight/code-to-html.ts b/packages/core/src/highlight/code-to-html.ts
@@ -1,6 +1,6 @@
 import type {
   CodeToHastOptions,
-  ShikiInternal,
+  ShikiPrimitive,
   ShikiTransformerContextCommon,
 } from '@shikijs/types'
 
@@ -16,18 +16,18 @@ export const hastToHtml = toHtml
  * Get highlighted code in HTML.
  */
 export function codeToHtml(
-  internal: ShikiInternal,
+  primitive: ShikiPrimitive,
   code: string,
   options: CodeToHastOptions,
 ): string {
   const context: ShikiTransformerContextCommon = {
     meta: {},
     options,
-    codeToHast: (_code, _options) => codeToHast(internal, _code, _options),
-    codeToTokens: (_code, _options) => codeToTokens(internal, _code, _options),
+    codeToHast: (_code, _options) => codeToHast(primitive, _code, _options),
+    codeToTokens: (_code, _options) => codeToTokens(primitive, _code, _options),
   }
 
-  let result = hastToHtml(codeToHast(internal, code, options, context))
+  let result = hastToHtml(codeToHast(primitive, code, options, context))
 
   for (const transformer of getTransformers(options))
     result = transformer.postprocess?.call(context, result, options) || result