@vmz/plugin-shiki 0.0.1 → 0.0.3

package/README.md

@@ -1,3 +1,38 @@
 # @vmz/plugin-shiki
 
-Placeholder package (0.0.1). Reserved for the VMZ project.
+## Code examples that are part of the reading experience
+
+`@vmz/plugin-shiki` brings Shiki's high-quality syntax highlighting to VMZ applications. It is designed for guides, API
+reference, technical blogs, source browsers, tutorials, and any product surface where code is meant to be read
+carefully.
+
+## Why Shiki fits VMZ documents
+
+Code snippets should remain useful before a page becomes interactive. Shiki supports a content-first experience: source
+can be highlighted as part of the rendered document instead of relying on a browser-only code viewer to make a page
+readable.
+
+For VMZ examples, the plugin can share the same language presentation used by VMZ editor tooling. That consistency helps
+readers move from documentation to a real `.vmz` file without relearning the visual grammar.
+
+It is especially useful for:
+
+- product documentation that must be readable before interaction starts;
+- API and configuration references where source is the main content;
+- tutorials that move between prose and real VMZ components;
+- source browsers that need trustworthy language presentation.
+
+## VMZ boundary
+
+Shiki owns source presentation. VMZ owns document structure, SSR, optional interaction, testing, and delivery. The
+plugin should make code easier to understand without becoming a parallel application runtime.
+
+## A content-first feature set 🎨
+
+- **Readable SSR:** highlighted source can arrive with the page instead of flashing into place later.
+- **VMZ consistency:** examples can share the grammar readers see in their editor.
+- **Theme-aware presentation:** technical content can belong to the surrounding design.
+- **Graceful fallback:** source remains readable when rich highlighting is unavailable.
+
+Use Shiki where code itself is part of the product. If users are meant to edit the code, pair the reading experience
+with CodeMirror or Monaco rather than stretching a highlighter into an editor.

package/components/Shiki.vmz

@@ -0,0 +1,20 @@
+<template>
+  <div class="shiki-host" html={html != null ? html : highlightSync(code, lang, theme)}></div>
+</template>
+
+<script client>
+import { highlight, highlightSync } from '@vmz/plugin-shiki/runtime';
+
+export default class Shiki {
+  public code: string = '';
+  public lang: string = 'text';
+  public theme: string = 'vitesse-dark';
+
+  /** null → sync fallback / prewarm cache; set after async highlight. */
+  html: string | null = null;
+
+  async onMount() {
+    this.html = await highlight(this.code, this.lang, this.theme);
+  }
+}
+</script>

package/package.json

@@ -1,12 +1,45 @@
 {
   "name": "@vmz/plugin-shiki",
-  "version": "0.0.1",
-  "description": "VMZ placeholder 鈥?not for production use.",
+  "version": "0.0.3",
+  "type": "module",
+  "description": "VMZ Shiki adapter - <Shiki> + code engine registration",
   "license": "MIT",
-  "private": false,
-  "files": [
-    "README.md"
+  "main": "./vmz.plugin.ts",
+  "types": "./vmz.plugin.ts",
+  "exports": {
+    ".": {
+      "types": "./vmz.plugin.ts",
+      "default": "./vmz.plugin.ts"
+    },
+    "./runtime": {
+      "types": "./runtime.ts",
+      "default": "./runtime.ts"
+    }
+  },
+  "dependencies": {
+    "@vmz/plugin": "0.0.3"
+  },
+  "peerDependencies": {
+    "shiki": ">=3",
+    "vmz-textmate": "0.0.3"
+  },
+  "peerDependenciesMeta": {
+    "shiki": {
+      "optional": false
+    },
+    "vmz-textmate": {
+      "optional": true
+    }
+  },
+  "keywords": [
+    "vmz",
+    "plugin",
+    "shiki",
+    "code"
   ],
+  "publishConfig": {
+    "access": "public"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/doki-land/vmz-framework.git"

package/runtime.ts

@@ -0,0 +1,62 @@
+/**
+ * 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

@@ -0,0 +1,50 @@
+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: [] };
+    },
+});