fb-slides 0.7.0-rc.1 → 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
@@ -20,8 +20,10 @@ that stamps the version renames that heading to the version and its date.
   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'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 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. When the editor cannot
   start — no `code` in `PATH`, port taken — the deck comes up as usual and says

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

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' });
@@ -108,16 +117,17 @@ const startEditor = async (spec, children) => {
     };
   }
 
-  if (await portInUse(spec.port)) {
+  const port = await freePort(spec.port);
+  if (port === null) {
     return {
       note: [
-        `⚠  source ↗ off: port ${spec.port} is in use.`,
-        `Free it, or give the editor another one: \`editor: { port: n }\`.`,
+        `⚠  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.
@@ -127,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',

package/package.json

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