@scenario-labs/sdk 2.1.0 → 2.2.1

package/src/lib/workflow_converter.ts

@@ -47,6 +47,7 @@ export type WorkflowEditorNode =
     }
   | { id: string; type: 'transformText'; data: NodeCommonData & { value?: string } }
   | { id: string; type: 'splitText'; data: NodeCommonData & { splitDelimiter?: string } }
+  | { id: string; type: 'aspectRatio'; data: NodeCommonData & { output?: string } }
   | { id: string; type: 'groupItems'; data: NodeCommonData & { value?: string } }
   | {
       id: string;
@@ -86,12 +87,57 @@ export type WorkflowEditorModelInput = {
   name: string;
   type: string;
   inputs?: Array<{ name: string; type: string }>;
+  min?: number;
+  max?: number;
+  step?: number;
+  allowedValues?: string[];
+};
+
+export type WorkflowEditorResolutionPreset = {
+  width?: number;
+  height?: number;
 };
 
 export type WorkflowEditorModel = {
   id?: string;
   inputs?: WorkflowEditorModelInput[];
   tags?: string[];
+  uiConfig?: {
+    resolutionComponent?: {
+      widthInput?: string;
+      heightInput?: string;
+      presets?: WorkflowEditorResolutionPreset[];
+    };
+  };
+};
+
+const RUNNABLE_TYPES = new Set(['model', 'llm', 'forEach', 'forEachEnd']);
+export const ASPECT_RATIO_PRESETS = [
+  '21:9',
+  '16:9',
+  '3:2',
+  '4:3',
+  '5:4',
+  '1:1',
+  '4:5',
+  '3:4',
+  '2:3',
+  '9:16',
+  '9:21',
+] as const;
+
+export type AspectRatioBounds = {
+  minWidth: number;
+  maxWidth: number;
+  minHeight: number;
+  maxHeight: number;
+  multipleOf: number;
+};
+
+export type AspectRatioModelInputNames = {
+  widthInputName?: string | undefined;
+  heightInputName?: string | undefined;
+  aspectRatioInputName?: string | undefined;
 };
 
 export type WorkflowEditorFlowInputRef = {
@@ -176,6 +222,125 @@ function getConditionalInputHandleId(nodeId: string): string {
   return `${nodeId}-source-conditional`;
 }
 
+function handleTypeIncludes(handleType: string | string[] | undefined, value: string): boolean {
+  if (Array.isArray(handleType)) return handleType.includes(value);
+  return handleType === value;
+}
+
+type ParsedAspectRatio = { width: number; height: number };
+
+function parseAspectRatio(aspectRatio: string | undefined): ParsedAspectRatio | undefined {
+  if (!aspectRatio) return undefined;
+  const [rawWidth, rawHeight] = aspectRatio.split(':');
+  const width = Number(rawWidth);
+  const height = Number(rawHeight);
+  if (
+    !Number.isFinite(width) ||
+    !Number.isFinite(height) ||
+    width <= 0 ||
+    height <= 0 ||
+    !Number.isInteger(width) ||
+    !Number.isInteger(height)
+  ) {
+    return undefined;
+  }
+  return { width, height };
+}
+
+function getGreatestCommonDivisor(a: number, b: number): number {
+  let x = Math.abs(Math.trunc(a));
+  let y = Math.abs(Math.trunc(b));
+  while (y) {
+    const temp = y;
+    y = x % y;
+    x = temp;
+  }
+  return x || 1;
+}
+
+function makeNumberAMultipleOfX(value: number, multipleOf: number): number {
+  if (multipleOf <= 0) return Math.round(value);
+  return Math.round(value / multipleOf) * multipleOf;
+}
+
+function clamp(value: number, min: number, max: number): number {
+  return Math.min(Math.max(value, min), max);
+}
+
+export function normalizeAspectRatio(aspectRatio: string | undefined): string | undefined {
+  const parsed = parseAspectRatio(aspectRatio);
+  if (!parsed) return undefined;
+  const divisor = getGreatestCommonDivisor(parsed.width, parsed.height);
+  const normalizedAspectRatio = `${parsed.width / divisor}:${parsed.height / divisor}`;
+  return (
+    {
+      '3:7': '9:21',
+      '7:3': '21:9',
+    }[normalizedAspectRatio] ?? normalizedAspectRatio
+  );
+}
+
+export function getAspectRatioModelInputNames(
+  model: WorkflowEditorModel | undefined,
+): AspectRatioModelInputNames {
+  if (!model) return {};
+
+  const widthInputName =
+    model.uiConfig?.resolutionComponent?.widthInput ??
+    model.inputs?.find((input) => input.name === 'width')?.name;
+  const heightInputName =
+    model.uiConfig?.resolutionComponent?.heightInput ??
+    model.inputs?.find((input) => input.name === 'height')?.name;
+  const aspectRatioInputName = model.inputs?.find((input) => input.name === 'aspectRatio')?.name;
+
+  return { widthInputName, heightInputName, aspectRatioInputName };
+}
+
+export function getAspectRatioBounds(
+  model: WorkflowEditorModel | undefined,
+  { widthInputName, heightInputName }: Pick<AspectRatioModelInputNames, 'widthInputName' | 'heightInputName'>,
+): AspectRatioBounds | undefined {
+  if (!model || !widthInputName || !heightInputName) return undefined;
+
+  const widthInput = model.inputs?.find((input) => input.name === widthInputName);
+  const heightInput = model.inputs?.find((input) => input.name === heightInputName);
+  const presets = model.uiConfig?.resolutionComponent?.presets;
+  const widthPresets = (presets ?? [])
+    .map((preset) => preset.width)
+    .filter((value): value is number => typeof value === 'number');
+  const heightPresets = (presets ?? [])
+    .map((preset) => preset.height)
+    .filter((value): value is number => typeof value === 'number');
+  const multipleOf = widthInput?.step ?? 8;
+
+  return {
+    maxWidth: widthInput?.max ?? (widthPresets.length > 0 ? Math.max(...widthPresets) : 2048),
+    minWidth: widthInput?.min ?? (widthPresets.length > 0 ? Math.min(...widthPresets) : 64),
+    maxHeight: heightInput?.max ?? (heightPresets.length > 0 ? Math.max(...heightPresets) : 2048),
+    minHeight: heightInput?.min ?? (heightPresets.length > 0 ? Math.min(...heightPresets) : 64),
+    multipleOf,
+  };
+}
+
+export function getDimensionsFromAspectRatio(args: {
+  aspectRatio: string;
+  bounds: AspectRatioBounds;
+}): { width: number; height: number } | undefined {
+  const parsed = parseAspectRatio(args.aspectRatio);
+  if (!parsed) return undefined;
+
+  const ratio = parsed.width / parsed.height;
+  let width = ratio >= 1 ? args.bounds.maxWidth : Math.round(args.bounds.maxHeight * ratio);
+  let height = ratio >= 1 ? Math.round(args.bounds.maxWidth / ratio) : args.bounds.maxHeight;
+
+  width = makeNumberAMultipleOfX(width, args.bounds.multipleOf);
+  height = makeNumberAMultipleOfX(height, args.bounds.multipleOf);
+  width = clamp(width, args.bounds.minWidth, args.bounds.maxWidth);
+  height = clamp(height, args.bounds.minHeight, args.bounds.maxHeight);
+
+  return { width, height };
+}
+
 function getForEachFlowListInputDescriptor(args: {
   listProvider: WorkflowEditorNode | undefined;
   outputHandle: WorkflowEditorHandleOutput | undefined;
@@ -448,14 +613,14 @@ function toStaticInput(name: string, type: string, value: unknown): WorkflowEdit
   return { name, type, value: value as string | number | string[] | boolean };
 }
 
-function isFormArray(value: unknown): value is Record<string, unknown>[] {
+function getIsFormArray(value: unknown): value is Record<string, unknown>[] {
   return (
     Array.isArray(value) &&
     (value as unknown[]).every((item) => typeof item === 'object' && item !== null && !Array.isArray(item))
   );
 }
 
-function isModelCompose(model: WorkflowEditorModel | undefined): boolean {
+function getIsModelCompose(model: WorkflowEditorModel | undefined): boolean {
   return !!model?.id && (model.tags ?? []).includes('compose');
 }
 
@@ -473,6 +638,120 @@ function getIsConditionallyExecuted(
   });
 }
 
+function buildDimensionLookupCEL(args: {
+  variable: string;
+  presets: Array<{ aspectRatio: string; width: number; height: number }>;
+  dimension: 'width' | 'height';
+  fallback: number;
+}): string {
+  let expression = String(args.fallback);
+  for (let i = args.presets.length - 1; i >= 0; i--) {
+    const preset = args.presets[i]!;
+    expression = `trim(${args.variable}) == '${preset.aspectRatio}' ? ${
+      preset[args.dimension]
+    } : ${expression}`;
+  }
+  return expression;
+}
+
+function applyAspectRatioInputs(args: {
+  flow: WorkflowEditorFlowItem[];
+  flowInputs: WorkflowEditorFlowInput[];
+  flowId: string;
+  aspectRatioRef: WorkflowEditorFlowInputRef;
+  model: WorkflowEditorModel;
+}): void {
+  const modelInputNames = getAspectRatioModelInputNames(args.model);
+  const modelBounds = getAspectRatioBounds(args.model, modelInputNames);
+  const { widthInputName, heightInputName, aspectRatioInputName } = modelInputNames;
+
+  if (aspectRatioInputName) {
+    const transformId = `${args.flowId}_aspectRatio_value`;
+    args.flow.push({
+      id: transformId,
+      type: 'transform',
+      logic: { transform: 'trim(aspectRatio)' },
+      inputs: [{ name: 'aspectRatio', type: 'string', ref: args.aspectRatioRef }],
+    });
+
+    setOrPushFlowInput(
+      args.flowInputs,
+      args.flowInputs.findIndex((inp) => inp.name === aspectRatioInputName),
+      {
+        name: aspectRatioInputName,
+        type: 'string',
+        ref: { node: transformId, name: 'all' },
+      },
+    );
+  }
+
+  if (widthInputName && heightInputName && modelBounds) {
+    const presetDimensions = ASPECT_RATIO_PRESETS.flatMap((preset) => {
+      const dims = getDimensionsFromAspectRatio({ aspectRatio: preset, bounds: modelBounds });
+      if (!dims) return [];
+      const normalized = normalizeAspectRatio(preset);
+      if (!normalized) return [];
+      return [{ aspectRatio: normalized, ...dims }];
+    });
+
+    const fallbackDimensions = presetDimensions.find((preset) => preset.aspectRatio === '1:1') ??
+      presetDimensions[0] ?? {
+        width: modelBounds.maxWidth,
+        height: modelBounds.maxHeight,
+      };
+
+    const widthTransformId = `${args.flowId}_aspectRatio_width`;
+    const heightTransformId = `${args.flowId}_aspectRatio_height`;
+
+    args.flow.push({
+      id: widthTransformId,
+      type: 'transform',
+      logic: {
+        transform: buildDimensionLookupCEL({
+          variable: 'aspectRatio',
+          presets: presetDimensions,
+          dimension: 'width',
+          fallback: fallbackDimensions.width,
+        }),
+      },
+      inputs: [{ name: 'aspectRatio', type: 'string', ref: args.aspectRatioRef }],
+    });
+
+    args.flow.push({
+      id: heightTransformId,
+      type: 'transform',
+      logic: {
+        transform: buildDimensionLookupCEL({
+          variable: 'aspectRatio',
+          presets: presetDimensions,
+          dimension: 'height',
+          fallback: fallbackDimensions.height,
+        }),
+      },
+      inputs: [{ name: 'aspectRatio', type: 'string', ref: args.aspectRatioRef }],
+    });
+
+    setOrPushFlowInput(
+      args.flowInputs,
+      args.flowInputs.findIndex((inp) => inp.name === widthInputName),
+      {
+        name: widthInputName,
+        type: 'number',
+        ref: { node: widthTransformId, name: 'all' },
+      },
+    );
+    setOrPushFlowInput(
+      args.flowInputs,
+      args.flowInputs.findIndex((inp) => inp.name === heightInputName),
+      {
+        name: heightInputName,
+        type: 'number',
+        ref: { node: heightTransformId, name: 'all' },
+      },
+    );
+  }
+}
+
 function getForEachBodyEditorNodeIds(
   forEachId: string,
   forEachEndId: string,
@@ -532,8 +811,6 @@ function getNodeOutputValue(
   return undefined;
 }
 
-const RUNNABLE_TYPES = new Set(['model', 'llm', 'forEach', 'forEachEnd']);
-
 function internalGetConnectedNodes(
   nodes: WorkflowEditorNode[],
   edges: WorkflowEditorEdge[],
@@ -605,18 +882,17 @@ function resolveIfElseConditionField(
 function normalizeNodes(nodes: WorkflowEditorNode[]): WorkflowEditorNode[] {
   return nodes.map((node) => {
     if (node.type !== 'model' && node.type !== 'llm') return node;
-    const hasType = (t: string | string[] | undefined, v: string) =>
-      Array.isArray(t) ? t.includes(v) : t === v;
     const inputHandles = (node.data.inputHandles ?? [])
       .flatMap((h) => (h.subHandles ? h.subHandles : [h]))
       .filter(
         (h) =>
-          hasType(h.type, 'conditional') ||
-          hasType(h.type, 'prompt') ||
-          hasType(h.type, 'image') ||
-          hasType(h.type, 'video') ||
-          hasType(h.type, '3d') ||
-          hasType(h.type, 'audio') ||
+          handleTypeIncludes(h.type, 'conditional') ||
+          handleTypeIncludes(h.type, 'aspectRatio') ||
+          handleTypeIncludes(h.type, 'prompt') ||
+          handleTypeIncludes(h.type, 'image') ||
+          handleTypeIncludes(h.type, 'video') ||
+          handleTypeIncludes(h.type, '3d') ||
+          handleTypeIncludes(h.type, 'audio') ||
           (node.type === 'llm' && h.name === 'textInputs'),
       );
     return { ...node, data: { ...node.data, inputHandles } } as WorkflowEditorNode;
@@ -635,25 +911,31 @@ function normalizeNodes(nodes: WorkflowEditorNode[]): WorkflowEditorNode[] {
  * await client.workflows.update(workflowId, { flow: flow as WorkflowUpdateParams.Flow[] });
  * ```
  */
-export function convertWorkflowEditorToFlow(params: {
+export type ConvertWorkflowEditorToFlowParams = {
   nodes: WorkflowEditorNode[];
   edges: WorkflowEditorEdge[];
   inputKeys: string[];
   /** Optional model resolver — return the model object, 'unknown', or undefined. */
   getModel?: (modelId: string) => WorkflowEditorModel | 'unknown' | undefined;
-}): WorkflowEditorFlowItem[] {
+};
+
+export function convertWorkflowEditorToFlow(
+  params: ConvertWorkflowEditorToFlowParams,
+): WorkflowEditorFlowItem[] {
   const { edges, inputKeys } = params;
   const nodes = normalizeNodes(params.nodes);
 
   const inputNodeIds = nodes.filter((n) => !!n.data.isInput).map((n) => n.id);
 
   const selectedOutputNodes = nodes.filter(
-    (n) => (n.type === 'model' || n.type === 'forEachEnd') && !!n.data.isOutput,
+    (n) => (n.type === 'model' || n.type === 'forEachEnd' || n.type === 'llm') && !!n.data.isOutput,
   );
   const selectedOutputNodeIds = selectedOutputNodes.map((n) => n.id);
   const selectedOutputModelNodeIds = new Set(
     selectedOutputNodes
-      .filter((n): n is WorkflowEditorNode & { type: 'model' } => n.type === 'model')
+      .filter(
+        (n): n is WorkflowEditorNode & { type: 'model' | 'llm' } => n.type === 'model' || n.type === 'llm',
+      )
       .map((n) => n.id),
   );
 
@@ -777,12 +1059,17 @@ export function convertWorkflowEditorToFlow(params: {
       const model = remoteModel === 'unknown' ? undefined : remoteModel;
       const modelInputs = model?.inputs;
       const conditionalHandleId = getConditionalInputHandleId(node.id);
+      const aspectRatioEdges: WorkflowEditorEdge[] = [];
 
       const edgesByInput = new Map<string, WorkflowEditorEdge[]>();
       for (const edge of incomingEdges) {
         if (edge.sourceHandle === conditionalHandleId) continue;
         const handle = getInputHandle(edge, node.data.inputHandles);
         if (!handle?.name) continue;
+        if (handleTypeIncludes(handle.type, 'aspectRatio')) {
+          aspectRatioEdges.push(edge);
+          continue;
+        }
         const existing = edgesByInput.get(handle.name);
         if (existing) existing.push(edge);
         else edgesByInput.set(handle.name, [edge]);
@@ -794,7 +1081,7 @@ export function convertWorkflowEditorToFlow(params: {
           const modelInput = modelInputs?.find((inp) => inp.name === key);
 
           if (modelInput?.type === 'inputs_array') {
-            if (!isFormArray(value)) continue;
+            if (!getIsFormArray(value)) continue;
             const nestedInputs = modelInput.inputs ?? [];
             const items: WorkflowEditorFlowInput[][] = [];
 
@@ -813,7 +1100,7 @@ export function convertWorkflowEditorToFlow(params: {
                 }
               }
               const isValid =
-                isModelCompose(model) ? getHasComposeLayerSourceInput(itemInputs) : itemInputs.length > 0;
+                getIsModelCompose(model) ? getHasComposeLayerSourceInput(itemInputs) : itemInputs.length > 0;
               if (isValid) items.push(itemInputs);
             }
             if (items.length > 0) flowInputs.push({ name: key, type: 'inputs_array', items });
@@ -829,6 +1116,19 @@ export function convertWorkflowEditorToFlow(params: {
         }
       }
 
+      if (aspectRatioEdges.length > 0 && model) {
+        const aspectRatioRef = getSourceRef(aspectRatioEdges[0]!, ctx);
+        if (aspectRatioRef) {
+          applyAspectRatioInputs({
+            flow,
+            flowInputs,
+            flowId,
+            aspectRatioRef,
+            model,
+          });
+        }
+      }
+
       for (const [inputName, inputEdges] of edgesByInput) {
         const existingIndex = flowInputs.findIndex((inp) => inp.name === inputName);
         const modelInput = modelInputs?.find((inp) => inp.name === inputName);
@@ -897,7 +1197,7 @@ export function convertWorkflowEditorToFlow(params: {
               const isRequired =
                 (targetNode?.type === 'asset' &&
                   !!(targetNode.data as { isRequired?: boolean }).isRequired) ||
-                isModelCompose(model);
+                getIsModelCompose(model);
               transformVariables.push({ name: targetNodeKey, isArray: isArr, isRequired });
 
               if (
@@ -973,7 +1273,9 @@ export function convertWorkflowEditorToFlow(params: {
         modelId: nodeData.modelId,
         inputs: flowInputs.length > 0 ? flowInputs : undefined,
         includeOutputsInWorkflowJob:
-          node.type === 'model' && selectedOutputModelNodeIds.has(node.id) ? true : undefined,
+          (node.type === 'model' || node.type === 'llm') && selectedOutputModelNodeIds.has(node.id) ?
+            true
+          : undefined,
       });
 
       ensureInputVideoTransformsAdded();
@@ -1037,6 +1339,19 @@ export function convertWorkflowEditorToFlow(params: {
         addVideoFirstLastFrameTransforms(node.id, flowId, node, edges, flow, nodeHandleTransformMap);
       }
 
+      // ------------------------------------
+      // AspectRatio -> transform with ratio literal
+      // ------------------------------------
+    } else if (node.type === 'aspectRatio') {
+      const flowInputs = collectConditionalConnectionInputs(incomingEdges, node.id, ctx);
+      const value = (node.data as { output?: string }).output || '1:1';
+      flow.push({
+        id: flowId,
+        type: 'transform',
+        logic: { transform: `'${escapeCELString(value)}'` },
+        inputs: flowInputs.length > 0 ? flowInputs : undefined,
+      });
+
       // ------------------------------------
       // TransformText -> transform (CEL)
       // ------------------------------------
@@ -1303,7 +1618,18 @@ export function convertWorkflowEditorToFlow(params: {
 
   // Populate loopBodyNodeIds on each forEach flow item
   for (const [forEachId, forEachFlowItem] of forEachFlowItemRefs) {
-    forEachFlowItem.loopBodyNodeIds = forEachLoopFlowIds.get(forEachId) ?? [];
+    const loopFlowIds = forEachLoopFlowIds.get(forEachId) ?? [];
+    // Approval nodes attached to a node inside the loop body belong to the loop too,
+    // but they are appended to the flow separately and never tracked above.
+    const bodyEditorNodeIds = forEachBodyEditorNodeIds.get(forEachId);
+    if (bodyEditorNodeIds) {
+      for (const [approvedNodeId, approvalInfo] of approvalByApprovedNodeId) {
+        if (bodyEditorNodeIds.has(approvedNodeId) && !loopFlowIds.includes(approvalInfo.approvalFlowId)) {
+          loopFlowIds.push(approvalInfo.approvalFlowId);
+        }
+      }
+    }
+    forEachFlowItem.loopBodyNodeIds = loopFlowIds;
   }
 
   applyApprovalsToFlow({ flow, edges, approvalByApprovedNodeId, nodeIdToFlowIdMap });

package/src/lib/workflow_import_validator.ts

@@ -8,6 +8,7 @@ export class WorkflowImportError extends Error {
 export type WorkflowEditorNodeType =
   | 'text'
   | 'asset'
+  | 'aspectRatio'
   | 'model'
   | 'llm'
   | 'transformText'
@@ -17,11 +18,13 @@ export type WorkflowEditorNodeType =
   | 'sliceAssets'
   | 'forEach'
   | 'forEachEnd'
-  | 'stickyNote';
+  | 'stickyNote'
+  | 'approval';
 
 export const VALID_EDITOR_NODE_TYPES: readonly WorkflowEditorNodeType[] = [
   'text',
   'asset',
+  'aspectRatio',
   'model',
   'llm',
   'transformText',
@@ -32,6 +35,7 @@ export const VALID_EDITOR_NODE_TYPES: readonly WorkflowEditorNodeType[] = [
   'forEach',
   'forEachEnd',
   'stickyNote',
+  'approval',
 ];
 
 export interface WorkflowExportData {