Workspace Mode - Vision & Design Decisions

This document captures the key design decisions and vision for workspace mode.

---

Vision Summary

Transform fac into a workspace-aware editor where:

• Workspace = directory + persistent editor state (tabs, panes, positions)
• Fortress = navigator UI for finding workspaces and files
• State persists across sessions
• Single-file mode still works unchanged

---

Key Concepts

Workspace

A workspace is created when opening a directory:

fac .                    # Open cwd as workspace
fac ~/projects/myapp     # Open that directory as workspace
fac                      # Opens Fortress welcome menu

Workspace contains:

• Tabs and which files are open
• Pane splits and layouts
• Cursor positions per file
• Viewport scroll positions
• Fuss mode state (open/closed)
• Dirty buffer backups

Persisted in: .fac/workspace.json in workspace root

Fortress Navigator (Ctrl-O)

Dual-pane file/directory browser for:

1. Opening new workspaces - navigate to directory, press Enter
2. Opening orphan files - navigate to file (outside workspace), press Enter

Features:

• Dual-pane display (parent 30% | current 70%)
• Navigate with arrow keys
• Enter on directory → switch to that workspace
• Enter on file → open as orphan tab in current workspace
• '8' key → toggle between favorites and recents view
• 'f' key → add current directory to favorites
• ESC/q → cancel and return

Orphan Tabs

Files opened from outside the workspace via Fortress:

• Displayed in greyish/subtle color in tab bar
• NOT persisted in workspace state
• If closed, hard to reopen (need Fortress again)
• Similar to VSCode's non-workspace files

Favorites & Recents

Stored in ~/.config/fac/:

• favorites.json - manually marked favorite workspaces
• recents.json - automatically tracked recent workspaces (last 10-20)
• Press '8' in Fortress to toggle between favorites/recents view

---

File Structure

Workspace Root

~/projects/myapp/
  .fac/
    workspace.json       # Editor state (tabs, panes, positions)
    backups/             # Dirty buffer backups
      main.f90.bak
      test.f90.bak
      .backup-metadata.json
  src/
    main.f90
    ...

User Config

~/.config/fac/
  favorites.json         # User-marked favorites
  recents.json          # Auto-tracked recent workspaces

---

Command Line Behavior

Command	Behavior
fac	Open Fortress welcome menu (favorites/recents)
fac .	Open cwd as workspace (create if new)
fac ~/dir	Open that directory as workspace
fac file.txt	Single-file mode (check parent for workspace)

---

Key Workflows

1. Start Working on Project

cd ~/projects/myapp
fac .
# Opens workspace (or creates if first time)
# Restores tabs/panes from last session

2. Switch to Another Project

While in fac:

Ctrl-O
# Navigate to ~/projects/other-project
# Press Enter
# Saves current workspace state
# Opens new workspace with its state

3. Open Orphan File

While in fac workspace:

Ctrl-O
# Navigate to /etc/hosts (outside workspace)
# Press Enter
# Opens in new tab (grey color, not persisted)

4. Quick Edit Single File

fac /etc/hosts
# Single-file mode (no workspace)
# Works like current fac

---

Design Decisions

1. Orphan Tabs

• Visual: Greyish/subtle color in tab bar
• Persistence: NOT saved in workspace.json
• Rationale: Similar to VSCode - you can open any file, but it won't be restored next session

2. Favorites vs Recents

• Both available, like VSCode
• Toggle with '8' key between views
• Favorites: Manual (user adds with 'f' key)
• Recents: Automatic (last 10-20 opened workspaces)

3. Workspace Discovery

• fac with no args → Fortress welcome menu
• fac path → Try to load workspace from that path
• Silent creation (no prompt) when creating new workspace

4. Backup Strategy

• On quit: Prompt to save dirty buffers
• If 'n': Create backup in .fac/backups/
• On open: Detect backups, prompt to restore
• Options: [r]estore / [i]gnore / [d]iff
• Always show diff option for safety

5. Storage Location

• Workspace state: .fac/workspace.json in workspace root
  • Rationale: Self-contained, obvious location, easy to delete
• User config: ~/.config/fac/
  • Rationale: Standard XDG location for user preferences

6. File Paths in workspace.json

• Workspace files: Relative paths (e.g., src/main.f90)
• Orphan files: Absolute paths (e.g., /etc/hosts)
• Rationale: Workspace portable if directory moves

7. Missing Files

• Behavior: Show warning, skip that tab, continue loading
• Warning: "File not found: src/missing.f90"
• Rationale: Don't block workspace load due to one missing file

8. Fortress Integration

• Copy Fortress modules into fac (not shell out)
• Use: Filesystem, terminal, UI modules
• Omit: Git integration (fuss menu has this), multiselect (for now)
• Rationale: Single binary, no Python dependency, full control

---

State Persistence

What Gets Saved in workspace.json

✅ Tab list with file paths ✅ Pane splits and layouts ✅ Cursor positions per file ✅ Viewport scroll positions per file ✅ Active tab index ✅ Active pane per tab ✅ Fuss mode state (open/closed, width)

❌ Orphan tabs (not persisted) ❌ Undo history (too large, unnecessary) ❌ Search history (not critical) ❌ Yank stack (session-specific)

workspace.json Schema

{
  "version": "1.0",
  "workspace_path": "/home/user/project",
  "last_opened": "2025-01-05T10:30:00Z",
  "tabs": [
    {
      "label": "main.f90",
      "panes": [
        {
          "file": "src/main.f90",
          "cursor": {"line": 42, "col": 10},
          "viewport": {"line": 30, "col": 1},
          "modified": false
        }
      ],
      "split_type": "none|vertical|horizontal",
      "active_pane": 0
    }
  ],
  "active_tab": 0,
  "fuss_mode": {
    "active": true,
    "width": 30
  }
}

---

Fortress Keybindings

Navigation

• ↑/↓: Move cursor
• →: Enter directory
• ←: Go to parent
• ~: Jump to home directory
• /: Jump to root directory
• Enter: Select (directory = switch workspace, file = open as orphan)
• q/ESC: Cancel and return to editor

Favorites & Recents

• 8: Toggle between favorites and recents view
• f: Add current directory to favorites
• r/x: Remove favorite (in favorites view)

Future (not Phase 1)

• s: Fuzzy search with fzf (maybe later)
• .: Toggle dotfiles (maybe later)

---

Backwards Compatibility

Critical: Single-file mode must work unchanged

• fac file.txt behaves exactly as before
• Ctrl-B shows parent directory tree
• No workspace created
• No persistence

Testing: Extensive regression tests for non-workspace mode

---

Open Questions / Future Enhancements

Not in Initial Implementation

• Fuzzy search within workspace (fzf integration)
• Multiselect in Fortress
• Git indicators in Fortress (fuss menu has this)
• Multiple workspaces open simultaneously
• Workspace templates
• Per-workspace editor settings

Maybe Later

• Workspace sharing (commit .fac/ to git?)
• Remote workspaces
• Workspace import/export
• Workspace groups

---

Success Criteria

The implementation is successful when:

• ✅ fac launches Fortress welcome menu
• ✅ fac . creates/loads workspace seamlessly
• ✅ Ctrl-O navigates to workspaces and files
• ✅ All tabs, panes, positions persist across sessions
• ✅ Orphan tabs work and are visually distinct
• ✅ Favorites and recents track correctly
• ✅ Backups save/restore with diff option
• ✅ Single-file mode works unchanged
• ✅ No regressions in existing features
• ✅ Documentation is complete

---

References

• See WORKSPACE_ROADMAP.md for implementation phases
• See WORKSPACE_TASKS.md for task tracking
• See workspace_spec.md for technical specifications (Phase 0 deliverable)

---

Last Updated: 2025-01-05