prometeu-studio/discussion/workflow/plans/PLN-0014-project-navigator-snapshot-and-read-only-file-opening.md

---
id: PLN-0014
ticket: studio-code-editor-workspace-foundations
title: Implement the Project Navigator snapshot and read-only file opening flow
status: open
created: 2026-03-30
completed:
tags:
  - studio
  - editor
  - implementation
  - navigator
  - tabs
---

## Objective

Implement the DEC-0008 operational core of the first `Code Editor` wave: full-project navigator snapshot, manual refresh, opening files into responsive tabs, read-only buffers, and unsupported-file modal behavior.

## Background

DEC-0008 requires the editor to operate over the full project, maintain an in-memory structural snapshot for the navigator, tag frontend-relevant roots using `prometeu.json`, and open supported files into read-only tabs without save/dirty/merge behavior.

The current codebase already includes project services such as `ProjectReference`, `ProjectLanguageCatalogService`, and `ProjectStudioPaths`, but the editor workspace does not yet use them to build a real project tree or manage open files.

## Scope

### Included
- Build a structural project-tree snapshot model for the navigator.
- Add initial and manual refresh behavior.
- Open supported files into read-only tabs.
- Keep opened-file content in memory for the active session only.
- Show a simple modal for unsupported/non-text files.

### Excluded
- Save, dirty tracking, write flows, or merge/conflict resolution.
- Watcher-driven automatic refresh.
- Semantic/LSP integration.
- Cross-session restoration of tabs or tree state.

## Execution Steps

### Step 1 - Implement the Project Navigator structural snapshot

**What:**
Create a structural project-tree model that covers the full project and the DEC-0008 ordering/tagging rules.

**How:**
Introduce a navigator snapshot service/model that:
1. scans all project files and directories, including hidden files,
2. orders folders before files and sorts alphabetically,
3. derives frontend-relevant tags from `prometeu.json` and the selected frontend,
4. and keeps filesystem truth outside the in-memory snapshot itself.

**File(s):**
- `prometeu-studio/src/main/java/p/studio/workspaces/editor/`
- `prometeu-studio/src/main/java/p/studio/projects/ProjectLanguageCatalogService.java`
- `prometeu-studio/src/main/java/p/studio/projects/ProjectReference.java`
- `prometeu-studio/src/main/java/p/studio/projects/ProjectStudioPaths.java`

### Step 2 - Wire refresh behavior into the navigator shell

**What:**
Support the refresh model closed by DEC-0008.

**How:**
Ensure the navigator:
1. performs one initial refresh when the workspace loads,
2. exposes a manual refresh button directly on the navigator surface,
3. and never assumes watcher-based automatic refresh in this wave.

**File(s):**
- `prometeu-studio/src/main/java/p/studio/workspaces/editor/`
- `prometeu-studio/src/main/java/p/studio/workspaces/editor/EditorWorkspace.java`

### Step 3 - Implement read-only file opening and tab session state

**What:**
Open supported files into read-only tabs while keeping session state in memory only for the current Studio run.

**How:**
Add editor session models/services that:
1. open a new tab when the selected file is not already open,
2. keep the active tab visible in the responsive tab strip,
3. label tabs with file name plus extension only,
4. load supported text file contents into read-only editor buffers,
5. and keep tab/tree state session-local only.

**File(s):**
- `prometeu-studio/src/main/java/p/studio/workspaces/editor/`
- `prometeu-studio/src/main/java/p/studio/workspaces/editor/EditorWorkspace.java`

### Step 4 - Handle unsupported files explicitly

**What:**
Reject unsupported/non-text file opening through the UX rule closed by DEC-0008.

**How:**
When a navigator selection targets an unsupported file type, show a simple modal stating that the file is not supported in this wave instead of trying to fake a preview or partially open it.

**File(s):**
- `prometeu-studio/src/main/java/p/studio/workspaces/editor/`

## Test Requirements

### Unit Tests

- Add unit tests for the structural project-tree snapshot model:
  - hidden-file inclusion,
  - folder-before-file ordering,
  - alphabetical ordering,
  - frontend-root tagging.
- Add unit tests for any editor tab/session model extracted from the UI layer:
  - open-new-tab behavior,
  - no duplicate tab on reopening the same file,
  - label formatting,
  - session-local state behavior.

### Integration Tests

- No full JavaFX integration harness is required, but any extracted coordinator/service should be exercised through focused tests where possible.

### Manual Verification

- Verify the navigator shows the full project, including hidden files.
- Verify the manual refresh button rebuilds the tree on demand.
- Verify supported text files open read-only in tabs.
- Verify unsupported files trigger the simple modal.
- Verify no save/dirty/write affordance appears in the resulting flow.

## Acceptance Criteria

- [ ] The editor has a structural navigator snapshot that covers the whole project and tags frontend-relevant roots.
- [ ] The navigator performs initial refresh and supports manual refresh without watcher dependency.
- [ ] Supported files open into read-only tabs with responsive/overflow behavior preserved.
- [ ] Unsupported files trigger a simple modal instead of a partial preview.
- [ ] Opened-file content and visual tab state remain session-local only.

## Dependencies

- DEC-0008 accepted.
- PLN-0012 should land first or in parallel if naming/spec wording is stable.
- PLN-0013 should land before or alongside this plan because navigator and tabs need the new workspace shell surfaces.

## Risks

- If snapshot and tab state live only inside UI controls, the implementation will become hard to test and harder to evolve later.
- If unsupported-file handling is loose, the first wave will silently imply file-format support it does not actually have.