@k-l-lambda/lilylet-markdown 0.1.19

package/README.md

@@ -0,0 +1,145 @@
+# lilylet-markdown
+
+A [markdown-it](https://github.com/markdown-it/markdown-it) plugin for rendering [Lilylet](https://github.com/k-l-lambda/lilylet) music notation in Markdown.
+
+## Features
+
+- Render Lilylet notation in fenced code blocks
+- Server-side SVG rendering with Verovio
+- Client-side rendering support (placeholder mode)
+- Supports `lilylet` and `lyl` language aliases
+
+## Installation
+
+```bash
+npm install @k-l-lambda/lilylet-markdown
+```
+
+## Usage
+
+### Basic Usage (Placeholder Mode)
+
+When no Verovio toolkit is provided, the plugin outputs placeholders with embedded MEI data for client-side rendering:
+
+```javascript
+import MarkdownIt from 'markdown-it';
+import lilyletPlugin from '@k-l-lambda/lilylet-markdown';
+
+const md = new MarkdownIt();
+md.use(lilyletPlugin);
+
+const result = md.render(`
+# My Score
+
+\`\`\`lilylet
+\\key c \\major
+\\time 4/4
+c'4 d' e' f' | g'1
+\`\`\`
+`);
+```
+
+Output:
+```html
+<h1>My Score</h1>
+<div class="lilylet-container" data-lilylet data-source="..." data-mei="..."></div>
+```
+
+### Server-side SVG Rendering
+
+For server-side rendering, initialize Verovio and pass it to the plugin:
+
+```javascript
+import MarkdownIt from 'markdown-it';
+import lilyletPlugin, { initVerovio, prerender } from '@k-l-lambda/lilylet-markdown';
+
+async function render(content) {
+  // Initialize Verovio
+  const verovioToolkit = await initVerovio();
+
+  // Create markdown-it instance with plugin
+  const md = new MarkdownIt();
+  md.use(lilyletPlugin, { verovioToolkit });
+
+  // Pre-render all lilylet blocks (async)
+  await prerender(md, content, { verovioToolkit });
+
+  // Render markdown (sync)
+  return md.render(content);
+}
+```
+
+### Options
+
+```typescript
+interface LilyletPluginOptions {
+  // Initialized Verovio toolkit instance
+  verovioToolkit?: VerovioToolkit;
+
+  // Verovio rendering options
+  verovioOptions?: {
+    scale?: number;        // Default: 40
+    pageWidth?: number;    // Default: 2000
+    adjustPageHeight?: boolean;  // Default: true
+  };
+
+  // Language aliases that trigger rendering
+  langAliases?: string[];  // Default: ['lilylet', 'lyl']
+
+  // CSS class for container
+  containerClass?: string; // Default: 'lilylet-container'
+
+  // CSS class for errors
+  errorClass?: string;     // Default: 'lilylet-error'
+
+  // Include source in data attribute
+  includeSource?: boolean; // Default: true
+}
+```
+
+## Markdown Syntax
+
+Use fenced code blocks with `lilylet` or `lyl` language identifier:
+
+~~~markdown
+```lilylet
+\key g \major
+\time 3/4
+d'4 g' b' | d''2.
+```
+~~~
+
+Or using the short alias:
+
+~~~markdown
+```lyl
+c'4 d' e' f' | g'1
+```
+~~~
+
+## Client-side Rendering
+
+For client-side rendering, use the embedded MEI data:
+
+```javascript
+import createVerovioModule from 'verovio/wasm';
+
+document.querySelectorAll('[data-lilylet]').forEach(async (container) => {
+  const mei = container.dataset.mei;
+  if (!mei) return;
+
+  const verovio = await createVerovioModule();
+  const toolkit = new verovio.toolkit();
+  toolkit.loadData(mei);
+  container.innerHTML = toolkit.renderToSVG(1);
+});
+```
+
+## Similar Projects
+
+- [remark-abcjs](https://github.com/breqdev/remark-abcjs) - Remark plugin for ABC notation
+- [markdown-it-mermaid](https://github.com/tylingsoft/markdown-it-mermaid) - Mermaid diagrams in markdown
+
+## License
+
+ISC

package/lib/index.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Lilylet Markdown-it Plugin
+ *
+ * Renders Lilylet music notation in fenced code blocks.
+ *
+ * Usage:
+ * ```lilylet
+ * c'4 d' e' f' | g'1
+ * ```
+ *
+ * Or with alias:
+ * ```lyl
+ * c'4 d' e' f' | g'1
+ * ```
+ */
+import type MarkdownIt from 'markdown-it';
+/**
+ * Verovio toolkit interface
+ */
+export interface VerovioToolkit {
+    loadData(data: string): boolean;
+    renderToSVG(page?: number, options?: object): string;
+    getLog(): string;
+    setOptions?(options: object): void;
+}
+/**
+ * Plugin options
+ */
+export interface LilyletPluginOptions {
+    /**
+     * Initialized Verovio toolkit instance.
+     * If not provided, MEI output will be wrapped in a data attribute for client-side rendering.
+     */
+    verovioToolkit?: VerovioToolkit;
+    /**
+     * Verovio rendering options
+     */
+    verovioOptions?: {
+        scale?: number;
+        pageWidth?: number;
+        pageHeight?: number;
+        adjustPageHeight?: boolean;
+        border?: number;
+        [key: string]: unknown;
+    };
+    /**
+     * Language aliases that trigger lilylet rendering.
+     * Default: ['lilylet', 'lyl']
+     */
+    langAliases?: string[];
+    /**
+     * CSS class for the container div.
+     * Default: 'lilylet-container'
+     */
+    containerClass?: string;
+    /**
+     * CSS class for error display.
+     * Default: 'lilylet-error'
+     */
+    errorClass?: string;
+    /**
+     * Whether to include the source code as a data attribute.
+     * Default: true
+     */
+    includeSource?: boolean;
+}
+/**
+ * Create the markdown-it plugin
+ */
+export declare function lilyletPlugin(md: MarkdownIt, options?: LilyletPluginOptions): void;
+/**
+ * Pre-render all lilylet blocks in markdown content.
+ * Call this before md.render() for async rendering.
+ */
+export declare function prerender(md: MarkdownIt, content: string, options?: LilyletPluginOptions): Promise<void>;
+/**
+ * Initialize Verovio toolkit (helper function)
+ */
+export declare function initVerovio(): Promise<VerovioToolkit>;
+export default lilyletPlugin;

package/lib/index.js

@@ -0,0 +1,188 @@
+/**
+ * Lilylet Markdown-it Plugin
+ *
+ * Renders Lilylet music notation in fenced code blocks.
+ *
+ * Usage:
+ * ```lilylet
+ * c'4 d' e' f' | g'1
+ * ```
+ *
+ * Or with alias:
+ * ```lyl
+ * c'4 d' e' f' | g'1
+ * ```
+ */
+import { parseCode, meiEncoder } from '@k-l-lambda/lilylet';
+const DEFAULT_OPTIONS = {
+    verovioToolkit: undefined,
+    verovioOptions: {
+        scale: 40,
+        adjustPageHeight: true,
+        pageWidth: 2000,
+    },
+    langAliases: ['lilylet', 'lyl'],
+    containerClass: 'lilylet-container',
+    errorClass: 'lilylet-error',
+    includeSource: true,
+};
+/**
+ * Check if language tag indicates playable mode
+ * e.g., "lyl.play", "lilylet.play"
+ */
+function parseLanguageTag(info, aliases) {
+    const lower = info.toLowerCase();
+    // Check for .play suffix
+    if (lower.endsWith('.play')) {
+        const base = lower.slice(0, -5); // Remove ".play"
+        return { isLilylet: aliases.includes(base), isPlayable: true };
+    }
+    return { isLilylet: aliases.includes(lower), isPlayable: false };
+}
+/**
+ * Escape HTML special characters
+ */
+function escapeHtml(str) {
+    return str
+        .replace(/&/g, '&')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&#039;');
+}
+/**
+ * Render lilylet code to HTML
+ */
+async function renderLilylet(code, options) {
+    const { verovioToolkit, verovioOptions, containerClass, errorClass, includeSource } = options;
+    try {
+        // Parse lilylet code
+        const doc = await parseCode(code);
+        // Encode to MEI
+        const mei = meiEncoder.encode(doc);
+        // Build data attributes
+        const sourceAttr = includeSource ? ` data-source="${escapeHtml(code)}"` : '';
+        const meiAttr = ` data-mei="${escapeHtml(mei)}"`;
+        // If no Verovio toolkit, return MEI for client-side rendering
+        if (!verovioToolkit) {
+            return `<div class="${containerClass}" data-lilylet${sourceAttr}${meiAttr}></div>`;
+        }
+        // Calculate pageHeight based on measure count
+        const measureCount = doc.measures?.length || 1;
+        const basePageHeight = 2000;
+        const measuresPerPage = 20;
+        const pageHeight = Math.max(basePageHeight, Math.ceil(measureCount / measuresPerPage) * basePageHeight);
+        // Set Verovio options with dynamic pageHeight
+        if (verovioToolkit.setOptions) {
+            verovioToolkit.setOptions({
+                ...verovioOptions,
+                pageHeight,
+            });
+        }
+        // Load MEI data
+        const loaded = verovioToolkit.loadData(mei);
+        if (!loaded) {
+            const log = verovioToolkit.getLog();
+            throw new Error(`Verovio failed to load MEI: ${log}`);
+        }
+        // Render to SVG
+        const svg = verovioToolkit.renderToSVG(1);
+        return `<div class="${containerClass}" data-lilylet${sourceAttr}${meiAttr}>${svg}</div>`;
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        return `<div class="${errorClass}" data-lilylet-error><pre>${escapeHtml(errorMessage)}</pre><pre>${escapeHtml(code)}</pre></div>`;
+    }
+}
+/**
+ * Synchronous render (for immediate use, returns placeholder if no toolkit)
+ */
+function renderLilyletSync(code, options, cache, playable = false) {
+    // Check cache first (include playable flag in cache key)
+    const cacheKey = playable ? `play:${code}` : code;
+    const cached = cache.get(cacheKey);
+    if (cached !== undefined) {
+        return cached;
+    }
+    const { containerClass, includeSource } = options;
+    const sourceAttr = includeSource ? ` data-source="${escapeHtml(code)}"` : '';
+    const playableAttr = playable ? ' data-playable' : '';
+    // Return placeholder for async rendering
+    return `<div class="${containerClass}" data-lilylet-pending${playableAttr}${sourceAttr}><code>${escapeHtml(code)}</code></div>`;
+}
+/**
+ * Create the markdown-it plugin
+ */
+export function lilyletPlugin(md, options = {}) {
+    const opts = {
+        ...DEFAULT_OPTIONS,
+        ...options,
+        verovioOptions: { ...DEFAULT_OPTIONS.verovioOptions, ...options.verovioOptions },
+    };
+    // Cache for pre-rendered content
+    const renderCache = new Map();
+    // Store original fence renderer
+    const originalFence = md.renderer.rules.fence || function (tokens, idx, options, env, self) {
+        return self.renderToken(tokens, idx, options);
+    };
+    // Override fence renderer
+    md.renderer.rules.fence = function (tokens, idx, mdOptions, env, self) {
+        const token = tokens[idx];
+        const info = token.info.trim();
+        const code = token.content.trim();
+        // Check if this is a lilylet block (with optional .play suffix)
+        const { isLilylet, isPlayable } = parseLanguageTag(info, opts.langAliases);
+        if (isLilylet) {
+            return renderLilyletSync(code, opts, renderCache, isPlayable);
+        }
+        // Fall back to original renderer
+        return originalFence(tokens, idx, mdOptions, env, self);
+    };
+    // Expose async render method for pre-rendering
+    md.lilylet = {
+        prerenderCode: async function (code) {
+            const result = await renderLilylet(code, opts);
+            renderCache.set(code, result);
+            return result;
+        }
+    };
+}
+/**
+ * Pre-render all lilylet blocks in markdown content.
+ * Call this before md.render() for async rendering.
+ */
+export async function prerender(md, content, options = {}) {
+    const opts = {
+        ...DEFAULT_OPTIONS,
+        ...options,
+        verovioOptions: { ...DEFAULT_OPTIONS.verovioOptions, ...options.verovioOptions },
+    };
+    // Parse to find all lilylet blocks
+    const tokens = md.parse(content, {});
+    for (const token of tokens) {
+        if (token.type === 'fence') {
+            const { isLilylet } = parseLanguageTag(token.info.trim(), opts.langAliases);
+            if (isLilylet) {
+                const code = token.content.trim();
+                const lilyletExt = md.lilylet;
+                if (lilyletExt) {
+                    await lilyletExt.prerenderCode(code);
+                }
+            }
+        }
+    }
+}
+/**
+ * Initialize Verovio toolkit (helper function)
+ */
+export async function initVerovio() {
+    const verovioModule = await import('verovio');
+    const verovio = verovioModule.default;
+    return new Promise((resolve) => {
+        verovio.module.onRuntimeInitialized = () => {
+            resolve(new verovio.toolkit());
+        };
+    });
+}
+// Default export
+export default lilyletPlugin;

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@k-l-lambda/lilylet-markdown",
+  "version": "0.1.19",
+  "description": "Markdown-it plugin for rendering Lilylet music notation",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    }
+  },
+  "files": [
+    "lib"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "node --experimental-vm-modules tests/test.js",
+    "prepublishOnly": "npm run build"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/k-l-lambda/lilylet-markdown.git"
+  },
+  "keywords": [
+    "markdown-it",
+    "markdown",
+    "music",
+    "notation",
+    "lilylet",
+    "lilypond",
+    "sheet-music"
+  ],
+  "author": "k.l.lambda",
+  "license": "ISC",
+  "dependencies": {
+    "@k-l-lambda/lilylet": "^0.1.30",
+    "verovio": "^4.3.0"
+  },
+  "devDependencies": {
+    "@types/markdown-it": "^14.0.0",
+    "@types/node": "^20.11.0",
+    "markdown-it": "^14.0.0",
+    "typescript": "^5.3.0"
+  },
+  "peerDependencies": {
+    "markdown-it": ">=12.0.0"
+  }
+}