FORGE Studio

Appearance

IPC API Reference ​

The renderer communicates with the main process exclusively through window.forgeAPI, exposed via the Electron contextBridge. This document lists all available methods and push event subscriptions.

All IPC channels use the forge: prefix internally. Methods that accept or return complex objects are typed in src/shared/ipc-types.ts.

Dialog ​

selectInputFile(): Promise<string | null> ​

Opens a file picker filtered to MRI data formats (.h5, .dat, .mrd). Returns the selected path or null if cancelled.

selectOutputDirectory(): Promise<string | null> ​

Opens a directory picker. Returns the selected path or null if cancelled.

selectExecutable(): Promise<string | null> ​

Opens a file picker for selecting a binary executable (MATLAB, Python, Julia). Returns the selected path or null if cancelled.

selectInputFiles(): Promise<string[]> ​

Opens a multi-select file picker. Returns an array of selected paths (empty if cancelled).

Job Control ​

inspectInput(path: string): Promise<InputInspection> ​

Reads the header of an MRI data file (ISMRMRD or TWIX) and returns metadata, measurements, and matched workflows.

startJob(config: JobStartConfig): Promise<string> ​

Starts a reconstruction job. Returns the new jobId.

typescript
interface JobStartConfig {
  inputPath: string;
  workflowId: string;
  paramOverrides?: Record<string, Record<string, unknown>>;
  outputDir?: string;
}

cancelJob(jobId: string): Promise<void> ​

Cancels a running job.

approveGate(jobId: string, resultPath: string, edited: boolean): Promise<void> ​

Approves an interactive gate, optionally marking the mask as edited.

rejectGate(jobId: string, reason?: string): Promise<void> ​

Rejects an interactive gate, causing the job to fail.

retryStage(jobId: string, stageIndex: number): Promise<void> ​

Retries a failed stage within the same job.

extendTimeout(jobId: string, additionalMs: number): Promise<void> ​

Extends the timeout for the currently running stage.

getJobHistory(): Promise<JobSummary[]> ​

Returns all past jobs ordered by start time, newest first.

getJobDetail(jobId: string): Promise<JobDetail> ​

Returns full detail for a single job including per-stage results and diagnostics.

clearJobHistory(jobIds: string[]): Promise<void> ​

Deletes the specified job records from history.

Workflow Management ​

listWorkflows(): Promise<WorkflowListItem[]> ​

Returns all available workflows (bundled + user).

loadWorkflow(id: string): Promise<WorkflowDefinition> ​

Loads and parses a single workflow by ID.

saveWorkflow(def: WorkflowDefinition): Promise<void> ​

Saves a workflow definition to ~/.forge-studio/workflows/<id>.yaml.

deleteWorkflow(id: string): Promise<void> ​

Deletes a user workflow. Throws WORKFLOW_BUNDLED_READONLY for bundled workflows.

validateWorkflow(def: WorkflowDefinition): Promise<ValidationResult> ​

Validates a workflow against the JSON Schema and business rules. Returns errors and warnings.

exportYarraMode(workflowId: string): Promise<string> ​

Exports the workflow as a Yarra .mode file. Returns the file path.

importYarraMode(modePath: string): Promise<WorkflowDefinition> ​

Imports a Yarra .mode file and converts it to a WorkflowDefinition.

Palette Library ​

listPaletteCards(): Promise<PaletteLibrary> ​

Returns all palette cards (bundled + user) grouped into stageCards and stepCards.

savePaletteCard(card: PaletteCard): Promise<string> ​

Saves a palette card to ~/.forge-studio/palette/<id>.yaml. Returns the file path.

exportPaletteCard(card: PaletteCard): Promise<void> ​

Opens a save dialog and exports the card to a user-chosen location.

Settings & Configuration ​

getSettings(): Promise<AppSettings> ​

Returns the current application settings.

updateSettings(patch: Partial<AppSettings>): Promise<void> ​

Merges a partial settings object into stored settings.

getSetupState(): Promise<SetupState> ​

Returns the first-run setup state.

completeSetup(state: SetupState): Promise<void> ​

Marks setup as complete and stores the setup state.

validateBackendPath(backend, path): Promise<BackendValidation> ​

Validates an executable path for a backend, returning version and module availability.

typescript
backend: 'matlab' | 'runmat' | 'python' | 'julia'

Compute Backend ​

detectHardware(): Promise<ComputeBackendInfo> ​

Detects available GPU hardware and FORGE binaries.

detectBackendRuntimes(): Promise<RuntimeDetectionResult> ​

Auto-detects installed MATLAB, Python, and Julia executables.

typescript
interface RuntimeDetectionResult {
  matlab: { path: string; version: string | null } | null;
  python: { path: string; version: string | null } | null;
  julia:  { path: string; version: string | null } | null;
}

getComputeBackendInfo(): Promise<ComputeBackendInfo> ​

Returns current compute backend selection and GPU info.

setComputeBackend(backend: 'cuda' | 'metal' | 'cpu'): Promise<void> ​

Overrides the automatic backend selection.

FORGE Engine ​

verifyForgeEngine(): Promise<ForgeEngineStatus> ​

Checks that the FORGE binaries are present and executable.

setForgeSource(source, externalDir?): Promise<ForgeEngineStatus> ​

Switches between the bundled FORGE installation and an external one.

System ​

getSystemInfo(): Promise<SystemInfo> ​

Returns app version, platform, GPU, and active backend info.

getForgeVersion(): Promise<string> ​

Returns the FORGE binary version string.

openExternal(url: string): Promise<void> ​

Opens a URL in the system browser.

showItemInFolder(path: string): Promise<void> ​

Reveals a file in the system file manager.

copyToClipboard(text: string): Promise<void> ​

Copies text to the system clipboard.

getPendingRecovery(): Promise<PendingRecovery | null> ​

Returns a pending crash recovery record if one exists.

clearPendingRecovery(): Promise<void> ​

Clears the pending crash recovery record.

clearCache(): Promise<void> ​

Deletes all cached stage outputs from ~/.forge-studio/cache/.

Batch Processing ​

startBatch(config: BatchConfig): Promise<string> ​

Starts a batch job. Returns the batchId.

cancelBatch(batchId: string): Promise<void> ​

Cancels the running batch.

pauseBatch(batchId: string): Promise<void> ​

Pauses a running batch after the current item completes.

resumeBatch(batchId: string): Promise<void> ​

Resumes a paused batch.

getBatchState(): Promise<BatchSummary | null> ​

Returns the current batch state, or null if no batch is active.

scanDirectory(dir: string, pattern: string): Promise<string[]> ​

Scans a directory for files matching a glob pattern. Returns matching paths.

retryBatchItem(batchId: string, itemId: string): Promise<void> ​

Resets a failed batch item to queued and increments its retry count.

Auto-Updater ​

checkForUpdate(): Promise<void> ​

Triggers an update check against the configured release channel.

downloadUpdate(): Promise<void> ​

Downloads a pending update.

installUpdate(): Promise<void> ​

Quits and installs a downloaded update.

Push Event Subscriptions ​

All subscription methods return an UnsubscribeFn — call it to remove the listener.

typescript
type UnsubscribeFn = () => void;

onJobStateChanged(cb): UnsubscribeFn ​

Fired when a job transitions state (pending → running → completed/failed/cancelled).

typescript
interface JobStateEvent {
  jobId: string;
  status: JobStatus;
  stageIndex: number | null;
  stageName: string | null;
  progress: number | null;
  elapsedMs: number;
}

onStageEvent(cb): UnsubscribeFn ​

Fired on stage lifecycle events: stage:started, stage:completed, stage:failed, stage:cached, stage:skipped, stage:timeout, stage:gated, stage:gate-approved, stage:gate-rejected.

onJsonlEvent(cb): UnsubscribeFn ​

Fired for each JSONL event emitted on FORGE stderr: progress (add/tick/done), metrics, log.

onImagePreview(cb): UnsubscribeFn ​

Fired when FORGE emits an image_preview JSONL event with orthogonal slice planes.

onForgeStart(cb): UnsubscribeFn ​

Fired when a FORGE process starts.

onForgeExit(cb): UnsubscribeFn ​

Fired when a FORGE process exits.

onForgeLog(cb): UnsubscribeFn ​

Fired for each raw log line from any backend process.

onFileChanged(cb): UnsubscribeFn ​

Fired when the file watcher detects a new or modified NIfTI output file.

onToast(cb): UnsubscribeFn ​

Fired when the main process wants to display a toast notification.

onResourceSnapshot(cb): UnsubscribeFn ​

Fired at the configured poll interval with CPU, RAM, and GPU utilisation data.

onBatchStateChanged(cb): UnsubscribeFn ​

Fired when a batch item changes state.

onUpdateStatus(cb): UnsubscribeFn ​

Fired when the auto-updater status changes (checking, available, downloading, ready).

Error Handling ​

All invoke calls throw a ForgeIPCError on failure:

typescript
interface ForgeIPCError {
  code: ForgeErrorCode;
  message: string;
  details?: Record<string, unknown>;
}

Common error codes: WORKFLOW_NOT_FOUND, WORKFLOW_BUNDLED_READONLY, JOB_ALREADY_RUNNING, JOB_NOT_RUNNING, BACKEND_NOT_FOUND, FORGE_ENGINE_MISSING, INPUT_FORMAT_UNKNOWN.

Full list: src/shared/ipc-types.ts → ForgeErrorCode.

FORGE Studio