fb-slides 0.6.3 → 0.7.0-rc.0

package/CHANGELOG.md

@@ -7,6 +7,22 @@ this — which makes it worth being able to see what arrived.
 Entries are written as the work lands, under **Unreleased**; the release commit
 that stamps the version renames that heading to the version and its date.
 
+## Unreleased
+
+- **A `source ↗` button on demo slides.** `editor: true` in `slides.config.js`
+  starts `code serve-web` — the web server built into VS Code — alongside the
+  deck, and every demo slide gets a link that opens its folder in a real editor
+  in a new tab: file tree, search, terminal, extensions. Nothing is installed and
+  nothing is embedded in the slide. The folder is worked out from the marker for
+  a folder demo, and for one embedded by URL from the `servers:` entry serving
+  that address — which is the first thing `url:` has ever been used for.
+  `<!-- demo: … | src: demo/cart -->` says it outright when nothing else knows.
+  The editor's port — the deck's plus 100 — is checked before it starts, because
+  `serve-web` has no `--strictPort` and two decks are enough to collide. A built
+  deck never carries the button: the link is a localhost address and a path on
+  your disk. `--no-editor` turns it off for one run.
+  [docs/source-code.md](docs/source-code.md)
+
 ## 0.6.3 — 2026-09-05
 
 - **Disabled slides.** `<!-- disabled -->` on a line of its own keeps a slide in

package/README.md

@@ -101,6 +101,14 @@ A demo can also be a whole application with its own dev server — Angular, or a
 Vite — copied into `demo/` as it is. It is embedded by **URL**, not by folder name:
 [docs/framework-demos.md](docs/framework-demos.md).
 
+### The source button
+
+`editor: true` puts a `source ↗` link on every demo slide, opening that demo's folder in
+**real VS Code** in a new tab — `code serve-web`, the web server built into the editor you
+already have, started alongside the deck. Nothing is installed and nothing is embedded, and
+a built deck never carries it. Run `dev` once at your desk first: VS Code downloads its
+server half on the very first use. [docs/source-code.md](docs/source-code.md).
+
 ### Stepped code highlighting
 
 The line ranges live in the fence's info string — reveal reveals one group per click:
@@ -286,6 +294,8 @@ export default {
     { name: 'angular demo', cwd: 'demo/app', command: 'npm', args: ['start', '--', '--port', '4200'] },
   ],
 
+  editor: true,                  // a `source ↗` button on every demo slide
+
   port: 4000,
   open: true,
   outDir: 'dist',
@@ -304,6 +314,10 @@ Copying a real Angular or Vite app into `demo/` and wiring it up — including t
 Vite needs so a busy port fails instead of moving:
 [docs/framework-demos.md](docs/framework-demos.md).
 
+`editor: true` is a side process of the same kind, and fails the same way — a missing
+`code` in PATH, a port already taken, and you get a warning and demo slides without their
+`source ↗` button: [docs/source-code.md](docs/source-code.md).
+
 ## Theming
 
 `theme.css` in the project is loaded **after** the package's base theme, so it overrides

package/bin/fb-slides.mjs

@@ -34,7 +34,8 @@ 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 dev               serve the deck and open it        [--port n] [--no-open]
+                                                                [--no-servers] [--no-editor]
   fb-slides build             build dist/                       [--out dir] [--watch]
   fb-slides preview           build, then serve the result      [--port n]
 
@@ -46,6 +47,7 @@ const overrides = () => ({
   outDir: option('out'),
   open: flag('no-open') ? false : undefined,
   servers: flag('no-servers') ? false : undefined,
+  editor: flag('no-editor') ? false : undefined,
 });
 
 const run = async () => {

package/docs/source-code.md

@@ -0,0 +1,133 @@
+# The source button
+
+A demo slide shows the app running. `source ↗`, next to `open in a tab ↗`, shows
+what it is made of: the demo's folder, open in **VS Code** in a new tab.
+
+Not an editor written for this package, and not a viewer that resembles one. It
+is `code serve-web` — the web server built into the VS Code on the machine
+running the talk — pointed at the demo's folder. The file tree, the search, the
+terminal, the extensions, the keybindings: the editor, in a tab.
+
+## Turning it on
+
+```js
+// slides.config.js
+export default {
+  editor: true,
+};
+```
+
+That is the whole configuration. `dev` starts it alongside the deck, on the
+deck's port plus 100, and every demo slide grows the link.
+
+```
+$ npm run dev
+
+  ↑ code serve-web → http://localhost:4100/
+
+  My Talk
+  → http://localhost:4000/
+```
+
+Both defaults move if they have to:
+
+```js
+editor: { port: 5000, command: 'code-insiders' },
+```
+
+`command` is a name in PATH. `code-insiders` and `cursor` answer `serve-web`
+too; whatever you name has to be a VS Code CLI, because that subcommand is what
+this uses.
+
+## Run it once before you need it
+
+**The first run downloads about 100 MB** — the server half of VS Code, into
+`~/.vscode/cli`. It happens once per machine and it is cached from then on, but
+a minute of silent downloading is not something to meet in front of a room.
+
+Start `dev` once at your desk after turning the key on. That is the whole
+precaution, and it is why `editor:` is off in a fresh deck rather than on.
+
+If `code` is not in PATH at all, the deck says so and carries on without the
+button:
+
+```
+⚠  code is not in PATH — the demo slides get no source button.
+   In VS Code: Shell Command: Install 'code' command in PATH.
+```
+
+## When the port is taken
+
+The default is the deck's port plus 100, and **two decks are enough to collide**:
+one on 4000 puts its editor on 4100, which is a perfectly ordinary port for the
+second deck to be on.
+
+`code serve-web` does not fail on a busy port the way the deck server does — a
+process holding the IPv6 side leaves the IPv4 side free, both bind, and
+`localhost` in the browser then lands on whichever the resolver picked. That is
+the failure you find out about on stage. So the port is checked before the
+editor is started, and a taken one is a message rather than a wrong tab:
+
+```
+⚠  port 4100 is in use — no source button.
+   Free it, or give the editor another one: `editor: { port: n }`.
+```
+
+## Where a slide's code is found
+
+The button has to be told which folder a demo comes from. Three of the four
+answers need nothing from you:
+
+| the slide says | the folder |
+| --- | --- |
+| `<!-- demo: counter -->` | `demo/counter` — a name is a folder in the demos dir |
+| `<!-- demo: ../shared/cart/ -->` | that path, as written |
+| `<!-- demo: http://localhost:4200/ -->` | the `cwd` of whichever `servers:` entry has that `url` |
+| `<!-- demo: https://example.com/ \| src: demo/cart -->` | `demo/cart` |
+
+The third row is the one worth knowing about. A framework demo is embedded by
+**URL** — the slide has no idea there is a folder anywhere. `servers:` does:
+
+```js
+{
+  name: 'checkout',
+  cwd: 'demo/checkout',        // ← the sources
+  command: 'npm',
+  args: ['start', '--', '--port', '4200'],
+  url: 'http://localhost:4200/', // ← what the slide points at
+}
+```
+
+That pairing used to be a log line and nothing else. It is now also how the
+button finds the code behind a running app.
+
+The fourth row, `| src:`, is the escape hatch for what is left: a demo deployed
+somewhere, or embedded from a server the config does not declare. It wins over
+everything else when it is there.
+
+A demo whose folder is unknown simply has no button. Nothing breaks, and the
+rest of the slide is unchanged.
+
+## What it does not do
+
+- **It is not in the built deck.** `build` never writes it out: the link is a
+  `localhost` address and an absolute path on your disk, and neither means
+  anything to someone reading the deck on the web. This is a presenting tool,
+  like the demos that need `servers:` running.
+- **It does not open in the slide.** A new tab, deliberately — an editor is
+  heavy, and a deck that never mounts one has nothing to tear down when the
+  slide moves on.
+- **`--no-editor` turns it off** for one run. It is deliberately not part of
+  `--no-servers`: that flag is for skipping a demo's own dev server, and a demo
+  that is not running is exactly when you want to open its code. The URL → folder
+  table above is read from `servers:` as written in the config, so it still
+  works when none of those servers were started.
+
+## It is your real filesystem
+
+The editor opens the actual folder, with write access, as an editor does. Saving
+a file in that tab changes the file on disk.
+
+That is the feature, if you mean to edit live: change a component in the tab,
+switch back to the slide, watch the demo's own dev server pick it up. It is
+worth knowing about all the same, because the same is true of a stray keystroke.

package/lib/config.mjs

@@ -21,6 +21,19 @@ 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'];
 
+// `editor: true` turns the source button on with the defaults; `{ port, command }`
+// changes them; leaving the key out is no button at all. The port follows the
+// deck's so two talks open at once do not fight over it, and the command is a
+// name in PATH — `code-insiders` and `cursor` answer `serve-web` too.
+const editorSpec = (value, deckPort) => {
+  if (!value) return null;
+  const user = value === true ? {} : value;
+  return {
+    command: user.command ?? 'code',
+    port: Number(user.port ?? deckPort + 100),
+  };
+};
+
 export const findConfigFile = (root) => CONFIG_FILES.map((name) => join(root, name)).find(existsSync) ?? null;
 
 const importConfig = async (file) => {
@@ -93,6 +106,19 @@ export const loadConfig = async (root = process.cwd(), overrides = {}) => {
   // silently wears the wrong clothes.
   if (config.revealTheme) await assertRevealTheme(config.revealTheme);
 
+  // `--no-editor` is its own flag rather than a part of `--no-servers`: that one
+  // is for skipping a demo's dev server, and a demo that is not running is
+  // exactly when you want to be able to open its code.
+  config.editor = overrides.editor === false ? null : editorSpec(user.editor, config.port);
+  // The folder behind each demo embedded by URL, taken from `servers:` as the
+  // project wrote it rather than from the list `dev` will start: `--no-servers`
+  // empties that one, and a demo that is not running is exactly when its code is
+  // worth opening. `url:` had never been used for anything until this.
+  config.demoSources = Object.fromEntries(
+    (user.servers ?? [])
+      .filter((spec) => spec.url && spec.cwd)
+      .map((spec) => [String(spec.url).replace(/\/$/, ''), spec.cwd]),
+  );
   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.

package/lib/dev.mjs

@@ -7,6 +7,7 @@
 // ---------------------------------------------------------------------------
 
 import { spawn } from 'node:child_process';
+import { connect } from 'node:net';
 import { existsSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 
@@ -54,6 +55,84 @@ const startSideServer = (spec, root, children) => {
   });
 };
 
+// ---------------------------------------------------------------------------
+// The source-code editor. `code serve-web` is VS Code's own web server, shipped
+// inside the editor the presenter already has: no dependency is added here, and
+// what opens in the tab is the real thing rather than a viewer pretending to be
+// one. It is a side process like any other — it dies with the deck, and its
+// failure is never the deck's failure, only a slide without its button.
+// ---------------------------------------------------------------------------
+
+// `serve-web` has no --strictPort, and it does not fail on a taken port the way
+// the deck server does: another process holding the IPv6 side leaves the IPv4
+// side free, both bind, and `localhost` in the browser then lands on whichever
+// the resolver picked. Two fb-slides decks are enough to arrange that — one on
+// 4000 puts its editor on 4100, which is a perfectly ordinary port for the
+// second deck. So ask first, and say which port to use instead.
+const portInUse = (port) =>
+  Promise.all(
+    ['127.0.0.1', '::1'].map(
+      (host) =>
+        new Promise((done) => {
+          const probe = connect({ host, port });
+          const settle = (taken) => {
+            probe.destroy();
+            done(taken);
+          };
+          probe.setTimeout(400, () => settle(false));
+          probe.on('connect', () => settle(true));
+          probe.on('error', () => settle(false));
+        }),
+    ),
+  ).then((answers) => answers.some(Boolean));
+
+const hasCommand = (command) =>
+  new Promise((done) => {
+    const probe = spawn(command, ['--version'], { stdio: 'ignore' });
+    probe.on('error', () => done(false));
+    probe.on('exit', (code) => done(code === 0));
+  });
+
+const startEditor = async (spec, children) => {
+  if (!(await hasCommand(spec.command))) {
+    console.warn(`  ⚠  ${spec.command} is not in PATH — the demo slides get no source button.`);
+    console.warn(`     In VS Code: Shell Command: Install 'code' command in PATH.`);
+    return null;
+  }
+
+  if (await portInUse(spec.port)) {
+    console.warn(`  ⚠  port ${spec.port} is in use — no source button.`);
+    console.warn(`     Free it, or give the editor another one: \`editor: { port: n }\`.`);
+    return null;
+  }
+
+  const url = `http://localhost:${spec.port}/`;
+  // First run downloads the server half of VS Code into ~/.vscode/cli, which is
+  // a hundred megabytes and a minute — hence `stdio: 'inherit'`, so it happens
+  // in front of whoever started the deck rather than silently before a talk.
+  console.log(`  ↑ ${spec.command} serve-web → ${url}`);
+  const child = spawn(
+    spec.command,
+    [
+      'serve-web',
+      '--port',
+      String(spec.port),
+      // No token in the URL: the slide has to be able to link straight to a
+      // folder, and this listens on localhost only.
+      '--without-connection-token',
+      '--accept-server-license-terms',
+      '--disable-telemetry',
+    ],
+    { stdio: 'inherit' },
+  );
+  children.push(child);
+  child.on('error', (error) => console.warn(`  ⚠  ${spec.command}: ${error.message}`));
+  child.on('exit', (code) => {
+    if (code) console.warn(`\n  ⚠  ${spec.command} serve-web stopped (exit ${code}) — no source button.\n`);
+  });
+  return url;
+};
+
 // What the page is built from, read again on every request. A config with a
 // syntax error in it — the state it is in halfway through an edit — leaves the
 // last good one standing rather than serving a broken deck.
@@ -73,6 +152,7 @@ const reader = (config, reload) => {
 export const dev = async (config, runtimeDir, reload) => {
   assertUsable(config);
   const current = reader(config, reload);
+  let editorUrl = null;
 
   const mounts = [
     // The project first: a file next to the decks shadows the one this package
@@ -92,7 +172,13 @@ export const dev = async (config, runtimeDir, reload) => {
     // the theme or the signature and reloading is enough. What was fixed when
     // the server came up — the mounts, the port, the side processes — still
     // needs a restart.
-    index: async () => renderIndex(await current(), runtimeDir),
+    index: async () => {
+      const now = await current();
+      // Read at request time, not at wiring time: the editor is started below,
+      // after the port is bound, and the first page load comes later still.
+      const editor = editorUrl ? { url: editorUrl, root: config.root, sources: now.demoSources } : null;
+      return renderIndex(now, runtimeDir, editor ? { editor } : {});
+    },
     // Editing a slide in the browser saves it back into its .md — dev only,
     // which is what makes the edit button appear at all (the runtime probes
     // /api/editable). Build and preview never mount this.
@@ -111,6 +197,7 @@ export const dev = async (config, runtimeDir, reload) => {
   const url = `http://localhost:${config.port}/`;
   const children = [];
   for (const spec of config.servers) startSideServer(spec, config.root, children);
+  if (config.editor) editorUrl = await startEditor(config.editor, children);
 
   console.log(`\n  ${config.title}\n  → ${url}\n`);
   if (config.open) setTimeout(() => openBrowser(url), 400);

package/lib/render.mjs

@@ -38,7 +38,11 @@ const headHtml = (config) => {
   return tags.join('\n    ');
 };
 
-export const renderIndex = async (config, runtimeDir) => {
+// `extra` is what only one command knows. `dev` puts the source-code editor
+// there — a localhost URL and absolute paths, both of which are true for the
+// machine running the talk and nowhere else, so `build` never passes it and a
+// published deck has no button to press.
+export const renderIndex = async (config, runtimeDir, extra = {}) => {
   const template = await readFile(join(runtimeDir, 'index.html'), 'utf8');
 
   const runtime = {
@@ -47,6 +51,7 @@ export const renderIndex = async (config, runtimeDir) => {
     reveal: config.reveal,
     fragmentLists: config.fragmentLists,
     snippets: config.snippets,
+    ...extra,
   };
 
   // The chrome reads this to take its colours from the reveal theme instead of

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fb-slides",
-  "version": "0.6.3",
+  "version": "0.7.0-rc.0",
   "type": "module",
   "description": "Markdown-driven reveal.js decks: live demo embeds, annotation, mermaid, and a zero-config dev server",
   "keywords": [

package/runtime/deck.js

@@ -58,9 +58,36 @@ if (!DECKS.length) console.error(`[deck] no .md found in ${DECKS_DIR}`);
 // running in an iframe. The marker lives in the Markdown, so the position of a
 // demo is decided there — like any other slide. The value is a folder inside the
 // project's demos dir, a ./ or ../ path, or a full http(s) URL for anything external.
-const DEMO_MARKER = /^<!--\s*demo:\s*(\S+?)\s*-->/;
+//
+// `| src: demo/cart` after it names the folder that code comes from, for the
+// source button. It is only ever needed for a URL whose server the config does
+// not declare — every other form already says where its own sources are.
+const DEMO_MARKER = /^<!--\s*demo:\s*(\S+?)(?:\s*\|\s*src:\s*(\S+?))?\s*-->/;
 const DEMOS_DIR = CFG.demos ?? 'demo/';
 
+// `dev` fills this in when `editor:` is on: the address VS Code's own web server
+// is answering at, the project's absolute path, and the folder behind each demo
+// URL. A built deck never carries it — both halves are true of one machine only —
+// so the button exists while presenting and nowhere else.
+const EDITOR = CFG.editor ?? null;
+
+// Where a demo's code sits, relative to the project root. A bare name is a
+// folder in the demos dir, a ./ or ../ path is itself, and a URL is whichever
+// `servers:` entry serves it — unless the slide said outright with `| src:`.
+const sourceOf = (target, src, isUrl) => {
+  if (src) return src;
+  if (isUrl) return EDITOR?.sources?.[target.replace(/\/$/, '')] ?? null;
+  return /^[./]/.test(target) ? target : `${DEMOS_DIR}${target}`;
+};
+
+// VS Code for the Web opens whatever `?folder=` names, and it wants a path on
+// disk — which the browser has no way of knowing, so the server sent the root.
+const editorHref = (relative) => {
+  if (!EDITOR?.url || !relative) return null;
+  const folder = `${EDITOR.root}/${relative.replace(/^\.\//, '').replace(/\/+$/, '')}`;
+  return `${EDITOR.url}?folder=${encodeURIComponent(folder)}`;
+};
+
 // A slide whose source carries `<!-- disabled -->` stays in the file and in the
 // navigator, but steps out of the talk: the arrows walk past it and it is not
 // counted. The line is stripped before rendering — what is left is an ordinary
@@ -107,7 +134,7 @@ const markdownSection = (source, deck) => {
 };
 
 // The real page, running, inside the slide.
-const demoSection = (target, deck) => {
+const demoSection = (target, src, deck) => {
   const isUrl = /^https?:\/\//.test(target);
   const name = isUrl ? target : target.replace(/\/$/, '');
   // Bare names are folders in the demos dir; a ./ or ../ path and a full URL are
@@ -115,6 +142,9 @@ const demoSection = (target, deck) => {
   const path = isUrl || /^[./]/.test(name) ? name : `${DEMOS_DIR}${name}/`;
   // A whole URL in the header would drown the slide: show just the host.
   const label = isUrl ? new URL(name).host : name;
+  // A new tab on purpose: the editor is heavy, and a deck that never mounts it
+  // has nothing of it to tear down when the slide moves on.
+  const source = editorHref(sourceOf(name, src, isUrl));
   const section = document.createElement('section');
   section.className = 'demo-slide';
   section.dataset.deck = deck.label;
@@ -122,6 +152,7 @@ const demoSection = (target, deck) => {
     <header>
       <span class="tag">live</span>
       <code>${label}</code>
+      ${source ? `<a href="${source}" target="_blank" rel="noreferrer">source ↗</a>` : ''}
       <a href="${path}" target="_blank" rel="noreferrer">open in a tab ↗</a>
     </header>
     <iframe data-src="${path}" title="${name}" loading="lazy"></iframe>
@@ -146,7 +177,7 @@ for (const file of DECKS) {
     const disabled = DISABLED_MARKER.test(raw);
     const source = disabled ? raw.replace(DISABLED_MARKER, '') : raw;
     const marker = source.match(DEMO_MARKER);
-    const section = marker ? demoSection(marker[1], deck) : markdownSection(source, deck);
+    const section = marker ? demoSection(marker[1], marker[2], deck) : markdownSection(source, deck);
     if (disabled) {
       section.classList.add(OFF);
       // Reveal's own answer to "in the deck, out of the count": it leaves an

package/runtime/theme.base.css

@@ -335,6 +335,8 @@ html[data-reveal-theme] .reveal strong { color: var(--r-heading-color, var(--tex
   white-space: nowrap;
 }
 .reveal .slides section.demo-slide header a { margin-left: auto; font-size: 0.9em; }
+/* The first link is the one that pushes right; the rest ride along on the gap. */
+.reveal .slides section.demo-slide header a ~ a { margin-left: 0; }
 .reveal .slides section.demo-slide .tag {
   font: 600 0.8em/1 var(--sans);
   letter-spacing: 0.08em;

package/templates/starter/decks/02-demos.md

@@ -78,5 +78,6 @@ Note what never happens: the model never touches the DOM, the network, or your s
 - what follows it is the fallback for GitHub and Marp
 - `demo/angular-hello` is started by `servers:` in `slides.config.js`
 - the `+` in the edit drawer writes all three, and `/` opens the same list
+- `editor: true` in the config adds `source ↗`: the demo's folder in real VS Code
 
 Note: the iframe is reloaded every time you arrive on the slide, so a demo is always in its initial state.

package/templates/starter/slides.config.js

@@ -38,6 +38,17 @@ export default {
     },
   ],
 
+  // A `source ↗` button on every demo slide, opening that demo's folder in real
+  // VS Code in a new tab. It is `code serve-web` — the web server built into the
+  // editor you already have — started alongside the deck, so nothing is installed
+  // and nothing is embedded. Off by default because the very first run downloads
+  // VS Code's server half (~100 MB) and you do not want to discover that on
+  // stage: uncomment, run `dev` once at your desk, and it is cached from then on.
+  // `{ port: 4100, command: 'code' }` to change either — the default port is the
+  // deck's plus 100. `--no-editor` turns it off for one run, and a
+  // built deck never has it: the link is a localhost address and a path on disk.
+  editor: true,
+
   // The corner signature. Uncomment to show it.
   // signature: { name: 'fabiobiondi.dev', url: 'https://www.fabiobiondi.dev', logo: 'assets/logo.png' },