fb-slides 0.7.0-rc.0 → 0.7.0

package/CHANGELOG.md

@@ -7,7 +7,7 @@ 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
+## 0.7.0 — 2026-09-07
 
 - **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
@@ -17,10 +17,17 @@ that stamps the version renames that heading to the version and its date.
   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
+  The slide's address and the one in `servers:` need not match to the character:
+  the exact URL is tried first, then the origin, so a demo embedded at `#/` or
+  `/tools` still finds its folder.
+  The editor listens on 7100 — clear of 3000, 4200, 5173 and the rest of the band
+  the demos want, since the editor must never land on the app it exists to open —
+  and walks up from there if something holds it, because `serve-web` has no
+  `--strictPort` and would otherwise half-bind a busy port. 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.
+  your disk. `--no-editor` turns it off for one run. When the editor cannot
+  start — no `code` in `PATH`, port taken — the deck comes up as usual and says
+  why under its own URL, where the demo servers' banners cannot bury it.
   [docs/source-code.md](docs/source-code.md)
 
 ## 0.6.3 — 2026-09-05

package/docs/source-code.md

@@ -17,13 +17,13 @@ export default {
 };
 ```
 
-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.
+That is the whole configuration. `dev` starts it alongside the deck, on port
+7100, and every demo slide grows the link.
 
 ```
 $ npm run dev
 
-  ↑ code serve-web → http://localhost:4100/
+  ↑ code serve-web → http://localhost:7100/
 
   My Talk
   → http://localhost:4000/
@@ -32,10 +32,11 @@ $ npm run dev
 Both defaults move if they have to:
 
 ```js
-editor: { port: 5000, command: 'code-insiders' },
+editor: { port: 7300, command: 'code-insiders' },
 ```
 
-`command` is a name in PATH. `code-insiders` and `cursor` answer `serve-web`
+`command` is a name in PATH, or a path to the binary when the shell you start
+the deck from does not carry it. `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.
 
@@ -49,28 +50,30 @@ 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:
+button — see [When no slide has one](#when-no-slide-has-one) below.
 
-```
-⚠  code is not in PATH — the demo slides get no source button.
-   In VS Code: Shell Command: Install 'code' command in PATH.
-```
+## Why 7100
 
-## When the port is taken
+Because the demos own everything below it. 3000 is Next's default, 4200 is
+`ng serve`'s, 5173 and 5174 are Vite's, 6006 is Storybook's, 8080 is everyone's.
+The editor landing on the very app it exists to open is the one collision that
+must not happen — and since `dev` starts the demo servers first, the editor is
+the one that would lose.
 
-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.
+It is not derived from the deck's port for the same reason: a deck on 4100 would
+put its editor on 4200, which is `ng serve` waiting to happen.
 
 `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:
+editor starts, and a taken one moves the editor along: 7101, 7102, up to ten
+tries. Nobody types this address — the page is handed it — so a different number
+costs nothing. Only ten taken ports in a row is a message:
 
 ```
-⚠  port 4100 is in use — no source button.
-   Free it, or give the editor another one: `editor: { port: n }`.
+⚠  source ↗ off: ports 7100–7109 are all in use.
+   Give the editor one of its own: `editor: { port: n }`.
 ```
 
 ## Where a slide's code is found
@@ -101,6 +104,12 @@ The third row is the one worth knowing about. A framework demo is embedded by
 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 two addresses do not have to match to the character. A slide embeds an app
+at the route the demo opens on — `http://localhost:5173/#/settings`, `/tools`,
+a query string — while `url:` names where the app answers. The exact address is
+tried first, and a miss falls back to the **origin**: same host and port, same
+app, same sources. On a port shared by two entries, the first one wins.
+
 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.
@@ -108,6 +117,27 @@ 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.
 
+## When no slide has one
+
+The button is missing everywhere — not on one demo, on all of them — when the
+editor never started. `dev` says so as the last thing it prints, under the deck
+URL, because the demo servers write their own banners over anything said before
+it:
+
+```
+  MCP UI
+  → http://localhost:4100/
+  ⚠  source ↗ off: code is not in PATH.
+```
+
+`code` living in `/usr/local/bin` and a shell that does not have that directory
+in its `PATH` is the usual reason — an IDE's built-in terminal often does not.
+Either start the deck from a shell that has it, or skip `PATH` altogether:
+
+```js
+editor: { command: '/usr/local/bin/code' },
+```
+
 ## What it does not do
 
 - **It is not in the built deck.** `build` never writes it out: the link is a

package/lib/config.mjs

@@ -21,16 +21,24 @@ 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'];
 
+// The editor's port. A fixed number rather than one derived from the deck's,
+// because the band under 6000 belongs to the demos: 3000 is Next's, 4200 is
+// `ng serve`'s, 5173 and 5174 are Vite's, 8080 is everyone's. An editor that
+// lands on the app it exists to open is the one collision that must not happen
+// — and `dev` starts the demo servers first, so it would be the editor that
+// loses. Two decks at once are handled by walking up from here instead.
+const EDITOR_PORT = 7100;
+
 // `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) => {
+// changes them; leaving the key out is no button at all. The command is a name in
+// PATH — `code-insiders` and `cursor` answer `serve-web` too — or a path, for a
+// shell whose PATH does not carry the editor.
+const editorSpec = (value) => {
   if (!value) return null;
   const user = value === true ? {} : value;
   return {
     command: user.command ?? 'code',
-    port: Number(user.port ?? deckPort + 100),
+    port: Number(user.port ?? EDITOR_PORT),
   };
 };
 
@@ -109,7 +117,7 @@ export const loadConfig = async (root = process.cwd(), overrides = {}) => {
   // `--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);
+  config.editor = overrides.editor === false ? null : editorSpec(user.editor);
   // 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

package/lib/dev.mjs

@@ -66,9 +66,7 @@ const startSideServer = (spec, root, children) => {
 // `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.
+// the resolver picked — the failure you find out about on stage. So ask first.
 const portInUse = (port) =>
   Promise.all(
     ['127.0.0.1', '::1'].map(
@@ -86,6 +84,17 @@ const portInUse = (port) =>
     ),
   ).then((answers) => answers.some(Boolean));
 
+// A second deck, or anything else already sitting there, moves the editor along
+// rather than turning it off: nobody types this address — the page is handed it.
+const EDITOR_PORT_TRIES = 10;
+
+const freePort = async (start) => {
+  for (let port = start; port < start + EDITOR_PORT_TRIES; port += 1) {
+    if (!(await portInUse(port))) return port;
+  }
+  return null;
+};
+
 const hasCommand = (command) =>
   new Promise((done) => {
     const probe = spawn(command, ['--version'], { stdio: 'ignore' });
@@ -93,20 +102,32 @@ const hasCommand = (command) =>
     probe.on('exit', (code) => done(code === 0));
   });
 
+// Returns `{ url }` when the editor is up, `{ note }` when it is not. The note
+// is printed with the summary rather than here: the side servers spawn first
+// with `stdio: 'inherit'`, and vite writing its banner over the one line that
+// explains a missing button is how a presenter ends up hunting for it.
 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;
+    return {
+      note: [
+        `⚠  source ↗ off: ${spec.command} is not in PATH.`,
+        `In VS Code: Shell Command: Install '${spec.command}' command in PATH —`,
+        `or name it outright: \`editor: { command: '/usr/local/bin/code' }\`.`,
+      ],
+    };
   }
 
-  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 port = await freePort(spec.port);
+  if (port === null) {
+    return {
+      note: [
+        `⚠  source ↗ off: ports ${spec.port}–${spec.port + EDITOR_PORT_TRIES - 1} are all in use.`,
+        `Give the editor one of its own: \`editor: { port: n }\`.`,
+      ],
+    };
   }
 
-  const url = `http://localhost:${spec.port}/`;
+  const url = `http://localhost:${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.
@@ -116,7 +137,7 @@ const startEditor = async (spec, children) => {
     [
       'serve-web',
       '--port',
-      String(spec.port),
+      String(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',
@@ -130,7 +151,7 @@ const startEditor = async (spec, children) => {
   child.on('exit', (code) => {
     if (code) console.warn(`\n  ⚠  ${spec.command} serve-web stopped (exit ${code}) — no source button.\n`);
   });
-  return url;
+  return { url };
 };
 
 // What the page is built from, read again on every request. A config with a
@@ -197,9 +218,13 @@ 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);
+  const editor = config.editor ? await startEditor(config.editor, children) : {};
+  editorUrl = editor.url ?? null;
 
-  console.log(`\n  ${config.title}\n  → ${url}\n`);
+  // The last thing printed, so nothing scrolls over it.
+  const summary = [``, `  ${config.title}`, `  → ${url}`];
+  if (editor.note) summary.push(...editor.note.map((line, i) => (i ? `     ${line}` : `  ${line}`)));
+  console.log(summary.join('\n') + '\n');
   if (config.open) setTimeout(() => openBrowser(url), 400);
 
   for (const signal of ['SIGINT', 'SIGTERM']) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fb-slides",
-  "version": "0.7.0-rc.0",
+  "version": "0.7.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

@@ -76,8 +76,17 @@ const EDITOR = CFG.editor ?? null;
 // `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}`;
+  if (!isUrl) return /^[./]/.test(target) ? target : `${DEMOS_DIR}${target}`;
+  const sources = EDITOR?.sources;
+  if (!sources) return null;
+  const exact = sources[target.replace(/\/$/, '')];
+  if (exact) return exact;
+  // A slide embeds an app at whatever route the demo opens on — `#/`, `/tools`,
+  // a query string — while `servers:` names the address the app answers at. The
+  // two rarely match to the character, so a miss falls back to the origin: one
+  // app per port is what a demo is, and on a shared port the first entry wins.
+  const { origin } = new URL(target);
+  return Object.entries(sources).find(([url]) => new URL(url).origin === origin)?.[1] ?? null;
 };
 
 // VS Code for the Web opens whatever `?folder=` names, and it wants a path on

package/templates/starter/slides.config.js

@@ -44,9 +44,10 @@ export default {
   // 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.
+  // `{ port: 7300, command: 'code' }` to change either — the default is 7100,
+  // which is clear of the ports the demos want. `--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.