@vmz/plugin-shiki 0.3.11 → 0.3.13

package/README.md

@@ -31,12 +31,13 @@ bundled dependency, so install it alongside the plugin:
 pnpm add @vmz/plugin-shiki shiki
 ```
 
-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 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.
 
 ## 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 +48,9 @@ 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`.
+
 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

@@ -4,9 +4,14 @@
  */
 import type { Highlighter } 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'>;
@@ -21,7 +26,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 {
@@ -102,8 +124,11 @@ async function loadTextmateHighlighter(themes) {
     return null;
 }
 async function loadGenericHighlighter(themes) {
-    const genericPackage = 'shiki';
-    const { createHighlighter } = await import(genericPackage);
+    // Literal specifier 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'],
@@ -116,19 +141,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 +172,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 +186,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,13 @@
 {
   "dependencies": {
-    "@vmz/plugin": "0.3.11"
+    "@vmz/plugin": "0.3.13"
   },
   "description": "VMZ Shiki adapter - <Shiki> + code engine registration",
   "devDependencies": {
     "@types/node": "^22.15.0",
     "shiki": "^3.12.2",
     "typescript": "^5.8.3",
-    "vmz-textmate": "0.3.11"
+    "vmz-textmate": "0.3.13"
   },
   "engines": {
     "node": ">=24.12.0"
@@ -37,16 +37,7 @@
   "main": "./dist/vmz.plugin.js",
   "name": "@vmz/plugin-shiki",
   "peerDependencies": {
-    "shiki": ">=3",
-    "vmz-textmate": "*"
-  },
-  "peerDependenciesMeta": {
-    "shiki": {
-      "optional": false
-    },
-    "vmz-textmate": {
-      "optional": true
-    }
+    "shiki": ">=3"
   },
   "publishConfig": {
     "access": "public"
@@ -61,5 +52,5 @@
   },
   "type": "module",
   "types": "./dist/vmz.plugin.d.ts",
-  "version": "0.3.11"
+  "version": "0.3.13"
 }