poveste 0.5.2 → 0.5.3

package/dist/node/bin.js

@@ -6,6 +6,7 @@ const __dirname = dirname(fileURLToPath(import.meta.url));
 const { version } = JSON.parse(fs.readFileSync(resolve(__dirname, '../../package.json'), 'utf8'));
 process.env.NODE_ENV = 'development';
 process.env.HISTOIRE = 'true';
+process.env.POVESTE = 'true';
 const program = sade('poveste');
 program.version(version);
 program.command('dev')

package/dist/node/builtin-plugins/pinceau-tokens.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pinceau-tokens.d.ts","sourceRoot":"","sources":["../../../src/node/builtin-plugins/pinceau-tokens.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAiB,MAAM,iBAAiB,CAAA;AAI5D,MAAM,WAAW,oBAAoB;IACnC,aAAa,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAA;IACjC,cAAc,CAAC,EAAE,MAAM,CAAA;CACxB;AAED,wBAAgB,aAAa,CAAC,QAAQ,GAAE,oBAAyB,GAAG,MAAM,CA2DzE"}
+{"version":3,"file":"pinceau-tokens.d.ts","sourceRoot":"","sources":["../../../src/node/builtin-plugins/pinceau-tokens.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAiB,MAAM,iBAAiB,CAAA;AAI5D,MAAM,WAAW,oBAAoB;IACnC,aAAa,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAA;IACjC,cAAc,CAAC,EAAE,MAAM,CAAA;CACxB;AAED,wBAAgB,aAAa,CAAC,QAAQ,GAAE,oBAAyB,GAAG,MAAM,CA6DzE"}

package/dist/node/builtin-plugins/pinceau-tokens.js

@@ -41,7 +41,8 @@ export function pinceauTokens(_options = {}) {
                 });
             }
         },
-        onDev(api, onCleanup) {
+        async onDev(api, onCleanup) {
+            await generate(api);
             const watcher = api.watcher.watch(themePath)
                 .on('change', () => generate(api))
                 .on('add', () => generate(api));

package/dist/node/builtin-plugins/tailwind-tokens.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tailwind-tokens.d.ts","sourceRoot":"","sources":["../../../src/node/builtin-plugins/tailwind-tokens.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAiB,MAAM,iBAAiB,CAAA;AAI5D,MAAM,WAAW,qBAAqB;IACpC;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AAqBD,wBAAgB,cAAc,CAAC,OAAO,GAAE,qBAA0B,GAAG,MAAM,CAgE1E"}
+{"version":3,"file":"tailwind-tokens.d.ts","sourceRoot":"","sources":["../../../src/node/builtin-plugins/tailwind-tokens.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAiB,MAAM,iBAAiB,CAAA;AAI5D,MAAM,WAAW,qBAAqB;IACpC;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AAqBD,wBAAgB,cAAc,CAAC,OAAO,GAAE,qBAA0B,GAAG,MAAM,CAkE1E"}

package/dist/node/builtin-plugins/tailwind-tokens.js

@@ -61,8 +61,9 @@ export function tailwindTokens(options = {}) {
                 }
             }
         },
-        onDev(api, onCleanup) {
+        async onDev(api, onCleanup) {
             if (tailwindCssFile) {
+                await generate(api);
                 const watcher = api.watcher.watch(tailwindCssFile)
                     .on('change', () => generate(api))
                     .on('add', () => generate(api));

package/dist/node/commands/dev.d.ts

@@ -1,5 +1,5 @@
 export interface DevOptions {
-    port: number;
+    port?: number | string;
     open?: boolean;
     host?: string | boolean;
     config?: string;

package/dist/node/commands/dev.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dev.d.ts","sourceRoot":"","sources":["../../../src/node/commands/dev.ts"],"names":[],"mappings":"AAOA,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAA;IACvB,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAED,wBAAsB,UAAU,CAAC,OAAO,EAAE,UAAU,iBAoDnD"}
+{"version":3,"file":"dev.d.ts","sourceRoot":"","sources":["../../../src/node/commands/dev.ts"],"names":[],"mappings":"AAQA,MAAM,WAAW,UAAU;IACzB,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAAA;IACtB,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAA;IACvB,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAED,wBAAsB,UAAU,CAAC,OAAO,EAAE,UAAU,iBAsDnD"}

package/dist/node/commands/dev.js

@@ -3,7 +3,9 @@ import pc from 'picocolors';
 import { resolveConfigFile } from '../config.js';
 import { createContext } from '../context.js';
 import { createServer } from '../server.js';
+import { resolvePort } from './port.js';
 export async function devCommand(options) {
+    const port = resolvePort(options.port, 'dev');
     let stop;
     async function start() {
         const ctx = await createContext({
@@ -11,7 +13,7 @@ export async function devCommand(options) {
             mode: 'dev',
         });
         const { server, viteConfigFile, close } = await createServer(ctx, {
-            port: options.port,
+            port,
             open: options.open,
             host: options.host,
         });

package/dist/node/commands/port.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Reads a `--port` value off the parsed CLI options.
+ *
+ * sade declares the flag as taking a value but does not enforce one, so
+ * `poveste preview --port` arrives as the boolean `true` and reaches node's
+ * listen validation, which rejects it with `ERR_INVALID_ARG_VALUE` and names
+ * neither the flag nor the mistake. A non-numeric value fails the same way.
+ */
+export declare function resolvePort(value: unknown, command: string): number | undefined;
+//# sourceMappingURL=port.d.ts.map

package/dist/node/commands/port.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"port.d.ts","sourceRoot":"","sources":["../../../src/node/commands/port.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAoB/E"}

package/dist/node/commands/port.js

@@ -0,0 +1,24 @@
+/**
+ * Reads a `--port` value off the parsed CLI options.
+ *
+ * sade declares the flag as taking a value but does not enforce one, so
+ * `poveste preview --port` arrives as the boolean `true` and reaches node's
+ * listen validation, which rejects it with `ERR_INVALID_ARG_VALUE` and names
+ * neither the flag nor the mistake. A non-numeric value fails the same way.
+ */
+export function resolvePort(value, command) {
+    if (value === undefined || value === null) {
+        return undefined;
+    }
+    // Checked by type, not by coercion: a valueless flag arrives as `true`, and
+    // `Number(true)` is 1, a valid port that would bind to a privileged one.
+    const port = typeof value === 'number'
+        ? value
+        : typeof value === 'string' && value.trim() !== ''
+            ? Number(value)
+            : Number.NaN;
+    if (!Number.isInteger(port) || port < 0 || port > 65535) {
+        throw new TypeError(`--port needs a number between 0 and 65535, got ${JSON.stringify(value)}. Try \`poveste ${command} --port 6006\`.`);
+    }
+    return port;
+}

package/dist/node/commands/preview.d.ts

@@ -1,5 +1,5 @@
 export interface PreviewOptions {
-    port?: number;
+    port?: number | string;
     host?: string | boolean;
     open?: boolean;
 }

package/dist/node/commands/preview.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"preview.d.ts","sourceRoot":"","sources":["../../../src/node/commands/preview.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,cAAc;IAC7B,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAA;IACvB,IAAI,CAAC,EAAE,OAAO,CAAA;CACf;AAED,wBAAsB,cAAc,CAAC,OAAO,EAAE,cAAc,iBAiB3D"}
+{"version":3,"file":"preview.d.ts","sourceRoot":"","sources":["../../../src/node/commands/preview.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,cAAc;IAC7B,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAAA;IACtB,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAA;IACvB,IAAI,CAAC,EAAE,OAAO,CAAA;CACf;AAED,wBAAsB,cAAc,CAAC,OAAO,EAAE,cAAc,iBAmB3D"}

package/dist/node/commands/preview.js

@@ -1,6 +1,8 @@
 import { createContext } from '../context.js';
 import { startPreview } from '../preview.js';
+import { resolvePort } from './port.js';
 export async function previewCommand(options) {
+    const port = resolvePort(options.port, 'preview');
     const ctx = await createContext({
         mode: 'build',
     });
@@ -10,7 +12,7 @@ export async function previewCommand(options) {
         }
     }
     const { printUrls } = await startPreview({
-        port: options.port,
+        port,
         host: options.host,
         open: options.open,
     }, ctx);

package/dist/node/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/node/config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,UAAU,EAEV,aAAa,EAEd,MAAM,iBAAiB,CAAA;AACxB,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AAkB3C,wBAAgB,gBAAgB,IAAI,aAAa,CA4HhD;AAED,eAAO,MAAM,eAAe,UAU3B,CAAA;AAED,wBAAgB,iBAAiB,CAAC,GAAG,GAAE,MAAsB,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,CAQ1F;AAED,wBAAsB,cAAc,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,aAAa,CAAC,CAAC,CAexF;AAED,eAAO,MAAM,gBAAgB,uBAK3B,CAAA;AAEF,eAAO,MAAM,WAAW,uBA8DtB,CAAA;AAEF,wBAAsB,aAAa,CAAC,GAAG,EAAE,MAAsB,EAAE,IAAI,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAgB7H;AA2BD,wBAAsB,aAAa,CAAC,GAAG,EAAE,OAAO,iBAoE/C;AAED,wBAAgB,YAAY,CAAC,MAAM,EAAE,OAAO,CAAC,aAAa,CAAC,0BAE1D;AAED,OAAO,QAAQ,MAAM,CAAC;IACpB,UAAU,UAAU;QAClB;;WAEG;QACH,OAAO,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,CAAA;QAChC;;WAEG;QACH,QAAQ,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,CAAA;KAClC;CACF"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/node/config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,UAAU,EAEV,aAAa,EAEd,MAAM,iBAAiB,CAAA;AACxB,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AAkB3C,wBAAgB,gBAAgB,IAAI,aAAa,CA2HhD;AAED,eAAO,MAAM,eAAe,UAU3B,CAAA;AAED,wBAAgB,iBAAiB,CAAC,GAAG,GAAE,MAAsB,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,CAQ1F;AAED,wBAAsB,cAAc,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,aAAa,CAAC,CAAC,CAexF;AAED,eAAO,MAAM,gBAAgB,uBAK3B,CAAA;AAEF,eAAO,MAAM,WAAW,uBA8DtB,CAAA;AAEF,wBAAsB,aAAa,CAAC,GAAG,EAAE,MAAsB,EAAE,IAAI,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAgB7H;AA2BD,wBAAsB,aAAa,CAAC,GAAG,EAAE,OAAO,iBAoE/C;AAED,wBAAgB,YAAY,CAAC,MAAM,EAAE,OAAO,CAAC,aAAa,CAAC,0BAE1D;AAED,OAAO,QAAQ,MAAM,CAAC;IACpB,UAAU,UAAU;QAClB;;WAEG;QACH,OAAO,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,CAAA;QAChC;;WAEG;QACH,QAAQ,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,CAAA;KAClC;CACF"}

package/dist/node/config.js

@@ -110,7 +110,6 @@ export function getDefaultConfig() {
                 contrastColor: '#eee',
             },
         ],
-        sandboxDarkClass: 'dark',
         routerMode: 'history',
         build: {
             excludeFromVendorsChunk: [],

package/dist/node/preview.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"preview.d.ts","sourceRoot":"","sources":["../../src/node/preview.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AAG3C,MAAM,WAAW,mBAAmB;IAClC,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAA;IACvB,IAAI,CAAC,EAAE,OAAO,CAAA;CACf;AAED,UAAU,aAAa;IACrB,OAAO,EAAE,MAAM,CAAA;IACf,SAAS,EAAE,MAAM,IAAI,CAAA;IACrB,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;CAC3B;AAED,wBAAsB,YAAY,CAAC,OAAO,EAAE,mBAAmB,EAAE,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,aAAa,CAAC,CAwBrG"}
+{"version":3,"file":"preview.d.ts","sourceRoot":"","sources":["../../src/node/preview.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AAG3C,MAAM,WAAW,mBAAmB;IAClC,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAA;IACvB,IAAI,CAAC,EAAE,OAAO,CAAA;CACf;AAED,UAAU,aAAa;IACrB,OAAO,EAAE,MAAM,CAAA;IACf,SAAS,EAAE,MAAM,IAAI,CAAA;IACrB,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;CAC3B;AAED,wBAAsB,YAAY,CAAC,OAAO,EAAE,mBAAmB,EAAE,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,aAAa,CAAC,CA6BrG"}

package/dist/node/preview.js

@@ -12,7 +12,12 @@ export async function startPreview(options, ctx) {
             port,
             host: options.host,
             open: options.open,
-            strictPort: false,
+            // A port asked for by name has to be that port or nothing. Moving to the
+            // next free one serves the book where nobody is looking, and lands it on
+            // whatever example owns that number, whose suite then adopts it (#175).
+            // Without an explicit port there is no such expectation, and `build`'s
+            // internal preview reads the port back off the server.
+            strictPort: options.port != null,
         },
     });
     const baseUrl = server.resolvedUrls?.local[0] ?? `http://localhost:${port}${ctx.resolvedViteConfig.base}`;

package/dist/node/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/node/server.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AAa3C,MAAM,WAAW,mBAAmB;IAClC,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAA;CACxB;AAED,wBAAsB,YAAY,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,GAAE,mBAAwB;;;;GAsNjF"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/node/server.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AAa3C,MAAM,WAAW,mBAAmB;IAClC,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAA;CACxB;AAED,wBAAsB,YAAY,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,GAAE,mBAAwB;;;;GA6NjF"}

package/dist/node/server.js

@@ -19,6 +19,12 @@ export async function createServer(ctx, options = {}) {
             if (options.host) {
                 viteConfig.server.host = options.host;
             }
+            // Same rule as `preview`: a port asked for by name is that port or
+            // nothing. Floating to the next free one hands back a server nobody asked
+            // for, and whoever opens the port they typed reads a different book.
+            if (options.port != null) {
+                viteConfig.server.strictPort = true;
+            }
         }
         const server = await createViteServer(mergeViteConfig(viteConfig, {
             optimizeDeps: { include: viteConfig.optimizeDeps?.include ?? [], noDiscovery: collecting },

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "poveste",
   "type": "module",
-  "version": "0.5.2",
+  "version": "0.5.3",
   "description": "A fast story book powered by Vite",
   "author": {
     "name": "Sorin Gitlan"
@@ -68,10 +68,10 @@
     "sirv": "^3.0.0",
     "unhead": "^3.1.0",
     "vite-node": "^6.0.0",
-    "@poveste/app": "^0.5.2",
-    "@poveste/controls": "^0.5.2",
-    "@poveste/shared": "^0.5.2",
-    "@poveste/vendors": "^0.5.2"
+    "@poveste/app": "^0.5.3",
+    "@poveste/shared": "^0.5.3",
+    "@poveste/controls": "^0.5.3",
+    "@poveste/vendors": "^0.5.3"
   },
   "devDependencies": {
     "@types/fs-extra": "^11.0.4",

package/src/node/__tests__/port.spec.ts

@@ -0,0 +1,33 @@
+import { describe, expect, it } from 'vitest'
+import { resolvePort } from '../commands/port.js'
+
+describe('resolvePort', () => {
+  it('returns undefined when the flag was not passed', () => {
+    expect(resolvePort(undefined, 'preview')).toBeUndefined()
+  })
+
+  it('parses the number sade hands over as a string', () => {
+    expect(resolvePort('4569', 'preview')).toBe(4569)
+  })
+
+  it('passes a number through', () => {
+    expect(resolvePort(6006, 'dev')).toBe(6006)
+  })
+
+  // sade declares `--port <port>` but does not enforce the value, so a bare
+  // `--port` arrives as `true`. `Number(true)` is 1 — a valid port that binds
+  // to a privileged one — so this has to be rejected by type.
+  it.each([
+    ['a valueless flag', true],
+    ['a non-numeric value', 'abc'],
+    ['an empty value', ''],
+    ['a port above the range', '99999'],
+    ['a fractional port', '80.5'],
+  ])('rejects %s', (_name, value) => {
+    expect(() => resolvePort(value, 'preview')).toThrow(/--port needs a number/)
+  })
+
+  it('names the command in the message, so the hint is runnable', () => {
+    expect(() => resolvePort(true, 'dev')).toThrow(/poveste dev --port 6006/)
+  })
+})

package/src/node/bin.ts

@@ -9,6 +9,7 @@ const { version } = JSON.parse(fs.readFileSync(resolve(__dirname, '../../package
 
 process.env.NODE_ENV = 'development'
 process.env.HISTOIRE = 'true'
+process.env.POVESTE = 'true'
 
 const program = sade('poveste')
 program.version(version)

package/src/node/builtin-plugins/pinceau-tokens.ts

@@ -52,7 +52,9 @@ export function pinceauTokens(_options: PinceauTokensOptions = {}): Plugin {
       }
     },
 
-    onDev(api, onCleanup) {
+    async onDev(api, onCleanup) {
+      await generate(api)
+
       const watcher = api.watcher.watch(themePath)
         .on('change', () => generate(api))
         .on('add', () => generate(api))

package/src/node/builtin-plugins/tailwind-tokens.ts

@@ -77,8 +77,10 @@ export function tailwindTokens(options: TailwindTokensOptions = {}): Plugin {
       }
     },
 
-    onDev(api, onCleanup) {
+    async onDev(api, onCleanup) {
       if (tailwindCssFile) {
+        await generate(api)
+
         const watcher = api.watcher.watch(tailwindCssFile)
           .on('change', () => generate(api))
           .on('add', () => generate(api))

package/src/node/commands/dev.ts

@@ -4,15 +4,18 @@ import pc from 'picocolors'
 import { resolveConfigFile } from '../config.js'
 import { createContext } from '../context.js'
 import { createServer } from '../server.js'
+import { resolvePort } from './port.js'
 
 export interface DevOptions {
-  port: number
+  port?: number | string
   open?: boolean
   host?: string | boolean
   config?: string
 }
 
 export async function devCommand(options: DevOptions) {
+  const port = resolvePort(options.port, 'dev')
+
   let stop: () => Promise<void>
 
   async function start() {
@@ -21,7 +24,7 @@ export async function devCommand(options: DevOptions) {
       mode: 'dev',
     })
     const { server, viteConfigFile, close } = await createServer(ctx, {
-      port: options.port,
+      port,
       open: options.open,
       host: options.host,
     })

package/src/node/commands/port.ts

@@ -0,0 +1,29 @@
+/**
+ * Reads a `--port` value off the parsed CLI options.
+ *
+ * sade declares the flag as taking a value but does not enforce one, so
+ * `poveste preview --port` arrives as the boolean `true` and reaches node's
+ * listen validation, which rejects it with `ERR_INVALID_ARG_VALUE` and names
+ * neither the flag nor the mistake. A non-numeric value fails the same way.
+ */
+export function resolvePort(value: unknown, command: string): number | undefined {
+  if (value === undefined || value === null) {
+    return undefined
+  }
+
+  // Checked by type, not by coercion: a valueless flag arrives as `true`, and
+  // `Number(true)` is 1, a valid port that would bind to a privileged one.
+  const port = typeof value === 'number'
+    ? value
+    : typeof value === 'string' && value.trim() !== ''
+      ? Number(value)
+      : Number.NaN
+
+  if (!Number.isInteger(port) || port < 0 || port > 65535) {
+    throw new TypeError(
+      `--port needs a number between 0 and 65535, got ${JSON.stringify(value)}. Try \`poveste ${command} --port 6006\`.`,
+    )
+  }
+
+  return port
+}

package/src/node/commands/preview.ts

@@ -1,13 +1,16 @@
 import { createContext } from '../context.js'
 import { startPreview } from '../preview.js'
+import { resolvePort } from './port.js'
 
 export interface PreviewOptions {
-  port?: number
+  port?: number | string
   host?: string | boolean
   open?: boolean
 }
 
 export async function previewCommand(options: PreviewOptions) {
+  const port = resolvePort(options.port, 'preview')
+
   const ctx = await createContext({
     mode: 'build',
   })
@@ -19,7 +22,7 @@ export async function previewCommand(options: PreviewOptions) {
   }
 
   const { printUrls } = await startPreview({
-    port: options.port,
+    port,
     host: options.host,
     open: options.open,
   }, ctx)

package/src/node/config.ts

@@ -122,7 +122,6 @@ export function getDefaultConfig(): PovesteConfig {
         contrastColor: '#eee',
       },
     ],
-    sandboxDarkClass: 'dark',
     routerMode: 'history',
     build: {
       excludeFromVendorsChunk: [],

package/src/node/preview.ts

@@ -26,7 +26,12 @@ export async function startPreview(options: StartPreviewOptions, ctx: Context):
       port,
       host: options.host,
       open: options.open,
-      strictPort: false,
+      // A port asked for by name has to be that port or nothing. Moving to the
+      // next free one serves the book where nobody is looking, and lands it on
+      // whatever example owns that number, whose suite then adopts it (#175).
+      // Without an explicit port there is no such expectation, and `build`'s
+      // internal preview reads the port back off the server.
+      strictPort: options.port != null,
     },
   })
 

package/src/node/server.ts

@@ -30,6 +30,13 @@ export async function createServer(ctx: Context, options: CreateServerOptions =
       if (options.host) {
         viteConfig.server.host = options.host
       }
+
+      // Same rule as `preview`: a port asked for by name is that port or
+      // nothing. Floating to the next free one hands back a server nobody asked
+      // for, and whoever opens the port they typed reads a different book.
+      if (options.port != null) {
+        viteConfig.server.strictPort = true
+      }
     }
 
     const server = await createViteServer(