@inditextech/docouture-cli 0.1.0-SNAPSHOT.83.1 → 0.1.0-SNAPSHOT.88.1

package/build/bin.js

@@ -89,7 +89,9 @@ change to docs/ or antora-playbook.yml. --dir is the repository root
 (the parent of docs/), same as new/version — not the site directory.
 
 Options:
-  --port <port>  Port to listen on (default: 5000)
+  --port <port>  Port to listen on (default: 5000, falls back to a random
+                 free port if 5000 is busy — an explicit --port that's busy
+                 is still a hard error)
   --dir <path>   Repository root (default: cwd, or its enclosing repo)
 `,
     },

package/build/lib/dev-server.js

@@ -26,6 +26,7 @@ const RELOAD_PATH = '/__dev/reload';
 const CLIENT_PATH = '/__dev/client.js';
 const DEBOUNCE_MS = 150;
 const BUILD_TIMEOUT_MS = 120_000;
+const DEFAULT_PORT = 5000;
 const CLIENT_SCRIPT = `// Injected by docouture dev. Not part of the built site.
 const es = new EventSource(${JSON.stringify(RELOAD_PATH)})
 es.addEventListener('message', () => location.reload())
@@ -315,14 +316,36 @@ export async function startDevServer(options) {
         logError('initial rebuild failed, serving the previous build');
     }
     await new Promise((resolvePromise, reject) => {
-        server.once('error', reject);
-        server.listen(options.port ?? 5000, () => {
-            server.off('error', reject);
+        // `options.port` set (including 0, which a test uses to pick any free
+        // port) means the caller chose this port deliberately — a busy port
+        // there is a hard failure, same as always. Nothing set means the
+        // *default* port, which is routinely squatted by something the user
+        // never asked to avoid (macOS AirPlay Receiver on 5000, most commonly):
+        // that case retries with `listen(0)`, an OS-assigned free port, instead
+        // of failing the whole dev server over a port nobody actually chose.
+        const explicitPort = options.port !== undefined;
+        const requestedPort = options.port ?? options.defaultPort ?? DEFAULT_PORT;
+        const onListenError = (err) => {
+            if (!explicitPort && err.code === 'EADDRINUSE') {
+                server.off('error', onListenError);
+                logError(`port ${requestedPort} is already in use, falling back to a random free port`);
+                server.once('error', reject);
+                server.listen(0, () => {
+                    server.off('error', reject);
+                    resolvePromise();
+                });
+                return;
+            }
+            reject(err);
+        };
+        server.once('error', onListenError);
+        server.listen(requestedPort, () => {
+            server.off('error', onListenError);
             resolvePromise();
         });
     });
     const address = server.address();
-    const port = typeof address === 'object' && address ? address.port : (options.port ?? 5000);
+    const port = typeof address === 'object' && address ? address.port : (options.port ?? DEFAULT_PORT);
     log(`serving ${root}`);
     log(`  http://localhost:${port}${basePath}/`);
     const watchers = [

package/build/templates/starter/src/modules/main/pages/components.adoc

@@ -96,6 +96,9 @@ fragment: xref:main:getting-started.adoc#add-a-page[a specific section on that p
 .A block image, capped at its own natural size
 image::ROOT:hero-placeholder.png[A placeholder image,480]
 
+.The same image, marked `role=zoom-in` — click it for a bigger, fullscreen view (GH-197)
+image::ROOT:hero-placeholder.png[A placeholder image,480,role=zoom-in]
+
 An inline image sits mid-paragraph: image:ROOT:card-placeholder.png[A small inline
 placeholder,20,20] like so. Font icons, keyboard shortcuts and UI paths:
 icon:check[] done, kbd:[Ctrl+C] to copy, btn:[Save] to save, menu:File[Save As] to open
@@ -764,10 +767,39 @@ includes an `excalidraw` service alongside `mermaid` for exactly that reason:
       "fontSize": 20,
       "seed": 2
     }
-  ]
+   ]
 }
 ....
 
+==== Zoom
+
+Any diagram (or, per the "Images and icons" section above, any plain `image::` block)
+marked `role=zoom-in` gets a click-to-zoom affordance: a `zoom-in` cursor and a subtle
+hover tint for a mouse, a small persistent badge for touch, and clicking/tapping opens
+a fullscreen overlay with a bigger view — Esc, the close icon, or the backdrop all
+dismiss it:
+
+[,asciidoc]
+----
+[mermaid,role=zoom-in]
+....
+stateDiagram-v2
+  [*] --> Idle
+  Idle --> Running : start
+  Running --> Idle : stop
+....
+----
+
+[mermaid,role=zoom-in]
+....
+stateDiagram-v2
+  [*] --> Idle
+  Idle --> Running : start
+  Running --> Idle : stop
+....
+
+Static, no pan/pinch-zoom — a bigger, still image, not an image viewer.
+
 === Inline macros: `label:` and `mono:`
 
 label:grey[Default] label:red[Blocked] label:orange[Pending] label:green[Stable]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inditextech/docouture-cli",
-  "version": "0.1.0-SNAPSHOT.83.1",
+  "version": "0.1.0-SNAPSHOT.88.1",
   "description": "Command-line tool for docouture documentation sites: scaffold a new site and set its Antora version outside the monorepo",
   "repository": {
     "type": "git",