Development Guide

Complete setup and workflow documentation for developing FiberPath GUI.

Prerequisites

Required

• Node.js 24.x and npm 11.x (nodejs.org)
• Rust 1.70+ (rustup.rs)
• Python CLI installed and available in PATH (for development mode)
• Via pip: pip install fiberpath
• Via uv: uv pip install fiberpath
• From source: pip install -e . in repo root

Important: Production installers bundle the CLI—end users don't need Python. Developers need it for local testing.

Platform-Specific

Windows:

• Microsoft Visual Studio C++ Build Tools
• WebView2 (usually pre-installed on Windows 10+)

macOS:

• Xcode Command Line Tools: xcode-select --install

Linux:

• Build essentials: sudo apt install build-essential libwebkit2gtk-4.1-dev libappindicator3-dev librsvg2-dev patchelf

CLI Discovery & Fallback

The GUI uses a two-stage CLI discovery process implemented in src-tauri/src/cli_path.rs:

1. Check for Bundled CLI (Production Mode):

• Windows installed: resources\_up_\bundled-cli\fiberpath.exe
• Windows dev: resources\bundled-cli\fiberpath.exe
• macOS: Resources/bundled-cli/fiberpath (relative to .app bundle)
• Linux: resources/bundled-cli/fiberpath

2. Fallback to System PATH (Development Mode):

If bundled CLI not found, uses which fiberpath (Unix) or where fiberpath (Windows).

3. Error if Neither Found:

Returns user-friendly message suggesting pip install fiberpath.

Why This Design:

• Production users: Zero setup—CLI bundled in installer
• Contributors: No PyInstaller required for local dev
• CI testing: Works in both modes automatically

Verification:

# Ensure CLI is on PATH for development
fiberpath --version
# Test GUI with bundled CLI
npm run tauri build  # Check src-tauri/target/release/bundle/

Initial Setup

# Clone repository
git clone https://github.com/your-org/fiberpath.git
cd fiberpath/fiberpath_gui
# Install dependencies
npm install
# Verify CLI is available
fiberpath --version

Development

Run Development Build

npm run tauri dev

This starts:

• Vite dev server with HMR (Hot Module Replacement)
• Tauri window with development console enabled
• File watcher for Rust changes (auto-rebuild)

Hot Reload:

• Frontend changes (React/TypeScript) reload instantly
• Rust changes trigger rebuild (~5-15 seconds)

Run Frontend Only

npm run dev

Starts Vite dev server at http://localhost:5173. Useful for:

• UI development without Tauri overhead
• Browser DevTools debugging
• Faster iteration on styling/components

Note: Tauri commands will fail in browser mode.

Testing

Run All Tests

npm test

Run Tests in Watch Mode

npm test -- --watch

Run Specific Test File

npm test -- schemas.test.ts

Test Coverage

npm test -- --coverage

Current Test Suite:

• 43 schema validation tests (all passing)
• Project store tests
• Component tests (planned)

Building

Development Build

npm run tauri build -- --debug

Creates debug binary with:

• Development console enabled
• Faster build time
• Source maps included

Production Build

npm run tauri build

Creates optimized release bundle:

• Windows: .exe installer in src-tauri/target/release/bundle/msi/
• macOS: .dmg disk image in src-tauri/target/release/bundle/dmg/
• Linux: .AppImage or .deb in src-tauri/target/release/bundle/

Build Output:

src-tauri/target/release/
├── fiberpath-gui[.exe]         # Binary executable
└── bundle/
    ├── msi/                     # Windows installer
    ├── dmg/                     # macOS disk image
    └── appimage/                # Linux portable app

Packaging

Create Distributable Package

npm run package

This runs:

1. npm run tauri build (production build)
2. Package verification
3. Signing (if configured)

Release Checklist:

• [ ] Update version in package.json, Cargo.toml, tauri.conf.json
• [ ] Run npm run check:all and npm test
• [ ] Run npm run build and npm run perf:bundle
• [ ] Test on target platforms
• [ ] Build production bundles
• [ ] Verify bundle functionality
• [ ] Tag release in git

Code Quality

Run All Checks

npm run check:all

Runs in sequence:

1. TypeScript compiler (tsc --noEmit)
2. Stylelint (src/**/*.css)
3. CSS variable guard (lint:css:vars)
4. Rust formatter check (cargo fmt --check)
5. Clippy (Rust linting)

CI Pipeline: These checks plus npm run build and npm run perf:bundle run on every PR.

Individual Commands

# TypeScript and CSS checks
npm run lint              # TypeScript type check (tsc --noEmit)
npm run lint:css          # Stylelint
npm run lint:css:vars     # CSS variable guard
npm run lint:css:fix      # Auto-fix CSS lint issues
# Rust checks
npm run format:check      # cargo fmt --check
npm run format:fix        # cargo fmt
npm run clippy            # cargo clippy -- -D warnings
# Tests and build
npm test                  # Vitest
npm run test:coverage     # Vitest with coverage
npm run build             # Vite production build
npm run perf:bundle       # Enforce bundle budget and emit metrics

Project Structure

fiberpath_gui/
├── src/                          # Frontend code
│   ├── main.tsx                  # App entry point
│   ├── App.tsx                   # Root component with tab layout
│   ├── components/               # UI components (tabs, dialogs, forms, stream)
│   ├── hooks/                    # Custom React hooks
│   ├── layouts/                  # Layout wrappers
│   ├── lib/                      # Tauri command bindings, validation helpers
│   ├── stores/                   # Project, streaming, and toast stores
│   ├── styles/                   # Global CSS + design tokens
│   ├── tests/                    # Integration and setup files
│   └── types/                    # TypeScript domain models
├── src-tauri/                    # Rust backend
│   ├── src/
│   │   ├── main.rs               # Tauri command registration + app bootstrap
│   │   └── marlin.rs             # Streaming state and command handling
│   ├── Cargo.toml                # Rust dependencies
│   ├── tauri.conf.json           # Tauri configuration
│   └── icons/                    # App icons
├── schemas/                      # JSON schemas
│   └── FiberPathProject.schema.json
├── docs/                         # This documentation
├── package.json                  # NPM scripts and dependencies
├── tsconfig.json                 # TypeScript config (strict mode)
├── vite.config.ts                # Vite build config
└── vitest.config.ts              # Test configuration

Common Tasks

Add New Tauri Command

1. Define in Rust (src-tauri/src/main.rs):

#[tauri::command]
fn my_command(arg: String) -> Result<String, String> {
    Ok(format!("Hello {}", arg))
}

1. Register in main():

tauri::Builder::default()
    .invoke_handler(tauri::generate_handler![my_command])
    .run(tauri::generate_context!())

1. Call from Frontend (src/lib/commands.ts):

export async function myCommand(arg: string): Promise<string> {
  return invoke("my_command", { arg });
}

Add New Layer Type

1. Define Zod schema (src/lib/schemas.ts)
2. Add discriminated union case to WindLayerSchema
3. Update TypeScript types (src/types/fiberpath.ts)
4. Add form fields in PlanForm.tsx
5. Add tests in schemas.test.ts

Add UI Component

1. Create component file in src/components/MyComponent.tsx
2. Create CSS module in src/styles/MyComponent.module.css
3. Use design tokens from tokens.css
4. Add prop types with TypeScript
5. Write tests (if stateful)

Debugging

Frontend Debugging

Browser DevTools (dev mode only):

• Right-click → Inspect Element
• Or press F12 in Tauri window

Zustand DevTools:

// In store definition
devtools(
  (set) => ({
    /* state */
  }),
  { name: "ProjectStore" }
);

Then use Redux DevTools extension in browser.

Rust Debugging

Console Logging:

println!("Debug: {:?}", value);

Run with backtrace:

RUST_BACKTRACE=1 npm run tauri dev

CLI Integration Debugging

Test CLI directly:

fiberpath plan examples/simple_cylinder/input.wind

Check CLI version:

fiberpath --version

Verify CLI in PATH:

# Windows PowerShell
Get-Command fiberpath
# macOS/Linux
which fiberpath

Troubleshooting

"Command 'fiberpath' not found"

Solution: Install Python CLI and ensure it's in PATH:

pip install fiberpath
fiberpath --version

"Tauri build failed on Linux"

Solution: Install WebKit dependencies:

sudo apt install libwebkit2gtk-4.1-dev libappindicator3-dev

Tests fail with "Cannot find module"

Solution: Rebuild dependencies:

rm -rf node_modules package-lock.json
npm install

HMR not working

Solution: Restart dev server:

# Ctrl+C to stop
npm run tauri dev

Streaming connection timeout

Solution: Check serial port permissions:

• Linux: Add user to dialout group: sudo usermod -a -G dialout $USER (logout required)
• macOS: Grant permissions in System Settings → Security
• Windows: Usually no action needed

Performance Profiling

See Performance Guide for detailed profiling instructions using React DevTools Profiler.

Next Steps

• Tech Stack Details
• State Management Architecture
• Schema Validation Guide
• Styling Guide