@vmz/plugin-shiki 0.3.13 → 0.3.15

package/README.md

@@ -24,16 +24,19 @@ It is especially useful for:
 
 ## Install
 
-`@vmz/plugin-shiki` resolves Shiki from the application. `shiki` (`>=3`) is a required peer dependency, not a
-bundled dependency, so install it alongside the plugin:
+`@vmz/plugin-shiki` resolves Shiki from the application. `shiki`, `@shikijs/langs` and `@shikijs/themes` (`>=3`) are
+required peer dependencies, not bundled dependencies, so install them alongside the plugin:
 
 ```bash
-pnpm add @vmz/plugin-shiki shiki
+pnpm add @vmz/plugin-shiki shiki @shikijs/langs @shikijs/themes
 ```
 
-The runtime loads plain `shiki` by default (a literal dynamic import that client bundles can vendor). A TextMate
-adapter adds custom grammars on top; installing `@shikijs/*` transitively through an adapter does not replace the
-application-level `shiki` install.
+The runtime loads `shiki/core` plus explicitly imported grammar and theme modules, so a client bundle only carries the
+grammars this plugin can actually resolve instead of every `bundle-full` language. Supported grammars:
+`javascript`, `typescript`, `tsx`, `jsx`, `json`, `html`, `css`, `markdown`, `bash` (plus `text`/`plaintext`, which
+Shiki serves without a grammar module). Supported themes: `vitesse-dark` (default) and `vitesse-light`. A theme outside
+that set is rejected with an explicit error instead of being silently swapped. A TextMate adapter adds custom grammars
+on top; it does not replace the application-level `shiki` install.
 
 ## Third-party TextMate grammar (VMZ-2)
 
@@ -49,7 +52,8 @@ export default defineConfig({
 ```
 
 The adapter specifier is host-resolved (serve-host resolve hooks on Node, an import map or vendor copy in the
-browser) and never vendored by the packer; when it fails to load, the runtime falls back to plain `shiki`.
+browser) and never vendored by the packer; when it fails to load, the runtime falls back to the built-in grammar set
+above.
 
 The plugin writes `dist/_vmz/plugin-shiki.config.json`; the runtime reads it in SSR (`VMZ_DIST`) and in the browser (`fetch`).
 

package/components/Shiki.vmz

@@ -9,11 +9,18 @@ export default class Shiki {
     public lang: string = "text";
     public theme: string = "vitesse-dark";
 
-    /** null → sync fallback / prewarm cache; set after async highlight. */
+    /**
+     * `null` means "no client payload": the sync path only fills it on the
+     * server (or after prewarm). Keeping it null lets the resumed host keep the
+     * SSR payload instead of replacing tokenized markup with a fallback shell.
+     */
     html: string | null = null;
 
     async onMount() {
-        this.html = await highlight(this.code, this.lang, this.theme);
+        const next = await highlight(this.code, this.lang, this.theme);
+        // A degraded payload must not replace the server's tokenized markup:
+        // only an actual highlight is an improvement over what SSR wrote.
+        if (!next.includes('shiki-fallback')) this.html = next;
     }
 }
 </script>

package/dist/runtime.d.ts

@@ -2,7 +2,7 @@
  * Shiki highlight helper — async with optional sync cache after prewarm.
  * TextMate grammar via configurable peer (default `vmz-textmate/shiki`).
  */
-import type { Highlighter } from 'shiki';
+import type { ShikiTransformer } from 'shiki';
 export type ShikiRuntimeConfig = {
     /**
      * TextMate Shiki adapter module id (e.g. `vmz-textmate/shiki`). Explicit
@@ -14,7 +14,19 @@ export type ShikiRuntimeConfig = {
     /** Default themes passed to the highlighter factory. */
     themes?: string[];
 };
-type CodeHighlighter = Pick<Highlighter, 'codeToHtml'>;
+/**
+ * The highlight surface every adapter must provide. Kept structural instead of
+ * `Pick<Highlighter, 'codeToHtml'>`: the fine-grained entry returns a
+ * `HighlighterCore`, and both satisfy this shape.
+ */
+type CodeHighlighter = {
+    codeToHtml(code: string, options: {
+        lang: string;
+        theme: string;
+        transformers?: ShikiTransformer[];
+        structure?: 'classic' | 'inline';
+    }): string;
+};
 /** @internal test hook */
 export declare function getShikiRuntimeConfig(): Readonly<ShikiRuntimeConfig>;
 /** Reset module state (tests). */
@@ -27,8 +39,17 @@ export declare function prewarmShiki(opts?: {
     themes?: string[];
 }): Promise<CodeHighlighter>;
 export declare function highlight(code: string, lang?: string, theme?: string | null): Promise<string>;
-/** Sync highlight when prewarmed; otherwise escaped `<pre><code>`. */
-export declare function highlightSync(code: string, lang?: string, theme?: string | null): string;
+/**
+ * Sync highlight when the runtime is prewarmed.
+ *
+ * `null` means "this runtime has no payload for this language yet". The server
+ * never has a better source than one it cannot resolve, so it degrades to the
+ * escaped shell. A browser with a cold cache (or a grammar the shipped generic
+ * path cannot resolve) must not invent one: the host may already hold the
+ * server's tokenized payload, and replacing it with an un-tokenized shell
+ * throws that payload away.
+ */
+export declare function highlightSync(code: string, lang?: string, theme?: string | null): string | null;
 /**
  * Inline-structure sync highlight for embedders that own the `<pre>` chrome
  * (markdown-it fence callback in the document pipeline). Returns the token

package/dist/runtime.js

@@ -123,15 +123,62 @@ async function loadTextmateHighlighter(themes) {
     }
     return null;
 }
+/**
+ * Grammars the generic (non-TextMate) path can resolve. `shiki`'s root entry
+ * reaches `bundle-full`, which registers every bundled grammar and theme as its
+ * own dynamic import — 272 async chunks of unused `@shikijs/langs` grammars in
+ * the delivered pack. The fine-grained entry below keeps the reachable grammar
+ * set equal to what the runtime can actually resolve.
+ *
+ * `text` / `plaintext` / `txt` / `plain` need no module: Shiki treats them as
+ * plain text (`isPlainLang`).
+ */
+const LANG_MODULES = {
+    javascript: () => import('@shikijs/langs/javascript'),
+    typescript: () => import('@shikijs/langs/typescript'),
+    tsx: () => import('@shikijs/langs/tsx'),
+    jsx: () => import('@shikijs/langs/jsx'),
+    json: () => import('@shikijs/langs/json'),
+    html: () => import('@shikijs/langs/html'),
+    css: () => import('@shikijs/langs/css'),
+    markdown: () => import('@shikijs/langs/markdown'),
+    bash: () => import('@shikijs/langs/bash'),
+};
+/** Themes the generic path can resolve (`vitesse-dark` is the runtime default). */
+const THEME_MODULES = {
+    'vitesse-dark': () => import('@shikijs/themes/vitesse-dark'),
+    'vitesse-light': () => import('@shikijs/themes/vitesse-light'),
+};
 async function loadGenericHighlighter(themes) {
-    // Literal specifier only: a computed dynamic import (variable argument) is
+    // Literal specifiers only: a computed dynamic import (variable argument) is
     // invisible to the packer, so the browser chunk would keep a bare specifier
     // and fail with "Failed to resolve module specifier 'shiki'". Literal
     // imports let vmz-pack vendor the highlighter into an async client chunk.
-    const { createHighlighter } = await import('shiki');
-    return createHighlighter({
-        themes,
-        langs: ['javascript', 'typescript', 'tsx', 'jsx', 'json', 'html', 'css', 'markdown', 'bash', 'text'],
+    for (const theme of themes) {
+        if (!THEME_MODULES[theme]) {
+            // Explicit rejection, no silent substitution: a theme outside the
+            // shipped set cannot be highlighted, and pretending otherwise would
+            // emit the wrong colours.
+            throw new Error(`@vmz/plugin-shiki: unsupported theme ${JSON.stringify(theme)} ` +
+                `(supported: ${Object.keys(THEME_MODULES).join(', ')})`);
+        }
+    }
+    // Every supported theme is registered at once: the highlighter is created
+    // once per process and per-call `theme` switches must not hit an
+    // unregistered theme. The requested list only decides what must be
+    // resolvable (validation above), not what is registered.
+    const [{ createHighlighterCore }, { createJavaScriptRegexEngine }, themeModules, langModules] = await Promise.all([
+        import('shiki/core'),
+        import('shiki/engine/javascript'),
+        Promise.all(Object.values(THEME_MODULES).map((load) => load())),
+        Promise.all(Object.values(LANG_MODULES).map((load) => load())),
+    ]);
+    return createHighlighterCore({
+        themes: themeModules.map((module) => module.default),
+        langs: langModules.map((module) => module.default),
+        // Grammar fidelity comes from the same JS RegExp engine `vmz-textmate`
+        // ships: it needs no 608 KiB inlined Oniguruma wasm beside the chunk.
+        engine: createJavaScriptRegexEngine(),
     });
 }
 export async function prewarmShiki(opts = {}) {
@@ -171,10 +218,19 @@ export async function highlight(code, lang = 'text', theme = DEFAULT_THEME) {
         return fallbackPre(code);
     }
 }
-/** Sync highlight when prewarmed; otherwise escaped `<pre><code>`. */
+/**
+ * Sync highlight when the runtime is prewarmed.
+ *
+ * `null` means "this runtime has no payload for this language yet". The server
+ * never has a better source than one it cannot resolve, so it degrades to the
+ * escaped shell. A browser with a cold cache (or a grammar the shipped generic
+ * path cannot resolve) must not invent one: the host may already hold the
+ * server's tokenized payload, and replacing it with an un-tokenized shell
+ * throws that payload away.
+ */
 export function highlightSync(code, lang = 'text', theme = DEFAULT_THEME) {
     if (!cached)
-        return fallbackPre(code);
+        return isServerRuntime() ? fallbackPre(code) : null;
     try {
         return cached.codeToHtml(code ?? '', {
             lang: normalizeLang(lang),
@@ -183,9 +239,13 @@ export function highlightSync(code, lang = 'text', theme = DEFAULT_THEME) {
         });
     }
     catch {
-        return fallbackPre(code);
+        return isServerRuntime() ? fallbackPre(code) : null;
     }
 }
+/** No `document` means the serialize path (SSR) — see {@link highlightSync}. */
+function isServerRuntime() {
+    return typeof document === 'undefined';
+}
 /**
  * Inline-structure sync highlight for embedders that own the `<pre>` chrome
  * (markdown-it fence callback in the document pipeline). Returns the token

package/package.json

@@ -1,13 +1,15 @@
 {
   "dependencies": {
-    "@vmz/plugin": "0.3.13"
+    "@vmz/plugin": "0.3.15"
   },
   "description": "VMZ Shiki adapter - <Shiki> + code engine registration",
   "devDependencies": {
+    "@shikijs/langs": "^3.23.0",
+    "@shikijs/themes": "^3.23.0",
     "@types/node": "^22.15.0",
     "shiki": "^3.12.2",
     "typescript": "^5.8.3",
-    "vmz-textmate": "0.3.13"
+    "vmz-textmate": "0.3.15"
   },
   "engines": {
     "node": ">=24.12.0"
@@ -37,6 +39,8 @@
   "main": "./dist/vmz.plugin.js",
   "name": "@vmz/plugin-shiki",
   "peerDependencies": {
+    "@shikijs/langs": ">=3",
+    "@shikijs/themes": ">=3",
     "shiki": ">=3"
   },
   "publishConfig": {
@@ -52,5 +56,5 @@
   },
   "type": "module",
   "types": "./dist/vmz.plugin.d.ts",
-  "version": "0.3.13"
+  "version": "0.3.15"
 }