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 |
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.
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:
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/"
`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 | — |
- `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>/`.
- 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`.
- 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`.
| 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` |
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.