> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lynxhub.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Installation stepper wizard

> Build installation and update workflows using the host stepper wizard.

If your card requires repository downloading, virtual environment creation, or manual setup, define a custom wizard flow. The host runs this flow inside the central installation modal.

***

## Stepper lifecycle

To attach a wizard to a card, register the `manager` property in your renderer card definition:

```typescript theme={null}
const card = {
  id: 'my-card',
  // ... other properties
  methods: {
    manager: {
      startInstall: async (stepper: InstallationStepper) => {
        // Wizard flow logic
      },
      updater: {
        updateType: 'stepper', // 'git' | 'stepper'
        startUpdate: async (stepper: InstallationStepper, dir?: string) => {
          // Wizard update logic
        },
      },
    },
  },
};
```

***

## InstallationStepper API

The `stepper` parameter exposes UI actions to step through setup stages, request user choices, run commands, and update progress bars.

### Progress and wizard navigation

* `initialSteps(stepTitles: string[]): void` - Configures the titles of your installation steps on the timeline.
* `nextStep(): Promise<void>` - Advances the wizard to the next stage in the timeline.
* `progressBar(isIndeterminate: boolean, title?: string, percentage?: number, description?: { label: string; value: string }[]): void` - Customizes the current progress bar message.
* `showFinalStep(resultType: 'success' | 'error', title: string, description?: string): void` - Ends the installer flow with a final status window.

### User interaction

* `starterStep(options?: StarterStepOptions): Promise<InstallationMethod>` - Displays the default setup page. Resolves to the user's choice: `{ chosen: 'install' | 'locate', targetDirectory: string }`.
* `collectUserInput(inputFields: UserInputField[], title?: string): Promise<UserInputResult[]>` - Renders a form requesting text inputs, dropdown selections, or checkmarks.

### Filesystem and terminal execution

* `cloneRepository(url: string): Promise<string>` - Clones a Git repository. Returns the destination folder path.
* `runTerminalScript(dir: string, script: string): Promise<void>` - Executes a script file (e.g. `.bat`, `.sh`) inside a separate terminal overlay. Resolves when the script finishes.
* `executeTerminalCommands(commands: string | string[], dir?: string): Promise<void>` - Runs inline CLI commands inside a terminal overlay. Resolves when commands finish.
* `downloadFileFromUrl(url: string): Promise<string>` - Downloads a file to the user's downloads folder. Returns the local path.
* `setInstalled(dir?: string): void` - Saves the target installation path and registers the card as installed.
* `setUpdated(): void` - Flags the card update as complete.

***

## Step-by-step example

Below is a complete installation flow that configures stages, downloads a repository, prompts for options, runs an environment compiler, and completes the setup:

```javascript theme={null}
async stepper => {
  try {
    // 1. Register step names
    stepper.initialSteps(['Choose Folder', 'Download Files', 'Setup Environment', 'Finish']);

    // 2. Locate or select the installation path
    const setup = await stepper.starterStep();
    await stepper.nextStep();

    // 3. Clone repository files
    stepper.progressBar(true, 'Downloading codebase...');
    const targetDir = await stepper.cloneRepository('https://github.com/example/model-repo');
    await stepper.nextStep();

    // 4. Prompt the user for graphics settings
    const inputs = await stepper.collectUserInput(
      [{id: 'cuda', label: 'Enable GPU (CUDA) acceleration?', type: 'checkbox', defaultValue: true}],
      'Hardware Configuration',
    );

    // 5. Run installation terminal script
    stepper.progressBar(true, 'Configuring environments...');
    const useCuda = inputs.find(i => i.id === 'cuda')?.result;
    const installScript = useCuda ? 'install_gpu.bat' : 'install_cpu.bat';

    await stepper.runTerminalScript(targetDir, installScript);
    await stepper.nextStep();

    // 6. Complete installation
    stepper.setInstalled(targetDir);
    stepper.showFinalStep('success', 'Installation Completed!', 'Your card is ready to run.');
  } catch (err) {
    stepper.showFinalStep('error', 'Installation Failed', err.message);
  }
};
```