@vmz/plugin-shiki 0.1.10 → 0.1.12

package/README.md

@@ -22,6 +22,21 @@ It is especially useful for:
 - tutorials that move between prose and real VMZ components;
 - source browsers that need trustworthy language presentation.
 
+## Third-party TextMate grammar (VMZ-2)
+
+By default the runtime loads `vmz-textmate/shiki`. For other languages (e.g. VOS), pass a peer adapter:
+
+```ts
+import shiki from '@vmz/plugin-shiki';
+
+export default defineConfig({
+  plugins: [shiki({ textmate: '@game-gpt/vos-textmate/shiki' })],
+  engines: { code: '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
 
 Shiki owns source presentation. VMZ owns document structure, SSR, optional interaction, testing, and delivery. The

package/dist/runtime.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Shiki highlight helper — async with optional sync cache after prewarm.
+ * TextMate grammar via configurable peer (default `vmz-textmate/shiki`).
+ */
+import type { Highlighter } from 'shiki';
+export type ShikiRuntimeConfig = {
+    /** Shiki + TextMate adapter module (default `vmz-textmate/shiki`). */
+    textmate?: string;
+    /** Default themes passed to the textmate highlighter factory. */
+    themes?: string[];
+};
+/** @internal test hook */
+export declare function getShikiRuntimeConfig(): Readonly<ShikiRuntimeConfig>;
+/** Reset module state (tests). */
+export declare function resetShikiRuntimeForTests(): void;
+/**
+ * Configure runtime before highlight (also called by `shiki()` plugin factory).
+ */
+export declare function configureShiki(opts: ShikiRuntimeConfig): void;
+export declare function prewarmShiki(opts?: {
+    themes?: string[];
+}): Promise<Highlighter>;
+export declare function highlight(code: string, lang?: string, theme?: string): Promise<string>;
+/** Sync highlight when prewarmed; otherwise escaped `<pre><code>`. */
+export declare function highlightSync(code: string, lang?: string, theme?: string): string;

package/dist/runtime.js

@@ -0,0 +1,147 @@
+/**
+ * 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';
+let config = {};
+let configResolved = false;
+let cached = null;
+let pending = null;
+/** @internal test hook */
+export function getShikiRuntimeConfig() {
+    return config;
+}
+/** Reset module state (tests). */
+export function resetShikiRuntimeForTests() {
+    config = {};
+    configResolved = false;
+    cached = null;
+    pending = null;
+}
+/**
+ * Configure runtime before highlight (also called by `shiki()` plugin factory).
+ */
+export function configureShiki(opts) {
+    if (opts.textmate)
+        config.textmate = opts.textmate;
+    if (opts.themes?.length)
+        config.themes = [...opts.themes];
+    configResolved = Boolean(opts.textmate);
+    cached = null;
+    pending = null;
+}
+async function resolveRuntimeConfig() {
+    if (configResolved)
+        return;
+    const globalCfg = globalThis.__vmzPluginShiki;
+    if (globalCfg?.textmate) {
+        config.textmate = globalCfg.textmate;
+        if (globalCfg.themes?.length)
+            config.themes = [...globalCfg.themes];
+        configResolved = true;
+        return;
+    }
+    try {
+        if (typeof fetch === 'function') {
+            const res = await fetch('/_vmz/plugin-shiki.config.json', { cache: 'no-store' });
+            if (res.ok) {
+                const parsed = (await res.json());
+                if (parsed.textmate)
+                    config.textmate = parsed.textmate;
+                if (parsed.themes?.length)
+                    config.themes = [...parsed.themes];
+            }
+        }
+    }
+    catch {
+        /* optional sidecar */
+    }
+    try {
+        const dist = typeof process !== 'undefined' ? process.env.VMZ_DIST : undefined;
+        if (dist) {
+            const { readFile } = await import('node:fs/promises');
+            const { join } = await import('node:path');
+            const raw = await readFile(join(dist, '_vmz', 'plugin-shiki.config.json'), 'utf8');
+            const parsed = JSON.parse(raw);
+            if (parsed.textmate)
+                config.textmate = parsed.textmate;
+            if (parsed.themes?.length)
+                config.themes = [...parsed.themes];
+        }
+    }
+    catch {
+        /* optional sidecar */
+    }
+    configResolved = true;
+}
+function textmateSpec() {
+    return config.textmate || DEFAULT_TEXTMATE;
+}
+async function loadTextmateHighlighter(themes) {
+    const spec = textmateSpec();
+    try {
+        const mod = (await import(/* webpackIgnore: true */ spec));
+        const factory = mod.createVmzHighlighter ?? mod.createHighlighter ?? mod.default?.createVmzHighlighter;
+        if (typeof factory === 'function') {
+            return factory({ themes, langs: [] });
+        }
+    }
+    catch {
+        /* try generic shiki below */
+    }
+    return null;
+}
+async function loadGenericHighlighter(themes) {
+    const { createHighlighter } = await import('shiki');
+    return createHighlighter({
+        themes,
+        langs: ['javascript', 'typescript', 'tsx', 'jsx', 'json', 'html', 'css', 'markdown', 'bash', 'text'],
+    });
+}
+export async function prewarmShiki(opts = {}) {
+    if (cached)
+        return cached;
+    if (pending)
+        return pending;
+    pending = (async () => {
+        await resolveRuntimeConfig();
+        const themes = opts.themes?.length ? opts.themes : config.themes?.length ? config.themes : ['vitesse-dark'];
+        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] });
+    try {
+        return highlighter.codeToHtml(code ?? '', {
+            lang: lang || 'text',
+            theme,
+        });
+    }
+    catch {
+        return fallbackPre(code);
+    }
+}
+/** Sync highlight when prewarmed; otherwise escaped `<pre><code>`. */
+export function highlightSync(code, lang = 'text', theme = 'vitesse-dark') {
+    if (!cached)
+        return fallbackPre(code);
+    try {
+        return cached.codeToHtml(code ?? '', {
+            lang: lang || 'text',
+            theme,
+        });
+    }
+    catch {
+        return fallbackPre(code);
+    }
+}
+function fallbackPre(code) {
+    const escaped = String(code ?? '')
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;');
+    return `<pre class="shiki shiki-fallback"><code>${escaped}</code></pre>`;
+}

package/dist/vmz.plugin.d.ts

@@ -0,0 +1,23 @@
+export type ShikiPluginOptions = {
+    /**
+     * TextMate Shiki adapter module id.
+     * Default `vmz-textmate/shiki`; VOS uses `@game-gpt/vos-textmate/shiki`.
+     */
+    textmate?: string;
+    /** Default Shiki themes for prewarm. */
+    themes?: string[];
+};
+/**
+ * VMZ Shiki plugin factory — register `<Shiki>` + `engines.code`.
+ *
+ * @example
+ * ```ts
+ * import shiki from '@vmz/plugin-shiki';
+ * export default defineConfig({
+ *   plugins: [shiki({ textmate: '@game-gpt/vos-textmate/shiki' })],
+ *   engines: { code: 'shiki' },
+ * });
+ * ```
+ */
+export declare function shiki(options?: ShikiPluginOptions): import("@vmz/plugin").VmzPlugin;
+export default shiki;

package/dist/vmz.plugin.js

@@ -0,0 +1,82 @@
+import { mkdirSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { definePlugin, loadPluginSource } from '@vmz/plugin';
+import { configureShiki } 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.themes?.length ? { themes: opts.themes } : {}),
+    };
+    const dir = path.join(outDir, '_vmz');
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(path.join(dir, 'plugin-shiki.config.json'), `${JSON.stringify(payload, null, 2)}\n`, 'utf8');
+}
+/**
+ * VMZ Shiki plugin factory — register `<Shiki>` + `engines.code`.
+ *
+ * @example
+ * ```ts
+ * import shiki from '@vmz/plugin-shiki';
+ * export default defineConfig({
+ *   plugins: [shiki({ textmate: '@game-gpt/vos-textmate/shiki' })],
+ *   engines: { code: 'shiki' },
+ * });
+ * ```
+ */
+export function shiki(options = {}) {
+    configureShiki({
+        textmate: options.textmate ?? DEFAULT_TEXTMATE,
+        themes: options.themes,
+    });
+    return definePlugin({
+        name: '@vmz/plugin-shiki',
+        version: '0.1.0',
+        protocol: '0.1.0',
+        stages: ['workspace_resolve', 'analyzer'],
+        deterministic: true,
+        async contribute(ctx) {
+            if (ctx.stage === 'workspace_resolve') {
+                writeRuntimeSidecar(ctx.outDir, options);
+                return {
+                    stage: 'workspace_resolve',
+                    cacheKey: `@vmz/plugin-shiki:Shiki.vmz:${source.contentHash.slice(0, 12)}:${options.textmate ?? DEFAULT_TEXTMATE}`,
+                    items: [
+                        {
+                            id: 'component-shiki',
+                            kind: 'source',
+                            path: 'src/components/Shiki.vmz',
+                            content: source.content,
+                            contentHash: source.contentHash,
+                            materialize: true,
+                            engine: 'shiki',
+                            engineKind: 'code',
+                        },
+                    ],
+                };
+            }
+            if (ctx.stage === 'analyzer') {
+                return {
+                    stage: 'analyzer',
+                    cacheKey: '@vmz/plugin-shiki:analyzer',
+                    items: [
+                        {
+                            id: 'engine-shiki',
+                            kind: 'analyzer',
+                            path: 'src/components/Shiki.vmz',
+                            severity: 'advice',
+                            message: 'code engine shiki online',
+                            code: 'vmz.engine.shiki',
+                            engine: 'shiki',
+                            engineKind: 'code',
+                        },
+                    ],
+                };
+            }
+            return { stage: ctx.stage, items: [] };
+        },
+    });
+}
+export default shiki;

package/package.json

@@ -1,27 +1,35 @@
 {
   "name": "@vmz/plugin-shiki",
-  "version": "0.1.10",
+  "version": "0.1.12",
   "type": "module",
   "description": "VMZ Shiki adapter - <Shiki> + code engine registration",
   "license": "MIT",
-  "main": "./vmz.plugin.ts",
-  "types": "./vmz.plugin.ts",
+  "main": "./dist/vmz.plugin.js",
+  "types": "./dist/vmz.plugin.d.ts",
   "exports": {
     ".": {
-      "types": "./vmz.plugin.ts",
-      "default": "./vmz.plugin.ts"
+      "types": "./dist/vmz.plugin.d.ts",
+      "default": "./dist/vmz.plugin.js"
     },
     "./runtime": {
-      "types": "./runtime.ts",
-      "default": "./runtime.ts"
+      "types": "./dist/runtime.d.ts",
+      "default": "./dist/runtime.js"
     }
   },
+  "files": [
+    "dist",
+    "components",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json"
+  },
   "dependencies": {
-    "@vmz/plugin": "0.1.10"
+    "@vmz/plugin": "0.1.12"
   },
   "peerDependencies": {
     "shiki": ">=3",
-    "vmz-textmate": "0.1.10"
+    "vmz-textmate": "0.1.12"
   },
   "peerDependenciesMeta": {
     "shiki": {

package/runtime.ts

@@ -1,62 +0,0 @@
-/**
- * Shiki highlight helper — async with optional sync cache after prewarm.
- * For `lang === 'vmz'`, prefers `vmz-textmate/shiki` when available.
- */
-
-import type { Highlighter } from 'shiki';
-
-let cached: Highlighter | null = null;
-let pending: Promise<Highlighter> | null = null;
-
-export async function prewarmShiki(opts: { themes?: string[] } = {}): Promise<Highlighter> {
-    if (cached) return cached;
-    if (pending) return pending;
-    pending = (async () => {
-        const themes = opts.themes?.length ? opts.themes : ['vitesse-dark'];
-        try {
-            const { createVmzHighlighter } = await import('vmz-textmate/shiki');
-            cached = await createVmzHighlighter({ themes });
-        } catch {
-            const { createHighlighter } = await import('shiki');
-            cached = await createHighlighter({
-                themes,
-                langs: ['javascript', 'typescript', 'tsx', 'jsx', 'json', 'html', 'css', 'markdown', 'bash'],
-            });
-        }
-        return cached!;
-    })();
-    return pending;
-}
-
-export async function highlight(code: string, lang = 'text', theme = 'vitesse-dark'): Promise<string> {
-    const highlighter = await prewarmShiki({ themes: [theme] });
-    try {
-        return highlighter.codeToHtml(code ?? '', {
-            lang: lang || 'text',
-            theme,
-        });
-    } catch {
-        return fallbackPre(code);
-    }
-}
-
-/** Sync highlight when prewarmed; otherwise escaped `<pre><code>`. */
-export function highlightSync(code: string, lang = 'text', theme = 'vitesse-dark'): string {
-    if (!cached) return fallbackPre(code);
-    try {
-        return cached.codeToHtml(code ?? '', {
-            lang: lang || 'text',
-            theme,
-        });
-    } catch {
-        return fallbackPre(code);
-    }
-}
-
-function fallbackPre(code: string): string {
-    const escaped = String(code ?? '')
-        .replace(/&/g, '&amp;')
-        .replace(/</g, '&lt;')
-        .replace(/>/g, '&gt;');
-    return `<pre class="shiki shiki-fallback"><code>${escaped}</code></pre>`;
-}

package/vmz.plugin.ts

@@ -1,50 +0,0 @@
-import { definePlugin, loadPluginSource } from '@vmz/plugin';
-
-const source = loadPluginSource(import.meta.url, 'components/Shiki.vmz');
-
-export default definePlugin({
-    name: '@vmz/plugin-shiki',
-    version: '0.1.0',
-    protocol: '0.1.0',
-    stages: ['workspace_resolve', 'analyzer'],
-    deterministic: true,
-    async contribute(ctx) {
-        if (ctx.stage === 'workspace_resolve') {
-            return {
-                stage: 'workspace_resolve',
-                cacheKey: `@vmz/plugin-shiki:Shiki.vmz:${source.contentHash.slice(0, 12)}`,
-                items: [
-                    {
-                        id: 'component-shiki',
-                        kind: 'source',
-                        path: 'src/components/Shiki.vmz',
-                        content: source.content,
-                        contentHash: source.contentHash,
-                        materialize: true,
-                        engine: 'shiki',
-                        engineKind: 'code',
-                    },
-                ],
-            };
-        }
-        if (ctx.stage === 'analyzer') {
-            return {
-                stage: 'analyzer',
-                cacheKey: '@vmz/plugin-shiki:analyzer',
-                items: [
-                    {
-                        id: 'engine-shiki',
-                        kind: 'analyzer',
-                        path: 'src/components/Shiki.vmz',
-                        severity: 'advice',
-                        message: 'code engine shiki online',
-                        code: 'vmz.engine.shiki',
-                        engine: 'shiki',
-                        engineKind: 'code',
-                    },
-                ],
-            };
-        }
-        return { stage: ctx.stage, items: [] };
-    },
-});