Intrepid/prometeu-studio
Intrepid/prometeu-studio
3
0
Fork 0
Code Pull Requests 1 Activity
prometeu-studio/discussion/lessons/DSC-0010-studio-code-editor-workspace-foundations/LSN-0026-read-only-editor-foundations-and-semantic-deferral.md

6.6 KiB
Raw Blame History

id ticket title created tags
LSN-0026 studio-code-editor-workspace-foundations Read-Only Editor Foundations and Semantic Deferral 2026-03-31
studio
editor
workspace
read-only
navigator
tabs
lsp-deferred
ui-foundations

Context

Studio needed a real Code Editor workspace, but the team explicitly did not want the first wave to collapse UI structure, file management, write behavior, and language semantics into one premature implementation.

The discussion closed a narrower and more durable target:

  • Studio owns the editorial workspace shell.
  • The first wave is read-only.
  • The workspace must still be useful enough to navigate a full project and open files.
  • Semantic behavior such as diagnostics, symbols, completion, or other LSP-like surfaces must remain deferred.

This turned the problem from "build an editor" into "stabilize the workspace composition and file-management shell without hardcoding semantic ownership too early."

Key Decisions

Treat the First Editor Wave as an Editorial Shell, Not a Language Tool

What: The first Code Editor wave is a Studio-owned read-only workspace foundation with:

  • Project Navigator
  • reserved Outline region
  • responsive tab strip
  • central read-only editor surface
  • passive helper region
  • passive status bar

Why: The workspace needed to become structurally real before it could safely host future semantic providers. By freezing the editorial shell first, the team avoided inventing incomplete semantic behavior just to justify the layout.

Trade-offs: The result is intentionally incomplete as an editor. It opens files and manages workspace composition, but it does not yet save, mark dirty state, or provide language-aware interactions.

Separate Structural Project State from Open-Document Content State

What: The final implementation keeps two different kinds of in-memory state:

  • a structural project-tree snapshot for navigation and visual state
  • read-only file buffers only for opened files

Why: These are different responsibilities. The navigator needs fast structural state over the whole project, while the editor only needs content snapshots for documents the user has actually opened.

Trade-offs: This adds a small amount of model code up front, but it keeps the workspace testable and prevents the navigator from degenerating into ad hoc filesystem reads during rendering.

Keep Semantic Ownership Deferred but Architectural Seams Open

What: The workspace now reserves real regions for future semantic surfaces such as Outline, helper features, and later LSP-backed integrations, but those surfaces remain passive in this wave.

Why: The important rule was not to "solve LSP later" by ignoring layout now. The rule was to reserve the correct shell surfaces now without pretending semantic capability already exists.

Trade-offs: The first implementation includes visible placeholders and passive chrome. That can feel sparse, but it prevents later layout churn and keeps ownership boundaries explicit.

Final Implementation

The Studio domain now has a dedicated Code Editor workspace specification and a concrete read-only implementation:

  • docs/specs/studio/5. Code Editor Workspace Specification.md defines the normative first-wave contract.
  • EditorWorkspace now mounts a left navigator column, reserved Outline, responsive tabs, read-only code area, helper region, and status bar.
  • EditorProjectSnapshotService builds a full-project structural tree, including hidden files, folder-first ordering, alphabetical sorting, and frontend-root tagging from prometeu.json.
  • EditorOpenFileSession keeps opened tabs session-local and read-only.
  • unsupported or non-text files trigger an explicit modal instead of a fake preview.
  • the navigator and status bar share a consistent visual language for folders, source roots, build directories, and prometeu.json.

Patterns and Algorithms

Pattern: Stabilize Workspace Chrome Before Semantic Capability

When a new workspace will eventually host rich language tooling, first define and implement:

  1. shell composition
  2. project navigation
  3. document opening model
  4. session-local view state
  5. passive reserved regions for future semantic consumers

Only after those are stable should the team decide how semantic providers plug into the shell.

Pattern: Make Read-Only a Deliberate First-Wave Contract

Read-only mode is not just a shortcut. It is a way to avoid accidentally committing to:

  • save semantics
  • dirty tracking semantics
  • conflict resolution UX
  • write affordances
  • or editor-to-filesystem mutation rules

until those deserve their own discussion.

Pattern: Use Full-Project Visibility with Frontend-Aware Tagging

The navigator should not hide non-source files just because the selected frontend only cares about some roots. A better pattern is:

  • show the whole project
  • tag the frontend-relevant roots
  • and keep the filesystem as the source of truth

This preserves workspace usability without confusing project ownership with compiler ownership.

Pitfalls

  • Do not let passive first-wave regions start pretending they are semantic features.
  • Do not reintroduce save or dirty indicators without an explicit decision revision.
  • Do not make the navigator a filtered "source-only" view when the workspace is supposed to expose the real project.
  • Do not collapse structural snapshot state and open-document content buffers into one model.
  • Do not let visual polish quietly smuggle new product behavior into a read-only wave.

References

  • DEC-0008 Read-only foundations for the Studio Code Editor workspace
  • PLN-0012 Propagate DEC-0008 into Studio shell and workspace specs
  • PLN-0013 Implement the read-only Code Editor workspace shell and passive surfaces
  • PLN-0014 Implement the Project Navigator snapshot and read-only file opening flow
  • docs/specs/studio/5. Code Editor Workspace Specification.md
  • docs/specs/studio/1. Studio Shell and Workspace Layout Specification.md
  • docs/specs/studio/2. Studio UI Foundations Specification.md
  • prometeu-studio/src/main/java/p/studio/workspaces/editor/EditorWorkspace.java
  • prometeu-studio/src/main/java/p/studio/workspaces/editor/EditorProjectSnapshotService.java
  • prometeu-studio/src/main/java/p/studio/workspaces/editor/EditorOpenFileSession.java

Takeaways

  • A good first editor wave can be structurally complete while still being intentionally read-only.
  • Structural project navigation and opened-document content are different state models and should stay separate.
  • Future semantic integration becomes easier when the shell reserves the right surfaces early but refuses to fake capability before the contract exists.