pmx-canvas 0.1.10 → 0.1.12

package/src/server/canvas-operations.ts

@@ -67,6 +67,7 @@ export interface CanvasStructuredNodeUpdateInput extends Omit<CanvasGraphNodeUpd
   content?: unknown;
   data?: unknown;
   arrangeLocked?: unknown;
+  strictSize?: boolean;
   chartHeight?: unknown;
 }
 
@@ -82,6 +83,7 @@ interface CanvasAddNodeInput {
   defaultWidth?: number;
   defaultHeight?: number;
   fileMode?: 'path' | 'inline' | 'auto';
+  strictSize?: boolean;
 }
 
 interface CanvasCreateGroupInput {
@@ -164,6 +166,8 @@ function hasGraphUpdateFields(input: Record<string, unknown>): boolean {
     input.zKey !== undefined ||
     input.nameKey !== undefined ||
     input.valueKey !== undefined ||
+    input.showLegend !== undefined ||
+    input.showLabels !== undefined ||
     input.axisKey !== undefined ||
     input.metrics !== undefined ||
     input.series !== undefined ||
@@ -200,6 +204,7 @@ function mergeNodeDataFields(
     ...base,
     ...(isRecord(input.data) ? input.data : {}),
     ...(typeof input.arrangeLocked === 'boolean' ? { arrangeLocked: input.arrangeLocked } : {}),
+    ...(typeof input.strictSize === 'boolean' ? { strictSize: input.strictSize } : {}),
   };
 }
 
@@ -251,6 +256,8 @@ function graphConfigToInput(config: Record<string, unknown>, fallbackTitle: stri
     ...(pickString(config, 'zKey') ? { zKey: pickString(config, 'zKey') } : {}),
     ...(pickString(config, 'nameKey') ? { nameKey: pickString(config, 'nameKey') } : {}),
     ...(pickString(config, 'valueKey') ? { valueKey: pickString(config, 'valueKey') } : {}),
+    ...(typeof config.showLegend === 'boolean' ? { showLegend: config.showLegend } : {}),
+    ...(typeof config.showLabels === 'boolean' ? { showLabels: config.showLabels } : {}),
     ...(pickString(config, 'axisKey') ? { axisKey: pickString(config, 'axisKey') } : {}),
     ...(pickStringArray(config, 'metrics') ? { metrics: pickStringArray(config, 'metrics') } : {}),
     ...(pickStringArray(config, 'series') ? { series: pickStringArray(config, 'series') } : {}),
@@ -276,6 +283,12 @@ function mergeGraphInput(source: Record<string, unknown>, fallback: GraphNodeInp
     ...((pickString(source, 'zKey') ?? fallback?.zKey) ? { zKey: pickString(source, 'zKey') ?? fallback?.zKey } : {}),
     ...((pickString(source, 'nameKey') ?? fallback?.nameKey) ? { nameKey: pickString(source, 'nameKey') ?? fallback?.nameKey } : {}),
     ...((pickString(source, 'valueKey') ?? fallback?.valueKey) ? { valueKey: pickString(source, 'valueKey') ?? fallback?.valueKey } : {}),
+    ...(typeof source.showLegend === 'boolean' || typeof fallback?.showLegend === 'boolean'
+      ? { showLegend: typeof source.showLegend === 'boolean' ? source.showLegend : fallback?.showLegend }
+      : {}),
+    ...(typeof source.showLabels === 'boolean' || typeof fallback?.showLabels === 'boolean'
+      ? { showLabels: typeof source.showLabels === 'boolean' ? source.showLabels : fallback?.showLabels }
+      : {}),
     ...((pickString(source, 'axisKey') ?? fallback?.axisKey) ? { axisKey: pickString(source, 'axisKey') ?? fallback?.axisKey } : {}),
     ...((pickStringArray(source, 'metrics') ?? fallback?.metrics) ? { metrics: pickStringArray(source, 'metrics') ?? fallback?.metrics } : {}),
     ...((pickStringArray(source, 'series') ?? fallback?.series) ? { series: pickStringArray(source, 'series') ?? fallback?.series } : {}),
@@ -752,6 +765,7 @@ function buildNodeData(input: CanvasAddNodeInput): Record<string, unknown> {
     ...(input.data ?? {}),
     ...(input.title ? { title: input.title } : {}),
     ...(input.content ? { content: input.content } : {}),
+    ...(input.strictSize ? { strictSize: true } : {}),
   };
 }
 
@@ -1271,6 +1285,7 @@ export function createCanvasJsonRenderNode(
     dockPosition: null,
     data: createJsonRenderNodeData(id, input.title?.trim() || inferJsonRenderNodeTitle(spec), spec, {
       viewerType: 'json-render',
+      ...(input.strictSize ? { strictSize: true } : {}),
     }),
   };
 
@@ -1302,6 +1317,7 @@ export function createCanvasGraphNode(
     data: createJsonRenderNodeData(id, title, spec, {
       viewerType: 'graph',
       graphConfig: buildGraphConfig(input),
+      ...(input.strictSize ? { strictSize: true } : {}),
     }),
   };
 
@@ -1418,6 +1434,7 @@ export async function executeCanvasBatch(
               ...(typeof args.y === 'number' ? { y: args.y } : {}),
               ...(typeof args.width === 'number' ? { width: args.width } : {}),
               ...(typeof args.height === 'number' ? { height: args.height } : {}),
+              ...(args.strictSize === true ? { strictSize: true } : {}),
               defaultWidth: 520,
               defaultHeight: 420,
             });
@@ -1441,6 +1458,7 @@ export async function executeCanvasBatch(
               ...(typeof args.y === 'number' ? { y: args.y } : {}),
               ...(typeof args.width === 'number' ? { width: args.width } : {}),
               ...(typeof args.height === 'number' ? { height: args.height } : {}),
+              ...(args.strictSize === true ? { strictSize: true } : {}),
               defaultWidth: 360,
               defaultHeight: 200,
               fileMode: 'auto',
@@ -1471,12 +1489,13 @@ export async function executeCanvasBatch(
           if (args.dockPosition === null || args.dockPosition === 'left' || args.dockPosition === 'right') {
             patch.dockPosition = args.dockPosition;
           }
-          if (typeof args.title === 'string' || typeof args.content === 'string' || typeof args.arrangeLocked === 'boolean' || isPlainRecord(args.data)) {
+          if (typeof args.title === 'string' || typeof args.content === 'string' || typeof args.arrangeLocked === 'boolean' || typeof args.strictSize === 'boolean' || isPlainRecord(args.data)) {
             patch.data = {
               ...node.data,
               ...(typeof args.title === 'string' ? { title: args.title } : {}),
               ...(typeof args.content === 'string' ? { content: args.content } : {}),
               ...(typeof args.arrangeLocked === 'boolean' ? { arrangeLocked: args.arrangeLocked } : {}),
+              ...(typeof args.strictSize === 'boolean' ? { strictSize: args.strictSize } : {}),
               ...(isPlainRecord(args.data) ? args.data : {}),
             };
           }
@@ -1511,6 +1530,7 @@ export async function executeCanvasBatch(
             ...(typeof args.y === 'number' ? { y: args.y } : {}),
             ...(typeof args.width === 'number' ? { width: args.width } : {}),
             ...(typeof args.nodeHeight === 'number' ? { heightPx: args.nodeHeight } : {}),
+            ...(args.strictSize === true ? { strictSize: true } : {}),
           });
           result = {
             ok: true,

package/src/server/canvas-schema.ts

@@ -72,6 +72,7 @@ const CANVAS_CREATE_TYPES: CanvasCreateTypeSchema[] = [
       { name: 'y', type: 'number', required: false, description: 'Optional Y position.' },
       { name: 'width', type: 'number', required: false, description: 'Optional node width.' },
       { name: 'height', type: 'number', required: false, description: 'Optional node height.' },
+      { name: 'strictSize', type: 'boolean', required: false, description: 'Keep explicit width/height fixed and scroll overflowing content instead of browser auto-fitting.', aliases: ['strict-size', 'scroll-overflow'] },
     ],
     example: {
       type: 'markdown',
@@ -203,6 +204,7 @@ const CANVAS_CREATE_TYPES: CanvasCreateTypeSchema[] = [
       { name: 'y', type: 'number', required: false, description: 'Optional Y position.' },
       { name: 'width', type: 'number', required: false, description: 'Optional node width.' },
       { name: 'height', type: 'number', required: false, description: 'Optional node height.' },
+      { name: 'strictSize', type: 'boolean', required: false, description: 'Keep explicit width/height fixed and scroll overflowing content instead of browser auto-fitting.', aliases: ['strict-size', 'scroll-overflow'] },
     ],
     example: {
       type: 'webpage',
@@ -337,8 +339,11 @@ const CANVAS_CREATE_TYPES: CanvasCreateTypeSchema[] = [
       { name: 'barColor', type: 'string', required: false, description: 'Optional bar color for composed charts.', aliases: ['bar-color'] },
       { name: 'lineColor', type: 'string', required: false, description: 'Optional line color for composed charts.', aliases: ['line-color'] },
       { name: 'height', type: 'number', required: false, description: 'Optional chart content height.', aliases: ['chart-height'] },
+      { name: 'showLegend', type: 'boolean', required: false, description: 'Show chart legend when supported; pass false for compact node layouts.', aliases: ['show-legend'] },
+      { name: 'showLabels', type: 'boolean', required: false, description: 'Show direct labels when supported, such as pie slice labels; defaults to true.', aliases: ['show-labels'] },
       { name: 'width', type: 'number', required: false, description: 'Optional node width.' },
       { name: 'nodeHeight', type: 'number', required: false, description: 'Optional node height (canvas frame). Distinct from `height`, which sets only the chart content height inside the node.', aliases: ['node-height'] },
+      { name: 'strictSize', type: 'boolean', required: false, description: 'Keep explicit node size fixed and scroll overflowing content instead of browser auto-fitting.', aliases: ['strict-size', 'scroll-overflow'] },
     ],
     example: {
       title: 'Deploy Trend',

package/src/server/diagram-presets.ts

@@ -115,6 +115,18 @@ function elementHasCameraUpdate(elements: Array<Record<string, unknown>>): boole
   return elements.some((element) => element.type === 'cameraUpdate');
 }
 
+function hasRenderableExcalidrawElement(elements: Array<Record<string, unknown>>): boolean {
+  return elements.some((element) => {
+    if (element.isDeleted === true) return false;
+    if (element.type === 'cameraUpdate' || element.type === 'restoreCheckpoint' || element.type === 'delete') return false;
+    if (typeof element.type !== 'string' || element.type.length === 0) return false;
+    if (element.type === 'text') {
+      return typeof element.text === 'string' && element.text.trim().length > 0;
+    }
+    return finiteNumber(element.x) !== null && finiteNumber(element.y) !== null;
+  });
+}
+
 function normalizeExcalidrawBoundText(elements: Array<Record<string, unknown>>): Array<Record<string, unknown>> {
   const elementsById = new Map<string, Record<string, unknown>>();
   for (const element of elements) {
@@ -123,38 +135,58 @@ function normalizeExcalidrawBoundText(elements: Array<Record<string, unknown>>):
 
   let changed = false;
   const boundElementIdsByContainer = new Map<string, Set<string>>();
+  const labelByContainer = new Map<string, Record<string, unknown>>();
+  const textIdsConvertedToLabels = new Set<string>();
 
   for (const element of elements) {
     if (element.type !== 'text' || typeof element.id !== 'string' || typeof element.containerId !== 'string') continue;
-    if (!elementsById.has(element.containerId)) continue;
+    const container = elementsById.get(element.containerId);
+    if (!container) continue;
     const ids = boundElementIdsByContainer.get(element.containerId) ?? new Set<string>();
     ids.add(element.id);
     boundElementIdsByContainer.set(element.containerId, ids);
+    const text = typeof element.text === 'string' ? element.text.trim() : '';
+    if (!isRecord(container.label) && text.length > 0) {
+      labelByContainer.set(element.containerId, {
+        text,
+        ...(typeof element.fontSize === 'number' && Number.isFinite(element.fontSize) ? { fontSize: element.fontSize } : {}),
+      });
+      textIdsConvertedToLabels.add(element.id);
+    }
   }
 
-  const normalized = elements.map((element) => {
+  const normalized = elements.flatMap<Record<string, unknown>>((element) => {
+    if (typeof element.id === 'string' && textIdsConvertedToLabels.has(element.id)) {
+      changed = true;
+      return [];
+    }
     if (typeof element.id !== 'string') return element;
     const boundTextIds = boundElementIdsByContainer.get(element.id);
-    if (!boundTextIds || boundTextIds.size === 0) return element;
+    const label = labelByContainer.get(element.id);
+    if ((!boundTextIds || boundTextIds.size === 0) && !label) return element;
 
     const existing = Array.isArray(element.boundElements)
       ? element.boundElements.filter(isRecord)
       : [];
+    const remainingExisting = existing.filter((boundElement) => {
+      return !(boundElement.type === 'text' && typeof boundElement.id === 'string' && textIdsConvertedToLabels.has(boundElement.id));
+    });
     const existingTextIds = new Set(
-      existing
+      remainingExisting
         .filter((boundElement) => boundElement.type === 'text' && typeof boundElement.id === 'string')
         .map((boundElement) => boundElement.id as string),
     );
-    const missing = [...boundTextIds].filter((id) => !existingTextIds.has(id));
-    if (missing.length === 0) return element;
+    const missing = [...(boundTextIds ?? [])]
+      .filter((id) => !textIdsConvertedToLabels.has(id) && !existingTextIds.has(id));
+    if (missing.length === 0 && !label && remainingExisting.length === existing.length) return element;
 
     changed = true;
     return {
       ...element,
-      boundElements: [
-        ...existing,
-        ...missing.map((id) => ({ type: 'text', id })),
-      ],
+      ...(label ? { label } : {}),
+      ...(remainingExisting.length > 0 || missing.length > 0
+        ? { boundElements: [...remainingExisting, ...missing.map((id) => ({ type: 'text', id }))] }
+        : {}),
     };
   });
 
@@ -251,12 +283,12 @@ function withInferredCameraUpdate(
 
 export function normalizeExcalidrawElements(elements: unknown): string {
   const parsed = parseExcalidrawElements(elements);
-  return JSON.stringify(parsed.length > 0 ? parsed : DEFAULT_EXCALIDRAW_ELEMENTS);
+  return JSON.stringify(hasRenderableExcalidrawElement(parsed) ? parsed : DEFAULT_EXCALIDRAW_ELEMENTS);
 }
 
 export function normalizeExcalidrawElementsForToolInput(elements: unknown): string {
   const parsed = parseExcalidrawElements(elements);
-  const seeded = parsed.length > 0 ? parsed : [...DEFAULT_EXCALIDRAW_ELEMENTS];
+  const seeded = hasRenderableExcalidrawElement(parsed) ? parsed : [...DEFAULT_EXCALIDRAW_ELEMENTS];
   return JSON.stringify(withInferredCameraUpdate(normalizeExcalidrawBoundText(seeded)));
 }
 

package/src/server/index.ts

@@ -97,7 +97,7 @@ export class PmxCanvas extends EventEmitter {
     open?: boolean;
     automationWebView?: boolean | CanvasAutomationWebViewOptions;
   }): Promise<void> {
-    const base = startCanvasServer({ port: this._port });
+    const base = startCanvasServer({ port: this._port, allowPortFallback: false });
     if (!base) {
       throw new Error(`Failed to start canvas server on port ${this._port}`);
     }
@@ -162,6 +162,7 @@ export class PmxCanvas extends EventEmitter {
     y?: number;
     width?: number;
     height?: number;
+    strictSize?: boolean;
   }): string {
     if (input.type === 'webpage') {
       throw new Error('Use addWebpageNode for webpage nodes so page content is fetched and cached on the server.');
@@ -171,6 +172,7 @@ export class PmxCanvas extends EventEmitter {
       defaultWidth: 360,
       defaultHeight: 200,
       fileMode: 'path',
+      ...(input.strictSize ? { strictSize: true } : {}),
     });
 
     emitPrimaryWorkbenchEvent('canvas-layout-update', { layout: canvasState.getLayout() });
@@ -191,6 +193,7 @@ export class PmxCanvas extends EventEmitter {
     y?: number;
     width?: number;
     height?: number;
+    strictSize?: boolean;
   }): Promise<{ ok: boolean; id: string; error?: string; fetch: { ok: boolean; error?: string } }> {
     const { id } = addCanvasNode({
       type: 'webpage',
@@ -200,6 +203,7 @@ export class PmxCanvas extends EventEmitter {
       ...(typeof input.y === 'number' ? { y: input.y } : {}),
       ...(typeof input.width === 'number' ? { width: input.width } : {}),
       ...(typeof input.height === 'number' ? { height: input.height } : {}),
+      ...(input.strictSize ? { strictSize: true } : {}),
       defaultWidth: 520,
       defaultHeight: 420,
     });
@@ -238,7 +242,8 @@ export class PmxCanvas extends EventEmitter {
       patch.data !== undefined ||
       patch.title !== undefined ||
       patch.content !== undefined ||
-      typeof patch.arrangeLocked === 'boolean'
+      typeof patch.arrangeLocked === 'boolean' ||
+      typeof patch.strictSize === 'boolean'
     ) {
       resolvedPatch.data = {
         ...existing.data,
@@ -246,6 +251,7 @@ export class PmxCanvas extends EventEmitter {
         ...(typeof patch.title === 'string' ? { title: patch.title } : {}),
         ...(typeof patch.content === 'string' ? { content: patch.content } : {}),
         ...(typeof patch.arrangeLocked === 'boolean' ? { arrangeLocked: patch.arrangeLocked } : {}),
+        ...(typeof patch.strictSize === 'boolean' ? { strictSize: patch.strictSize } : {}),
       };
     }
 
@@ -599,7 +605,7 @@ export class PmxCanvas extends EventEmitter {
   async startAutomationWebView(
     options: CanvasAutomationWebViewOptions = {},
   ): Promise<CanvasAutomationWebViewStatus> {
-    const base = this._server ?? startCanvasServer({ port: this._port });
+    const base = this._server ?? startCanvasServer({ port: this._port, allowPortFallback: false });
     if (!base) {
       throw new Error(`Failed to start canvas server on port ${this._port}`);
     }

package/src/server/server.ts

@@ -828,6 +828,24 @@ function findOnlyPendingCanvasExtAppNodeId(serverName: string, toolName: string)
   return matchId;
 }
 
+function extAppEventGeometryPatch(
+  node: CanvasNodeState,
+  payload: PrimaryWorkbenchEventPayload,
+): Partial<Pick<CanvasNodeState, 'position' | 'size'>> {
+  const x = typeof payload.x === 'number' ? payload.x : undefined;
+  const y = typeof payload.y === 'number' ? payload.y : undefined;
+  const width = typeof payload.width === 'number' ? payload.width : undefined;
+  const height = typeof payload.height === 'number' ? payload.height : undefined;
+  return {
+    ...(x !== undefined || y !== undefined
+      ? { position: { x: x ?? node.position.x, y: y ?? node.position.y } }
+      : {}),
+    ...(width !== undefined || height !== undefined
+      ? { size: { width: width ?? node.size.width, height: height ?? node.size.height } }
+      : {}),
+  };
+}
+
 function toSseFrame(event: string, payload: PrimaryWorkbenchEventPayload): Uint8Array {
   const id = nextWorkbenchEventId++;
   const lines = [`id: ${id}`, `event: ${event}`, `data: ${JSON.stringify(payload)}`, ''];
@@ -1250,6 +1268,7 @@ async function createCanvasWebpageNode(body: Record<string, unknown>): Promise<R
     ...(typeof body.title === 'string' ? { title: body.title } : {}),
     content: normalizedUrl,
     ...(extraData ? { data: extraData } : {}),
+    ...(body.strictSize === true ? { strictSize: true } : {}),
     ...geometry,
     ...(geometry.width === undefined ? { width: WEBPAGE_NODE_DEFAULT_SIZE.width } : {}),
     ...(geometry.height === undefined ? { height: WEBPAGE_NODE_DEFAULT_SIZE.height } : {}),
@@ -1312,6 +1331,7 @@ async function handleCanvasAddNode(req: Request): Promise<Response> {
       ...(typeof body.title === 'string' ? { title: body.title } : {}),
       ...(typeof content === 'string' ? { content } : {}),
       ...(extraData ? { data: extraData } : {}),
+      ...(body.strictSize === true ? { strictSize: true } : {}),
       ...geometry,
       defaultWidth: 360,
       defaultHeight: 200,
@@ -1475,7 +1495,7 @@ async function handleCanvasUpdateNode(nodeId: string, req: Request): Promise<Res
     } catch (error) {
       return responseJson({ ok: false, error: error instanceof Error ? error.message : String(error) }, 400);
     }
-  } else if (body.title !== undefined || body.content !== undefined || body.data || typeof body.arrangeLocked === 'boolean') {
+  } else if (body.title !== undefined || body.content !== undefined || body.data || typeof body.arrangeLocked === 'boolean' || typeof body.strictSize === 'boolean') {
     const data = { ...existing.data };
     if (body.title !== undefined) {
       data.title = String(body.title);
@@ -1485,6 +1505,7 @@ async function handleCanvasUpdateNode(nodeId: string, req: Request): Promise<Res
     }
     if (body.content !== undefined) data.content = String(body.content);
     if (typeof body.arrangeLocked === 'boolean') data.arrangeLocked = body.arrangeLocked;
+    if (typeof body.strictSize === 'boolean') data.strictSize = body.strictSize;
     // Merge extra data fields (for status, context, ledger, trace nodes)
     if (body.data && typeof body.data === 'object' && !Array.isArray(body.data)) {
       Object.assign(data, body.data as Record<string, unknown>);
@@ -1720,6 +1741,7 @@ async function handleCanvasAddJsonRender(req: Request): Promise<Response> {
     const result = createCanvasJsonRenderNode({
       ...(title ? { title } : {}),
       spec: rawSpec,
+      ...(body.strictSize === true ? { strictSize: true } : {}),
       ...geometry,
     });
     emitPrimaryWorkbenchEvent('canvas-layout-update', { layout: canvasState.getLayout() });
@@ -1756,6 +1778,8 @@ async function handleCanvasAddGraph(req: Request): Promise<Response> {
     const y = pickFiniteNumber(body, 'y') ?? (position ? pickFiniteNumber(position, 'y') : undefined);
     const width = pickPositiveNumber(body, 'width') ?? (size ? pickPositiveNumber(size, 'width') : undefined);
     const nodeHeight = pickPositiveNumber(body, 'nodeHeight') ?? (size ? pickPositiveNumber(size, 'height') : undefined);
+    const showLegend = typeof body.showLegend === 'boolean' ? body.showLegend : undefined;
+    const showLabels = typeof body.showLabels === 'boolean' ? body.showLabels : undefined;
     const result = createCanvasGraphNode({
       title,
       graphType,
@@ -1775,6 +1799,9 @@ async function handleCanvasAddGraph(req: Request): Promise<Response> {
       ...(typeof body.barColor === 'string' ? { barColor: body.barColor } : {}),
       ...(typeof body.lineColor === 'string' ? { lineColor: body.lineColor } : {}),
       ...(typeof body.height === 'number' ? { height: body.height } : {}),
+      ...(showLegend !== undefined ? { showLegend } : {}),
+      ...(showLabels !== undefined ? { showLabels } : {}),
+      ...(body.strictSize === true ? { strictSize: true } : {}),
       ...(x !== undefined ? { x } : {}),
       ...(y !== undefined ? { y } : {}),
       ...(width !== undefined ? { width } : {}),
@@ -3336,7 +3363,10 @@ function syncEventToCanvasState(event: string, payload: PrimaryWorkbenchEventPay
       if (previousSessionId && nextSessionId && previousSessionId !== nextSessionId) {
         closeMcpAppSession(previousSessionId);
       }
-      canvasState.updateNode(id, { data: { ...existing.data, ...dataPatch } });
+      canvasState.updateNode(id, {
+        data: { ...existing.data, ...dataPatch },
+        ...extAppEventGeometryPatch(existing, payload),
+      });
     } else {
       const reusableNodeId =
         typeof payload.serverName === 'string' &&
@@ -3355,6 +3385,7 @@ function syncEventToCanvasState(event: string, payload: PrimaryWorkbenchEventPay
         }
         canvasState.updateNode(reusableNodeId, {
           data: { ...reusableNode.data, ...dataPatch },
+          ...extAppEventGeometryPatch(reusableNode, payload),
         });
         return;
       }
@@ -3696,6 +3727,7 @@ export interface CanvasServerOptions {
   port?: number;
   workspaceRoot?: string;
   autoOpenBrowser?: boolean;
+  allowPortFallback?: boolean;
 }
 
 export function startCanvasServer(options: CanvasServerOptions = {}): string | null {
@@ -3733,7 +3765,9 @@ export function startCanvasServer(options: CanvasServerOptions = {}): string | n
   rotatePrimaryWorkbenchSessionIfNeeded();
 
   const preferredPort = options.port ?? Number(process.env.PMX_WEB_CANVAS_PORT ?? DEFAULT_PORT);
-  const portCandidates = buildPortCandidates(preferredPort);
+  const portCandidates = options.allowPortFallback === false
+    ? [preferredPort > 0 ? Math.floor(preferredPort) : DEFAULT_PORT]
+    : buildPortCandidates(preferredPort);
 
   for (const portCandidate of portCandidates) {
     try {