stagecraft 0.1.0

package/bin/lib/edit-ops.js

@@ -0,0 +1,405 @@
+'use strict';
+
+/**
+ * Edit operations on stagecraft slide files.
+ *
+ * - writeSlideNote(root, file, text)     — write @note: comment above Stage.register(
+ * - writeElementNote(root, file, key, t) — write @note[stage-key=...]: comment above register
+ * - writeInlineEdit(root, file, path, v) — AST-aware: replace string literal at prop path
+ * - reorderManifest(root, newOrder)      — rewrite stagecraft.config.js slides array
+ * - setManifestTransition(root, idx, t)  — set transition on slide at idx in manifest
+ */
+
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { parse } from '@babel/parser';
+import _traverseMod from '@babel/traverse';
+import _generateMod from '@babel/generator';
+import * as t from '@babel/types';
+
+const traverse = _traverseMod.default || _traverseMod;
+const generate = _generateMod.default || _generateMod;
+
+function resolveFile(root, file) {
+  // file may already be absolute or relative
+  const p = path.isAbsolute(file) ? file : path.resolve(root, file);
+  if (!p.startsWith(root)) throw new Error('refused: file outside project root');
+  return p;
+}
+
+function parseFile(src) {
+  return parse(src, {
+    sourceType: 'unambiguous',
+    plugins: [],
+    errorRecovery: false
+  });
+}
+
+function regenerate(ast, src) {
+  // Use retainLines+compact:false to preserve formatting as much as possible
+  return generate(ast, { retainLines: false, compact: false, jsescOption: { minimal: true } }, src).code;
+}
+
+// ---------------------------------------------------------------------------
+// Slide-level note: insert/replace `// @note: ...` immediately above the first
+// Stage.register(...) call. Multi-line note becomes consecutive comment lines.
+// ---------------------------------------------------------------------------
+export async function writeSlideNote(root, file, text) {
+  const p = resolveFile(root, file);
+  let src = await fs.readFile(p, 'utf8');
+  src = removeNoteComments(src, /\/\/\s*@note:\s*[\s\S]*?(?=\n[^/]|\nStage\.register|\nStage\.\w+\()/g);
+  src = removeSimpleNoteLines(src);
+  const noteLines = String(text).split(/\r?\n/).map(l => `// @note: ${l}`).join('\n');
+  // Find first occurrence of "Stage.register(" or "stage.register(" or "Stage.<Cap>(" used as register arg
+  const m = src.match(/(^|\n)([ \t]*)(Stage\.register\s*\()/);
+  if (!m) {
+    // Prepend at top of file (after first comment block if any)
+    src = noteLines + '\n' + src;
+  } else {
+    const indent = m[2];
+    const noteWithIndent = noteLines.split('\n').map(l => indent + l).join('\n');
+    const insertion = (m[1] === '\n' ? '\n' : '') + noteWithIndent + '\n';
+    src = src.slice(0, m.index + (m[1] === '\n' ? 1 : 0))
+      + noteWithIndent + '\n'
+      + src.slice(m.index + (m[1] === '\n' ? 1 : 0));
+  }
+  await fs.writeFile(p, src, 'utf8');
+}
+
+function removeSimpleNoteLines(src) {
+  // Remove standalone "// @note: ..." lines (single-line form)
+  return src.split('\n').filter(l => !/^\s*\/\/\s*@note(\[|:)/.test(l)).join('\n');
+}
+
+function removeNoteComments(src) {
+  // Generic removal of any line starting with // @note ... (covers Level 1 + 2)
+  return removeSimpleNoteLines(src);
+}
+
+// ---------------------------------------------------------------------------
+// Element-pin note: `// @note[stage-key="K"]: text` placed above Stage.register
+// ---------------------------------------------------------------------------
+export async function writeElementNote(root, file, stageKey, text) {
+  const p = resolveFile(root, file);
+  let src = await fs.readFile(p, 'utf8');
+  // Remove any existing note for this same key
+  const escKey = stageKey.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const existingRe = new RegExp(`^\\s*//\\s*@note\\[stage-key=\\"${escKey}\\"\\]:.*$`, 'gm');
+  src = src.replace(existingRe, '');
+  // Build new note
+  const noteLines = String(text).split(/\r?\n/).map((l, i) =>
+    i === 0
+      ? `// @note[stage-key="${stageKey}"]: ${l}`
+      : `// @note[stage-key="${stageKey}"]: ${l}`
+  ).join('\n');
+  const m = src.match(/(^|\n)([ \t]*)(Stage\.register\s*\()/);
+  if (!m) {
+    src = noteLines + '\n' + src;
+  } else {
+    const indent = m[2];
+    const noteWithIndent = noteLines.split('\n').map(l => indent + l).join('\n');
+    src = src.slice(0, m.index + (m[1] === '\n' ? 1 : 0))
+      + noteWithIndent + '\n'
+      + src.slice(m.index + (m[1] === '\n' ? 1 : 0));
+  }
+  // Clean up double blank lines
+  src = src.replace(/\n{3,}/g, '\n\n');
+  await fs.writeFile(p, src, 'utf8');
+}
+
+// ---------------------------------------------------------------------------
+// Inline edit: parse the file, find the Stage.<Component>({...}) call argument
+// (the props object), navigate the propPath, replace the string literal.
+//
+// propPath examples:
+//   "lines[0].text"
+//   "items[2].name"
+//   "title"
+//   "left.items[1]"
+// ---------------------------------------------------------------------------
+export async function writeInlineEdit(root, file, propPath, value) {
+  const p = resolveFile(root, file);
+  const src = await fs.readFile(p, 'utf8');
+  const ast = parseFile(src);
+
+  const tokens = parsePropPath(propPath);
+  let updated = false;
+  let error = null;
+
+  traverse(ast, {
+    CallExpression(pathNode) {
+      if (updated) return;
+      const callee = pathNode.node.callee;
+      // Match Stage.register(Stage.X({...})) or Stage.X({...}) directly
+      // We want to find the deepest ObjectExpression that's an argument to
+      // a Stage.<Component>(...) call or the argument of Stage.register({...})
+      const targetObj = findPropsObject(pathNode.node);
+      if (!targetObj) return;
+
+      // Try to navigate the propPath
+      try {
+        const node = navigatePath(targetObj, tokens);
+        if (!node) return;
+        if (!t.isStringLiteral(node) && !t.isTemplateLiteral(node)) {
+          error = new Error(`prop path "${propPath}" does not resolve to a string literal (got ${node.type})`);
+          return;
+        }
+        if (t.isTemplateLiteral(node) && (node.expressions.length > 0 || node.quasis.length !== 1)) {
+          error = new Error(`prop path "${propPath}" is an interpolated template literal — cannot inline-edit`);
+          return;
+        }
+        // Replace the value
+        if (t.isStringLiteral(node)) {
+          node.value = String(value);
+        } else {
+          // single-quasi template literal
+          node.quasis[0].value.raw = String(value);
+          node.quasis[0].value.cooked = String(value);
+        }
+        updated = true;
+      } catch (e) {
+        // path doesn't apply here, continue to next call
+      }
+    }
+  });
+
+  if (error) throw error;
+  if (!updated) throw new Error(`no matching call/prop path "${propPath}" found in ${file}`);
+
+  const out = regenerate(ast, src);
+  await fs.writeFile(p, out, 'utf8');
+}
+
+function findPropsObject(callNode) {
+  // Common shapes:
+  //   Stage.register({...})           → args[0] is the obj
+  //   Stage.register(Stage.X({...}))  → args[0].arguments[0] is the obj
+  //   Stage.X({...})                  → args[0] is the obj  (when matched independently)
+  const callee = callNode.callee;
+  if (!t.isMemberExpression(callee)) return null;
+  const obj = callee.object;
+  const prop = callee.property;
+  if (!t.isIdentifier(obj) || obj.name !== 'Stage') return null;
+  if (!t.isIdentifier(prop)) return null;
+
+  // Stage.register(...)
+  if (prop.name === 'register') {
+    const arg = callNode.arguments[0];
+    if (!arg) return null;
+    if (t.isObjectExpression(arg)) return arg;
+    if (t.isCallExpression(arg)) {
+      // nested Stage.X({...}) — recurse
+      return findPropsObject(arg);
+    }
+    return null;
+  }
+  // Stage.X(...) where X starts with an uppercase
+  if (/^[A-Z]/.test(prop.name)) {
+    const arg = callNode.arguments[0];
+    if (arg && t.isObjectExpression(arg)) return arg;
+  }
+  return null;
+}
+
+function parsePropPath(p) {
+  // 'a.b[2].c' → ['a', 'b', 2, 'c']
+  const tokens = [];
+  const re = /([a-zA-Z_$][\w$]*)|\[(\d+)\]/g;
+  let m;
+  while ((m = re.exec(p)) !== null) {
+    if (m[1] !== undefined) tokens.push(m[1]);
+    else tokens.push(Number(m[2]));
+  }
+  return tokens;
+}
+
+function navigatePath(node, tokens) {
+  let cur = node;
+  for (const tok of tokens) {
+    if (typeof tok === 'string') {
+      if (!t.isObjectExpression(cur)) return null;
+      const prop = cur.properties.find(p =>
+        (t.isObjectProperty(p) || t.isObjectMethod(p)) &&
+        ((t.isIdentifier(p.key) && p.key.name === tok) ||
+         (t.isStringLiteral(p.key) && p.key.value === tok))
+      );
+      if (!prop || !t.isObjectProperty(prop)) return null;
+      cur = prop.value;
+    } else {
+      if (!t.isArrayExpression(cur)) return null;
+      if (tok < 0 || tok >= cur.elements.length) return null;
+      cur = cur.elements[tok];
+    }
+  }
+  return cur;
+}
+
+// ---------------------------------------------------------------------------
+// Manifest operations
+// ---------------------------------------------------------------------------
+
+async function readManifest(root) {
+  const p = path.resolve(root, 'stagecraft.config.js');
+  return { path: p, src: await fs.readFile(p, 'utf8') };
+}
+
+async function rewriteManifest(p, src, mutator) {
+  const ast = parseFile(src);
+  let updated = false;
+  traverse(ast, {
+    CallExpression(pathNode) {
+      const callee = pathNode.node.callee;
+      if (!t.isMemberExpression(callee)) return;
+      if (!t.isIdentifier(callee.object, { name: 'Stage' })) return;
+      if (!t.isIdentifier(callee.property, { name: 'deck' })) return;
+      const arg = pathNode.node.arguments[0];
+      if (!arg || !t.isObjectExpression(arg)) return;
+      const slidesProp = arg.properties.find(p =>
+        t.isObjectProperty(p) && t.isIdentifier(p.key, { name: 'slides' })
+      );
+      if (!slidesProp || !t.isArrayExpression(slidesProp.value)) return;
+      mutator(slidesProp.value);
+      updated = true;
+    }
+  });
+  if (!updated) throw new Error('no Stage.deck({ slides: [...] }) call found in manifest');
+  await fs.writeFile(p, regenerate(ast, src), 'utf8');
+}
+
+export async function reorderManifest(root, newOrder) {
+  const { path: p, src } = await readManifest(root);
+  await rewriteManifest(p, src, arr => {
+    const original = arr.elements.slice();
+    arr.elements = newOrder.map(i => original[i]).filter(Boolean);
+  });
+}
+
+export async function setManifestTransition(root, idx, transition) {
+  const { path: p, src } = await readManifest(root);
+  await rewriteManifest(p, src, arr => {
+    const target = arr.elements[idx];
+    if (!target || !t.isObjectExpression(target)) {
+      throw new Error('manifest entry at ' + idx + ' is not an object');
+    }
+    const existing = target.properties.find(pr =>
+      t.isObjectProperty(pr) && t.isIdentifier(pr.key, { name: 'transition' })
+    );
+    const valueNode = t.stringLiteral(String(transition));
+    if (existing) existing.value = valueNode;
+    else target.properties.push(t.objectProperty(t.identifier('transition'), valueNode));
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Theme — update the top-level `theme:` prop on Stage.deck({...})
+// ---------------------------------------------------------------------------
+export async function setManifestTheme(root, theme) {
+  const { path: p, src } = await readManifest(root);
+  const ast = parseFile(src);
+  let updated = false;
+  traverse(ast, {
+    CallExpression(pathNode) {
+      const callee = pathNode.node.callee;
+      if (!t.isMemberExpression(callee)) return;
+      if (!t.isIdentifier(callee.object, { name: 'Stage' })) return;
+      if (!t.isIdentifier(callee.property, { name: 'deck' })) return;
+      const arg = pathNode.node.arguments[0];
+      if (!arg || !t.isObjectExpression(arg)) return;
+      const themeProp = arg.properties.find(pr =>
+        t.isObjectProperty(pr) && t.isIdentifier(pr.key, { name: 'theme' })
+      );
+      const valueNode = t.stringLiteral(String(theme));
+      if (themeProp) themeProp.value = valueNode;
+      else arg.properties.unshift(t.objectProperty(t.identifier('theme'), valueNode));
+      updated = true;
+    }
+  });
+  if (!updated) throw new Error('no Stage.deck({...}) call found');
+  await fs.writeFile(p, regenerate(ast, src), 'utf8');
+}
+
+// ---------------------------------------------------------------------------
+// CRUD: add / remove a slide entry in the manifest
+// ---------------------------------------------------------------------------
+export async function addSlideToManifest(root, atIdx, srcPath, transition) {
+  const { path: p, src } = await readManifest(root);
+  await rewriteManifest(p, src, arr => {
+    const props = [t.objectProperty(t.identifier('src'), t.stringLiteral(String(srcPath)))];
+    if (transition) {
+      props.push(t.objectProperty(t.identifier('transition'), t.stringLiteral(String(transition))));
+    }
+    const newEntry = t.objectExpression(props);
+    const insertAt = typeof atIdx === 'number'
+      ? Math.max(0, Math.min(arr.elements.length, atIdx))
+      : arr.elements.length;
+    arr.elements.splice(insertAt, 0, newEntry);
+  });
+}
+
+export async function removeSlideFromManifest(root, idx) {
+  const { path: p, src } = await readManifest(root);
+  await rewriteManifest(p, src, arr => {
+    if (idx < 0 || idx >= arr.elements.length) {
+      throw new Error('slide index out of range: ' + idx);
+    }
+    arr.elements.splice(idx, 1);
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Speaker notes — update the second arg of Stage.register(slide, { notes: ... })
+// Creates the meta arg if missing.
+// ---------------------------------------------------------------------------
+export async function writeSpeakerNotes(root, file, notes) {
+  const p = resolveFile(root, file);
+  const src = await fs.readFile(p, 'utf8');
+  const ast = parseFile(src);
+  let updated = false;
+
+  traverse(ast, {
+    CallExpression(pathNode) {
+      if (updated) return;
+      const callee = pathNode.node.callee;
+      if (!t.isMemberExpression(callee)) return;
+      if (!t.isIdentifier(callee.object, { name: 'Stage' })) return;
+      if (!t.isIdentifier(callee.property, { name: 'register' })) return;
+
+      let meta = pathNode.node.arguments[1];
+      const value = t.stringLiteral(String(notes));
+      if (!meta) {
+        meta = t.objectExpression([t.objectProperty(t.identifier('notes'), value)]);
+        pathNode.node.arguments.push(meta);
+      } else if (t.isObjectExpression(meta)) {
+        const existing = meta.properties.find(pr =>
+          t.isObjectProperty(pr) && t.isIdentifier(pr.key, { name: 'notes' })
+        );
+        if (existing) existing.value = value;
+        else meta.properties.push(t.objectProperty(t.identifier('notes'), value));
+      } else {
+        // The 2nd arg is something we don't understand — refuse to mutate.
+        throw new Error('Stage.register 2nd arg is not an object literal');
+      }
+      updated = true;
+    }
+  });
+
+  if (!updated) throw new Error('no Stage.register(...) call found in ' + file);
+  await fs.writeFile(p, regenerate(ast, src), 'utf8');
+}
+
+// ---------------------------------------------------------------------------
+// Element-pin notes — scan a slide file for `@note[stage-key="..."]:` comments
+// and return them as { stageKey, text } objects. Used by present-mode to
+// render pin markers on the slide.
+// ---------------------------------------------------------------------------
+export async function readElementNotes(root, file) {
+  const p = resolveFile(root, file);
+  const src = await fs.readFile(p, 'utf8');
+  const re = /^\s*\/\/\s*@note\[stage-key="([^"]+)"\]:\s*(.*)$/gm;
+  const out = [];
+  let m;
+  while ((m = re.exec(src)) !== null) {
+    out.push({ stageKey: m[1], text: m[2].trim() });
+  }
+  return out;
+}

package/bin/serve.js

@@ -0,0 +1,278 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * stagecraft serve — local dev server with hot reload + edit-mode API.
+ *
+ * Serves the project directory over HTTP, opens a WebSocket on
+ * /stagecraft for the browser to talk to. Endpoints:
+ *
+ *   POST /api/note/slide          { file, text }
+ *   POST /api/note/element        { file, stageKey, text }
+ *   POST /api/edit/inline         { file, propPath, value }
+ *   POST /api/manifest/reorder    { newOrder: [oldIdx, ...] }
+ *   POST /api/manifest/transition { idx, transition }
+ *
+ * Watches all source files; broadcasts granular reload events.
+ */
+
+import http from 'node:http';
+import fs from 'node:fs';
+import path from 'node:path';
+import url from 'node:url';
+import { WebSocketServer } from 'ws';
+import chokidar from 'chokidar';
+import mime from 'mime-types';
+
+import {
+  writeSlideNote, writeElementNote, writeInlineEdit,
+  reorderManifest, setManifestTransition, setManifestTheme,
+  addSlideToManifest, removeSlideFromManifest,
+  writeSpeakerNotes, readElementNotes
+} from './lib/edit-ops.js';
+import fsp from 'node:fs/promises';
+
+// --- args ---
+const args = process.argv.slice(2);
+let rootArg = '.';
+let port = 3000;
+for (let i = 0; i < args.length; i++) {
+  if (args[i] === '--root') rootArg = args[++i];
+  else if (args[i] === '--port') port = parseInt(args[++i], 10);
+}
+const ROOT = path.resolve(rootArg);
+
+if (!fs.existsSync(ROOT)) {
+  console.error(`[stagecraft] root directory not found: ${ROOT}`);
+  process.exit(1);
+}
+
+console.log(`[stagecraft] serving ${ROOT}`);
+
+// --- HTTP server ---
+const server = http.createServer(async (req, res) => {
+  try {
+    const parsed = url.parse(req.url, true);
+    if (req.method === 'POST' && parsed.pathname.startsWith('/api/')) {
+      return handleApi(req, res, parsed);
+    }
+    return serveStatic(req, res, parsed);
+  } catch (e) {
+    console.error('[stagecraft] error', e);
+    res.statusCode = 500;
+    res.end('Internal error');
+  }
+});
+
+// --- WebSocket ---
+const wss = new WebSocketServer({ noServer: true });
+const clients = new Set();
+
+server.on('upgrade', (req, socket, head) => {
+  if (req.url !== '/stagecraft') {
+    socket.destroy();
+    return;
+  }
+  // Refuse non-loopback
+  const addr = req.socket.remoteAddress;
+  if (!isLoopback(addr)) {
+    socket.destroy();
+    return;
+  }
+  wss.handleUpgrade(req, socket, head, ws => {
+    clients.add(ws);
+    ws.on('close', () => clients.delete(ws));
+    ws.send(JSON.stringify({ type: 'hello' }));
+  });
+});
+
+function broadcast(msg) {
+  const s = JSON.stringify(msg);
+  clients.forEach(c => { if (c.readyState === 1) c.send(s); });
+}
+
+// --- File watching ---
+const watcher = chokidar.watch(['slides/**/*.js', 'stagecraft.config.js', 'index.html', '../themes/**/*.css'], {
+  cwd: ROOT,
+  ignored: /node_modules/,
+  ignoreInitial: true
+});
+watcher.on('all', (event, filePath) => {
+  const ext = path.extname(filePath);
+  let target = 'slide';
+  if (filePath.endsWith('stagecraft.config.js')) target = 'manifest';
+  else if (ext === '.css') target = 'theme-css';
+  else if (filePath.includes('themes/') && ext === '.js') target = 'theme-js';
+  console.log(`[stagecraft] ${event}: ${filePath} → reload ${target}`);
+  broadcast({ type: 'reload', target, file: filePath });
+});
+
+// --- Static file serving ---
+function serveStatic(req, res, parsed) {
+  let p = decodeURIComponent(parsed.pathname);
+  if (p === '/') p = '/index.html';
+
+  // First try project root
+  let full = safeJoin(ROOT, p);
+
+  // If not found, try the stagecraft package root (so /src/engine.js works
+  // for the starter without npm install in dev)
+  if (!full || !fs.existsSync(full)) {
+    const pkgRoot = path.resolve(path.dirname(url.fileURLToPath(import.meta.url)), '..');
+    const pkgPath = safeJoin(pkgRoot, p);
+    if (pkgPath && fs.existsSync(pkgPath)) full = pkgPath;
+  }
+
+  if (!full || !fs.existsSync(full)) {
+    res.statusCode = 404;
+    res.end('Not found: ' + p);
+    return;
+  }
+  const stat = fs.statSync(full);
+  if (stat.isDirectory()) {
+    full = path.join(full, 'index.html');
+    if (!fs.existsSync(full)) { res.statusCode = 404; res.end(); return; }
+  }
+  const type = mime.lookup(full) || 'application/octet-stream';
+  res.setHeader('Content-Type', type);
+  res.setHeader('Cache-Control', 'no-store');
+  fs.createReadStream(full).pipe(res);
+}
+
+function safeJoin(root, p) {
+  const resolved = path.resolve(root, '.' + p);
+  if (!resolved.startsWith(root)) return null;
+  return resolved;
+}
+
+function isLoopback(addr) {
+  return addr === '127.0.0.1' || addr === '::1' || addr === '::ffff:127.0.0.1';
+}
+
+// Create a new slide file from a small template. Used by /api/manifest/add-slide.
+async function createSlideFile(root, filePath, template) {
+  const full = path.resolve(root, filePath);
+  if (!full.startsWith(root)) throw new Error('refused: file outside project');
+  await fsp.mkdir(path.dirname(full), { recursive: true });
+  let body;
+  switch (template || 'kinetic-text') {
+    case 'section-card':
+      body = `'use strict';
+
+Stage.register(Stage.SectionCard({
+  section: 1,
+  number: '00',
+  title: 'New section',
+  tag: 'edit this in the storyboard'
+}));
+`;
+      break;
+    case 'blank':
+      body = `'use strict';
+
+Stage.register({
+  section: 1,
+  title: 'New slide',
+  render(el) {
+    el.innerHTML = '<div class="hero">Edit me</div>';
+  }
+});
+`;
+      break;
+    case 'kinetic-text':
+    default:
+      body = `'use strict';
+
+Stage.register(Stage.KineticText({
+  section: 1,
+  title: 'New slide',
+  pace: 700,
+  lines: [
+    { text: 'A new slide.',       color: 'fg' },
+    { text: 'Ready to be edited.', color: 'accent', pause: 300 }
+  ]
+}));
+`;
+      break;
+  }
+  await fsp.writeFile(full, body, 'utf8');
+}
+
+// --- API handlers ---
+async function handleApi(req, res, parsed) {
+  const body = await readBody(req);
+  let data;
+  try { data = JSON.parse(body); } catch (e) {
+    return sendJson(res, 400, { error: 'invalid JSON' });
+  }
+  try {
+    switch (parsed.pathname) {
+      case '/api/note/slide':
+        await writeSlideNote(ROOT, data.file, data.text);
+        return sendJson(res, 200, { ok: true });
+      case '/api/note/element':
+        await writeElementNote(ROOT, data.file, data.stageKey, data.text);
+        return sendJson(res, 200, { ok: true });
+      case '/api/edit/inline':
+        await writeInlineEdit(ROOT, data.file, data.propPath, data.value);
+        return sendJson(res, 200, { ok: true });
+      case '/api/manifest/reorder':
+        await reorderManifest(ROOT, data.newOrder);
+        return sendJson(res, 200, { ok: true });
+      case '/api/manifest/transition':
+        await setManifestTransition(ROOT, data.idx, data.transition);
+        return sendJson(res, 200, { ok: true });
+      case '/api/manifest/theme':
+        await setManifestTheme(ROOT, data.theme);
+        return sendJson(res, 200, { ok: true });
+      case '/api/manifest/add-slide':
+        // Create the slide file from a template, then prepend to manifest
+        await createSlideFile(ROOT, data.file, data.template);
+        await addSlideToManifest(ROOT, data.atIdx, data.file, data.transition);
+        return sendJson(res, 200, { ok: true });
+      case '/api/manifest/remove-slide':
+        // Remove from manifest. Optionally delete the file.
+        await removeSlideFromManifest(ROOT, data.idx);
+        if (data.deleteFile && data.file) {
+          try {
+            const full = path.resolve(ROOT, data.file);
+            if (full.startsWith(ROOT)) await fsp.unlink(full);
+          } catch (e) { /* ignore */ }
+        }
+        return sendJson(res, 200, { ok: true });
+      case '/api/edit/notes':
+        await writeSpeakerNotes(ROOT, data.file, data.notes);
+        return sendJson(res, 200, { ok: true });
+      case '/api/notes/element':
+        // GET-style via POST — read pin notes for a slide file
+        const pins = await readElementNotes(ROOT, data.file);
+        return sendJson(res, 200, { ok: true, pins });
+      default:
+        return sendJson(res, 404, { error: 'unknown endpoint' });
+    }
+  } catch (e) {
+    console.error('[stagecraft] api error', e);
+    return sendJson(res, 500, { error: e.message });
+  }
+}
+
+function readBody(req) {
+  return new Promise((resolve, reject) => {
+    let chunks = '';
+    req.on('data', c => chunks += c);
+    req.on('end', () => resolve(chunks));
+    req.on('error', reject);
+  });
+}
+
+function sendJson(res, status, obj) {
+  res.statusCode = status;
+  res.setHeader('Content-Type', 'application/json');
+  res.end(JSON.stringify(obj));
+}
+
+// --- Start ---
+server.listen(port, '127.0.0.1', () => {
+  console.log(`[stagecraft] http://localhost:${port}`);
+  console.log(`[stagecraft] websocket  ws://localhost:${port}/stagecraft`);
+});