# Smoothie — Architecture Specification

**Status:** As-built (v0.1.2)
**Scope:** Desktop application for discovering, installing, isolating, and launching Blender builds.
**Audience:** Maintainers and contributors.

---

## 1. Overview

Smoothie is a Tauri 2 desktop application that manages multiple Blender installations from a single, portable library folder.

The application:

- Discovers official Blender builds from `download.blender.org`.
- Downloads and extracts builds into a user-configurable library.
- Isolates each install's Blender user resources so versions and templates do not share configuration.
- Launches Blender with per-install environment variables and optional application templates.
- Registers builds with the operating system and creates desktop shortcuts (Linux).
- Generates per-install icons and splash banners.
- Keeps update, tray, notification, and window-state behavior in the Tauri host.

### Goals

1. **Portability.** All versions, configuration, and templates live under one library directory that can be moved, backed up, or copied.
2. **Isolation.** Each Blender build reads and writes its own `BLENDER_USER_RESOURCES` directory.
3. **Low-friction management.** Install, launch, favorite, delete, and set default from one GUI.
4. **Desktop-native behavior.** Tray support, OS shortcuts, file associations, signed auto-updates.
5. **Thin native layer.** Rust is used only for capabilities the webview cannot perform reliably.

### Non-goals

- Building or compiling Blender from source.
- Hosting or mirroring Blender binaries.
- Multi-user or cloud-synced library management.
- Plugin/add-on marketplace functionality.
- Mobile support (the Tauri entry point exists, but the capabilities and UX target desktop).

---

## 2. System Context

```mermaid
flowchart TB
    User[User] --> UI[Svelte 5 UI]
    UI --> Services[JS service modules]
    Services --> Stores[Svelte stores]
    Services --> TauriJS[Tauri JS APIs]
    Services --> Commands[Rust commands]
    TauriJS --> Plugins[Tauri plugins]
    Plugins --> Net[download.blender.org]
    Plugins --> OS[OS: dialogs, notifications, shell, tray]
    Commands --> FS[(Local filesystem)]
    Plugins --> FS
    Commands --> Blender[Blender process]
    Plugins --> Updater[Update endpoint]
    FS --> Library[Portable Blender library]
```

Smoothie has no application server. The only runtime network dependencies are:

- `https://download.blender.org` for release discovery and downloads.
- The configured updater endpoint for signed application updates.

---

## 3. Technology Stack

| Layer | Technology | Notes |
| --- | --- | --- |
| Desktop shell | Tauri 2 (Rust, edition 2021) | One window, one main process |
| Frontend | SvelteKit 2 + Svelte 5 runes | `adapter-static`, prerendered, SSR disabled |
| Bundler | Vite 6 | Fixed dev port `1420` |
| Package manager | Bun | `bun.lock` committed |
| UI | Hand-written CSS + `@webtui/css` | Splitpanes, tabs, custom components |
| Persistence | `@tauri-apps/plugin-store` | `settings.json`, `versions.json` |
| Downloads | `@tauri-apps/plugin-upload` | Streaming download with progress |
| HTTP | `@tauri-apps/plugin-http` | Scoped to Blender hosts |
| Filesystem | `@tauri-apps/plugin-fs` + persisted scope | Library and shortcut operations |
| OS integration | dialog, os, shell, notification, opener, window-state | Linux shortcut creation in JS |
| Updates | `@tauri-apps/plugin-updater` | Signed artifacts |
| Archives | Rust crates: `zip`, `tar`, `flate2`, `xz2`, `bzip2` | Custom Tauri commands |

---

## 4. High-Level Architecture

Smoothie is organized into four layers:

```mermaid
flowchart TB
    subgraph Presentation
        Routes[routes/+page.svelte]
        Components[lib/components]
        Styles[app.css and component styles]
    end

    subgraph Application
        Settings[settings.js]
        Fetch[blenderfetch.js]
        Download[download.js]
        Library[library.js]
        FileUtils[file_utils.js]
        Tray[trayicon.js]
        Notify[notification.js]
    end

    subgraph PlatformBoundary
        TauriAPI[Tauri core API]
        TauriPlugins[Tauri plugins]
        RustCommands[Rust commands]
    end

    subgraph State
        SvelteStores[Svelte writable stores]
        LazyStores[plugin-store JSON files]
        Disk[Library filesystem]
    end

    Presentation --> Application
    Application --> PlatformBoundary
    Application --> SvelteStores
    Application --> LazyStores
    PlatformBoundary --> Disk
```

### Architectural principles

1. **Filesystem-first.** The library directory is the source of truth for installed versions. There is no installation database to drift out of sync.
2. **Stateless UI over persistent services.** Components read Svelte stores; service modules perform I/O and refresh stores.
3. **Thin Rust boundary.** Rust handles archive extraction and process spawning. All orchestration and file layout remain in JavaScript.
4. **Explicit per-version isolation.** Launches inject `BLENDER_USER_RESOURCES` pointing at a version-specific config folder.
5. **Idempotent maintenance.** Missing icons, banners, templates, and shortcuts are regenerated when versions are rescanned.
6. **Graceful degradation.** Missing executables are skipped; failed shortcuts and banners log warnings rather than aborting startup.

---

## 5. Repository Layout

```text
smoothie/
├── src/                          # SvelteKit frontend
│   ├── app.css                   # Global styles and theme variables
│   ├── app.html                  # Webview shell document
│   ├── routes/
│   │   ├── +layout.js            # prerender = true, ssr = false
│   │   ├── +layout.svelte
│   │   └── +page.svelte          # Main application shell and bootstrap
│   └── lib/
│       ├── assets/               # Base icon and embedded font
│       ├── components/           # UI components
│       ├── blenderfetch.js       # Release discovery and filename parsing
│       ├── download.js           # Download/extract pipeline
│       ├── file_utils.js         # Icons, banners, paths, copy/move helpers
│       ├── library.js            # Installed versions, launch, templates, shortcuts
│       ├── notification.js       # Transient notification store
│       ├── settings.js           # Settings, defaults, platform detection
│       ├── transition.js         # Crossfade transition
│       └── trayicon.js           # Tray menu and close-to-tray behavior
├── src-tauri/
│   ├── src/
│   │   ├── lib.rs                # Commands and plugin registration
│   │   └── main.rs               # Entry point
│   ├── capabilities/desktop.json # Permissions and scopes
│   ├── icons/                    # App and platform icons
│   ├── Cargo.toml
│   ├── build.rs
│   └── tauri.conf.json           # App, window, bundle, updater config
├── static/                       # Static web assets
├── .gitea/workflows/build.yml    # Release build workflow
├── package.json
├── svelte.config.js
└── vite.config.js
```

---

## 6. Frontend Architecture

### 6.1 Application shell

`src/routes/+page.svelte` owns:

- The splash screen and initialization sequence.
- The top-level tab state (`library`, `download`, `settings`).
- Subscription wiring between Svelte stores and component props.
- Global CSS variables and layout.

Bootstrap order:

```mermaid
sequenceDiagram
    participant UI as +page.svelte
    participant App as Tauri app API
    participant Settings as settings.js
    participant Fetch as blenderfetch.js
    participant Library as library.js
    participant Tray as trayicon.js

    UI->>App: getVersion()
    UI->>Settings: getSettings()
    Settings->>Settings: detect platform/arch
    Settings->>Settings: create library structure
    UI->>Fetch: getBlenderReleases()
    Fetch->>Fetch: scrape and parse release pages
    UI->>Library: getInstalledVersions()
    Library->>Library: scan library, find executables
    Library->>Library: generate icons/banners, shortcuts
    UI->>Tray: setupTrayIcon()
    UI->>UI: subscribe stores and show main UI
```

Initialization is intentionally serial and surfaced through splash status text. No routing is used beyond the single route; tabs are local component state.

### 6.2 Components

| Component | Responsibility |
| --- | --- |
| `Library.svelte` | Two-pane view: installed/favorite versions on the left, templates for the selected version on the right |
| `Download.svelte` | Lists major releases and their available minor versions |
| `Release.svelte` | Per-release row: version selector, progress, download/installed state |
| `VersionCard.svelte` | Version tile: favorite, select, launch, delete, set default |
| `TemplateCard.svelte` | Launch base Blender or a template; delete template |
| `Dropzone.svelte` | Accepts dropped `.blend` files as templates for the selected version |
| `Settings.svelte` | Displays settings and moves the library directory |
| `Splash.svelte` | Startup status display |
| `Dialog.svelte` | Promise-based confirmation dialog (`show({...})`) |
| `Popup.svelte` | Transient success/error toast |
| `Menu.svelte`, `MenuItem.svelte` | Context menu primitives |
| `Progress.svelte` | Download/extraction progress display |
| `Button.svelte` | Shared button styles and variants |

### 6.3 State management

State is split into two categories:

**In-memory Svelte stores**

| Store | Module | Shape |
| --- | --- | --- |
| `currentSettings` | `settings.js` | `Settings` |
| `installedVersionsStore` | `library.js` | `blenderVersion[]` |
| `selectedVersionStore` | `library.js` | `blenderVersion \| null` |
| `blenderReleases` | `blenderfetch.js` | `BlenderRelease[]` |
| `downloadTasksStore` | `download.js` | `DownloadTask[]` |
| `notification` | `notification.js` | `{ message, timeout } \| null` |

**Persisted stores (`plugin-store`)**

| File | Keys | Purpose |
| --- | --- | --- |
| `settings.json` | Setting names | User preferences |
| `versions.json` | Version string → boolean | Favorite flags |

The UI does not cache installed versions independently of `installedVersionsStore`; components rescan through `getInstalledVersions()` after mutations.

### 6.4 Service modules

#### `settings.js`

- Defines the `Settings` type and defaults.
- Detects host platform and architecture via `plugin-os`.
- Persists settings through `LazyStore`.
- Creates the library structure when the library directory changes.
- Exposes `BASE_LIBRARY_DIR = "smoothie-library"`.

#### `blenderfetch.js`

- Fetches `https://download.blender.org/release/`.
- Parses the index with `DOMParser`.
- Selects version folders matching `Blender<version>/` and greater than `2.78`.
- Fetches each version folder in parallel and parses filenames of the form:

  ```text
  blender-<version>-<platform>-<arch>.<extension>
  ```

- Filters to the selected platform and architecture.
- Sorts releases with a numeric dot-segment comparator.
- Emits `BlenderRelease[]` and `FileLink[]`.

This module is deliberately source-specific. It is the only component that understands Blender's download directory naming convention.

#### `download.js`

Implements the install pipeline:

```mermaid
sequenceDiagram
    participant UI as Release.svelte
    participant DL as download.js
    participant Store as plugin-upload
    participant Rust as extract_archive
    participant Lib as library.js

    UI->>DL: downloadBlenderVersion(link)
    DL->>DL: read settings and compute target dir
    DL->>Store: download(url, target/archive)
    loop progress
        Store-->>DL: loaded / total
        DL->>DL: updateDownloadProgress(version)
    end
    DL->>Rust: extract_archive(archive, target)
    Rust->>Rust: spawn_blocking extraction
    Rust->>Rust: strip single top-level directory
    DL->>DL: remove archive unless keepDownloadedArchives
    DL->>Lib: getInstalledVersions()
    DL-->>UI: { success, message, path }
```

Key behaviors:

- Target directory: `<libraryDir>/smoothie-library/blender/<version>`.
- Progress is keyed by version string, not by task ID.
- On download failure, an empty target directory is removed.
- On extraction failure, the archive is retained and the error is returned.
- Extraction is delegated to a single Rust command; the JS layer only decides retention and refresh.

#### `library.js`

The domain core. Responsibilities:

- Scan `<library>/blender/*` and build `blenderVersion` objects.
- Resolve the executable for the current platform.
- Load templates and ensure template directories exist.
- Generate missing icons and banners.
- Create/remove Linux `.desktop` entries.
- Launch Blender with isolated environment variables.
- Register a build as the system default (`blender --register`).
- Maintain favorites.
- Delete versions and clean up associated resources.
- Refresh `selectedVersionStore` after scans.

#### `file_utils.js`

- Canvas-based icon generation with the embedded base icon and `Europa-Mono` font.
- Canvas/figlet-based 600×90 banner generation.
- Directory creation, recursive copy, move, and existence checks.
- Single-top-level-directory flattening.
- `.blend` drag-and-drop import as templates.

#### `trayicon.js`

- Creates a tray icon with "Show/Hide" and "Quit".
- Intercepts window close and hides to tray when `closeToTray` is enabled.

#### `notification.js`

- Tiny writable store consumed by `+page.svelte` and rendered through `Popup.svelte`.

---

## 7. Native (Rust) Layer

`src-tauri/src/lib.rs` exposes seven commands and registers twelve plugins.

### 7.1 Commands

| Command | Signature | Behavior |
| --- | --- | --- |
| `extract_zip` | `(archive_path, target_dir)` | Extracts ZIP entries, creating parent directories |
| `extract_tar` | `(archive_path, target_dir)` | Extracts uncompressed TAR |
| `extract_tar_gz` | `(archive_path, target_dir)` | Extracts gzip-compressed TAR |
| `extract_tar_xz` | `(archive_path, target_dir)` | Extracts xz-compressed TAR |
| `extract_tar_bz2` | `(archive_path, target_dir)` | Extracts bzip2-compressed TAR |
| `extract_archive` | `(archive_path, target_dir)` | Async dispatcher; detects format by filename; runs in `spawn_blocking` |
| `launch_binary` | `(path, args, env?)` | Spawns a detached process with null stdio |

Format detection in `extract_archive`:

1. Multi-part suffixes: `.tar.xz` / `.txz`, `.tar.gz` / `.tgz`, `.tar.bz2` / `.tbz2` / `.tbz`.
2. Single suffix: `.tar`, `.zip`.
3. Unknown suffix: try ZIP, then uncompressed TAR.

All archive extractors call `strip_single_top_level_directory`, which flattens an archive that produced exactly one directory. This is required because Blender archives contain a versioned wrapping folder.

### 7.2 Plugins

Registered in `lib.rs` and declared in the frontend dependency set:

- `updater`, `upload`, `shell`, `fs`, `persisted-scope`, `store`, `os`, `notification`, `http`, `dialog`, `window-state`, `opener`.

`window-state` is registered twice (once in the builder chain and once in `setup`); this is redundant but harmless and should be consolidated.

### 7.3 Process model

Blender is launched as a detached child process with:

- `stdin`, `stdout`, `stderr` set to null.
- Optional environment variables.
- No process tracking or lifecycle supervision.

Smoothie does not wait for Blender and does not receive exit status.

---

## 8. Data Model

### 8.1 `Settings`

```js
{
  libraryDir: string,              // user-visible library root
  defaultPlatform: 'windows' | 'linux' | 'macos',
  defaultArch: string,             // host architecture string
  keepDownloadedArchives: boolean, // default false
  autoCreateShortcuts: boolean,    // default true (Linux desktop entries)
  theme: 'light' | 'dark',         // default 'light'
  closeToTray: boolean             // default true
}
```

Defaults are derived at runtime from `appDataDir()`, `plugin-os` platform, and `plugin-os` architecture. Missing persisted fields are patched from defaults on load.

### 8.2 `BlenderRelease`

```js
{
  original: string,      // original href, e.g. "Blender4.2/"
  version: string,       // major series, e.g. "4.2"
  fullPath: string,      // absolute folder URL
  lastModified: null,    // reserved
  links: FileLink[]
}
```

### 8.3 `FileLink`

```js
{
  version: string,       // full version, e.g. "4.2.1"
  downloadUrl: string,
  platform: 'linux' | 'windows' | 'macos',
  architecture: 'x64' | 'arm64',
  fileExtension: 'tar.xz' | 'zip' | ...,
  status: 'pending' | 'downloading' | 'completed' | 'error',
  percent: number
}
```

### 8.4 `blenderVersion`

```js
{
  version: string,
  path: string,
  executable: string,
  platform: string,
  favourite: boolean,
  templates: string[]   // template folder names
}
```

`installDate` is declared in the JSDoc but not populated.

### 8.5 `DownloadTask`

```js
{
  version: string,
  loaded: number,
  total: number,
  percent: number
}
```

---

## 9. Storage Layout

### 9.1 Library

`BASE_LIBRARY_DIR = "smoothie-library"` is created under the configured `libraryDir`.

```text
<libraryDir>/
└── smoothie-library/
    ├── blender/
    │   └── <version>/
    │       ├── blender            # or blender.exe
    │       ├── icon.png           # generated
    │       ├── banner.png         # generated
    │       ├── <major.minor>/
    │       │   └── scripts/
    │       │       └── startup/
    │       │           └── bl_app_templates_system/
    │       │               └── <Template>/
    │       │                   ├── startup.blend
    │       │                   └── banner.png
    │       └── ...
    └── config/
        └── <version>/             # BLENDER_USER_RESOURCES
```

The `config/<version>` folder is what makes installations independent. Blender writes preferences, startup files, add-ons, and caches there instead of the user's global Blender configuration.

### 9.2 OS artifacts

| Platform | Artifact | Location |
| --- | --- | --- |
| Linux | Desktop entry | `$LOCALDATA/applications/blender-smoothie-<version>.desktop` |
| Windows | No shortcut creation implemented | — |
| macOS | No shortcut creation implemented | — |

Desktop entries embed:

- `BLENDER_USER_RESOURCES=<library>/config/<version>`
- `BLENDER_CUSTOM_SPLASH_BANNER=<version>/banner.png`
- `Icon=<version>/icon.png`
- `MimeType=application/x-blender`

### 9.3 Settings and favorites

Both are managed by `plugin-store`:

- `settings.json` — scalar key/value pairs.
- `versions.json` — version string → favorite boolean.

These files live in the Tauri-managed application data/config location, not in the portable library. Moving machines requires copying the library separately from these preferences.

---

## 10. Key Workflows

### 10.1 Release discovery

1. Fetch the release index.
2. Parse anchors ending in `/` and matching `Blender<number><suffix>/`.
3. Ignore versions at or below 2.78.
4. Fetch every qualifying folder concurrently.
5. Parse `blender-<version>-<platform>-<arch>.<ext>` filenames.
6. Group by full version and select the entry matching the configured platform/architecture.
7. Sort major series and minor versions descending.
8. Publish results to `blenderReleases`.

### 10.2 Install

1. User selects a `FileLink` in the Download tab.
2. `downloadBlenderVersion` resolves the target directory.
3. `plugin-upload` streams the archive into that directory.
4. Progress updates are written to `downloadTasksStore` keyed by version.
5. `invoke('extract_archive')` runs extraction off the UI thread.
6. The single top-level directory is flattened.
7. The archive is deleted unless `keepDownloadedArchives` is true.
8. `getInstalledVersions()` rescans the library and regenerates artifacts.
9. The release row flips to "Installed".

### 10.3 Launch

1. User clicks the version tag, double-clicks a card, or launches a template.
2. Smoothie verifies the executable with `stat`.
3. It computes the isolated config path.
4. It selects the banner: version banner or template banner.
5. For a template, it passes `--app-template <name>`.
6. It invokes `launch_binary` with:
   - `BLENDER_USER_RESOURCES=<library>/config/<version>`
   - `BLENDER_CUSTOM_SPLASH_BANNER=<banner.png>`

### 10.4 Templates

- Template directories live inside the installed Blender build, not the config directory.
- A template is valid when it contains `startup.blend`.
- Built-in directories (`Storyboarding`, `2D_Animation`, `Sculpting`, `VFX`, `Video_Editing`) are ignored.
- Dropping a `.blend` copies it into a new template directory as `startup.blend`.
- Template deletion removes the directory recursively.
- Template banners are generated lazily.

### 10.5 Favorites and selection

- Favorites are toggled in memory and persisted immediately.
- On scan, the previously selected version is refreshed by version string.
- If nothing is selected:
  - Prefer the first favorite.
  - Otherwise select the first installed version.

### 10.6 Delete

1. Remove the version directory recursively.
2. Remove the favorite entry.
3. Remove the Linux desktop entry.
4. Reset any download-progress entry.
5. Update the in-memory installed list.

### 10.7 Set default

`registerVersion` invokes `launch_binary` with `--register`, letting Blender register `.blend` file associations. The result of the invocation is not awaited or reported.

### 10.8 Move library

Implemented in `Settings.svelte`:

1. Validate the destination is not inside the current library and vice versa.
2. Optionally confirm replacement of an existing destination.
3. Remove Linux desktop entries for current versions.
4. Attempt `rename`; fall back to recursive copy + delete for cross-device moves.
5. Persist the new `libraryDir`.
6. Rescan and recreate shortcuts.

### 10.9 Tray and window lifecycle

- Closing the window hides it when `closeToTray` is true.
- Tray menu toggles visibility and can destroy the window.
- Window size and position are persisted by `window-state`.
- Default window is 1024×576, resizable, bounded to 512×288 minimum and 1920×1080 maximum.

---

## 11. Platform Integration

### Linux (primary, most complete)

- `.desktop` entries created and removed automatically.
- Orphaned entries cleaned up during scans.
- `BLENDER_USER_RESOURCES` and splash banner configured in the entry.
- Archives typically `.tar.xz`.

### Windows (partial)

- Executable name: `blender.exe`.
- Archives typically `.zip`.
- No Start Menu or desktop shortcut creation.
- File association delegated to `blender --register`.

### macOS (partial)

- Platform mapping is `darwin → macos`.
- Download links use the `macos` filename segment.
- Executable discovery currently expects `<version>/blender`, while a standard macOS bundle places it at `Blender.app/Contents/MacOS/Blender`.
- No `.app` or Dock integration.

### Architecture handling

- Download selection maps `x86_64 → x64` and `arm64 → arm64`.
- Settings detection returns the raw OS architecture value.
- The two mappings are not fully aligned (for example, `aarch64` is not normalized to `arm64`), which can cause missing download matches on ARM Linux.

---

## 12. Security and Capabilities

### Current posture

- The webview loads only bundled local content.
- HTTP is scoped to `https://*.blender.org`.
- Filesystem access is scoped to app directories plus persisted paths granted through the directory picker.
- The updater uses a Minisign public key and signed artifacts.

Relevant capability entry points in `src-tauri/capabilities/desktop.json`:

- Window show/hide/close/destroy.
- Dialog open and confirm.
- App-scoped read/write, recursive.
- FS scope for `$LOCALDATA/applications`.
- Shell spawn.
- HTTP for `*.blender.org`.
- Store, OS, notification, upload, updater.

### Security considerations

1. **CSP is disabled** (`app.security.csp = null`). Tightening it is advisable now that the frontend is fully bundled.
2. **`launch_binary` accepts an arbitrary path and arguments** from the frontend. The trust boundary is the local webview, but an allowlist or explicit launch token would reduce blast radius if UI content were ever compromised.
3. **No checksum verification** is performed on downloaded Blender archives. `.md5` and `.sha256` files are explicitly ignored during parsing.
4. **Archive extraction** uses `mangled_name()` for ZIP entries, which normalizes traversal paths; TAR extraction relies on the `tar` crate's safety checks.
5. **Persisted scope** keeps directory grants across restarts; this is intentional for library access but should be reviewed when the library moves.
6. **Updater artifacts** must remain signed; the private key is provided only to CI.

---

## 13. Build, Packaging, and Release

### Local development

```bash
bun install
bun run tauri dev
```

- Vite serves on `localhost:1420`.
- `src-tauri` is excluded from Vite file watching.
- Tauri runs `bun run dev` before development and `bun run build` before production builds.

### Frontend build

- `adapter-static` prerenders the single route.
- `ssr = false` because Tauri has no Node server.
- Output is written to `build/` and bundled by Tauri.

### Packaging

- `bundle.targets = "all"`.
- `createUpdaterArtifacts = true`.
- Icons for Linux, Windows, macOS, Android, and iOS are present, though desktop is the supported target.

### Release workflow

`.gitea/workflows/build.yml`:

- Triggers on pushes to `master`.
- Builds on `ubuntu-22.04`.
- Installs Bun, Rust stable, and Linux system dependencies.
- Invokes a Tauri action that publishes a draft Gitea release tagged `app-v__VERSION__`.
- Signs update artifacts via CI secrets.
- Uploads artifacts to `https://git.floatingpoint.ch`.

### Update configuration

- Endpoint: `https://git.floatingpoint.ch/valerio/smoothie/releases/download/latest/update.json`.
- Signed with a Minisign key embedded in `tauri.conf.json`.

---

## 14. Reliability, Concurrency, and Error Handling

### Current behavior

- Service functions generally return `{ success, message, path? }` rather than throwing to the UI.
- Known recoverable failures are logged with `console.warn`.
- Downloads are tracked by version string, so two concurrent installs of the same version would collide.
- There is no global install queue or lock.
- Partial extraction leaves files behind; only a completely empty target directory is cleaned after a download failure.
- Store writes are immediate but not transactional across multiple keys.
- Installed-version scanning treats the filesystem as authoritative and tolerates malformed version folders by skipping them.
- A missing executable causes the version folder to be skipped, with removal commented out.

### Recommended invariants for future work

1. One active operation per version.
2. Install state machine: `idle → downloading → verifying → extracting → finalizing → installed | failed`.
3. Atomic finalize: extract to a temporary directory, then rename into place.
4. Cleanup of partial state on failure.
5. Explicit cancellation through an operation ID.

---

## 15. Known Limitations and Architectural Risks

| Area | Issue | Impact |
| --- | --- | --- |
| Release discovery | HTML scraping with regexes tied to current site markup | Breaks if Blender changes its index or filenames |
| Release discovery | Fetches every major-version folder on every launch; no cache | Startup latency and N+1 requests |
| Downloads | No checksum or signature verification | Supply-chain risk |
| Downloads | No cancellation despite a "Cancel" label | Confusing UX and orphaned work |
| Extraction | Not atomic; failure can leave partial installs | Library can contain unusable versions |
| Concurrency | No per-version lock or queue | Duplicate downloads and progress collisions |
| macOS | Executable discovery does not handle `.app` bundles | macOS installations are likely unusable |
| Architecture | `aarch64` is not normalized to `arm64` consistently | ARM Linux builds may not appear |
| Launch | Detached processes are not tracked | No exit status, crash detection, or running indicator |
| Registration | `--register` result is not awaited | UI may report success without confirmation |
| Portability | Settings and favorites live outside the library | Full setup is not completely portable |
| Security | CSP disabled; arbitrary binary launch command | Hardening opportunity |
| Testing | No automated tests or test harness | Regressions rely on manual verification |
| Versioning | `package.json` and `tauri.conf.json` are `0.1.2`; `Cargo.toml` is `0.1.0` | Inconsistent release metadata |
| Version scan | `exists()` is not awaited in one guard | Incorrect truthiness for missing library paths |
| Window state | Plugin is registered twice | Redundant initialization |

---

## 16. Extension Points

The architecture anticipates the following extensions without structural change:

- **Additional download sources / mirrors.** Add a source adapter that produces `BlenderRelease[]`.
- **Checksum verification.** Add a verification step between download and extraction.
- **Install queue.** Introduce an operation manager keyed by version, with cancellation and persisted job state.
- **Platform-specific shortcut adapters.** Extend the current Linux-only `.desktop` logic with Windows `.lnk` and macOS `.app`/alias handling.
- **Typed domain layer.** Migrate JSDoc types to TypeScript and define a typed IPC contract.
- **Library manifest.** Add an optional manifest for migration, integrity checks, and machine-readable provenance while keeping the filesystem authoritative.
- **Plugin management.** Extend the library model with per-version add-on directories and enable/disable state.
- **Template metadata.** Store display names, descriptions, and thumbnails alongside `startup.blend`.

---

## 17. Architectural Invariants

These should remain true unless the architecture is deliberately revised:

1. No installed-version state is stored outside the library except user preferences and favorites.
2. Each Blender launch receives a version-specific `BLENDER_USER_RESOURCES`.
3. Every installed version is discoverable by scanning `<library>/smoothie-library/blender`.
4. Rust remains a capability layer, not a business-logic layer.
5. Release discovery and installation are separate stages, joined by `FileLink`.
6. UI state flows from stores; components do not maintain duplicate authoritative copies.
7. Network access remains limited to Blender hosts and the updater endpoint.
8. The library remains relocatable and transferable as a directory tree.

---

## 18. Glossary

| Term | Meaning |
| --- | --- |
| Library | `<libraryDir>/smoothie-library`, the portable root containing builds and configs |
| Build / Version | An extracted Blender installation under `blender/<version>` |
| Template | A folder containing `startup.blend`, launchable via `--app-template` |
| Favorite | User-marked version persisted in `versions.json` |
| Default version | The build registered with the OS via `blender --register` |
| Config isolation | Per-version `BLENDER_USER_RESOURCES` directory |
| Splash banner | Generated PNG passed through `BLENDER_CUSTOM_SPLASH_BANNER` |