@lopecode/channel 0.1.4 → 0.1.5

package/README.md

@@ -0,0 +1,205 @@
+# @lopecode/channel
+
+Pair program with Claude Code inside [Lopecode](https://tomlarkworthy.github.io/lopecode/) notebooks. An MCP server that bridges browser-based Observable notebooks and Claude Code via WebSocket, enabling real-time collaboration: chat, define cells, watch reactive variables, run tests, and manipulate the DOM — all from inside the notebook.
+
+## Quick Start
+
+```bash
+# Requires Bun (https://bun.sh)
+bun install -g @lopecode/channel
+claude mcp add lopecode bunx @lopecode/channel
+
+# Start Claude Code with channels enabled
+claude --dangerously-load-development-channels server:lopecode
+```
+
+Then ask Claude: **"Open a lopecode notebook"**
+
+Claude gets a pairing token, opens the notebook in your browser, and auto-connects. No manual setup needed.
+
+## What is Lopecode?
+
+Lopecode notebooks are self-contained HTML files built on the [Observable runtime](https://github.com/observablehq/runtime). Each notebook contains:
+
+- **Modules** — collections of reactive cells (code units)
+- **Embedded dependencies** — everything needed to run, in a single file
+- **A multi-panel UI** (lopepage) — view and edit multiple modules side by side
+
+The Observable runtime provides **reactive dataflow**: cells automatically recompute when their dependencies change, similar to a spreadsheet.
+
+## How Pairing Works
+
+```
+Browser (Notebook)  ←→  WebSocket  ←→  Channel Server (Bun)  ←→  MCP stdio  ←→  Claude Code
+```
+
+1. The channel server starts a local WebSocket server and generates a pairing token (`LOPE-PORT-XXXX`)
+2. Claude opens a notebook URL with `&cc=TOKEN` in the hash
+3. The notebook auto-connects to the WebSocket server
+4. Claude can now use MCP tools to interact with the live notebook
+
+## Observable Cell Syntax
+
+Lopecode cells use [Observable JavaScript](https://observablehq.com/@observablehq/observable-javascript) syntax. Here's what you need to know:
+
+### Named Cells
+
+```javascript
+// A cell is a named expression. It re-runs when dependencies change.
+x = 42
+greeting = `Hello, ${name}!`   // depends on the 'name' cell
+```
+
+### Markdown
+
+```javascript
+// Use the md tagged template literal for rich text
+md`# My Title
+
+Some **bold** text and a list:
+- Item 1
+- Item 2
+`
+```
+
+### HTML
+
+```javascript
+// Use htl.html for DOM elements
+htl.html`<div style="color: red">Hello</div>`
+```
+
+### Imports
+
+```javascript
+// Import from other modules in the notebook
+import {md} from "@tomlarkworthy/editable-md"
+import {chart} from "@tomlarkworthy/my-visualization"
+```
+
+### viewof — Interactive Inputs
+
+```javascript
+// viewof creates two cells:
+//   "viewof slider" — the DOM element (a range input)
+//   "slider" — the current value (a number)
+viewof slider = Inputs.range([0, 100], {label: "Value", value: 50})
+
+// Other cells can depend on the value
+doubled = slider * 2
+```
+
+Common inputs: `Inputs.range`, `Inputs.select`, `Inputs.text`, `Inputs.toggle`, `Inputs.button`, `Inputs.table`.
+
+### mutable — Imperative State
+
+```javascript
+// mutable allows imperative updates from other cells
+mutable counter = 0
+
+increment = {
+  mutable counter++;
+  return counter;
+}
+```
+
+### Generators — Streaming Values
+
+```javascript
+// Yield successive values over time
+ticker = {
+  let i = 0;
+  while (true) {
+    yield i++;
+    await Promises.delay(1000);
+  }
+}
+```
+
+### Block Cells
+
+```javascript
+// Use braces for multi-statement cells
+result = {
+  const data = await fetch("https://api.example.com/data").then(r => r.json());
+  const filtered = data.filter(d => d.value > 10);
+  return filtered;
+}
+```
+
+## Testing
+
+Lopecode uses a reactive testing pattern. Any cell named `test_*` is a test:
+
+```javascript
+test_addition = {
+  const result = add(2, 2);
+  if (result !== 4) throw new Error(`Expected 4, got ${result}`);
+  return "2 + 2 = 4";  // shown on success
+}
+
+test_greeting = {
+  if (typeof greeting !== "string") throw new Error("Expected string");
+  return `greeting is: ${greeting}`;
+}
+```
+
+Tests pass if they don't throw. Use `run_tests` to execute all `test_*` cells.
+
+## MCP Tools Reference
+
+| Tool | Description |
+|------|-------------|
+| `get_pairing_token` | Get the session pairing token |
+| `reply` | Send markdown to the notebook chat |
+| `define_cell` | **Primary tool.** Define a cell using Observable source code |
+| `list_cells` | List cells with names, inputs, and source |
+| `get_variable` | Read a runtime variable's current value |
+| `define_variable` | Low-level: define a variable with a function string |
+| `delete_variable` | Remove a variable |
+| `list_variables` | List all named variables |
+| `create_module` | Create a new empty module |
+| `delete_module` | Remove a module and all its variables |
+| `watch_variable` | Subscribe to reactive updates |
+| `unwatch_variable` | Unsubscribe from updates |
+| `run_tests` | Run all `test_*` cells |
+| `eval_code` | Run ephemeral JS in the browser (not persisted) |
+| `export_notebook` | Save the notebook to disk (persists cells) |
+| `fork_notebook` | Create a copy as a sibling HTML file |
+
+### Tool Usage Tips
+
+- **`define_cell`** is the main tool for creating content. It accepts Observable source and compiles it via the toolchain.
+- **`eval_code`** is for throwaway actions (DOM hacks, debugging). Effects are lost on reload.
+- **`define_variable`** is a low-level escape hatch — prefer `define_cell`.
+- Always specify `module` when targeting a specific module.
+- Use `export_notebook` after defining cells to persist them across reloads.
+
+## Typical Workflow
+
+```
+1. create_module("@tomlarkworthy/my-app")
+2. define_cell('import {md} from "@tomlarkworthy/editable-md"', module: "...")
+3. define_cell('title = md`# My App`', module: "...")
+4. define_cell('viewof name = Inputs.text({label: "Name"})', module: "...")
+5. define_cell('greeting = md`Hello, **${name}**!`', module: "...")
+6. export_notebook()  // persist to disk
+```
+
+## Starting from a Notebook
+
+If you see the `@tomlarkworthy/claude-code-pairing` panel in a notebook but Claude isn't connected:
+
+1. Install Bun: https://bun.sh
+2. Install the plugin: `bun install -g @lopecode/channel`
+3. Register with Claude: `claude mcp add lopecode bunx @lopecode/channel`
+4. Start Claude: `claude --dangerously-load-development-channels server:lopecode`
+5. Ask Claude to connect — it will provide a URL with an auto-connect token
+
+## Environment Variables
+
+- `LOPECODE_PORT` — WebSocket server port (default: random free port)
+
+## License
+
+MIT

package/claude-code-pairing-module.js

@@ -33,7 +33,7 @@ const _cc_module = function _cc_module(thisModule){return(
   thisModule()
 )};
 
-const _cc_ws = function _cc_ws(cc_config, cc_notebook_id, cc_status, cc_messages, viewof_cc_watches, summarizeJS, observe, realize, createModule, deleteModule, lookupVariable, cc_module, runtime, invalidation){return(
+const _cc_ws = function _cc_ws(cc_config, cc_notebook_id, cc_status, cc_messages, viewof_cc_watches, summarizeJS, observe, realize, compile, createModule, deleteModule, lookupVariable, exportToHTML, cc_module, runtime, invalidation){return(
 (function() {
   var port = cc_config.port, host = cc_config.host;
   var ws = null;
@@ -131,6 +131,51 @@ const _cc_ws = function _cc_ws(cc_config, cc_notebook_id, cc_status, cc_messages
         });
       }
 
+      case "define-cell": {
+        var source = cmd.params.source;
+        var moduleName = cmd.params.module;
+        var mod = findModule(runtime, moduleName);
+        if (!mod) return { ok: false, error: "Module not found: " + (moduleName || "default") };
+
+        try {
+          var compiled = compile(source);
+          if (!compiled || compiled.length === 0) return { ok: false, error: "Compilation returned no definitions" };
+
+          var definitions = [];
+          for (var ci = 0; ci < compiled.length; ci++) {
+            definitions.push(compiled[ci]._definition);
+          }
+
+          return realize(definitions, runtime).then(function(fns) {
+            var defined = [];
+            for (var di = 0; di < compiled.length; di++) {
+              var cellDef = compiled[di];
+              var fn = fns[di];
+              var cellName = cellDef._name;
+              var cellInputs = cellDef._inputs || [];
+
+              var existingVar = mod._scope.get(cellName);
+              if (existingVar) {
+                existingVar.define(cellName, cellInputs, fn);
+              } else {
+                mod.variable(ojs_observer ? ojs_observer(cellName) : {}).define(cellName, cellInputs, fn);
+              }
+              defined.push(cellName);
+
+              // Auto-watch non-internal variables
+              if (cellName && !cellName.startsWith("module ")) {
+                watchVariable(runtime, cellName, moduleName || null);
+              }
+            }
+            return { ok: true, result: { success: true, defined: defined, module: moduleName || "default" } };
+          }).catch(function(e) {
+            return { ok: false, error: "define-cell realize failed: " + e.message };
+          });
+        } catch (e) {
+          return { ok: false, error: "define-cell compile failed: " + e.message };
+        }
+      }
+
       case "delete-variable": {
         var name = cmd.params.name;
         var moduleName = cmd.params.module;
@@ -163,6 +208,28 @@ const _cc_ws = function _cc_ws(cc_config, cc_notebook_id, cc_status, cc_messages
         return { ok: true, result: variables };
       }
 
+      case "list-cells": {
+        var moduleName = cmd.params.module;
+        var targetModule = findModule(runtime, moduleName);
+        if (!targetModule) return { ok: false, error: "Module not found: " + (moduleName || "default") };
+        var cells = [];
+        for (var entry of targetModule._scope) {
+          var v = entry[1];
+          var defStr = "";
+          try { defStr = String(v._definition).slice(0, 300); } catch(e) {}
+          cells.push({
+            name: entry[0],
+            inputs: (v._inputs || []).map(function(inp) { return inp._name || "?"; }),
+            definition: defStr,
+            hasValue: v._value !== undefined,
+            hasError: v._error !== undefined,
+            error: v._error ? (v._error.message || String(v._error)) : undefined
+          });
+        }
+        cells.sort(function(a, b) { return a.name.localeCompare(b.name); });
+        return { ok: true, result: cells };
+      }
+
       case "run-tests": {
         var filter = cmd.params.filter;
         var timeout = cmd.params.timeout || 30000;
@@ -202,7 +269,7 @@ const _cc_ws = function _cc_ws(cc_config, cc_notebook_id, cc_status, cc_messages
       }
 
       case "fork": {
-        return handleFork(runtime);
+        return handleFork();
       }
 
       case "watch": {
@@ -413,24 +480,19 @@ const _cc_ws = function _cc_ws(cc_config, cc_notebook_id, cc_status, cc_messages
     return { ok: true, result: { unwatched_all: true, count: keys.length } };
   }
 
-  function handleFork(runtime) {
-    return new Promise(function(resolve) {
-      for (var v of runtime._variables) {
-        if ((v._name === "_exportToHTML" || v._name === "exportToHTML") && typeof v._value === "function") {
-          try {
-            Promise.resolve(v._value()).then(function(html) {
-              resolve({ ok: true, result: { html: html } });
-            }).catch(function(e) {
-              resolve({ ok: false, error: "Export failed: " + e.message });
-            });
-            return;
-          } catch (e) {
-            resolve({ ok: false, error: "Export failed: " + e.message });
-            return;
-          }
-        }
+  function handleFork() {
+    if (typeof exportToHTML !== "function") {
+      return { ok: false, error: "exportToHTML not available. Does this notebook include @tomlarkworthy/exporter-2?" };
+    }
+    return Promise.resolve(exportToHTML({ mains: runtime.mains })).then(function(result) {
+      // exportToHTML returns { source: string, report: object }
+      var html = typeof result === "string" ? result : result.source;
+      if (!html || typeof html !== "string") {
+        return { ok: false, error: "Export returned no HTML source" };
       }
-      resolve({ ok: false, error: "_exportToHTML not found. Does this notebook include @tomlarkworthy/exporter-2?" });
+      return { ok: true, result: { html: html } };
+    }).catch(function(e) {
+      return { ok: false, error: "Export failed: " + e.message };
     });
   }
 
@@ -599,38 +661,31 @@ const _cc_watch_table = function _cc_watch_table(cc_watches, Inputs){return(
   })
 )};
 
-const _cc_change_forwarder = function _cc_change_forwarder(cc_ws, invalidation){return(
+const _cc_change_forwarder = function _cc_change_forwarder(cc_ws, history, invalidation){return(
 (function() {
   var highWaterMark = 0;
   var initializing = true;
 
   var interval = setInterval(function() {
     if (!cc_ws.paired || !cc_ws.ws) return;
-    var runtime = window.__ojs_runtime;
-    if (!runtime) return;
+    if (!history || !Array.isArray(history)) return;
 
-    for (var v of runtime._variables) {
-      if (v._name === "history" && v._value && Array.isArray(v._value)) {
-        var history = v._value;
-        var total = history.length;
+    var total = history.length;
 
-        if (initializing) { highWaterMark = total; initializing = false; return; }
-        if (total <= highWaterMark) return;
+    if (initializing) { highWaterMark = total; initializing = false; return; }
+    if (total <= highWaterMark) return;
 
-        var newEntries = history.slice(highWaterMark).map(function(e) {
-          return {
-            t: e.t, op: e.op, module: e.module, _name: e._name,
-            _inputs: e._inputs,
-            _definition: typeof e._definition === "function"
-              ? e._definition.toString().slice(0, 500)
-              : String(e._definition || "").slice(0, 500)
-          };
-        });
-        highWaterMark = total;
-        cc_ws.ws.send(JSON.stringify({ type: "cell-change", changes: newEntries }));
-        break;
-      }
-    }
+    var newEntries = history.slice(highWaterMark).map(function(e) {
+      return {
+        t: e.t, op: e.op, module: e.module, _name: e._name,
+        _inputs: e._inputs,
+        _definition: typeof e._definition === "function"
+          ? e._definition.toString().slice(0, 500)
+          : String(e._definition || "").slice(0, 500)
+      };
+    });
+    highWaterMark = total;
+    cc_ws.ws.send(JSON.stringify({ type: "cell-change", changes: newEntries }));
   }, 1000);
 
   invalidation.then(function() { clearInterval(interval); });
@@ -677,7 +732,7 @@ const _cc_chat = function _cc_chat(cc_messages, cc_status, cc_ws, md, htl, Input
       '<code style="background:var(--theme-background-alt);padding:2px 6px;border-radius:3px;font-size:12px;">bun install -g @lopecode/channel</code><br>' +
       '<code style="background:var(--theme-background-alt);padding:2px 6px;border-radius:3px;font-size:12px;">claude mcp add lopecode bunx @lopecode/channel</code></li>' +
       '<li>Start Claude Code:<br><code style="background:var(--theme-background-alt);padding:2px 6px;border-radius:3px;font-size:12px;">claude --dangerously-load-development-channels server:lopecode</code></li>' +
-      '<li>Ask Claude to connect, or paste a pairing token above</li>' +
+      '<li>Ask Claude for a pairing token, then paste it above</li>' +
       '</ol>';
 
     var container = document.createElement("div");
@@ -875,13 +930,20 @@ export default function define(runtime, observer) {
   main.variable().define("cc_watches", ["Generators", "viewof cc_watches"], (G, v) => G.input(v));
   $def("_cc_module", "viewof cc_module", ["thisModule"], _cc_module);
   main.variable().define("cc_module", ["Generators", "viewof cc_module"], (G, v) => G.input(v));
-  $def("_cc_ws", "cc_ws", ["cc_config","cc_notebook_id","cc_status","cc_messages","viewof cc_watches","summarizeJS","observe","realize","createModule","deleteModule","lookupVariable","cc_module","runtime","invalidation"], _cc_ws);
-  $def("_cc_change_forwarder", "cc_change_forwarder", ["cc_ws","invalidation"], _cc_change_forwarder);
+  $def("_cc_ws", "cc_ws", ["cc_config","cc_notebook_id","cc_status","cc_messages","viewof cc_watches","summarizeJS","observe","realize","compile","createModule","deleteModule","lookupVariable","exportToHTML","cc_module","runtime","invalidation"], _cc_ws);
+  $def("_cc_change_forwarder", "cc_change_forwarder", ["cc_ws","history","invalidation"], _cc_change_forwarder);
 
   // Imports
   main.define("module @tomlarkworthy/module-map", async () => runtime.module((await import("/@tomlarkworthy/module-map.js?v=4")).default));
   main.define("currentModules", ["module @tomlarkworthy/module-map", "@variable"], (_, v) => v.import("currentModules", _));
   main.define("moduleMap", ["module @tomlarkworthy/module-map", "@variable"], (_, v) => v.import("moduleMap", _));
+  main.define("module @tomlarkworthy/exporter-2", async () => runtime.module((await import("/@tomlarkworthy/exporter-2.js?v=4")).default));
+  main.define("exportToHTML", ["module @tomlarkworthy/exporter-2", "@variable"], (_, v) => v.import("exportToHTML", _));
+  main.define("module @tomlarkworthy/observablejs-toolchain", async () => runtime.module((await import("/@tomlarkworthy/observablejs-toolchain.js?v=4")).default));
+  main.define("compile", ["module @tomlarkworthy/observablejs-toolchain", "@variable"], (_, v) => v.import("compile", _));
+  main.define("module @tomlarkworthy/local-change-history", async () => runtime.module((await import("/@tomlarkworthy/local-change-history.js?v=4")).default));
+  main.define("viewof history", ["module @tomlarkworthy/local-change-history", "@variable"], (_, v) => v.import("viewof history", _));
+  main.define("history", ["Generators", "viewof history"], (G, v) => G.input(v));
   main.define("module @tomlarkworthy/runtime-sdk", async () => runtime.module((await import("/@tomlarkworthy/runtime-sdk.js?v=4")).default));
   main.define("viewof runtime_variables", ["module @tomlarkworthy/runtime-sdk", "@variable"], (_, v) => v.import("viewof runtime_variables", _));
   main.define("runtime_variables", ["module @tomlarkworthy/runtime-sdk", "@variable"], (_, v) => v.import("runtime_variables", _));

package/lopecode-channel.ts

@@ -60,6 +60,8 @@ const mcp = new Server(
     },
     instructions: `You are connected to Lopecode notebooks via the lopecode channel.
 
+Lopecode notebooks are self-contained HTML files built on the Observable runtime. Each notebook contains modules (collections of reactive cells). The Observable runtime provides reactive dataflow: cells automatically recompute when their dependencies change, like a spreadsheet.
+
 ## Starting a lopecode notebook
 
 When the user asks to start/open a lopecode notebook, or start a pairing/collaboration session:
@@ -71,6 +73,72 @@ When the user asks to start/open a lopecode notebook, or start a pairing/collabo
 
 If channels are not enabled, tell the user to restart with: claude --channels server:lopecode
 
+## Observable Cell Syntax
+
+Cells use Observable JavaScript. The define_cell tool accepts this syntax directly.
+
+### Named cells
+x = 42
+greeting = \`Hello, \${name}!\`   // depends on 'name' cell — auto-recomputes when name changes
+
+### Markdown
+md\`# Title\nSome **bold** text\`
+
+### HTML
+htl.html\`<div style="color: red">Hello</div>\`
+
+### Imports (from other modules in the notebook)
+import {md} from "@tomlarkworthy/editable-md"
+import {chart, data} from "@tomlarkworthy/my-viz"
+
+### viewof — interactive inputs (creates TWO cells: "viewof X" for DOM, "X" for value)
+viewof slider = Inputs.range([0, 100], {label: "Value", value: 50})
+viewof name = Inputs.text({label: "Name"})
+viewof choice = Inputs.select(["a", "b", "c"])
+
+### mutable — imperative state
+mutable counter = 0
+// Other cells can do: mutable counter++
+
+### Block cells (multi-statement)
+result = {
+  const data = await fetch(url).then(r => r.json());
+  return data.filter(d => d.value > 10);
+}
+
+### Generator cells (streaming values)
+ticker = {
+  let i = 0;
+  while (true) { yield i++; await Promises.delay(1000); }
+}
+
+## Testing
+
+Any cell named test_* is a test. It passes if it doesn't throw:
+test_addition = {
+  if (add(2, 2) !== 4) throw new Error("Expected 4");
+  return "2 + 2 = 4";
+}
+
+Use run_tests to execute all test_* cells.
+
+## Typical workflow
+
+1. create_module("@tomlarkworthy/my-app")
+2. define_cell('import {md} from "@tomlarkworthy/editable-md"', module: "...")
+3. define_cell('title = md\`# My App\`', module: "...")
+4. define_cell('viewof name = Inputs.text({label: "Name"})', module: "...")
+5. define_cell('greeting = md\`Hello, **\${name}**!\`', module: "...")
+6. export_notebook() to persist cells to disk
+
+## Tool guidance
+
+- define_cell: PRIMARY tool for creating content. Accepts Observable source, compiles via toolchain. Use for almost everything.
+- eval_code: For throwaway/ephemeral actions (DOM hacks, debugging, location.reload()). Lost on reload. NEVER use define_cell for one-off side effects.
+- define_variable: Low-level escape hatch with explicit function string + inputs array. Rarely needed.
+- export_notebook: Persists all runtime state to the HTML file. Call after defining cells so they survive reloads.
+- fork_notebook: Creates a sibling HTML copy (checkpoint).
+
 ## Message formats
 
 User chat messages:
@@ -86,16 +154,6 @@ Lifecycle:
 Variable updates (when watching):
   <channel source="lopecode" type="variable_update" notebook="..." name="varName" module="@author/mod">value</channel>
 
-## Tools
-
-- reply: Send markdown to notebook chat
-- get_variable / define_variable / delete_variable / list_variables: Interact with runtime
-- create_module / delete_module: Create or remove modules (registered in runtime.mains, visible in moduleMap)
-- watch_variable / unwatch_variable: Subscribe to reactive variable updates
-- run_tests: Run test_* variables
-- eval_code: Evaluate JS in browser context
-- fork_notebook: Create a copy as sibling HTML file
-
 IMPORTANT: Always specify the module parameter when calling define_variable, get_variable, etc.
 Use the currentModules watch to identify the user's content module (not lopepage, module-selection, or claude-code-pairing).
 When multiple notebooks are connected, specify notebook_id (the URL). When only one is connected, it's used automatically.`,
@@ -192,6 +250,24 @@ mcp.setRequestHandler(ListToolsRequestSchema, async () => ({
         required: ["name", "definition"],
       },
     },
+    {
+      name: "define_cell",
+      description:
+        "Define a cell using Observable source code. Supports full Observable syntax including imports (e.g. 'import {md} from \"@tomlarkworthy/editable-md\"'), named cells ('x = 42'), markdown ('md`# Hello`'), viewof, mutable, etc. The source is compiled via the Observable toolchain and may produce multiple runtime variables.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          notebook_id: { type: "string" },
+          source: {
+            type: "string",
+            description:
+              'Observable source code, e.g. \'import {md} from "@tomlarkworthy/editable-md"\' or \'x = 42\'',
+          },
+          module: { type: "string", description: "Target module name (optional)" },
+        },
+        required: ["source"],
+      },
+    },
     {
       name: "delete_variable",
       description: "Delete a variable from the runtime.",
@@ -216,6 +292,22 @@ mcp.setRequestHandler(ListToolsRequestSchema, async () => ({
         },
       },
     },
+    {
+      name: "list_cells",
+      description:
+        "List all cells in a module with their names, inputs, and definition source. More detailed than list_variables — shows the cell's dependency inputs and function definition.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          notebook_id: { type: "string" },
+          module: {
+            type: "string",
+            description: "Module name (required)",
+          },
+        },
+        required: ["module"],
+      },
+    },
     {
       name: "run_tests",
       description: "Run test_* variables and return results.",
@@ -240,6 +332,16 @@ mcp.setRequestHandler(ListToolsRequestSchema, async () => ({
         required: ["code"],
       },
     },
+    {
+      name: "export_notebook",
+      description: "Export/save the notebook in place. Serializes the current runtime state (all modules, cells, file attachments) back to the HTML file, overwriting it. Use this to persist cells created via define_cell.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          notebook_id: { type: "string" },
+        },
+      },
+    },
     {
       name: "fork_notebook",
       description: "Create a copy of the notebook as a sibling HTML file. Returns the new file path.",
@@ -348,6 +450,10 @@ mcp.setRequestHandler(CallToolRequestSchema, async (req) => {
         };
         break;
       }
+      case "define_cell":
+        action = "define-cell";
+        params = { source: args.source, module: args.module || null };
+        break;
       case "delete_variable":
         action = "delete-variable";
         params = { name: args.name, module: args.module || null };
@@ -356,6 +462,10 @@ mcp.setRequestHandler(CallToolRequestSchema, async (req) => {
         action = "list-variables";
         params = { module: args.module || null };
         break;
+      case "list_cells":
+        action = "list-cells";
+        params = { module: args.module };
+        break;
       case "run_tests":
         action = "run-tests";
         timeout = (args.timeout as number) || 30000;
@@ -370,6 +480,11 @@ mcp.setRequestHandler(CallToolRequestSchema, async (req) => {
         timeout = 120000;
         params = { suffix: args.suffix || null };
         break;
+      case "export_notebook":
+        action = "fork";
+        timeout = 120000;
+        params = { _save_in_place: true };
+        break;
       case "create_module":
         action = "create-module";
         params = { name: args.name };
@@ -398,13 +513,27 @@ mcp.setRequestHandler(CallToolRequestSchema, async (req) => {
 
     // Fork special handling: write the HTML to disk
     if (action === "fork" && result.result?.html) {
-      const originalUrl = target.url;
+      // Strip hash and query fragments before extracting the file path
+      const originalUrl = target.url.split("#")[0].split("?")[0];
       let originalPath: string;
       if (originalUrl.startsWith("file://")) {
         originalPath = decodeURIComponent(originalUrl.replace("file://", ""));
       } else {
         originalPath = originalUrl;
       }
+      if (params._save_in_place) {
+        // Export: overwrite the original file
+        const html = result.result.html;
+        const htmlStr = typeof html === "string" ? html : String(html);
+        if (typeof html !== "string") {
+          console.error(`[export] WARNING: html is ${typeof html}, keys: ${html && typeof html === "object" ? Object.keys(html).join(",") : "N/A"}`);
+        }
+        if (htmlStr.length < 1000) {
+          return { content: [{ type: "text", text: `Export failed: HTML content too small (${htmlStr.length} bytes). Type was: ${typeof html}` }], isError: true };
+        }
+        await Bun.write(originalPath, htmlStr);
+        return { content: [{ type: "text", text: `Exported to ${originalPath} (${(htmlStr.length / 1024 / 1024).toFixed(2)} MB)` }] };
+      }
       const dir = dirname(originalPath);
       const base = basename(originalPath, ".html");
       const suffix = params.suffix || Date.now().toString();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lopecode/channel",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "description": "Pair program with Claude inside Lopecode notebooks. MCP server bridging browser notebooks and Claude Code.",
   "type": "module",
   "bin": {
@@ -10,7 +10,8 @@
   "files": [
     "lopecode-channel.ts",
     "claude-code-pairing-module.js",
-    "sync-module.ts"
+    "sync-module.ts",
+    "README.md"
   ],
   "keywords": [
     "mcp",

package/sync-module.ts

@@ -126,8 +126,9 @@ function inject(
   const existing = html.match(scriptPattern);
 
   if (existing) {
-    // Replace in-place using string replacement (preserves backslashes)
-    html = html.replace(existing[0], scriptBlock);
+    // Replace in-place using indexOf+slice (avoids $ interpretation in String.replace)
+    const idx = html.indexOf(existing[0]);
+    html = html.slice(0, idx) + scriptBlock + html.slice(idx + existing[0].length);
     console.log(`Updated existing ${moduleId} module`);
   } else {
     // Insert before bootloader
@@ -141,84 +142,11 @@ function inject(
     console.log(`Inserted new ${moduleId} module`);
   }
 
-  // Ensure module is in bootconf.json mains
-  html = ensureBootconf(html, moduleId);
-
   writeFileSync(targetPath, html);
   const size = (html.length / 1024 / 1024).toFixed(2);
   console.log(`Wrote ${targetPath} (${size} MB)`);
 }
 
-function ensureBootconf(html: string, moduleId: string): string {
-  const bootconfPattern = 'id="bootconf.json"';
-  let bootconfScriptStart = html.lastIndexOf(bootconfPattern);
-  if (bootconfScriptStart === -1) {
-    console.warn("Could not find bootconf.json — skipping mains/hash update");
-    return html;
-  }
-
-  const next200 = html.substring(
-    bootconfScriptStart,
-    bootconfScriptStart + 200
-  );
-  if (!next200.includes("application/json")) {
-    console.warn(
-      "Found bootconf.json but it's not application/json — skipping"
-    );
-    return html;
-  }
-
-  const bootconfContentStart = html.indexOf(">", bootconfScriptStart) + 1;
-  const bootconfContentEnd = html.indexOf("</script>", bootconfContentStart);
-  const bootconfContent = html.slice(bootconfContentStart, bootconfContentEnd);
-
-  try {
-    const bootconf = JSON.parse(bootconfContent);
-
-    // Add to mains if missing
-    if (!bootconf.mains.includes(moduleId)) {
-      bootconf.mains.push(moduleId);
-    }
-
-    // Update hash to include module in layout
-    const currentHash: string = bootconf.hash || "";
-    if (!currentHash.includes(moduleId.split("/").pop()!)) {
-      const modulePattern = /S(\d+)\(([^)]+)\)/g;
-      const moduleRefs: { weight: number; module: string }[] = [];
-      let m;
-      while ((m = modulePattern.exec(currentHash)) !== null) {
-        moduleRefs.push({ weight: parseInt(m[1]), module: m[2] });
-      }
-
-      if (moduleRefs.length > 0) {
-        const totalWeight = moduleRefs.reduce((sum, r) => sum + r.weight, 0);
-        const scaled = moduleRefs.map((r) => ({
-          weight: Math.round((r.weight / totalWeight) * 75),
-          module: r.module,
-        }));
-        scaled.push({ weight: 25, module: moduleId });
-        const parts = scaled
-          .map((r) => `S${r.weight}(${r.module})`)
-          .join(",");
-        bootconf.hash = `#view=R100(${parts})`;
-      } else {
-        bootconf.hash = `#view=R100(S75(@tomlarkworthy/debugger),S25(${moduleId}))`;
-      }
-    }
-
-    const newBootconfContent =
-      "\n" + JSON.stringify(bootconf, null, 2) + "\n";
-    html =
-      html.slice(0, bootconfContentStart) +
-      newBootconfContent +
-      html.slice(bootconfContentEnd);
-  } catch (e: any) {
-    console.warn("Failed to parse bootconf.json:", e.message);
-  }
-
-  return html;
-}
-
 function extractToJs(targetPath: string, moduleId: string, jsPath: string): void {
   const html = readFileSync(targetPath, "utf8");
   const content = extractModuleContent(html, moduleId);