@vmz/plugin-shiki 0.3.12 → 0.3.14

package/README.md

@@ -24,19 +24,23 @@ 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 default `vmz-textmate/shiki` path also needs `shiki/core`; installing `@shikijs/*` transitively through
-`vmz-textmate` 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)
 
-By default the runtime loads `vmz-textmate/shiki`. For other languages (e.g. VOS), pass a peer adapter:
+Custom grammars (VMZ, VOS, …) come from an explicit adapter module id that the host must resolve:
 
 ```ts
 import shiki from '@vmz/plugin-shiki';
@@ -47,6 +51,10 @@ 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 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`).
 
 ## VMZ boundary

package/dist/runtime.d.ts

@@ -2,14 +2,31 @@
  * 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 = {
-    /** Shiki + TextMate adapter module (default `vmz-textmate/shiki`). */
+    /**
+     * TextMate Shiki adapter module id (e.g. `vmz-textmate/shiki`). Explicit
+     * opt-in: the adapter package is host-visible (not an npm dependency of
+     * this plugin), so the host must guarantee resolvability — serve-host
+     * resolve hooks on Node, an import map or vendor copy in the browser.
+     */
     textmate?: string;
-    /** Default themes passed to the textmate highlighter factory. */
+    /** 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). */
@@ -21,7 +38,14 @@ export declare function configureShiki(opts: ShikiRuntimeConfig): void;
 export declare function prewarmShiki(opts?: {
     themes?: string[];
 }): Promise<CodeHighlighter>;
-export declare function highlight(code: string, lang?: string, theme?: string): Promise<string>;
+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): string;
+export declare function highlightSync(code: string, lang?: string, theme?: string | null): string;
+/**
+ * Inline-structure sync highlight for embedders that own the `<pre>` chrome
+ * (markdown-it fence callback in the document pipeline). Returns the token
+ * spans only — no `<pre>` wrapper, no inline background. Empty string when no
+ * highlighter is prewarmed so the embedder can fall back to escaped code.
+ */
+export declare function highlightInline(code: string, lang?: string, theme?: string | null): string;
 export {};

package/dist/runtime.js

@@ -2,7 +2,22 @@
  * Shiki highlight helper — async with optional sync cache after prewarm.
  * TextMate grammar via configurable peer (default `vmz-textmate/shiki`).
  */
-const DEFAULT_TEXTMATE = 'vmz-textmate/shiki';
+const DEFAULT_THEME = 'vitesse-dark';
+const DEFAULT_LANG = 'text';
+/**
+ * Component props are nullable (`theme: string | null = null`) and a bound
+ * `null` overrides the prop default in the compiled component, so runtime
+ * entry points normalize before touching Shiki: `createHighlighter` rejects
+ * falsy theme/lang getters deep inside `@shikijs/core` (`normalizeGetter`
+ * dereferences the resolved module), which used to surface as a page-level
+ * SSR failure.
+ */
+function normalizeTheme(theme) {
+    return typeof theme === 'string' && theme.trim() ? theme : DEFAULT_THEME;
+}
+function normalizeLang(lang) {
+    return typeof lang === 'string' && lang.trim() ? lang : DEFAULT_LANG;
+}
 /**
  * Shiki writes `background-color` and `color` inline on `<pre>`, which makes
  * the site stylesheet need `!important` to own code surfaces. Strip that
@@ -85,15 +100,22 @@ async function resolveRuntimeConfig() {
     configResolved = true;
 }
 function textmateSpec() {
-    return config.textmate || DEFAULT_TEXTMATE;
+    return config.textmate || null;
 }
 async function loadTextmateHighlighter(themes) {
     const spec = textmateSpec();
+    if (!spec)
+        return null;
     try {
-        const mod = (spec === DEFAULT_TEXTMATE ? await import('vmz-textmate/shiki') : await import(/* webpackIgnore: true */ spec));
+        // The textmate adapter is an explicit opt-in module id resolved by the
+        // host (serve-host resolve hooks, import map), never vendored by pack —
+        // the generic path below is the pack-visible default.
+        const mod = (await import(/* webpackIgnore: true */ spec));
         const factory = mod.createVmzHighlighter ?? mod.createHighlighter ?? mod.default?.createVmzHighlighter;
         if (typeof factory === 'function') {
-            return factory({ themes, langs: [] });
+            // `return await` (not `return`): a rejected factory promise must be
+            // caught here so the generic Shiki path below still runs.
+            return await factory({ themes, langs: [] });
         }
     }
     catch {
@@ -101,12 +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) {
-    const genericPackage = 'shiki';
-    const { createHighlighter } = await import(genericPackage);
-    return createHighlighter({
-        themes,
-        langs: ['javascript', 'typescript', 'tsx', 'jsx', 'json', 'html', 'css', 'markdown', 'bash', 'text'],
+    // 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.
+    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 = {}) {
@@ -116,19 +188,29 @@ export async function prewarmShiki(opts = {}) {
         return pending;
     pending = (async () => {
         await resolveRuntimeConfig();
-        const themes = opts.themes?.length ? opts.themes : config.themes?.length ? config.themes : ['vitesse-dark'];
+        const requested = opts.themes?.length ? opts.themes : config.themes?.length ? config.themes : [DEFAULT_THEME];
+        const themes = requested.map((theme) => normalizeTheme(theme));
         const fromTextmate = await loadTextmateHighlighter(themes);
         cached = fromTextmate ?? (await loadGenericHighlighter(themes));
         return cached;
     })();
     return pending;
 }
-export async function highlight(code, lang = 'text', theme = 'vitesse-dark') {
-    const highlighter = await prewarmShiki({ themes: [theme] });
+export async function highlight(code, lang = 'text', theme = DEFAULT_THEME) {
+    const safeTheme = normalizeTheme(theme);
+    const safeLang = normalizeLang(lang);
+    let highlighter;
+    try {
+        highlighter = await prewarmShiki({ themes: [safeTheme] });
+    }
+    catch {
+        // Highlighter bootstrap failure must not take the page down.
+        return fallbackPre(code);
+    }
     try {
         return highlighter.codeToHtml(code ?? '', {
-            lang: lang || 'text',
-            theme,
+            lang: safeLang,
+            theme: safeTheme,
             transformers: [stripPreInlineStyle],
         });
     }
@@ -137,13 +219,13 @@ export async function highlight(code, lang = 'text', theme = 'vitesse-dark') {
     }
 }
 /** Sync highlight when prewarmed; otherwise escaped `<pre><code>`. */
-export function highlightSync(code, lang = 'text', theme = 'vitesse-dark') {
+export function highlightSync(code, lang = 'text', theme = DEFAULT_THEME) {
     if (!cached)
         return fallbackPre(code);
     try {
         return cached.codeToHtml(code ?? '', {
-            lang: lang || 'text',
-            theme,
+            lang: normalizeLang(lang),
+            theme: normalizeTheme(theme),
             transformers: [stripPreInlineStyle],
         });
     }
@@ -151,6 +233,27 @@ export function highlightSync(code, lang = 'text', theme = 'vitesse-dark') {
         return fallbackPre(code);
     }
 }
+/**
+ * Inline-structure sync highlight for embedders that own the `<pre>` chrome
+ * (markdown-it fence callback in the document pipeline). Returns the token
+ * spans only — no `<pre>` wrapper, no inline background. Empty string when no
+ * highlighter is prewarmed so the embedder can fall back to escaped code.
+ */
+export function highlightInline(code, lang = 'text', theme = DEFAULT_THEME) {
+    if (!cached)
+        return '';
+    try {
+        return cached.codeToHtml(code ?? '', {
+            lang: normalizeLang(lang),
+            theme: normalizeTheme(theme),
+            structure: 'inline',
+            transformers: [stripPreInlineStyle],
+        });
+    }
+    catch {
+        return '';
+    }
+}
 function fallbackPre(code) {
     const escaped = String(code ?? '')
         .replace(/&/g, '&amp;')

package/dist/vmz.plugin.d.ts

@@ -1,7 +1,8 @@
 export type ShikiPluginOptions = {
     /**
-     * TextMate Shiki adapter module id.
-     * Default `vmz-textmate/shiki`; VOS uses `@game-gpt/vos-textmate/shiki`.
+     * TextMate Shiki adapter module id (e.g. `vmz-textmate/shiki`). Explicit
+     * opt-in: the host must resolve this specifier (it is not an npm
+     * dependency of the plugin). Omit it to use the plain Shiki path.
      */
     textmate?: string;
     /** Default Shiki themes for prewarm. */

package/dist/vmz.plugin.js

@@ -1,13 +1,11 @@
 import { mkdirSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
 import { definePlugin, loadPluginSource } from '@vmz/plugin';
-import { configureShiki } from './runtime.js';
+import { configureShiki, prewarmShiki } from './runtime.js';
 const source = loadPluginSource(import.meta.url, '../components/Shiki.vmz');
-const DEFAULT_TEXTMATE = 'vmz-textmate/shiki';
 function writeRuntimeSidecar(outDir, opts) {
-    const textmate = opts.textmate ?? DEFAULT_TEXTMATE;
     const payload = {
-        textmate,
+        ...(opts.textmate ? { textmate: opts.textmate } : {}),
         ...(opts.themes?.length ? { themes: opts.themes } : {}),
     };
     const dir = path.join(outDir, '_vmz');
@@ -28,9 +26,14 @@ function writeRuntimeSidecar(outDir, opts) {
  */
 export function shiki(options = {}) {
     configureShiki({
-        textmate: options.textmate ?? DEFAULT_TEXTMATE,
+        textmate: options.textmate,
         themes: options.themes,
     });
+    // Warm the highlighter at config-load time (the same process later runs the
+    // document pipeline and page SSR), so `highlightSync` hits the cache during
+    // SSR and the first paint already carries the final tokenized markup — no
+    // unhighlighted fallback flash. Bootstrap failure degrades to plain fences.
+    void prewarmShiki({ themes: options.themes }).catch(() => { });
     return definePlugin({
         name: '@vmz/plugin-shiki',
         version: '0.1.0',
@@ -42,7 +45,7 @@ export function shiki(options = {}) {
                 writeRuntimeSidecar(ctx.outDir, options);
                 return {
                     stage: 'workspace_resolve',
-                    cacheKey: `@vmz/plugin-shiki:Shiki.vmz:${source.contentHash.slice(0, 12)}:${options.textmate ?? DEFAULT_TEXTMATE}`,
+                    cacheKey: `@vmz/plugin-shiki:Shiki.vmz:${source.contentHash.slice(0, 12)}:${options.textmate ?? 'generic'}`,
                     items: [
                         {
                             id: 'component-shiki',

package/package.json

@@ -1,13 +1,15 @@
 {
   "dependencies": {
-    "@vmz/plugin": "0.3.12"
+    "@vmz/plugin": "0.3.14"
   },
   "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.12"
+    "vmz-textmate": "0.3.14"
   },
   "engines": {
     "node": ">=24.12.0"
@@ -37,16 +39,9 @@
   "main": "./dist/vmz.plugin.js",
   "name": "@vmz/plugin-shiki",
   "peerDependencies": {
-    "shiki": ">=3",
-    "vmz-textmate": "*"
-  },
-  "peerDependenciesMeta": {
-    "shiki": {
-      "optional": false
-    },
-    "vmz-textmate": {
-      "optional": true
-    }
+    "@shikijs/langs": ">=3",
+    "@shikijs/themes": ">=3",
+    "shiki": ">=3"
   },
   "publishConfig": {
     "access": "public"
@@ -61,5 +56,5 @@
   },
   "type": "module",
   "types": "./dist/vmz.plugin.d.ts",
-  "version": "0.3.12"
+  "version": "0.3.14"
 }