fb-slides 0.1.2

package/lib/dev.mjs

@@ -0,0 +1,94 @@
+// ---------------------------------------------------------------------------
+// `fb-slides dev` — the deck on a port, plus whatever else the talk needs running.
+//
+// A talk that embeds a framework demo needs that demo's own dev server up too.
+// That used to be one hardcoded Angular app; it is now `servers:` in the config,
+// so any project can declare its own without touching this file.
+// ---------------------------------------------------------------------------
+
+import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+
+import { assertUsable } from './config.mjs';
+import { createDeckServer, listen } from './server.mjs';
+import { renderIndex } from './render.mjs';
+import { VENDOR_MOUNTS, packageDir } from './vendor.mjs';
+
+const OPEN = { darwin: 'open', win32: 'start' };
+
+const openBrowser = (url) => {
+  const opener = OPEN[process.platform] ?? 'xdg-open';
+  spawn(opener, [url], { stdio: 'ignore', detached: true, shell: process.platform === 'win32' }).unref();
+};
+
+// A side process: `{ name, cwd, command, args, env }`. Its failure is never the
+// deck's failure — the slide that embeds it comes up empty, everything else works.
+const startSideServer = (spec, root, children) => {
+  const cwd = resolve(root, spec.cwd ?? '.');
+  const name = spec.name ?? spec.cwd ?? spec.command;
+
+  if (!existsSync(cwd)) {
+    console.warn(`  ⚠  ${name}: ${spec.cwd} does not exist — skipping`);
+    return;
+  }
+  if (existsSync(join(cwd, 'package.json')) && !existsSync(join(cwd, 'node_modules'))) {
+    console.warn(`  ⚠  ${name}: no node_modules — run \`npm install\` in ${spec.cwd}.`);
+    console.warn(`     Its slides will show an empty frame until you do.`);
+    return;
+  }
+
+  console.log(`  ↑ ${name}${spec.url ? ` → ${spec.url}` : ''}`);
+  const child = spawn(spec.command, spec.args ?? [], {
+    cwd,
+    stdio: 'inherit',
+    shell: !spec.args,
+    env: { ...process.env, ...spec.env },
+  });
+  children.push(child);
+  child.on('error', (error) => console.warn(`  ⚠  ${name}: ${error.message}`));
+  child.on('exit', (code) => {
+    if (code) console.warn(`\n  ⚠  ${name} stopped (exit ${code}) — its slides will be empty.\n`);
+  });
+};
+
+export const dev = async (config, runtimeDir) => {
+  assertUsable(config);
+
+  const mounts = [
+    // The project first: a file next to the decks shadows the one this package
+    // ships, which is how you override deck.js or the theme for one talk.
+    { prefix: '/', dir: config.root },
+    { prefix: '/', dir: runtimeDir },
+    ...Object.entries(VENDOR_MOUNTS).map(([pkg, mount]) => ({
+      prefix: `/vendor/${mount}/`,
+      dir: packageDir(pkg),
+    })),
+  ];
+
+  const server = createDeckServer({
+    mounts,
+    decksPath: config.decksPath,
+    // Rendered per request: editing slides.config.js and reloading is enough.
+    index: () => renderIndex(config, runtimeDir),
+  });
+
+  await listen(server, config.port);
+
+  const url = `http://localhost:${config.port}/`;
+  const children = [];
+  for (const spec of config.servers) startSideServer(spec, config.root, children);
+
+  console.log(`\n  ${config.title}\n  → ${url}\n`);
+  if (config.open) setTimeout(() => openBrowser(url), 400);
+
+  for (const signal of ['SIGINT', 'SIGTERM']) {
+    process.on(signal, () => {
+      children.forEach((child) => child.kill(signal));
+      server.close();
+      process.exit(0);
+    });
+  }
+
+  return server;
+};

package/lib/render.mjs

@@ -0,0 +1,52 @@
+// ---------------------------------------------------------------------------
+// index.html is a template, not a file the project owns: the runtime ships it and
+// the config fills in the five things that differ between talks. Everything the
+// page needs to know at runtime goes out in one `window.__FB_SLIDES__` object.
+// ---------------------------------------------------------------------------
+
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+const escapeHtml = (value) =>
+  String(value).replace(/[&<>"']/g, (char) => `&#${char.charCodeAt(0)};`);
+
+// `</script>` inside a JSON literal would close the tag it sits in.
+const escapeJson = (value) => JSON.stringify(value).replace(/</g, '\\u003c');
+
+const signatureHtml = (signature) => {
+  if (!signature) return '';
+  const { name, url = '#', logo } = signature;
+  const image = logo
+    ? `\n      <a class="sig-logo" href="${escapeHtml(url)}" target="_blank" rel="noreferrer"><img src="${escapeHtml(logo)}" alt="${escapeHtml(name ?? '')}" /></a>`
+    : '';
+  const label = name
+    ? `\n      <a class="sig-name" href="${escapeHtml(url)}" target="_blank" rel="noreferrer">${escapeHtml(name)}</a>`
+    : '';
+  return `<div id="deck-sig">${image}${label}\n    </div>`;
+};
+
+const headHtml = (config) => {
+  const tags = [];
+  if (config.favicon) tags.push(`<link rel="icon" href="${escapeHtml(config.favicon)}" />`);
+  // After the base theme on purpose: the project's CSS overrides, it does not replace.
+  if (config.theme) tags.push(`<link rel="stylesheet" href="${escapeHtml(config.theme)}" />`);
+  return tags.join('\n    ');
+};
+
+export const renderIndex = async (config, runtimeDir) => {
+  const template = await readFile(join(runtimeDir, 'index.html'), 'utf8');
+
+  const runtime = {
+    decks: config.urls.decks,
+    demos: config.urls.demos,
+    reveal: config.reveal,
+    fragmentLists: config.fragmentLists,
+  };
+
+  return template
+    .replaceAll('{{lang}}', escapeHtml(config.lang))
+    .replaceAll('{{title}}', escapeHtml(config.title))
+    .replaceAll('{{head}}', headHtml(config))
+    .replaceAll('{{signature}}', signatureHtml(config.signature))
+    .replaceAll('{{config}}', escapeJson(runtime));
+};

package/lib/server.mjs

@@ -0,0 +1,168 @@
+// ---------------------------------------------------------------------------
+// A static server over several roots, in ~150 lines and no dependencies.
+//
+// It exists because the deck is assembled from two places: the project (decks,
+// assets, demos) and this package (deck.js, the theme, reveal and mermaid). The
+// project comes first, so any runtime file can be shadowed by putting a file of
+// the same name next to the decks — the escape hatch for one-off tweaks.
+//
+// It also answers /decks.json itself, from the folder as it is right now: the
+// deck never has to parse a directory listing to find out what to show.
+// ---------------------------------------------------------------------------
+
+import { createServer } from 'node:http';
+import { createReadStream } from 'node:fs';
+import { readdir, stat } from 'node:fs/promises';
+import { extname, join, relative, resolve, sep } from 'node:path';
+
+import { listDecks } from './decks.mjs';
+
+const MIME = {
+  '.html': 'text/html; charset=utf-8',
+  '.js': 'text/javascript; charset=utf-8',
+  '.mjs': 'text/javascript; charset=utf-8',
+  '.css': 'text/css; charset=utf-8',
+  '.json': 'application/json; charset=utf-8',
+  '.md': 'text/markdown; charset=utf-8',
+  '.svg': 'image/svg+xml',
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.gif': 'image/gif',
+  '.webp': 'image/webp',
+  '.avif': 'image/avif',
+  '.ico': 'image/x-icon',
+  '.woff': 'font/woff',
+  '.woff2': 'font/woff2',
+  '.ttf': 'font/ttf',
+  '.mp4': 'video/mp4',
+  '.webm': 'video/webm',
+  '.mp3': 'audio/mpeg',
+  '.wasm': 'application/wasm',
+  '.map': 'application/json; charset=utf-8',
+  '.txt': 'text/plain; charset=utf-8',
+};
+
+const mime = (path) => MIME[extname(path).toLowerCase()] ?? 'application/octet-stream';
+
+// Nothing is cached: editing a .md and hitting reload is the whole authoring loop.
+const NO_STORE = { 'Cache-Control': 'no-store' };
+
+const send = (res, status, body, headers = {}) => {
+  res.writeHead(status, { ...NO_STORE, ...headers });
+  res.end(body);
+};
+
+const statOrNull = (path) => stat(path).then((info) => info, () => null);
+
+// The project root is a mount, so everything beside the decks is reachable —
+// including things that have no business on the network. Dotfiles (`.env`, `.git`)
+// and dependency folders are off limits whatever the mount.
+const DENIED = /(^|\/)(\.[^/]+|node_modules)(\/|$)/;
+
+// Resolve inside `dir` only: a request for ../../etc/passwd resolves out of it.
+const within = (dir, requestPath) => {
+  const target = resolve(dir, `.${requestPath}`);
+  const inside = target === dir || target.startsWith(dir + sep);
+  return inside ? target : null;
+};
+
+const directoryListing = async (dir, urlPath) => {
+  const entries = (await readdir(dir, { withFileTypes: true }))
+    .filter((entry) => !entry.name.startsWith('.'))
+    .sort((a, b) => a.name.localeCompare(b.name, 'en', { numeric: true }));
+  const links = entries
+    .map((entry) => {
+      const name = entry.name + (entry.isDirectory() ? '/' : '');
+      return `<li><a href="${encodeURIComponent(entry.name)}${entry.isDirectory() ? '/' : ''}">${name}</a></li>`;
+    })
+    .join('\n');
+  return `<!doctype html><meta charset="utf-8"><title>${urlPath}</title>
+<h1>${urlPath}</h1><ul>${links}</ul>`;
+};
+
+// `<video>` in Safari will not play a file the server answers whole.
+const sendFile = (req, res, path, size) => {
+  const range = /^bytes=(\d*)-(\d*)$/.exec(req.headers.range ?? '');
+  const headers = { 'Content-Type': mime(path), ...NO_STORE, 'Accept-Ranges': 'bytes' };
+
+  if (range) {
+    const start = range[1] ? Number(range[1]) : Math.max(0, size - Number(range[2]));
+    const end = range[1] && range[2] ? Math.min(Number(range[2]), size - 1) : size - 1;
+    if (start > end || start >= size) return send(res, 416, '', { 'Content-Range': `bytes */${size}` });
+    res.writeHead(206, { ...headers, 'Content-Range': `bytes ${start}-${end}/${size}`, 'Content-Length': end - start + 1 });
+    return createReadStream(path, { start, end }).pipe(res);
+  }
+
+  res.writeHead(200, { ...headers, 'Content-Length': size });
+  createReadStream(path).pipe(res);
+};
+
+// mounts: [{ prefix: '/', dir }] — checked in order, first hit wins.
+export const createDeckServer = ({ mounts, index, decksPath }) => {
+  const handler = async (req, res) => {
+    if (req.method !== 'GET' && req.method !== 'HEAD') return send(res, 405, 'method not allowed');
+
+    let pathname;
+    try {
+      pathname = decodeURIComponent(new URL(req.url, 'http://localhost').pathname);
+    } catch {
+      return send(res, 400, 'bad request');
+    }
+
+    if (pathname === '/' || pathname === '/index.html') {
+      return send(res, 200, await index(), { 'Content-Type': MIME['.html'] });
+    }
+
+    // The deck's own index of the folder, always current.
+    if (pathname === '/decks.json') {
+      const body = JSON.stringify(await listDecks(decksPath).catch(() => []), null, 2);
+      return send(res, 200, body, { 'Content-Type': MIME['.json'] });
+    }
+
+    if (DENIED.test(pathname)) return send(res, 403, 'forbidden', { 'Content-Type': MIME['.txt'] });
+
+    for (const { prefix, dir } of mounts) {
+      if (!pathname.startsWith(prefix)) continue;
+      const target = within(dir, `/${pathname.slice(prefix.length)}`);
+      if (!target) continue;
+
+      const info = await statOrNull(target);
+      if (!info) continue;
+
+      if (info.isDirectory()) {
+        // A folder is its index.html when it has one — the demos rely on this.
+        const indexFile = join(target, 'index.html');
+        const indexInfo = await statOrNull(indexFile);
+        if (indexInfo?.isFile()) return sendFile(req, res, indexFile, indexInfo.size);
+        if (!pathname.endsWith('/')) return send(res, 302, '', { Location: `${pathname}/` });
+        return send(res, 200, await directoryListing(target, pathname), { 'Content-Type': MIME['.html'] });
+      }
+
+      return sendFile(req, res, target, info.size);
+    }
+
+    send(res, 404, `not found: ${pathname}`, { 'Content-Type': MIME['.txt'] });
+  };
+
+  return createServer((req, res) => {
+    handler(req, res).catch((error) => {
+      console.error(`[fb-slides] ${req.url} → ${error.message}`);
+      if (!res.headersSent) send(res, 500, 'server error');
+    });
+  });
+};
+
+// Fail on a busy port rather than move to another one and leave the browser
+// pointed at a server that is not this one.
+export const listen = (server, port) =>
+  new Promise((resolve, reject) => {
+    server.once('error', (error) =>
+      reject(
+        error.code === 'EADDRINUSE'
+          ? new Error(`port ${port} is already in use — free it, or pass --port <n>`)
+          : error,
+      ),
+    );
+    server.listen(port, () => resolve(server));
+  });

package/lib/vendor.mjs

@@ -0,0 +1,32 @@
+// ---------------------------------------------------------------------------
+// reveal.js and mermaid come from node_modules, not from a CDN: a talk has to
+// survive the conference wifi. They are dependencies of this package, so every
+// project that installs it gets the exact versions this runtime was built for.
+// ---------------------------------------------------------------------------
+
+import { createRequire } from 'node:module';
+import { dirname, join } from 'node:path';
+
+const require = createRequire(import.meta.url);
+
+export const packageDir = (name) => dirname(require.resolve(`${name}/package.json`));
+
+export const packageVersion = (name) => require(`${name}/package.json`).version;
+
+// In dev the whole package folder is mounted, so anything resolves. This is the
+// list the build copies — the UMD entry points and nothing else, which keeps
+// dist/ around 4 MB instead of 30.
+export const VENDOR_FILES = [
+  ['reveal.js', 'dist/reveal.js'],
+  ['reveal.js', 'dist/reveal.css'],
+  ['reveal.js', 'dist/reset.css'],
+  ['reveal.js', 'plugin/markdown/markdown.js'],
+  ['reveal.js', 'plugin/highlight/highlight.js'],
+  ['reveal.js', 'plugin/highlight/monokai.css'],
+  ['reveal.js', 'plugin/notes/notes.js'],
+  ['reveal.js', 'plugin/notes/speaker-view.html'],
+  ['mermaid', 'dist/mermaid.min.js'],
+];
+
+// Where each package is mounted for the browser: `vendor/reveal/dist/reveal.js`.
+export const VENDOR_MOUNTS = { 'reveal.js': 'reveal', mermaid: 'mermaid' };

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "fb-slides",
+  "version": "0.1.2",
+  "type": "module",
+  "description": "Markdown-driven reveal.js decks: live demo embeds, annotation, mermaid, and a zero-config dev server",
+  "keywords": [
+    "slides",
+    "reveal.js",
+    "markdown",
+    "presentation",
+    "deck"
+  ],
+  "license": "MIT",
+  "author": "Fabio Biondi <info@fabiobiondi.com> (https://www.fabiobiondi.dev)",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fabiobiondi/fb-slides.git"
+  },
+  "homepage": "https://github.com/fabiobiondi/fb-slides#readme",
+  "bugs": "https://github.com/fabiobiondi/fb-slides/issues",
+  "bin": {
+    "fb-slides": "bin/fb-slides.mjs"
+  },
+  "exports": {
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "bin",
+    "lib",
+    "runtime",
+    "templates",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20.11"
+  },
+  "scripts": {
+    "starter": "cd templates/starter && node ../../bin/fb-slides.mjs dev --no-servers",
+    "starter:build": "cd templates/starter && node ../../bin/fb-slides.mjs build --out ../../.sandbox/starter-dist",
+    "starter:preview": "cd templates/starter && node ../../bin/fb-slides.mjs preview --out ../../.sandbox/starter-dist",
+    "sandbox": "rm -rf .sandbox/talk && node bin/fb-slides.mjs create .sandbox/talk && cd .sandbox/talk && node ../../bin/fb-slides.mjs dev --no-servers --port 4010"
+  },
+  "dependencies": {
+    "mermaid": "^10.9.1",
+    "reveal.js": "^5.1.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}