From 29666928eaf67528511c15f5f45363e827b6cf35 Mon Sep 17 00:00:00 2001 From: bQUARKz Date: Mon, 30 Mar 2026 23:47:23 +0100 Subject: [PATCH] implements PLN-0012 --- discussion/index.ndjson | 2 +- ...012-studio-code-editor-spec-propagation.md | 4 +- ...hell and Workspace Layout Specification.md | 7 + .../2. Studio UI Foundations Specification.md | 5 + .../5. Code Editor Workspace Specification.md | 240 ++++++++++++++++++ docs/specs/studio/README.md | 4 +- 6 files changed, 258 insertions(+), 4 deletions(-) create mode 100644 docs/specs/studio/5. Code Editor Workspace Specification.md diff --git a/discussion/index.ndjson b/discussion/index.ndjson index dea9de50..cee27c4d 100644 --- a/discussion/index.ndjson +++ b/discussion/index.ndjson @@ -8,5 +8,5 @@ {"type":"discussion","id":"DSC-0007","status":"done","ticket":"pbs-learn-to-discussion-lessons-migration","title":"Migrate PBS Learn Documents into Discussion Lessons","created_at":"2026-03-27","updated_at":"2026-03-27","tags":["compiler","pbs","migration","discussion-framework","lessons","learn-prune"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0018","file":"discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0018-pbs-ast-and-parser-contract-legacy.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0019","file":"discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0019-pbs-name-resolution-and-linking-legacy.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0020","file":"discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0020-pbs-runtime-values-identity-memory-boundaries-legacy.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0021","file":"discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0021-pbs-diagnostics-and-conformance-governance-legacy.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0022","file":"discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0022-pbs-globals-lifecycle-and-published-entrypoint-legacy.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"}]} {"type":"discussion","id":"DSC-0008","status":"done","ticket":"pbs-low-level-asset-manager-surface","title":"PBS Low-Level Asset Manager Surface for Runtime AssetManager","created_at":"2026-03-27","updated_at":"2026-03-27","tags":["compiler","pbs","runtime","asset-manager","host-abi","stdlib","asset"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0023","file":"discussion/lessons/DSC-0008-pbs-low-level-asset-manager-surface/LSN-0023-lowassets-runtime-aligned-sdk-surface.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"}]} {"type":"discussion","id":"DSC-0009","status":"open","ticket":"studio-debugger-workspace-integration","title":"Integrate ../debugger into Studio as a dedicated workspace","created_at":"2026-03-30","updated_at":"2026-03-30","tags":["studio","debugger","workspace","integration","shell"],"agendas":[{"id":"AGD-0009","file":"AGD-0009-studio-debugger-workspace-integration.md","status":"open","created_at":"2026-03-30","updated_at":"2026-03-30"}],"decisions":[],"plans":[],"lessons":[]} -{"type":"discussion","id":"DSC-0010","status":"accepted","ticket":"studio-code-editor-workspace-foundations","title":"Establish Code Editor workspace foundations in Studio without LSP","created_at":"2026-03-30","updated_at":"2026-03-30","tags":["studio","editor","workspace","multi-frontend","lsp-deferred"],"agendas":[{"id":"AGD-0010","file":"AGD-0010-studio-code-editor-workspace-foundations.md","status":"accepted","created_at":"2026-03-30","updated_at":"2026-03-30"}],"decisions":[{"id":"DEC-0008","file":"DEC-0008-studio-code-editor-read-only-workspace-foundations.md","status":"accepted","created_at":"2026-03-30","updated_at":"2026-03-30","ref_agenda":"AGD-0010"}],"plans":[{"id":"PLN-0012","file":"PLN-0012-studio-code-editor-spec-propagation.md","status":"open","created_at":"2026-03-30","updated_at":"2026-03-30","ref_decisions":["DEC-0008"]},{"id":"PLN-0013","file":"PLN-0013-editor-workspace-layout-and-passive-surfaces.md","status":"open","created_at":"2026-03-30","updated_at":"2026-03-30","ref_decisions":["DEC-0008"]},{"id":"PLN-0014","file":"PLN-0014-project-navigator-snapshot-and-read-only-file-opening.md","status":"open","created_at":"2026-03-30","updated_at":"2026-03-30","ref_decisions":["DEC-0008"]}],"lessons":[]} +{"type":"discussion","id":"DSC-0010","status":"in_progress","ticket":"studio-code-editor-workspace-foundations","title":"Establish Code Editor workspace foundations in Studio without LSP","created_at":"2026-03-30","updated_at":"2026-03-30","tags":["studio","editor","workspace","multi-frontend","lsp-deferred"],"agendas":[{"id":"AGD-0010","file":"AGD-0010-studio-code-editor-workspace-foundations.md","status":"accepted","created_at":"2026-03-30","updated_at":"2026-03-30"}],"decisions":[{"id":"DEC-0008","file":"DEC-0008-studio-code-editor-read-only-workspace-foundations.md","status":"accepted","created_at":"2026-03-30","updated_at":"2026-03-30","ref_agenda":"AGD-0010"}],"plans":[{"id":"PLN-0012","file":"PLN-0012-studio-code-editor-spec-propagation.md","status":"done","created_at":"2026-03-30","updated_at":"2026-03-30","ref_decisions":["DEC-0008"]},{"id":"PLN-0013","file":"PLN-0013-editor-workspace-layout-and-passive-surfaces.md","status":"open","created_at":"2026-03-30","updated_at":"2026-03-30","ref_decisions":["DEC-0008"]},{"id":"PLN-0014","file":"PLN-0014-project-navigator-snapshot-and-read-only-file-opening.md","status":"open","created_at":"2026-03-30","updated_at":"2026-03-30","ref_decisions":["DEC-0008"]}],"lessons":[]} {"type":"discussion","id":"DSC-0011","status":"done","ticket":"compiler-analyze-compile-build-pipeline-split","title":"Split compiler pipeline into analyze, compile, and build entrypoints","created_at":"2026-03-30","updated_at":"2026-03-30","tags":["compiler","pipeline","artifacts","build","analysis"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0025","file":"discussion/lessons/DSC-0011-compiler-analyze-compile-build-pipeline-split/LSN-0025-compiler-pipeline-entrypoints-and-result-boundaries.md","status":"done","created_at":"2026-03-30","updated_at":"2026-03-30"}]} diff --git a/discussion/workflow/plans/PLN-0012-studio-code-editor-spec-propagation.md b/discussion/workflow/plans/PLN-0012-studio-code-editor-spec-propagation.md index 59aa5008..12d280a6 100644 --- a/discussion/workflow/plans/PLN-0012-studio-code-editor-spec-propagation.md +++ b/discussion/workflow/plans/PLN-0012-studio-code-editor-spec-propagation.md @@ -2,9 +2,9 @@ id: PLN-0012 ticket: studio-code-editor-workspace-foundations title: Propagate DEC-0008 into Studio shell and workspace specs -status: open +status: done created: 2026-03-30 -completed: +completed: 2026-03-30 tags: - studio - editor diff --git a/docs/specs/studio/1. Studio Shell and Workspace Layout Specification.md b/docs/specs/studio/1. Studio Shell and Workspace Layout Specification.md index 7407ef92..c21a86aa 100644 --- a/docs/specs/studio/1. Studio Shell and Workspace Layout Specification.md +++ b/docs/specs/studio/1. Studio Shell and Workspace Layout Specification.md @@ -48,6 +48,10 @@ The baseline workspace set includes: - Debugger/Profiler; - Shipper, temporarily represented by the current `BuilderWorkspace`. +Workspace-local behavior for the first `Code Editor` wave is defined in: + +- `5. Code Editor Workspace Specification.md` + `BuilderWorkspace` is transitional and must not be treated as a long-term architectural reference for the final shipping surface. ## Workspace Architecture Model @@ -64,6 +68,9 @@ Baseline workspace architecture rules are: The shell must not encourage a workspace model where every interaction falls back to whole-workspace refresh. +Detailed local workspace composition remains workspace-owned. +For example, `Code Editor`-local layout, navigator behavior, tab rules, passive placeholder surfaces, and read-only file behavior are not shell-global rules and must be defined by the workspace-local editor specification. + ## Right Utility Panel The right-side global utility surface is tab-based. diff --git a/docs/specs/studio/2. Studio UI Foundations Specification.md b/docs/specs/studio/2. Studio UI Foundations Specification.md index 5d219501..64f6bc6a 100644 --- a/docs/specs/studio/2. Studio UI Foundations Specification.md +++ b/docs/specs/studio/2. Studio UI Foundations Specification.md @@ -132,6 +132,9 @@ Shared Studio foundations include: - reusable workspace framework primitives; - reusable Studio control conventions. +Shared Studio foundations do not, by themselves, define workspace-local feature scope. +For example, read-only editor behavior, passive placeholder regions, manual-refresh-only navigator behavior, and similar local workspace rules must be closed by workspace-local specifications rather than inferred from this document alone. + ## Subscription Lifecycle Reusable Studio controls must have an explicit subscription lifecycle when they observe events or external state. @@ -166,6 +169,8 @@ The baseline reusable workspace framework should cover at least: - projection-host patterns for list/tree/detail surfaces; - local-patch versus structural-sync orchestration rules. +When a workspace first wave is intentionally passive or read-only, that workspace may still consume the framework without forcing a premature event or mutation contract. + The first concrete proving ground for this framework may be a single workspace, but the resulting framework is normative for future Studio workspace implementation. Shared Studio foundations do not include: diff --git a/docs/specs/studio/5. Code Editor Workspace Specification.md b/docs/specs/studio/5. Code Editor Workspace Specification.md new file mode 100644 index 00000000..2762f0b5 --- /dev/null +++ b/docs/specs/studio/5. Code Editor Workspace Specification.md @@ -0,0 +1,240 @@ +# Code Editor Workspace Specification + +## Status + +Active + +## Applies To + +- `prometeu-studio` +- the Studio `Code Editor` workspace +- the first read-only editor workspace wave + +## Purpose + +Define the normative Studio contract for the first `Code Editor` workspace wave. + +This specification stabilizes: + +- the baseline visual composition of the workspace, +- the `Project Navigator` role and scope, +- the read-only file-opening model, +- the responsive tab baseline, +- the passive `Outline`, helper, and status-bar surfaces, +- and the explicit deferral of write and semantic/LSP behavior. + +## Authority and Precedence + +This specification extends: + +- [`1. Studio Shell and Workspace Layout Specification.md`](1.%20Studio%20Shell%20and%20Workspace%20Layout%20Specification.md) +- [`2. Studio UI Foundations Specification.md`](2.%20Studio%20UI%20Foundations%20Specification.md) +- [`3. Studio Components Module Specification.md`](3.%20Studio%20Components%20Module%20Specification.md) + +If this document conflicts with the global Studio shell specifications, the shell specifications control shell-wide behavior and this document controls workspace-local editor behavior. + +## Normative Inputs + +The `Code Editor` workspace must assume: + +- the Studio shell already mounts `Code Editor` as a baseline workspace, +- the current wave is read-only, +- all project files remain visible in the editor workspace even when only some are frontend-relevant, +- `prometeu.json` plus the selected frontend may identify source roots worth tagging, +- future semantic providers such as LSP may arrive later, +- and the current wave must not depend on write/save or semantic behavior to remain coherent. + +This workspace may consume Studio project metadata and Studio-owned workspace framework primitives, but it must not infer a semantic-provider contract beyond keeping the path open for later integration. + +## Workspace Model + +The `Code Editor` workspace is: + +- project-aware, +- file-oriented, +- read-only in this first wave, +- and explicitly not a semantic IDE surface yet. + +The workspace must help the user: + +- see the full project tree, +- identify frontend-relevant source roots visually, +- open supported files into editor tabs, +- understand the active file context, +- and understand that semantic/editor-automation features are not part of this wave. + +The workspace must not pretend to offer: + +- save/write behavior, +- dirty state, +- merge behavior, +- active outline semantics, +- or LSP-backed coding assistance. + +## Baseline Layout + +The baseline workspace layout is: + +- a left editor column, +- a central editor work area, +- a lower helper region, +- and a bottom status bar. + +The left editor column must be a vertical stack containing: + +- a functional `Project Navigator` at the top, +- and a reserved `Outline` region below it. + +The central editor work area must contain: + +- a tab strip at the top, +- and the read-only editor body below it. + +The lower helper region is present in this wave only as a passive placeholder. + +## Component Ownership Rules + +The `Code Editor` workspace must be implemented as a composition root plus child controls/panels rather than one monolithic render surface. + +Rules: + +- the workspace root should coordinate layout, workspace-level session state, and structural synchronization; +- the `Project Navigator`, tab strip, editor body, reserved `Outline`, helper region, and status bar should exist as explicit local surfaces; +- passive placeholder surfaces must remain visually real without implying unsupported functionality; +- and the first wave should preserve a clean path for later extraction of reusable Studio controls when the surfaces become stable enough to justify that move. + +## Project Navigator Rules + +### Primary Navigation Unit + +- The primary navigation unit is the project file or directory. +- The navigator must cover the whole project rather than only frontend-tagged roots. +- Frontend tagging is supplementary context, not an inclusion filter. + +### Structural Snapshot + +- The navigator must maintain an in-memory structural snapshot of the project tree for navigation and visual state. +- That structural snapshot must not replace the filesystem as the source of truth. +- Content snapshots are separate and are only required for files that are actually opened in the editor. + +### Visibility and Ordering + +- All project files and directories must be visible in the navigator. +- Hidden files must be included by default. +- Folders must sort before files. +- Items within those groups must sort alphabetically. + +### Frontend-Aware Tagging + +- `prometeu.json` plus the selected frontend may be used to tag relevant source roots or source directories. +- That tagging must not hide non-source project files. +- That tagging must not imply semantic/editor-language ownership by the navigator itself. + +### Refresh Model + +- The navigator must perform one initial refresh when the project opens. +- The navigator must expose a manual refresh action directly on the navigator surface. +- Watcher-driven automatic refresh is explicitly deferred from this wave. + +### Unsupported Files + +- Unsupported or non-text files may still appear in the navigator. +- Attempting to open such a file must show a simple modal stating that the file is not supported in this wave. +- The workspace must not fake a partial preview to imply unsupported file-format coverage. + +## Tabs and File Opening Rules + +- Selecting a supported file that is not already open must open it in a new tab. +- The editor must maintain opened-file content in memory for the active Studio session only. +- The tab strip must be responsive rather than fixed to one hardcoded tab count. +- Overflow tabs must remain accessible through an IntelliJ-style overflow control. +- The active tab must remain visible. +- The tab label must use only the file name with extension. + +The first wave must not define: + +- tab pinning, +- drag-and-drop tab reordering, +- grouped tabs, +- split editors, +- or cross-session tab restoration. + +## Read-only File Model + +The first `Code Editor` wave is read-only. + +Rules: + +- supported files may be opened into read-only in-memory buffers, +- the workspace must not write files, +- the workspace must not expose save behavior, +- the workspace must not define dirty tracking, +- and the workspace must not define local merge/conflict behavior against disk changes. + +## Outline Rules + +- The `Outline` region must exist structurally in this wave. +- It must remain passive. +- It may show a discreet placeholder state. +- It must not fake semantic outline structure before real semantic ownership exists. + +## Helper Region Rules + +- The helper region must exist structurally in this wave. +- It must remain passive. +- It exists only to stabilize workspace composition and reserve future space. +- It must not become a substitute for the shell-level `Activity` surface. + +## Status Bar Rules + +The status bar must remain passive in this wave. + +Its left side must show the breadcrumb path of the active file, such as `proj > src > file.pbs`. + +Its right side must show: + +- `L:C`, +- line separator, +- tabs/spaces mode, +- file extension or language, +- and a read-only lock icon. + +For this wave: + +- `L:C` may remain a visual placeholder, +- and the read-only lock icon is visual only and does not imply file-permission enforcement. + +## Session State Rules + +Visual/editorial state in this wave is session-local only. + +That includes at minimum: + +- open tabs, +- active tab selection, +- tree expansion state, +- and similar visual editor state. + +Persisting that state across Studio executions is deferred. + +## Non-Goals + +- write/save behavior +- dirty tracking +- merge/conflict resolution +- watcher-driven automatic refresh +- active outline behavior +- helper panel functionality +- semantic analysis surfaces +- LSP integration details +- autocomplete, go-to-definition, symbols, rename, code actions, or semantic diagnostics while typing +- a normative editor event contract in this wave + +## Exit Criteria + +This specification is complete enough when: + +- the read-only first-wave scope is unambiguous, +- the `Project Navigator` and tab responsibilities are explicit, +- placeholder versus functional regions are clearly separated, +- and deferred write/semantic/LSP behavior is clearly outside the first-wave contract. diff --git a/docs/specs/studio/README.md b/docs/specs/studio/README.md index 82fb58c9..1be82fa5 100644 --- a/docs/specs/studio/README.md +++ b/docs/specs/studio/README.md @@ -54,6 +54,7 @@ The current Studio core corpus is: 2. [`2. Studio UI Foundations Specification.md`](2.%20Studio%20UI%20Foundations%20Specification.md) 3. [`3. Studio Components Module Specification.md`](3.%20Studio%20Components%20Module%20Specification.md) 4. [`4. Assets Workspace Specification.md`](4.%20Assets%20Workspace%20Specification.md) +5. [`5. Code Editor Workspace Specification.md`](5.%20Code%20Editor%20Workspace%20Specification.md) ## Reading Order @@ -62,4 +63,5 @@ Recommended order: 1. shell and workspace layout; 2. shared UI foundations; 3. components module policy; -4. assets workspace behavior. +4. assets workspace behavior; +5. code editor workspace behavior.