OS Desktop Runtime Workspace (Rust/WASM + Tauri)

This project is a Rust workspace implementing a desktop-style runtime and app shell that can run in browser (wasm32) or Tauri-hosted environments. It is organized into contract, runtime, host, storage-adapter, and app crates, with state managed through a reducer/effect model and persistence routed through typed host/storage abstractions.

It includes strong local tooling (xtask) for verification, documentation contract enforcement, and operational workflows, with moderate unit/integration test coverage concentrated in runtime and adapter logic.

Documentation is split by intent:

• rustdoc (generated from Rust source comments) is the authoritative API/reference surface.
• GitHub Wiki is the canonical documentation hub and navigation surface, organized with Diataxis (tutorials, how-to guides, explanations, and project reference indexes).
• docs/ (repo-native Markdown) remains the canonical storage for documentation governance, contracts, ADRs, SOPs, diagrams/assets, and tooling reference, validated by cargo xtask docs.
• .ai/ directory contains machine-consumable context for Claude and other LLMs, including architectural rules, operational contracts, naming conventions, and validation requirements. See .ai/INDEX.md for the discovery entry point.

Prototype Status

• Desktop shell with taskbar, launcher menu, windows, and persistence hooks
• Runtime behavior centered on reducer state transitions and RuntimeEffect execution
• Cross-environment shell execution path (browser/WASM and Tauri-hosted desktop workflows)
• Offline-first browser storage architecture:
  • IndexedDB for versioned namespaced app/system state and virtual filesystem
  • Cache API for cached file previews/responses
  • localStorage for lightweight preferences/config
  • in-memory session store for ephemeral UI state
• Deep-link bootstrap (/?open=..., hash variants)
• Mounted app crates:
  • Explorer (File System Access API + IndexedDB virtual FS fallback)
  • Notepad (editable persisted workspace)
  • Calculator (persisted memory/tape/history state)
  • Terminal (persisted transcript/input workspace)
• Placeholder app panels:
  • Paint (persisted placeholder settings/state schema scaffold)
  • Dial-up
• Docs-as-code system with Diataxis structure, governance contracts, and Rust-native local validation/audit workflows

Run the Prototype (Browser / WASM)

Prerequisites:

• Rust toolchain
• wasm32-unknown-unknown target
• trunk

Install prerequisites (one-time):

cargo setup-web

Create the recommended external GitHub Wiki checkout when you need to edit or validate wiki content:

cargo wiki clone

Start local prototype server:

cargo dev

Start/stop a managed background dev server (Rust-managed lifecycle; logs/state under .artifacts/dev-server/):

cargo dev start
cargo dev status
cargo dev logs --lines 80
cargo dev stop

Restart the managed background server:

cargo dev restart

Build a development static bundle (non-release) with the same trunk pipeline:

cargo dev build

Build a production-like static bundle:

cargo web-build

Run the Tauri desktop shell workflow (Stage 2 scaffold):

cargo xtask tauri check
cargo tauri-dev
cargo tauri-build

cargo tauri-dev / cargo tauri-build use Tauri hooks that delegate frontend serve/build work to cargo dev (xtask) and normalize NO_COLOR=1 to NO_COLOR=true for Trunk compatibility in environments that export numeric NO_COLOR.

cargo dev serve/build defaults disable Trunk SRI and file hashing (--no-sri=true, --filehash=false) unless explicitly overridden, which keeps the local prototype loop stable when assets are rebuilt frequently.

Run prototype-specific compile checks (CSR native + WASM):

cargo web-check

Standardized Verification

Fast inner-loop validation scoped to changed packages/docs:

cargo flow

Fast verification (workspace Rust + docs):

cargo verify-fast

cargo verify-fast automatically skips desktop host (desktop_tauri) checks when changed files do not touch desktop/host boundary trigger paths. Override auto-detection when needed:

cargo verify-fast --with-desktop
cargo verify-fast --without-desktop

Profile-driven verification is also available:

cargo verify --profile dev
cargo verify --profile ci-fast
cargo verify --profile ci-full
cargo verify --profile release

Profile definitions live in tools/automation/verify_profiles.toml.

Run local automation/tooling diagnostics and safe auto-remediation:

cargo doctor
cargo doctor --fix

Resolve the Cargo-managed E2E profile surface and prerequisites:

cargo e2e list
cargo e2e doctor
cargo e2e run --profile local-dev --dry-run
cargo e2e run --profile local-dev --scenario ui.shell.layout-baseline --slice shell.soft-neumorphic.default --no-diff
cargo e2e inspect --run <run-id>
cargo e2e promote --profile local-dev --scenario ui.shell.layout-baseline --slice shell.soft-neumorphic.default --source-run <run-id>

The current E2E slice now includes the first executable browser path: profiles and scenario sets are versioned under tools/automation/, cargo e2e doctor checks the local prerequisites, and cargo e2e run --profile ... starts an isolated per-run trunk serve instance under .artifacts/e2e/, bootstraps tools/e2e/ with npm ci when needed, and runs the Playwright harness with artifacts under .artifacts/e2e/runs/. Each browser run now writes a deterministic UI feedback manifest at reports/ui-feedback-manifest.json plus per-slice screenshots, DOM snapshots, accessibility snapshots, layout metrics, logs, traces, and diff artifacts. Approved baselines live under tools/e2e/baselines/ and are updated only through cargo e2e promote. Profile settings now materially affect the run: ci-headless uses headless Chromium plus retry-on-failure policy for validation, cross-browser fans out across Chromium/Firefox/WebKit, and debug runs headed with slow motion and always-retained traces. Desktop tauri-webdriver profiles are now versioned in the same config surface and reported by cargo e2e doctor, but macOS remains the stable browser-first development path. Desktop Linux/Windows execution is staged behind the same Cargo surface and tracked in docs/reference/cargo-e2e-desktop-platform-todo-spec.md; on macOS, those profiles fail immediately with an explicit unsupported-platform message. cargo e2e run --dry-run remains available for config-only validation.

Full verification (fast verification + prototype checks + optional clippy/trunk build):

cargo verify

cargo verify remains exhaustive and always includes desktop host coverage. Profile-driven verification via cargo verify --profile <name> can now optionally append a Cargo-managed E2E stage from tools/automation/verify_profiles.toml after the normal Rust/docs/clippy stages. cargo verify-fast and cargo verify print per-stage timing so bottlenecks are observable directly from command output.

Compatibility make targets still work (delegating to Cargo aliases):

make flow
make doctor
make verify-fast
make verify
make proto-serve
make proto-start
make proto-stop
make proto-logs

Direct commands remain available if you prefer (cargo run -p xtask -- ..., trunk ...). Workflow run artifacts are emitted to .artifacts/automation/runs/<run-id>/ with manifest.json and events.jsonl for postmortem/debug tooling.

Useful ad-hoc full-workspace aliases:

cargo check-all
cargo test-all

Performance Engineering Workflow (Benchmarks + Profiling)

The repository now exposes a standardized performance workflow through xtask so benchmark runs, baselines, and profiling artifacts are repeatable across local environments.

Tooling availability check:

cargo perf doctor

Capture a repeatable local development-loop baseline report:

cargo perf dev-loop-baseline --output .artifacts/perf/reports/dev-loop-baseline.json

Enable local compiler caching (optional, local-first):

source scripts/dev/setup-sccache.sh
sccache --show-stats

Preflight functional correctness before optimization (unit/integration tests, all-features tests, doctests, benchmark target compile):

cargo perf check

Run workspace benchmarks (including Criterion benches where present):

cargo perf bench

Capture and compare Criterion baselines:

cargo perf baseline local-main
cargo perf compare local-main

Profile CPU and memory (optional tools; host/OS dependent):

cargo perf flamegraph --bench <bench_name>
cargo perf heaptrack -- cargo bench --workspace

Performance artifacts default to .artifacts/perf/. See the performance SOP/reference pages (indexed from the wiki) for baseline thresholds, workload guidance, and documentation expectations for optimization decisions.

Project Documentation Hub

Use the GitHub Wiki as the primary documentation entry point for project navigation and artifact discovery:

• knowledge base: https://github.com/justinrayshort/os/wiki
• git-backed wiki repository: https://github.com/justinrayshort/os.wiki.git
• formal artifacts: docs/
• API reference workflow: cargo doc --workspace --no-deps

The wiki is maintained as a separate git repository outside the main source tree. The recommended local checkout path is ../os.wiki, managed through cargo wiki clone, cargo wiki status, and cargo wiki verify.

When adding or changing formal artifacts such as ADRs, SOPs, diagrams, or command references, update the corresponding wiki reference/index pages in the external wiki checkout and record the wiki commit SHA in PR or review notes.

Generate Rust API reference locally:

cargo doc --workspace --no-deps

Run rustdoc examples (doctests):

cargo test --workspace --doc

Run repo docs validation:

cargo xtask docs all

cargo xtask docs all validates repo-native docs by default. Use cargo xtask docs all --with-wiki or cargo xtask docs wiki when you want external wiki validation as part of the local workflow. Use cargo wiki status to inspect the configured external checkout and cargo wiki verify to confirm it is clean and synchronized.

Project Layout (Current)

• crates/site - Leptos app shell, routes, runtime mounting, theme CSS
• crates/desktop_runtime - desktop state, reducer, effects, shell components, registry
• crates/desktop_app_contract - typed app/runtime contracts for module mount context, host commands, and lifecycle/events
• crates/desktop_tauri - Tauri desktop shell host crate/configuration (tauri.conf.json, capabilities, CLI hooks)
• crates/platform_host - API-first host contracts/types crate (Phase 1 migration foundation)
• crates/platform_host_web - browser (wasm32) implementations of platform_host services (app-state/cache/prefs/explorer)
• crates/apps/explorer - Explorer app UI crate
• crates/apps/notepad - Notepad app UI crate
• crates/apps/calculator - Calculator app UI crate
• crates/apps/terminal - Terminal app UI crate
• docs/ - repo-native formal documentation artifacts (ADR/SOP/contracts/reference/assets) backing the wiki hub
• xtask/src/commands/docs/ - docs command-family façade used by cargo xtask docs
• xtask/src/docs.rs + xtask/src/docs/ - docs validation/audit module root plus split validation surfaces
• xtask/src/commands/ - standardized project verification and developer workflow command families (cargo xtask ...)
• xtask/src/runtime/ - shared xtask automation runtime (process execution, workflow recording, config loading, artifacts)
• tools/docs/wiki.toml - external wiki repo configuration (remote URL, default branch, recommended checkout path)