Phase 1: Draft State Ownership - Context

Gathered: 2026-03-28 Status: Ready for planning

## Phase Boundary

Separate editable runtime settings from live runtime state so polling, folder/model refresh work, and other background activity cannot clobber in-progress edits before the user explicitly saves or discards them.

This phase covers draft ownership, reset/save/reopen behavior, and safe async updates inside the runtime settings experience. It does not yet consolidate the external runtime status card into a single workspace; that belongs to Phase 3.

## Implementation Decisions

Draft lifecycle

D-01: Opening the runtime settings surface creates the editable draft from the latest saved baseline.
D-02: Live polling continues while the drawer is open, but only live operational state updates from polling; the draft itself is not rehydrated while dirty.
D-03: After a successful save, the saved values become the new clean baseline immediately and the settings surface stays open.
D-04: Cancel resets the full form back to the last saved baseline.
D-05: Revert is the same as full-form Cancel for Phase 1; no separate per-field undo behavior is required.
D-06: Closing the drawer or backdrop with unsaved edits hides the draft without discarding it, so reopening in the same session restores that hidden draft.

Async field behavior

D-07: Folder pickers and file choosers may update only the field they were launched for; they must not rehydrate or rewrite unrelated draft fields.
D-08: Model rescans may refresh available options, but should preserve the current draft selection unless that selection becomes invalid.
D-09: While the form is dirty, background polling may continue to refresh live status-oriented data (for example runtime health, readiness, or library status) but must not overwrite draft-facing fields or local async selections.
D-10: Older async responses for the same field or operation must be ignored; only the latest in-flight request for that field may update the draft-facing UI.
D-11: If a rescan or validation pass shows the currently drafted model or folder choice is invalid, keep the user's draft value, mark it invalid inline, and block save until the user fixes it.

the agent's Discretion

Exact UI treatment for showing live value versus draft value, as long as users can clearly tell when a field is unsaved.
Exact request identity/cancellation mechanism used to ignore stale async results.
Exact wording and placement of inline validation and dirty-state messaging, as long as draft safety remains clear.

<canonical_refs>

Canonical References

Downstream agents MUST read these before planning or implementing.

Project scope and phase requirements

.planning/PROJECT.md — Project context, brownfield constraints, and the core value that unsaved edits must not be overwritten.
.planning/REQUIREMENTS.md — Phase 1 requirement set (WORK-02, CONF-01, CONF-02, CONF-03, CONF-04) and requirement wording.
.planning/ROADMAP.md — Phase 1 goal, success criteria, and dependency boundary.
.planning/STATE.md — Current focus and locked project-level decisions carried into this phase.

Existing architecture and codebase context

.planning/codebase/ARCHITECTURE.md — Runtime management architecture, ownership boundaries, and frontend/backend integration path.
.planning/codebase/STACK.md — Current stack and runtime/config persistence context.

Runtime workspace implementation

tauri-app/src/features/runtime/useRuntimeManager.ts — Current live snapshot polling, save/start/stop mutation flow, and snapshot overwrite behavior.
tauri-app/src/features/runtime/components/RuntimeSettingsDrawer.tsx — Current form state, full rehydration effect, async helpers, and save actions.
tauri-app/src/features/runtime/runtime-settings-form.ts — Patch creation rules, model selection helper behavior, and local-vs-remote field preservation.
tauri-app/src/features/runtime/types.ts — RuntimeSnapshot and RuntimeConfig ownership boundary.
tauri-app/src/features/runtime/components/RuntimeStatusCard.tsx — Adjacent runtime surface kept in mind for Phase 3 separation, not for Phase 1 scope.

</canonical_refs>

<code_context>

Existing Code Insights

Reusable Assets

tauri-app/src/features/runtime/useRuntimeManager.ts: already centralizes runtime snapshot fetching, polling, and lifecycle mutations; Phase 1 should likely evolve this into a clearer live-state owner rather than duplicating runtime orchestration elsewhere.
tauri-app/src/features/runtime/runtime-settings-form.ts: already knows how to derive a config patch from baseline config plus form values; useful as the baseline-vs-draft merge boundary.
tauri-app/src/features/runtime/components/RuntimeSettingsDrawer.tsx: already contains the relevant settings controls and async hooks, so Phase 1 can refactor ownership inside the existing surface before any larger UI reorganization.

Established Patterns

Runtime state is currently polled every 3 seconds and stored as one RuntimeSnapshot; Phase 1 must break the assumption that this same object can also be the editable form source of truth.
Save/start/stop flows already return refreshed snapshots from the backend; Phase 1 should preserve that backend contract while changing how the frontend promotes saved state into the draft baseline.
The app is brownfield React + TypeScript without a global store; planning should prefer a feature-scoped ownership model over a whole-app state rewrite.

Integration Points

Draft creation and promotion connect directly to useRuntimeManager.ts save and refresh behavior.
Dirty-state-safe field updates connect directly to the rehydration effect and async picker/rescan logic inside RuntimeSettingsDrawer.tsx.
Validation and invalid-draft blocking connect to runtime-settings-form.ts patch generation and any field-level validation added during Phase 1.

</code_context>

## Specific Ideas

Closing with unsaved edits should behave differently from Cancel: the draft is hidden and restored on reopen within the same session.
Async helpers should be narrow and field-scoped: a folder pick should update that folder field, not cause a whole-form refresh.
Invalid async outcomes should preserve user intent visibly instead of silently auto-correcting the draft.
Note: the current phase directory slug (01-hf-model-discovery) is stale metadata from earlier planning artifacts; ROADMAP Phase 1 (Draft State Ownership) is the canonical phase definition for downstream work.

## Deferred Ideas

Full runtime workspace consolidation and moving the runtime manager into a single control center — Phase 3 (Unified Runtime Workspace).
Source-specific path/model validation UX beyond draft preservation basics — Phase 4 (Model Source Validation).

Phase: 01-hf-model-discovery Context gathered: 2026-03-28

7.0 KiB Raw Blame History