@vmz/plugin-katex 0.0.1 → 0.0.3

package/README.md

@@ -1,3 +1,37 @@
 # @vmz/plugin-katex
 
-Placeholder package (0.0.1). Reserved for the VMZ project.
+## Fast mathematical typesetting for VMZ documents and products
+
+`@vmz/plugin-katex` brings KaTeX into VMZ for applications that need clear, high-quality formulas without making
+mathematics a heavy client-side feature. It is the default choice for most technical documentation, educational content,
+dashboards, and product UI that renders common TeX notation.
+
+## Why choose KaTeX
+
+KaTeX prioritizes speed and compact output. That makes it well suited to VMZ's SSR-first and progressive-interaction
+direction: formulas can be part of the readable page rather than a reason to delay content behind a large browser
+dependency.
+
+Choose this plugin when your content uses mainstream TeX and you value predictable, lightweight rendering. Choose
+`@vmz/plugin-mathjax` instead when the breadth of TeX compatibility matters more than payload and execution cost.
+
+| Choose KaTeX when...                                   | Choose MathJax when...                                 |
+|--------------------------------------------------------|--------------------------------------------------------|
+| Fast, common formula rendering is the priority         | Advanced TeX compatibility is the priority             |
+| Documentation and product pages need a lighter default | The mathematical surface is central and more demanding |
+
+## VMZ boundary
+
+KaTeX supplies typesetting. VMZ still owns application compilation, document structure, server rendering, testing, and
+deployment. Using formulas should not create a separate rendering or state model inside the application.
+
+## Where it shines ✨
+
+- API references that include mathematical notation.
+- Educational products with many short formulas.
+- Technical articles that must remain readable in SSR output.
+- Dashboards and scientific tools where formulas support, rather than dominate, the interface.
+
+KaTeX keeps the common path simple: polished mathematics without turning an otherwise lightweight page into a
+mathematics runtime. Start here when you are unsure; move to MathJax when a real content requirement exceeds its
+coverage.

package/components/Katex.vmz

@@ -0,0 +1,23 @@
+<template>
+  <div class="katex-host" html={format(tex, display)}></div>
+</template>
+
+<script client>
+import katex from 'katex';
+
+function format(tex, display) {
+  try {
+    return katex.renderToString(tex ?? '', {
+      displayMode: !!display,
+      throwOnError: false,
+    });
+  } catch {
+    return '';
+  }
+}
+
+export default class Katex {
+  public tex: string = '';
+  public display: boolean = false;
+}
+</script>

package/package.json

@@ -1,12 +1,41 @@
 {
   "name": "@vmz/plugin-katex",
-  "version": "0.0.1",
-  "description": "VMZ placeholder 鈥?not for production use.",
+  "version": "0.0.3",
+  "type": "module",
+  "description": "VMZ KaTeX adapter - <Katex> + math 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": {
+    "katex": ">=0.16"
+  },
+  "peerDependenciesMeta": {
+    "katex": {
+      "optional": false
+    }
+  },
+  "keywords": [
+    "vmz",
+    "plugin",
+    "katex",
+    "math"
   ],
+  "publishConfig": {
+    "access": "public"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/doki-land/vmz-framework.git"

package/runtime.ts

@@ -0,0 +1,10 @@
+/** Optional helpers for apps that want KaTeX outside the materialized component. */
+
+export async function renderKatex(tex: string, display = false): Promise<string> {
+    const mod = await import('katex');
+    const katex = mod.default ?? mod;
+    return katex.renderToString(tex ?? '', {
+        displayMode: !!display,
+        throwOnError: false,
+    });
+}

package/vmz.plugin.ts

@@ -0,0 +1,50 @@
+import { definePlugin, loadPluginSource } from '@vmz/plugin';
+
+const source = loadPluginSource(import.meta.url, 'components/Katex.vmz');
+
+export default definePlugin({
+    name: '@vmz/plugin-katex',
+    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-katex:Katex.vmz:${source.contentHash.slice(0, 12)}`,
+                items: [
+                    {
+                        id: 'component-katex',
+                        kind: 'source',
+                        path: 'src/components/Katex.vmz',
+                        content: source.content,
+                        contentHash: source.contentHash,
+                        materialize: true,
+                        engine: 'katex',
+                        engineKind: 'math',
+                    },
+                ],
+            };
+        }
+        if (ctx.stage === 'analyzer') {
+            return {
+                stage: 'analyzer',
+                cacheKey: '@vmz/plugin-katex:analyzer',
+                items: [
+                    {
+                        id: 'engine-katex',
+                        kind: 'analyzer',
+                        path: 'src/components/Katex.vmz',
+                        severity: 'advice',
+                        message: 'math engine katex online',
+                        code: 'vmz.engine.katex',
+                        engine: 'katex',
+                        engineKind: 'math',
+                    },
+                ],
+            };
+        }
+        return { stage: ctx.stage, items: [] };
+    },
+});