mrmd-jupyter-bridge 0.1.0

package/bin/cli.js

@@ -0,0 +1,154 @@
+#!/usr/bin/env node
+
+/**
+ * mrmd-jupyter-bridge CLI
+ *
+ * Syncs Jupyter notebooks with MRMD markdown via Yjs collaboration.
+ *
+ * Usage:
+ *   mrmd-jupyter-bridge <notebook.ipynb> [options]
+ *
+ * Options:
+ *   --sync-url, -s    mrmd-sync WebSocket URL (default: ws://localhost:4444)
+ *   --name, -n        Name shown in collaboration (default: jupyter-bridge)
+ *   --help, -h        Show this help message
+ *
+ * Examples:
+ *   mrmd-jupyter-bridge notebook.ipynb
+ *   mrmd-jupyter-bridge notebook.ipynb --sync-url ws://localhost:5555
+ *   mrmd-jupyter-bridge /path/to/notebook.ipynb -n "Jupyter"
+ */
+
+import { resolve } from 'path';
+import { existsSync } from 'fs';
+import { createBridge } from '../src/index.js';
+
+function printHelp() {
+  console.log(`
+mrmd-jupyter-bridge - Sync Jupyter notebooks with MRMD
+
+Usage:
+  mrmd-jupyter-bridge <notebook.ipynb> [options]
+
+Options:
+  --sync-url, -s <url>   mrmd-sync WebSocket URL (default: ws://localhost:4444)
+  --name, -n <name>      Name shown in collaboration (default: jupyter-bridge)
+  --debounce <ms>        Write debounce delay in ms (default: 500)
+  --help, -h             Show this help message
+
+Examples:
+  mrmd-jupyter-bridge notebook.ipynb
+  mrmd-jupyter-bridge notebook.ipynb --sync-url ws://localhost:5555
+  mrmd-jupyter-bridge ./notebooks/analysis.ipynb -n "Jupyter"
+
+How it works:
+  1. The bridge watches your .ipynb file for changes
+  2. It connects to mrmd-sync as a Yjs collaborator
+  3. Changes in Jupyter appear in MRMD as if typed by "jupyter-bridge"
+  4. Changes in MRMD sync back to the .ipynb file
+
+The markdown file will be created next to the notebook with the same name:
+  notebook.ipynb -> notebook.md
+`);
+}
+
+function parseArgs(args) {
+  const options = {
+    ipynbPath: null,
+    syncUrl: 'ws://localhost:4444',
+    name: 'jupyter-bridge',
+    debounceMs: 500,
+  };
+
+  let i = 0;
+  while (i < args.length) {
+    const arg = args[i];
+
+    if (arg === '--help' || arg === '-h') {
+      printHelp();
+      process.exit(0);
+    } else if (arg === '--sync-url' || arg === '-s') {
+      options.syncUrl = args[++i];
+    } else if (arg === '--name' || arg === '-n') {
+      options.name = args[++i];
+    } else if (arg === '--debounce') {
+      options.debounceMs = parseInt(args[++i], 10);
+    } else if (!arg.startsWith('-')) {
+      options.ipynbPath = arg;
+    } else {
+      console.error(`Unknown option: ${arg}`);
+      process.exit(1);
+    }
+    i++;
+  }
+
+  return options;
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+
+  if (args.length === 0) {
+    printHelp();
+    process.exit(1);
+  }
+
+  const options = parseArgs(args);
+
+  if (!options.ipynbPath) {
+    console.error('Error: Please provide a notebook path');
+    printHelp();
+    process.exit(1);
+  }
+
+  // Resolve to absolute path
+  const ipynbPath = resolve(options.ipynbPath);
+
+  if (!ipynbPath.endsWith('.ipynb')) {
+    console.error('Error: File must have .ipynb extension');
+    process.exit(1);
+  }
+
+  // Note: File doesn't need to exist - we can create it from MRMD content
+  if (!existsSync(ipynbPath)) {
+    console.log(`Note: ${ipynbPath} does not exist yet. Will create from MRMD content if available.`);
+  }
+
+  console.log(`
+╔════════════════════════════════════════════════════════════╗
+║                  mrmd-jupyter-bridge                       ║
+╠════════════════════════════════════════════════════════════╣
+║  Notebook: ${options.ipynbPath.padEnd(46)}║
+║  Sync URL: ${options.syncUrl.padEnd(46)}║
+║  Name:     ${options.name.padEnd(46)}║
+╚════════════════════════════════════════════════════════════╝
+`);
+
+  try {
+    const bridge = await createBridge(options.syncUrl, ipynbPath, {
+      name: options.name,
+      debounceMs: options.debounceMs,
+      log: (msg) => console.log(msg),
+    });
+
+    console.log('Bridge is running. Press Ctrl+C to stop.\n');
+
+    // Handle graceful shutdown
+    const shutdown = () => {
+      console.log('\nShutting down...');
+      bridge.stop();
+      process.exit(0);
+    };
+
+    process.on('SIGINT', shutdown);
+    process.on('SIGTERM', shutdown);
+
+    // Keep the process running
+    await new Promise(() => {});
+  } catch (err) {
+    console.error(`\nFailed to start bridge: ${err.message}`);
+    process.exit(1);
+  }
+}
+
+main();

package/demo.ipynb

@@ -0,0 +1,75 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Demo Notebook\n",
+    "\n",
+    "Testing live sync between Jupyter and MRMD!\n",
+    "\n",
+    "## Added from MRMD Editor!\n",
+    "\n",
+    "This text was typed directly in the MRMD editor and should sync to the .ipynb file.\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 1,
+   "metadata": {},
+   "source": [
+    "print(\"Hello from Jupyter!\")"
+   ],
+   "outputs": [
+    {
+     "output_type": "stream",
+     "name": "stdout",
+     "text": [
+      "Hello from Jupyter!"
+     ]
+    }
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 2,
+   "metadata": {},
+   "source": [
+    "x = 42\n",
+    "print(f\"The answer is {x}\")"
+   ],
+   "outputs": [
+    {
+     "output_type": "stream",
+     "name": "stdout",
+     "text": [
+      "The answer is 42"
+     ]
+    }
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "\n",
+    "## Live Sync Test!\n",
+    "\n",
+    "This line was added at the end to test the sync. If it appears in demo.ipynb, the bridge works!"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "name": "python",
+   "version": "3.10.0"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

package/demo.md

@@ -0,0 +1,28 @@
+# Demo Notebook
+
+Testing live sync between Jupyter and MRMD!
+
+## Added from MRMD Editor!
+
+This text was typed directly in the MRMD editor and should sync to the .ipynb file.
+
+```python
+print("Hello from Jupyter!")
+```
+
+```output:jupyter-1
+Hello from Jupyter!
+```
+
+```python
+x = 42
+print(f"The answer is {x}")
+```
+
+```output:jupyter-2
+The answer is 42
+```
+
+## Live Sync Test!
+
+This line was added at the end to test the sync. If it appears in demo.ipynb, the bridge works!

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "mrmd-jupyter-bridge",
+  "version": "0.1.0",
+  "description": "Bidirectional sync bridge between Jupyter notebooks (.ipynb) and MRMD markdown",
+  "type": "module",
+  "main": "src/index.js",
+  "bin": {
+    "mrmd-jupyter-bridge": "./bin/cli.js"
+  },
+  "scripts": {
+    "start": "node bin/cli.js",
+    "dev": "node --watch bin/cli.js",
+    "test": "node --test src/*.test.js"
+  },
+  "keywords": [
+    "mrmd",
+    "jupyter",
+    "notebook",
+    "ipynb",
+    "markdown",
+    "yjs",
+    "sync",
+    "collaboration"
+  ],
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+    "yjs": "^13.6.0",
+    "y-websocket": "^2.0.0",
+    "lib0": "^0.2.0",
+    "chokidar": "^3.5.0",
+    "diff": "^5.2.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/src/bridge.js

@@ -0,0 +1,441 @@
+/**
+ * Jupyter Bridge
+ *
+ * Bidirectional sync bridge between Jupyter notebooks (.ipynb) and MRMD markdown.
+ * Connects to mrmd-sync as a Yjs peer, appearing as a collaborator.
+ */
+
+import * as Y from 'yjs';
+import { WebsocketProvider } from 'y-websocket';
+import { watch } from 'chokidar';
+import { diffChars } from 'diff';
+import { readFileSync, writeFileSync, existsSync } from 'fs';
+import { basename, dirname, join } from 'path';
+import {
+  ipynbToMarkdown,
+  markdownToIpynb,
+  parseIpynb,
+  serializeIpynb,
+} from './converter.js';
+
+/**
+ * @typedef {Object} BridgeOptions
+ * @property {string} [name='jupyter-bridge'] - Name shown in awareness
+ * @property {string} [color='#f59e0b'] - Color for awareness
+ * @property {number} [debounceMs=500] - Debounce delay for file writes
+ * @property {Function} [log] - Logger function
+ */
+
+/**
+ * Jupyter Bridge
+ *
+ * Syncs a .ipynb file bidirectionally with MRMD via Yjs.
+ */
+export class JupyterBridge {
+  /**
+   * @param {string} syncUrl - WebSocket URL for mrmd-sync (e.g., 'ws://localhost:4444')
+   * @param {string} ipynbPath - Path to the .ipynb file
+   * @param {BridgeOptions} [options]
+   */
+  constructor(syncUrl, ipynbPath, options = {}) {
+    this.syncUrl = syncUrl;
+    this.ipynbPath = ipynbPath;
+    this.options = {
+      name: 'jupyter-bridge',
+      color: '#f59e0b', // Amber - distinguishes from monitors (green) and editors
+      debounceMs: 500,
+      log: console.log,
+      ...options,
+    };
+
+    // Derive markdown path (same name, .md extension)
+    const dir = dirname(ipynbPath);
+    const base = basename(ipynbPath, '.ipynb');
+    this.mdPath = join(dir, `${base}.md`);
+
+    // The room name for mrmd-sync is the markdown path
+    // Use absolute path so mrmd-sync opens the right file
+    this.docPath = this.mdPath;
+
+    /** @type {Y.Doc} */
+    this.ydoc = new Y.Doc();
+
+    /** @type {WebsocketProvider|null} */
+    this.provider = null;
+
+    /** @type {import('chokidar').FSWatcher|null} */
+    this.watcher = null;
+
+    // State tracking
+    this._connected = false;
+    this._synced = false;
+    this._lastIpynbContent = null;
+    this._lastMdContent = null;
+    this._isWritingIpynb = false;
+    this._isWritingYjs = false;
+    this._writeTimeout = null;
+
+    // Store original notebook for metadata preservation
+    this._originalNotebook = null;
+  }
+
+  /**
+   * Log helper
+   */
+  _log(level, message, data = {}) {
+    const entry = {
+      timestamp: new Date().toISOString(),
+      level,
+      component: 'jupyter-bridge',
+      message,
+      ipynb: basename(this.ipynbPath),
+      ...data,
+    };
+    this.options.log(JSON.stringify(entry));
+  }
+
+  /**
+   * Start the bridge
+   *
+   * @returns {Promise<void>}
+   */
+  async start() {
+    this._log('info', 'Starting Jupyter bridge', {
+      ipynb: this.ipynbPath,
+      md: this.mdPath,
+      sync: this.syncUrl,
+    });
+
+    // Load initial notebook
+    await this._loadNotebook();
+
+    // Connect to mrmd-sync
+    await this._connect();
+
+    // Start watching the .ipynb file
+    this._startWatcher();
+
+    this._log('info', 'Bridge started');
+  }
+
+  /**
+   * Load the notebook and convert to markdown
+   */
+  async _loadNotebook() {
+    if (!existsSync(this.ipynbPath)) {
+      this._log('warn', 'Notebook file does not exist yet', { path: this.ipynbPath });
+      return;
+    }
+
+    try {
+      const content = readFileSync(this.ipynbPath, 'utf8');
+      const { notebook, error } = parseIpynb(content);
+
+      if (error) {
+        this._log('error', 'Failed to parse notebook', { error });
+        return;
+      }
+
+      this._originalNotebook = notebook;
+      this._lastIpynbContent = content;
+      this._lastMdContent = ipynbToMarkdown(notebook);
+
+      this._log('info', 'Loaded notebook', {
+        cells: notebook.cells.length,
+        mdChars: this._lastMdContent.length,
+      });
+    } catch (err) {
+      this._log('error', 'Failed to load notebook', { error: err.message });
+    }
+  }
+
+  /**
+   * Connect to mrmd-sync as a Yjs peer
+   */
+  _connect() {
+    return new Promise((resolve, reject) => {
+      this._log('info', 'Connecting to sync server', {
+        url: this.syncUrl,
+        doc: this.docPath,
+      });
+
+      this.provider = new WebsocketProvider(this.syncUrl, this.docPath, this.ydoc, {
+        connect: true,
+      });
+
+      // Set awareness - this shows up in MRMD as a collaborator
+      this.provider.awareness.setLocalStateField('user', {
+        name: this.options.name,
+        color: this.options.color,
+        type: 'jupyter-bridge',
+      });
+
+      // Track connection
+      this.provider.on('status', ({ status }) => {
+        const wasConnected = this._connected;
+        this._connected = status === 'connected';
+
+        if (this._connected && !wasConnected) {
+          this._log('info', 'Connected to sync server');
+        } else if (!this._connected && wasConnected) {
+          this._log('warn', 'Disconnected from sync server');
+        }
+      });
+
+      // Wait for sync
+      this.provider.on('sync', (isSynced) => {
+        if (isSynced && !this._synced) {
+          this._synced = true;
+          this._log('info', 'Document synced');
+
+          // Initialize: push notebook content to Yjs if we have it and Yjs is empty
+          this._initializeContent();
+
+          // Start listening for Yjs changes
+          this._watchYjs();
+
+          resolve();
+        }
+      });
+
+      this.provider.on('connection-error', (err) => {
+        this._log('error', 'Connection error', { error: err.message });
+        reject(err);
+      });
+    });
+  }
+
+  /**
+   * Initialize content - either from notebook or from existing Yjs state
+   */
+  _initializeContent() {
+    const ytext = this.ydoc.getText('content');
+    const yjsContent = ytext.toString();
+
+    if (yjsContent.length === 0 && this._lastMdContent) {
+      // Yjs is empty, push our notebook content
+      this._log('info', 'Initializing Yjs from notebook');
+      this._isWritingYjs = true;
+      this.ydoc.transact(() => {
+        ytext.insert(0, this._lastMdContent);
+      });
+      this._isWritingYjs = false;
+    } else if (yjsContent.length > 0) {
+      // Yjs has content, sync back to notebook
+      this._log('info', 'Syncing existing Yjs content to notebook');
+      this._lastMdContent = yjsContent;
+      this._scheduleIpynbWrite();
+    }
+  }
+
+  /**
+   * Watch Yjs for changes (from other collaborators or MRMD editor)
+   */
+  _watchYjs() {
+    const ytext = this.ydoc.getText('content');
+
+    ytext.observe((event) => {
+      if (this._isWritingYjs) return;
+
+      const newContent = ytext.toString();
+      if (newContent === this._lastMdContent) return;
+
+      this._log('debug', 'Yjs content changed', {
+        oldLen: this._lastMdContent?.length || 0,
+        newLen: newContent.length,
+      });
+
+      this._lastMdContent = newContent;
+      this._scheduleIpynbWrite();
+    });
+  }
+
+  /**
+   * Schedule debounced write to .ipynb
+   */
+  _scheduleIpynbWrite() {
+    clearTimeout(this._writeTimeout);
+
+    this._writeTimeout = setTimeout(() => {
+      this._writeIpynb();
+    }, this.options.debounceMs);
+  }
+
+  /**
+   * Write current markdown state back to .ipynb
+   */
+  _writeIpynb() {
+    if (this._isWritingIpynb || !this._lastMdContent) return;
+
+    this._isWritingIpynb = true;
+
+    try {
+      // Convert markdown to notebook, preserving original metadata
+      const notebook = markdownToIpynb(this._lastMdContent, this._originalNotebook);
+      const content = serializeIpynb(notebook);
+
+      // Skip if unchanged
+      if (content === this._lastIpynbContent) {
+        this._isWritingIpynb = false;
+        return;
+      }
+
+      writeFileSync(this.ipynbPath, content, 'utf8');
+      this._lastIpynbContent = content;
+      this._originalNotebook = notebook;
+
+      this._log('info', 'Wrote notebook', {
+        cells: notebook.cells.length,
+        bytes: content.length,
+      });
+    } catch (err) {
+      this._log('error', 'Failed to write notebook', { error: err.message });
+    } finally {
+      this._isWritingIpynb = false;
+    }
+  }
+
+  /**
+   * Start watching the .ipynb file for external changes
+   */
+  _startWatcher() {
+    this.watcher = watch(this.ipynbPath, {
+      ignoreInitial: true,
+      awaitWriteFinish: { stabilityThreshold: 300 },
+    });
+
+    this.watcher.on('change', () => {
+      this._handleIpynbChange();
+    });
+
+    this.watcher.on('error', (err) => {
+      this._log('error', 'File watcher error', { error: err.message });
+    });
+
+    this._log('info', 'Watching notebook file');
+  }
+
+  /**
+   * Handle external change to .ipynb file
+   */
+  async _handleIpynbChange() {
+    // Skip if we just wrote the file
+    if (this._isWritingIpynb) return;
+
+    this._log('debug', 'Notebook file changed externally');
+
+    try {
+      const content = readFileSync(this.ipynbPath, 'utf8');
+
+      // Skip if unchanged
+      if (content === this._lastIpynbContent) return;
+
+      const { notebook, error } = parseIpynb(content);
+      if (error) {
+        this._log('error', 'Failed to parse changed notebook', { error });
+        return;
+      }
+
+      this._lastIpynbContent = content;
+      this._originalNotebook = notebook;
+
+      const newMdContent = ipynbToMarkdown(notebook);
+
+      // Skip if markdown unchanged
+      if (newMdContent === this._lastMdContent) {
+        return;
+      }
+
+      // Apply changes to Yjs using diff
+      this._applyToYjs(newMdContent);
+
+      this._log('info', 'Applied notebook changes to Yjs', {
+        cells: notebook.cells.length,
+      });
+    } catch (err) {
+      this._log('error', 'Failed to handle notebook change', { error: err.message });
+    }
+  }
+
+  /**
+   * Apply changes to Yjs document using character-level diff
+   */
+  _applyToYjs(newContent) {
+    const ytext = this.ydoc.getText('content');
+    const oldContent = this._lastMdContent || '';
+
+    if (oldContent === newContent) return;
+
+    this._isWritingYjs = true;
+
+    const changes = diffChars(oldContent, newContent);
+
+    this.ydoc.transact(() => {
+      let pos = 0;
+      for (const change of changes) {
+        if (change.added) {
+          ytext.insert(pos, change.value);
+          pos += change.value.length;
+        } else if (change.removed) {
+          ytext.delete(pos, change.value.length);
+        } else {
+          pos += change.value.length;
+        }
+      }
+    });
+
+    this._lastMdContent = newContent;
+    this._isWritingYjs = false;
+  }
+
+  /**
+   * Stop the bridge
+   */
+  stop() {
+    this._log('info', 'Stopping bridge');
+
+    // Flush any pending write
+    clearTimeout(this._writeTimeout);
+    if (this._lastMdContent) {
+      this._writeIpynb();
+    }
+
+    // Stop file watcher
+    if (this.watcher) {
+      this.watcher.close();
+      this.watcher = null;
+    }
+
+    // Disconnect from sync
+    if (this.provider) {
+      this.provider.disconnect();
+      this.provider = null;
+    }
+
+    this._connected = false;
+    this._synced = false;
+
+    this._log('info', 'Bridge stopped');
+  }
+
+  /**
+   * Check if connected and synced
+   */
+  get isConnected() {
+    return this._connected && this._synced;
+  }
+}
+
+/**
+ * Create and start a bridge
+ *
+ * @param {string} syncUrl
+ * @param {string} ipynbPath
+ * @param {BridgeOptions} [options]
+ * @returns {Promise<JupyterBridge>}
+ */
+export async function createBridge(syncUrl, ipynbPath, options = {}) {
+  const bridge = new JupyterBridge(syncUrl, ipynbPath, options);
+  await bridge.start();
+  return bridge;
+}

package/src/converter.js

@@ -0,0 +1,368 @@
+/**
+ * Jupyter Notebook <-> MRMD Markdown Converter
+ *
+ * Handles bidirectional conversion between .ipynb JSON and MRMD markdown format.
+ * Preserves outputs using execId-based output blocks.
+ */
+
+/**
+ * Map Jupyter language names to MRMD fence languages
+ */
+const LANGUAGE_MAP = {
+  python: 'python',
+  python3: 'python',
+  javascript: 'javascript',
+  typescript: 'typescript',
+  julia: 'julia',
+  r: 'r',
+  bash: 'bash',
+  sh: 'bash',
+};
+
+/**
+ * Generate an execution ID from Jupyter's execution_count
+ * Format: jupyter-{execution_count} to distinguish from MRMD's exec-{timestamp}-{random}
+ *
+ * @param {number|null} executionCount
+ * @returns {string|null}
+ */
+export function executionCountToExecId(executionCount) {
+  if (executionCount === null || executionCount === undefined) {
+    return null;
+  }
+  return `jupyter-${executionCount}`;
+}
+
+/**
+ * Extract execution_count from an execId
+ *
+ * @param {string|null} execId
+ * @returns {number|null}
+ */
+export function execIdToExecutionCount(execId) {
+  if (!execId) return null;
+
+  // Handle jupyter-{n} format
+  if (execId.startsWith('jupyter-')) {
+    const num = parseInt(execId.slice(8), 10);
+    return isNaN(num) ? null : num;
+  }
+
+  // Handle MRMD exec-{timestamp}-{random} format - no execution count
+  return null;
+}
+
+/**
+ * Convert Jupyter cell outputs to text for the output block
+ *
+ * @param {Array} outputs - Jupyter cell outputs
+ * @returns {string}
+ */
+export function outputsToText(outputs) {
+  if (!outputs || outputs.length === 0) return '';
+
+  const parts = [];
+
+  for (const output of outputs) {
+    switch (output.output_type) {
+      case 'stream':
+        // stdout/stderr
+        parts.push(arrayToString(output.text));
+        break;
+
+      case 'execute_result':
+      case 'display_data':
+        // Rich output - prefer text/plain, note others
+        if (output.data) {
+          if (output.data['text/plain']) {
+            parts.push(arrayToString(output.data['text/plain']));
+          }
+          // TODO: Handle images, HTML, etc. with special markers
+          if (output.data['image/png']) {
+            parts.push('[Image: base64 PNG data]');
+          }
+          if (output.data['text/html'] && !output.data['text/plain']) {
+            parts.push('[HTML output]');
+          }
+        }
+        break;
+
+      case 'error':
+        // Error traceback
+        if (output.traceback) {
+          parts.push(output.traceback.join('\n'));
+        } else {
+          parts.push(`${output.ename}: ${output.evalue}`);
+        }
+        break;
+    }
+  }
+
+  return parts.join('');
+}
+
+/**
+ * Convert text from output block back to Jupyter outputs
+ * Note: This is lossy - we can't reconstruct rich outputs from plain text
+ *
+ * @param {string} text - Output block text
+ * @returns {Array}
+ */
+export function textToOutputs(text) {
+  if (!text || text.trim() === '') return [];
+
+  // Simple case: treat as stdout stream
+  return [{
+    output_type: 'stream',
+    name: 'stdout',
+    text: text.split('\n').map((line, i, arr) =>
+      i < arr.length - 1 ? line + '\n' : line
+    ).filter(line => line !== ''),
+  }];
+}
+
+/**
+ * Convert Jupyter notebook JSON to MRMD markdown
+ *
+ * @param {Object} notebook - Parsed .ipynb JSON
+ * @returns {string} MRMD markdown content
+ */
+export function ipynbToMarkdown(notebook) {
+  if (!notebook || !notebook.cells) {
+    return '';
+  }
+
+  const parts = [];
+
+  // Extract language from kernel info
+  const language = notebook.metadata?.kernelspec?.language ||
+                   notebook.metadata?.language_info?.name ||
+                   'python';
+  const fenceLanguage = LANGUAGE_MAP[language] || language;
+
+  for (const cell of notebook.cells) {
+    if (cell.cell_type === 'markdown') {
+      // Markdown cell - output as-is
+      parts.push(arrayToString(cell.source));
+    } else if (cell.cell_type === 'code') {
+      // Code cell with potential output
+      const code = arrayToString(cell.source);
+      const execId = executionCountToExecId(cell.execution_count);
+      const outputText = outputsToText(cell.outputs);
+
+      // Code block
+      parts.push(`\`\`\`${fenceLanguage}\n${code}\n\`\`\``);
+
+      // Output block (only if there's output or an execution count)
+      if (outputText || execId) {
+        const outputFence = execId ? `\`\`\`output:${execId}` : '```output';
+        parts.push(`${outputFence}\n${outputText}\`\`\``);
+      }
+    } else if (cell.cell_type === 'raw') {
+      // Raw cell - wrap in raw block
+      parts.push(`\`\`\`\n${arrayToString(cell.source)}\n\`\`\``);
+    }
+  }
+
+  return parts.join('\n\n');
+}
+
+/**
+ * Convert MRMD markdown to Jupyter notebook JSON
+ *
+ * @param {string} markdown - MRMD markdown content
+ * @param {Object} [existingNotebook] - Existing notebook to preserve metadata from
+ * @returns {Object} Jupyter notebook JSON
+ */
+export function markdownToIpynb(markdown, existingNotebook = null) {
+  const cells = [];
+  const lines = markdown.split('\n');
+
+  let i = 0;
+  let currentMarkdown = [];
+
+  // Preserve metadata from existing notebook or use defaults
+  const metadata = existingNotebook?.metadata || {
+    kernelspec: {
+      display_name: 'Python 3',
+      language: 'python',
+      name: 'python3',
+    },
+    language_info: {
+      name: 'python',
+      version: '3.10.0',
+    },
+  };
+
+  const nbformat = existingNotebook?.nbformat || 4;
+  const nbformat_minor = existingNotebook?.nbformat_minor || 5;
+
+  // Flush accumulated markdown as a cell
+  const flushMarkdown = () => {
+    if (currentMarkdown.length > 0) {
+      const text = currentMarkdown.join('\n');
+      if (text.trim()) {
+        cells.push({
+          cell_type: 'markdown',
+          metadata: {},
+          source: stringToArray(text),
+        });
+      }
+      currentMarkdown = [];
+    }
+  };
+
+  while (i < lines.length) {
+    const line = lines[i];
+
+    // Check for code fence
+    const fenceMatch = line.match(/^```(\w*)/);
+    if (fenceMatch) {
+      const language = fenceMatch[1].toLowerCase();
+
+      // Skip output blocks - they'll be handled with their code cell
+      if (language === 'output' || language.startsWith('output:')) {
+        // Find the closing fence
+        i++;
+        while (i < lines.length && !lines[i].match(/^```\s*$/)) {
+          i++;
+        }
+        i++; // Skip closing fence
+        continue;
+      }
+
+      // Skip stdin blocks
+      if (language.startsWith('stdin:')) {
+        i++;
+        while (i < lines.length && !lines[i].match(/^```\s*$/)) {
+          i++;
+        }
+        i++;
+        continue;
+      }
+
+      // Flush any accumulated markdown
+      flushMarkdown();
+
+      // Parse code block
+      const codeLines = [];
+      i++;
+      while (i < lines.length && !lines[i].match(/^```\s*$/)) {
+        codeLines.push(lines[i]);
+        i++;
+      }
+      i++; // Skip closing fence
+
+      const code = codeLines.join('\n');
+
+      // Look for following output block
+      let outputs = [];
+      let executionCount = null;
+
+      // Skip whitespace
+      let lookAhead = i;
+      while (lookAhead < lines.length && lines[lookAhead].trim() === '') {
+        lookAhead++;
+      }
+
+      // Check for output block
+      if (lookAhead < lines.length) {
+        const outputMatch = lines[lookAhead].match(/^```output(?::([^\s]*))?/);
+        if (outputMatch) {
+          const execId = outputMatch[1] || null;
+          executionCount = execIdToExecutionCount(execId);
+
+          // Parse output content
+          const outputLines = [];
+          lookAhead++;
+          while (lookAhead < lines.length && !lines[lookAhead].match(/^```\s*$/)) {
+            outputLines.push(lines[lookAhead]);
+            lookAhead++;
+          }
+          lookAhead++; // Skip closing fence
+
+          const outputText = outputLines.join('\n');
+          outputs = textToOutputs(outputText);
+
+          // Advance main index past the output block
+          i = lookAhead;
+        }
+      }
+
+      // Create code cell
+      cells.push({
+        cell_type: 'code',
+        execution_count: executionCount,
+        metadata: {},
+        source: stringToArray(code),
+        outputs,
+      });
+    } else {
+      // Regular markdown line
+      currentMarkdown.push(line);
+      i++;
+    }
+  }
+
+  // Flush remaining markdown
+  flushMarkdown();
+
+  return {
+    cells,
+    metadata,
+    nbformat,
+    nbformat_minor,
+  };
+}
+
+/**
+ * Convert Jupyter array-or-string to string
+ */
+function arrayToString(source) {
+  if (Array.isArray(source)) {
+    return source.join('');
+  }
+  return source || '';
+}
+
+/**
+ * Convert string to Jupyter array format (lines with \n)
+ */
+function stringToArray(str) {
+  if (!str) return [];
+  const lines = str.split('\n');
+  return lines.map((line, i) =>
+    i < lines.length - 1 ? line + '\n' : line
+  ).filter((line, i, arr) =>
+    // Keep all lines except trailing empty string
+    i < arr.length - 1 || line !== ''
+  );
+}
+
+/**
+ * Parse a .ipynb file content
+ *
+ * @param {string} content - Raw file content
+ * @returns {{notebook: Object|null, error: string|null}}
+ */
+export function parseIpynb(content) {
+  try {
+    const notebook = JSON.parse(content);
+    if (!notebook.cells || !Array.isArray(notebook.cells)) {
+      return { notebook: null, error: 'Invalid notebook: missing cells array' };
+    }
+    return { notebook, error: null };
+  } catch (err) {
+    return { notebook: null, error: `JSON parse error: ${err.message}` };
+  }
+}
+
+/**
+ * Serialize notebook to .ipynb format
+ *
+ * @param {Object} notebook
+ * @returns {string}
+ */
+export function serializeIpynb(notebook) {
+  return JSON.stringify(notebook, null, 1);
+}

package/src/index.js

@@ -0,0 +1,17 @@
+/**
+ * mrmd-jupyter-bridge
+ *
+ * Bidirectional sync between Jupyter notebooks and MRMD markdown via Yjs.
+ */
+
+export { JupyterBridge, createBridge } from './bridge.js';
+export {
+  ipynbToMarkdown,
+  markdownToIpynb,
+  parseIpynb,
+  serializeIpynb,
+  executionCountToExecId,
+  execIdToExecutionCount,
+  outputsToText,
+  textToOutputs,
+} from './converter.js';

package/test-converter.js

@@ -0,0 +1,50 @@
+#!/usr/bin/env node
+
+/**
+ * Quick test for the converter
+ */
+
+import { readFileSync } from 'fs';
+import {
+  ipynbToMarkdown,
+  markdownToIpynb,
+  parseIpynb,
+  serializeIpynb,
+} from './src/converter.js';
+
+// Test 1: Load notebook and convert to markdown
+console.log('=== Test 1: ipynb -> markdown ===\n');
+
+const ipynbContent = readFileSync('./test-notebook.ipynb', 'utf8');
+const { notebook, error } = parseIpynb(ipynbContent);
+
+if (error) {
+  console.error('Parse error:', error);
+  process.exit(1);
+}
+
+console.log(`Loaded notebook with ${notebook.cells.length} cells\n`);
+
+const markdown = ipynbToMarkdown(notebook);
+console.log('Generated markdown:\n');
+console.log('---');
+console.log(markdown);
+console.log('---\n');
+
+// Test 2: Convert markdown back to notebook
+console.log('=== Test 2: markdown -> ipynb ===\n');
+
+const roundTrip = markdownToIpynb(markdown, notebook);
+console.log(`Round-trip notebook has ${roundTrip.cells.length} cells`);
+console.log('\nCell types:');
+roundTrip.cells.forEach((cell, i) => {
+  const preview = (Array.isArray(cell.source) ? cell.source.join('') : cell.source).slice(0, 50);
+  console.log(`  ${i}: ${cell.cell_type} - "${preview}..."`);
+});
+
+// Test 3: Verify JSON output
+console.log('\n=== Test 3: Serialize ===\n');
+const json = serializeIpynb(roundTrip);
+console.log(`Output JSON is ${json.length} bytes`);
+
+console.log('\n✅ All tests passed!');

package/test-notebook.ipynb

@@ -0,0 +1,116 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Test Notebook\n",
+    "\n",
+    "This is a test notebook for the Jupyter bridge.\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 1,
+   "metadata": {},
+   "source": [
+    "print(\"Hello from Jupyter!\")"
+   ],
+   "outputs": [
+    {
+     "output_type": "stream",
+     "name": "stdout",
+     "text": [
+      "Hello from Jupyter!"
+     ]
+    }
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 2,
+   "metadata": {},
+   "source": [
+    "x = 42\n",
+    "y = 100\n",
+    "print(f\"x = {x}\")\n",
+    "print(f\"y = {y}\")"
+   ],
+   "outputs": [
+    {
+     "output_type": "stream",
+     "name": "stdout",
+     "text": [
+      "x = 42\n",
+      "y = 100"
+     ]
+    }
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "\n",
+    "## Results\n",
+    "\n",
+    "The calculation results are shown above.\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 3,
+   "metadata": {},
+   "source": [
+    "# NEW CELL - added externally!\n",
+    "result = x + y\n",
+    "print(f\"Result: {result}\")"
+   ],
+   "outputs": [
+    {
+     "output_type": "stream",
+     "name": "stdout",
+     "text": [
+      "Result: 142"
+     ]
+    }
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "\n",
+    "### This section was added from Jupyter!\n",
+    "\n",
+    "## Added from MRMD!\n",
+    "\n",
+    "This paragraph was added by editing the markdown directly.\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "source": [
+    "# This cell was added from MRMD markdown!\n",
+    "z = result * 2\n",
+    "print(f\"Double the result: {z}\")"
+   ],
+   "outputs": []
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "name": "python",
+   "version": "3.10.0"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

package/test-notebook.md

@@ -0,0 +1,49 @@
+# Test Notebook
+
+This is a test notebook for the Jupyter bridge.
+
+```python
+print("Hello from Jupyter!")
+```
+
+```output:jupyter-1
+Hello from Jupyter!
+```
+
+```python
+x = 42
+y = 100
+print(f"x = {x}")
+print(f"y = {y}")
+```
+
+```output:jupyter-2
+x = 42
+y = 100
+```
+
+## Results
+
+The calculation results are shown above.
+
+```python
+# NEW CELL - added externally!
+result = x + y
+print(f"Result: {result}")
+```
+
+```output:jupyter-3
+Result: 142
+```
+
+### This section was added from Jupyter!
+
+## Added from MRMD!
+
+This paragraph was added by editing the markdown directly.
+
+```python
+# This cell was added from MRMD markdown!
+z = result * 2
+print(f"Double the result: {z}")
+```