fb-slides 0.1.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Fabio Biondi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,225 @@
+# fb-slides
+
+Slides that are **just Markdown**. A [reveal.js](https://revealjs.com) deck that reads
+your `.md` files directly, embeds real pages as live demos, and ships as one
+self-contained folder.
+
+```bash
+npx fb-slides create my-talk
+cd my-talk && npm install && npm run dev
+```
+
+The engine is the package; a talk is only its own content. Bump the version and every
+deck you have written gets the new features.
+
+## The shape of a talk
+
+```
+my-talk/
+├─ decks/          01-intro.md, 02-…  ← the talk, in file-name order
+├─ demo/
+│  ├─ counter/     a static page a slide embeds and runs
+│  └─ angular-hello/  an app with its own dev server, started by `servers:`
+├─ assets/         images the Markdown links to
+├─ theme.css       colour overrides (optional)
+└─ slides.config.js  (optional — every key has a default)
+```
+
+That is what `create` gives you: two nearly empty decks showing the reveal features,
+and one demo of each kind. Delete what the talk does not need — the Angular folder,
+its `servers:` entry and its slide come out together.
+
+| | |
+| --- | --- |
+| `npm run dev` | serves the deck on :4000 and opens it |
+| `npm run build` | `dist/` — self-contained, relative URLs, works offline |
+| `npm run preview` | build, then serve the result |
+
+## Writing
+
+A slide is whatever sits between two `---` lines. Edit the `.md`, reload the page —
+there is no build step and no export. Adding a section to the talk is dropping a file
+into `decks/`; there is no list to keep in step anywhere.
+
+Three things happen automatically, so you never mark them up by hand:
+
+- a slide starting with an `#` h1 becomes a **section divider** (centred, gradient)
+- a slide starting with `<!-- demo: … -->` becomes a **live demo** (below)
+- bullet lists of 3+ items become **fragments**, revealed one at a time
+
+### Section names
+
+The badge in the corner is the file's own `section:`, from the front matter:
+
+```markdown
+---
+marp: true
+title: My talk — imperative tools
+section: Imperative
+---
+```
+
+Marp ignores the key, so the file still exports on its own. Without a `section:` the
+badge falls back to the file name.
+
+### Live demos
+
+A slide that opens with a `demo:` comment is replaced by that page, **running in an
+iframe**, full-bleed. You can click around in it without leaving the presentation.
+
+```markdown
+---
+
+<!-- demo: cart -->
+
+## Live demo
+
+[the fallback for GitHub and Marp goes here]
+```
+
+The comment must be the first thing in the slide. The value is a folder name inside
+`demo/`, a `./` or `../` path taken as-is, or a full `http(s)` URL for anything that is
+not in the project:
+
+```markdown
+<!-- demo: http://localhost:4200/checkout -->
+```
+
+The header then shows the host rather than the whole URL. Everything after the marker is
+what renderers that don't understand it will show — the deck replaces the whole slide.
+
+A demo iframe is loaded when you arrive on its slide and unloaded when you leave, so the
+page is **fresh every time**: the cart is empty again, the counter back to zero. The deck
+also nudges the iframe's width once it loads — an embedded app that measures its
+container at mount would otherwise come up blank, because reveal scales slides with a CSS
+transform and that fires no resize inside the frame.
+
+**Moving a demo is moving those lines.** Put the block wherever you want it, in any file;
+delete it and the demo slide is gone.
+
+### Stepped code highlighting
+
+The line ranges live in the fence's info string — reveal reveals one group per click:
+
+````markdown
+```js [2|3-4|5-9|10]
+````
+
+Harmless anywhere else: every other Markdown renderer just sees a `js` block.
+
+### Diagrams
+
+A ```` ```mermaid ```` fence becomes a real diagram, rendered locally.
+
+### Speaker notes
+
+A `Note:` block at the end of a slide never shows on screen, only in the speaker view (`S`):
+
+```markdown
+## The description *is* the prompt
+
+- `name` → how the agent **calls** it
+
+Note: a bad description is the most common reason a tool never gets used.
+```
+
+## Presenting
+
+| Key | |
+| --- | --- |
+| `→` / `Space` | next step (fragments included) |
+| `P` | the pen — draw on the slide, the ink fades on its own |
+| `Shift` (tap) | the spotlight — drag a rectangle, the rest of the slide dims and blurs |
+| `S` | speaker view — notes, timer, next slide |
+| `Esc` / `O` | overview — the slides as a grid |
+| `V` | the vertical navigator — every slide by title, down the left edge |
+| `F` | fullscreen |
+| `B` / `.` | black out the screen |
+
+- **`?nofrag`** — every bullet at once, for a fast read-through
+- **`?print-pdf`** — open it, then print to PDF (the iframes won't render)
+
+## slides.config.js
+
+Every key is optional.
+
+```js
+export default {
+  title: 'My talk',              // browser tab, and the built page
+  lang: 'en',
+
+  decks: 'decks',                // folder of .md
+  demos: 'demo',                 // folder behind a bare `<!-- demo: name -->`
+  static: ['assets', 'demo'],    // served and published; auto-detected when omitted
+  theme: 'theme.css',            // loaded after the base theme; auto when it exists
+  favicon: 'assets/favicon.png',
+
+  signature: {                   // the corner logo. Omit the key, omit the logo
+    name: 'fabiobiondi.dev',
+    url: 'https://www.fabiobiondi.dev',
+    logo: 'assets/logo.png',
+  },
+
+  servers: [                     // started by `dev`, alongside the deck
+    { name: 'angular demo', cwd: 'demo/app', command: 'npm', args: ['start', '--', '--port', '4200'] },
+  ],
+
+  port: 4000,
+  open: true,
+  outDir: 'dist',
+  exclude: ['dist'],             // extra path segments the build skips
+  fragmentLists: true,           // bullet lists reveal one item at a time
+  reveal: { transition: 'fade' },// passed to Reveal.initialize()
+  mermaid: {},                   // passed to mermaid.initialize()
+};
+```
+
+A `servers:` entry that fails — a missing `node_modules`, a busy port — prints a warning
+and nothing more: the slide that embeds it comes up empty, the rest of the deck works.
+
+## Theming
+
+`theme.css` in the project is loaded **after** the package's base theme, so it overrides
+rather than replaces. Almost everything hangs off the tokens in `:root`:
+
+```css
+:root {
+  --bg: #0e1116;
+  --card: #1a1f27;
+  --text: #e8ebf0;
+  --muted: #97a1b0;
+  --accent: #6ea8fe;
+  --accent-2: #7ee2b8;
+}
+```
+
+## Publishing
+
+```bash
+npm run build   # → dist/
+```
+
+`dist/` carries reveal.js and mermaid with it and uses only relative URLs, so it can be
+published at a domain root or in any subfolder, and it works with no network at all. It
+also holds `decks.json`, the file list a static host cannot produce on its own —
+generated, never hand-written.
+
+What the build cannot fix: a slide embedding `http://localhost:…` shows an empty frame
+once published. Those URLs exist only on the machine running them.
+
+## Also usable with Marp
+
+Each `.md` keeps its own front matter, so the files still work standalone:
+
+```bash
+npx @marp-team/marp-cli decks/01-intro.md --pdf
+```
+
+Marp does not render the mermaid fences or the demo slides — the deck does.
+
+## Overriding the engine
+
+The dev server serves the project **before** the package, so a file of the same name next
+to your decks shadows the one that ships here: dropping in your own `deck.js` or
+`theme.base.css` replaces it for that talk. It is the escape hatch, not the workflow —
+what you shadow stops receiving updates.

package/bin/fb-slides.mjs

@@ -0,0 +1,111 @@
+#!/usr/bin/env node
+// ---------------------------------------------------------------------------
+// fb-slides — Markdown-driven reveal.js decks.
+//
+//   fb-slides create <dir>   a new talk
+//   fb-slides dev            serve it, open it
+//   fb-slides build          dist/, self-contained
+//   fb-slides preview        build, then serve dist/
+// ---------------------------------------------------------------------------
+
+import { createRequire } from 'node:module';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const require = createRequire(import.meta.url);
+const self = require('../package.json');
+const packageRoot = join(dirname(fileURLToPath(import.meta.url)), '..');
+const RUNTIME = join(packageRoot, 'runtime');
+const TEMPLATES = join(packageRoot, 'templates');
+
+const argv = process.argv.slice(2);
+const command = argv.find((arg) => !arg.startsWith('-')) ?? 'dev';
+const positional = argv.filter((arg) => !arg.startsWith('-')).slice(1);
+
+const flag = (name) => argv.includes(`--${name}`);
+const option = (name, fallback) => {
+  const inline = argv.find((arg) => arg.startsWith(`--${name}=`));
+  if (inline) return inline.slice(name.length + 3);
+  const index = argv.indexOf(`--${name}`);
+  return index >= 0 && argv[index + 1] && !argv[index + 1].startsWith('-') ? argv[index + 1] : fallback;
+};
+
+const HELP = `
+  ${self.name} v${self.version}
+
+  fb-slides create <dir>      scaffold a new deck
+  fb-slides dev               serve the deck and open it        [--port n] [--no-open] [--no-servers]
+  fb-slides build             build dist/                       [--out dir] [--watch]
+  fb-slides preview           build, then serve the result      [--port n]
+
+  Run from a folder holding decks/*.md. slides.config.js is optional.
+`;
+
+const overrides = () => ({
+  port: option('port'),
+  outDir: option('out'),
+  open: flag('no-open') ? false : undefined,
+  servers: flag('no-servers') ? false : undefined,
+});
+
+const run = async () => {
+  if (flag('help') || flag('h') || command === 'help') return console.log(HELP);
+  if (flag('version') || flag('v') || command === 'version') return console.log(self.version);
+
+  if (command === 'create' || command === 'init') {
+    const { create } = await import('../lib/create.mjs');
+    const { dir, name } = await create(positional[0], TEMPLATES);
+    console.log(`
+  ${name} is ready.
+
+    cd ${positional[0] ?? '.'}
+    npm install
+    npm run dev
+
+  The talk is decks/*.md — edit one and reload. Everything else comes from ${self.name}.
+`);
+    return;
+  }
+
+  const { loadConfig } = await import('../lib/config.mjs');
+  const root = process.cwd();
+  const config = await loadConfig(root, overrides());
+
+  if (command === 'dev') {
+    const { dev } = await import('../lib/dev.mjs');
+    return void (await dev(config, RUNTIME));
+  }
+
+  if (command === 'build') {
+    const { build, buildWatch } = await import('../lib/build.mjs');
+    return void (await (flag('watch') ? buildWatch(config, RUNTIME) : build(config, RUNTIME)));
+  }
+
+  if (command === 'preview') {
+    const { build } = await import('../lib/build.mjs');
+    const { createDeckServer, listen } = await import('../lib/server.mjs');
+    const { readFile } = await import('node:fs/promises');
+    await build(config, RUNTIME);
+
+    // dist/ is served as it is — no runtime mounts, no rendering. What you see
+    // here is exactly what the host will serve.
+    const out = config.outPath;
+    const port = Number(option('port', config.port + 1));
+    const server = createDeckServer({
+      mounts: [{ prefix: '/', dir: out }],
+      decksPath: resolve(out, config.decksDir),
+      index: () => readFile(join(out, 'index.html'), 'utf8'),
+    });
+    await listen(server, port);
+    console.log(`\n  preview of ${config.outDir}/\n  → http://localhost:${port}/\n`);
+    return;
+  }
+
+  console.error(`unknown command: ${command}${HELP}`);
+  process.exitCode = 1;
+};
+
+run().catch((error) => {
+  console.error(`\n  ✗ ${error.message}\n`);
+  process.exitCode = 1;
+});

package/lib/build.mjs

@@ -0,0 +1,98 @@
+// ---------------------------------------------------------------------------
+// `fb-slides build` — dist/ as one self-contained folder, every URL in it
+// relative, so it can be published at a domain root or in any subfolder.
+//
+// It carries reveal and mermaid too: a published deck depends on nothing but the
+// host that serves it.
+// ---------------------------------------------------------------------------
+
+import { watch } from 'node:fs';
+import { cp, mkdir, rm, writeFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { basename, dirname, join, relative, resolve, sep } from 'node:path';
+
+import { assertUsable } from './config.mjs';
+import { listDecks } from './decks.mjs';
+import { renderIndex } from './render.mjs';
+import { VENDOR_FILES, VENDOR_MOUNTS, packageDir } from './vendor.mjs';
+
+const copyFile = async (from, to) => {
+  await mkdir(dirname(to), { recursive: true });
+  await cp(from, to);
+};
+
+export const build = async (config, runtimeDir, { quiet = false } = {}) => {
+  assertUsable(config);
+  const started = Date.now();
+  const out = config.outPath;
+
+  if (out === config.root) throw new Error('outDir cannot be the project root');
+  await rm(out, { recursive: true, force: true });
+  await mkdir(out, { recursive: true });
+
+  // Matched on the path *inside* the project: a project that happens to live
+  // under a folder called `dist` would otherwise exclude every file in it.
+  const excluded = (src) =>
+    relative(config.root, src).split(sep).some((part) => config.exclude.includes(part));
+
+  // 1. the runtime — everything this package ships except the index template,
+  //    which is rendered below rather than copied.
+  await cp(runtimeDir, out, {
+    recursive: true,
+    filter: (src) => basename(src) !== 'index.html' && !excluded(src),
+  });
+
+  // 2. reveal + mermaid, the UMD entry points only.
+  for (const [pkg, file] of VENDOR_FILES) {
+    const from = join(packageDir(pkg), file);
+    if (!existsSync(from)) continue; // a minor version moved a file: not fatal
+    await copyFile(from, join(out, 'vendor', VENDOR_MOUNTS[pkg], file));
+  }
+
+  // 3. the talk: the Markdown, then the folders it points at.
+  await cp(config.decksPath, join(out, config.decksDir), { recursive: true, filter: (src) => !excluded(src) });
+
+  for (const dir of config.static) {
+    const from = resolve(config.root, dir);
+    // A static dir that contains dist/ would copy the build into itself.
+    if (from === out || out.startsWith(from + sep)) continue;
+    await cp(from, join(out, dir), { recursive: true, filter: (src) => !excluded(src) });
+  }
+
+  // 4. loose root files the config names — a theme override, a favicon.
+  for (const file of [config.theme, config.favicon].filter(Boolean)) {
+    const from = resolve(config.root, file);
+    const to = join(out, file);
+    if (existsSync(from) && !existsSync(to)) await copyFile(from, to);
+  }
+
+  // 5. the page, and the deck list a static host cannot produce on its own.
+  await writeFile(join(out, 'index.html'), await renderIndex(config, runtimeDir));
+  const decks = await listDecks(config.decksPath);
+  if (!decks.length) throw new Error(`no .md in ${config.decksDir}/`);
+  await writeFile(join(out, 'decks.json'), `${JSON.stringify(decks, null, 2)}\n`);
+
+  if (!quiet) {
+    console.log(`  ${config.outDir}/ ← ${decks.length} decks · ${config.static.join(', ') || 'no static dirs'} · ${Date.now() - started}ms`);
+  }
+  return { decks, out };
+};
+
+export const buildWatch = async (config, runtimeDir) => {
+  await build(config, runtimeDir);
+  console.log('  watching… (ctrl-c to stop)');
+
+  const roots = [config.decksPath, ...config.static.map((dir) => resolve(config.root, dir))];
+  let pending;
+  for (const dir of roots) {
+    if (!existsSync(dir)) continue;
+    watch(dir, { recursive: true }, (_event, filename) => {
+      // A framework demo's dev server writes to .angular/ and its own dist/
+      // constantly; without this the deck would rebuild several times a second.
+      if (filename && filename.split(sep).some((part) => config.exclude.includes(part))) return;
+      // Editors save in bursts; one rebuild per burst is plenty.
+      clearTimeout(pending);
+      pending = setTimeout(() => build(config, runtimeDir).catch((error) => console.error(`  ✗ ${error.message}`)), 120);
+    });
+  }
+};

package/lib/config.mjs

@@ -0,0 +1,90 @@
+// ---------------------------------------------------------------------------
+// The project's slides.config — and the defaults that make it optional.
+//
+// Everything the deck used to hardcode lives here: the title, where the .md are,
+// where the embedded demos are, the corner signature, the side processes a talk
+// needs running. A project that follows the default shape needs no config at all.
+// ---------------------------------------------------------------------------
+
+import { existsSync } from 'node:fs';
+import { basename, join, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+const CONFIG_FILES = ['slides.config.js', 'slides.config.mjs', 'slides.config.json'];
+
+// Directories a project gets served and published for free when it has them, so
+// the common shape (decks + assets + demos) needs nothing declared.
+const AUTO_STATIC = ['assets', 'demo', 'public', 'images', 'img'];
+
+// Never served, never published — heavy, private, or generated.
+export const ALWAYS_EXCLUDED = ['node_modules', '.git', '.angular', '.next', '.cache', '.DS_Store'];
+
+export const findConfigFile = (root) => CONFIG_FILES.map((name) => join(root, name)).find(existsSync) ?? null;
+
+const importConfig = async (file) => {
+  const url = pathToFileURL(file).href;
+  const module = file.endsWith('.json')
+    ? await import(url, { with: { type: 'json' } })
+    : await import(url);
+  return module.default ?? module;
+};
+
+// A path the browser will use: always relative (so dist/ can be published in a
+// subfolder) and always with a trailing slash.
+const asDirUrl = (value) => `${String(value).replace(/^\.?\/+/, '').replace(/\/+$/, '')}/`;
+
+export const loadConfig = async (root = process.cwd(), overrides = {}) => {
+  const file = findConfigFile(root);
+  const user = file ? await importConfig(file) : {};
+
+  const decksDir = user.decks ?? 'decks';
+  const demosDir = user.demos ?? 'demo';
+
+  // `static:` replaces the auto-detected list when given; the demos folder is
+  // added back regardless, because the deck's iframes point straight at it.
+  const declared = user.static ?? AUTO_STATIC.filter((dir) => existsSync(join(root, dir)));
+  const statics = [...new Set([...declared, demosDir])].filter((dir) => existsSync(join(root, dir)));
+
+  const config = {
+    root,
+    configFile: file,
+    title: user.title ?? basename(root),
+    lang: user.lang ?? 'en',
+    decksDir,
+    demosDir,
+    static: statics,
+    // The project's own CSS, loaded *after* the base theme: an override, not a
+    // replacement. `theme.css` at the root is picked up without being declared.
+    theme: user.theme ?? (existsSync(join(root, 'theme.css')) ? 'theme.css' : null),
+    favicon: user.favicon ?? null,
+    signature: user.signature ?? null,
+    port: Number(overrides.port ?? user.port ?? 4000),
+    open: overrides.open ?? user.open ?? true,
+    outDir: overrides.outDir ?? user.outDir ?? 'dist',
+    // Side processes a talk needs running: a framework demo's own dev server.
+    servers: (overrides.servers === false ? [] : user.servers) ?? [],
+    // Passed straight to Reveal.initialize(), over the deck's own defaults.
+    reveal: user.reveal ?? {},
+    // Bullet lists of 3+ items appear one item at a time.
+    fragmentLists: user.fragmentLists ?? true,
+    // The build output, at any depth: a framework demo's own dist/ is its dev
+    // server's business, and the deck ships that demo as sources.
+    exclude: [...ALWAYS_EXCLUDED, overrides.outDir ?? user.outDir ?? 'dist', ...(user.exclude ?? [])],
+  };
+
+  config.decksPath = resolve(root, config.decksDir);
+  config.outPath = resolve(root, config.outDir);
+  // What the browser asks for, as opposed to where it is on disk.
+  config.urls = { decks: asDirUrl(config.decksDir), demos: asDirUrl(config.demosDir) };
+
+  return config;
+};
+
+export const assertUsable = (config) => {
+  if (!existsSync(config.decksPath)) {
+    throw new Error(
+      `no decks: expected Markdown in ${config.decksDir}/\n` +
+        `  create it, or point \`decks:\` somewhere else in slides.config.js`,
+    );
+  }
+};

package/lib/create.mjs

@@ -0,0 +1,59 @@
+// ---------------------------------------------------------------------------
+// `fb-slides create my-talk` — a project that is only its own content: the
+// Markdown, the config, and a dependency on this package. Everything else —
+// the engine, the theme, reveal, mermaid — arrives through npm and updates with it.
+// ---------------------------------------------------------------------------
+
+import { cp, mkdir, readdir, readFile, rename, writeFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { basename, dirname, join, resolve } from 'node:path';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const self = require('../package.json');
+
+// npm rewrites a published `.gitignore`, and a nested package.json confuses some
+// tooling — so the template keeps both under a `_` and they are renamed here.
+const RENAMED = { _gitignore: '.gitignore', '_package.json': 'package.json' };
+
+const title = (name) =>
+  name
+    .replace(/[-_]+/g, ' ')
+    .replace(/\b\w/g, (char) => char.toUpperCase())
+    .trim();
+
+export const create = async (target, templatesDir) => {
+  const dir = resolve(process.cwd(), target ?? '.');
+  const name = basename(dir);
+
+  if (existsSync(dir) && (await readdir(dir)).some((entry) => !entry.startsWith('.'))) {
+    throw new Error(`${target} already exists and is not empty`);
+  }
+
+  await mkdir(dir, { recursive: true });
+  await cp(join(templatesDir, 'starter'), dir, { recursive: true });
+
+  // At any depth: the Angular demo carries a package.json of its own.
+  for (const entry of await readdir(dir, { recursive: true })) {
+    const to = RENAMED[basename(entry)];
+    if (to) await rename(join(dir, entry), join(dir, dirname(entry), to));
+  }
+
+  // The two placeholders the scaffold fills in: what the project is called, and
+  // which version of the engine it starts on.
+  for (const file of ['package.json', 'slides.config.js', 'README.md', 'decks/01-intro.md']) {
+    const path = join(dir, file);
+    if (!existsSync(path)) continue;
+    const source = await readFile(path, 'utf8');
+    await writeFile(
+      path,
+      source
+        .replaceAll('__NAME__', name)
+        .replaceAll('__TITLE__', title(name))
+        .replaceAll('__PKG__', self.name)
+        .replaceAll('__VERSION__', `^${self.version}`),
+    );
+  }
+
+  return { dir, name };
+};

package/lib/decks.mjs

@@ -0,0 +1,13 @@
+// The deck list is the folder: every .md in decks/, in file-name order. Adding
+// or removing a talk section is dropping a file in or deleting it — there is no
+// list to keep in step, here or in the Markdown.
+
+import { readdir } from 'node:fs/promises';
+
+export const listDecks = async (dir) => {
+  const files = await readdir(dir);
+  return files
+    .filter((name) => name.endsWith('.md') && !name.startsWith('.'))
+    // `numeric` so 10- sorts after 09- rather than after 01-.
+    .sort((a, b) => a.localeCompare(b, 'en', { numeric: true }));
+};