@vmz/plugin-shiki 0.3.14 → 0.3.15

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

@@ -39,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

@@ -218,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),
@@ -230,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,6 +1,6 @@
 {
   "dependencies": {
-    "@vmz/plugin": "0.3.14"
+    "@vmz/plugin": "0.3.15"
   },
   "description": "VMZ Shiki adapter - <Shiki> + code engine registration",
   "devDependencies": {
@@ -9,7 +9,7 @@
     "@types/node": "^22.15.0",
     "shiki": "^3.12.2",
     "typescript": "^5.8.3",
-    "vmz-textmate": "0.3.14"
+    "vmz-textmate": "0.3.15"
   },
   "engines": {
     "node": ">=24.12.0"
@@ -56,5 +56,5 @@
   },
   "type": "module",
   "types": "./dist/vmz.plugin.d.ts",
-  "version": "0.3.14"
+  "version": "0.3.15"
 }