diff --git a/discussion/.backups/index.ndjson.20260330-205742.bak b/discussion/.backups/index.ndjson.20260330-205742.bak new file mode 100644 index 00000000..b81ff8f0 --- /dev/null +++ b/discussion/.backups/index.ndjson.20260330-205742.bak @@ -0,0 +1,12 @@ +{"type":"meta","next_id":{"DSC":12,"AGD":12,"DEC":8,"PLN":12,"LSN":26,"CLSN":1}} +{"type":"discussion","id":"DSC-0001","status":"done","ticket":"studio-docs-import","title":"Import docs/studio into discussion-framework artifacts","created_at":"2026-03-26","updated_at":"2026-03-26","tags":["studio","migration","discussion-framework","docs-import"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0001","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0001-assets-workspace-execution-wave-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0002","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0002-bank-composition-editor-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0003","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0003-mental-model-asset-mutations-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0004","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0004-mental-model-assets-workspace-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0005","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0005-mental-model-studio-events-and-components-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0006","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0006-mental-model-studio-shell-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0007","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0007-pack-wizard-shell-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0008","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0008-project-scoped-state-and-activity-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0016","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0016-studio-docs-import-pattern.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"}]} +{"type":"discussion","id":"DSC-0002","status":"open","ticket":"palette-management-in-studio","title":"Palette Management in Studio","created_at":"2026-03-26","updated_at":"2026-03-26","tags":["studio","legacy-import","palette-management","tile-bank","packer-boundary"],"agendas":[{"id":"AGD-0002","file":"AGD-0002-palette-management-in-studio.md","status":"open","created_at":"2026-03-26","updated_at":"2026-03-26"}],"decisions":[],"plans":[],"lessons":[]} +{"type":"discussion","id":"DSC-0003","status":"done","ticket":"packer-docs-import","title":"Import docs/packer into discussion-framework artifacts","created_at":"2026-03-26","updated_at":"2026-03-26","tags":["packer","migration","discussion-framework","docs-import"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0009","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0009-mental-model-packer-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0010","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0010-asset-identity-and-runtime-contract-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0011","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0011-foundations-workspace-runtime-and-build-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0012","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0012-runtime-ownership-and-studio-boundary-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0013","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0013-metadata-convergence-and-runtime-sink-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0014","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0014-pack-wizard-summary-validation-and-pack-execution-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0015","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0015-tile-bank-packing-contract-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0017","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0017-packer-docs-import-pattern.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"}]} +{"type":"discussion","id":"DSC-0004","status":"open","ticket":"tilemap-and-metatile-runtime-binary-layout","title":"Tilemap and Metatile Runtime Binary Layout","created_at":"2026-03-26","updated_at":"2026-03-26","tags":["packer","legacy-import","tilemap","metatile","runtime-layout"],"agendas":[{"id":"AGD-0004","file":"AGD-0004-tilemap-and-metatile-runtime-binary-layout.md","status":"open","created_at":"2026-03-26","updated_at":"2026-03-26"}],"decisions":[],"plans":[],"lessons":[]} +{"type":"discussion","id":"DSC-0005","status":"open","ticket":"variable-tile-bank-palette-serialization","title":"Variable Tile Bank Palette Serialization","created_at":"2026-03-26","updated_at":"2026-03-26","tags":["packer","legacy-import","tile-bank","palette-serialization","versioning"],"agendas":[{"id":"AGD-0005","file":"AGD-0005-variable-tile-bank-palette-serialization.md","status":"open","created_at":"2026-03-26","updated_at":"2026-03-26"}],"decisions":[],"plans":[],"lessons":[]} +{"type":"discussion","id":"DSC-0006","status":"done","ticket":"pbs-game-facing-asset-refs-and-call-result-discard","title":"PBS Game-Facing Asset References and Ignored Call Result Lowering","created_at":"2026-03-27","updated_at":"2026-03-30","tags":["compiler","pbs","ergonomics","lowering","runtime","asset-identity","expression-statements"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0024","file":"discussion/lessons/DSC-0006-pbs-game-facing-asset-refs-and-call-result-discard/LSN-0024-addressable-surface-host-metadata-and-ignored-value-discipline.md","status":"done","created_at":"2026-03-30","updated_at":"2026-03-30"}]} +{"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":"open","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":"open","created_at":"2026-03-30","updated_at":"2026-03-30"}],"decisions":[],"plans":[],"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/.backups/index.ndjson.20260330-234208.bak b/discussion/.backups/index.ndjson.20260330-234208.bak new file mode 100644 index 00000000..a4e040b3 --- /dev/null +++ b/discussion/.backups/index.ndjson.20260330-234208.bak @@ -0,0 +1,12 @@ +{"type":"meta","next_id":{"DSC":12,"AGD":12,"DEC":9,"PLN":12,"LSN":26,"CLSN":1}} +{"type":"discussion","id":"DSC-0001","status":"done","ticket":"studio-docs-import","title":"Import docs/studio into discussion-framework artifacts","created_at":"2026-03-26","updated_at":"2026-03-26","tags":["studio","migration","discussion-framework","docs-import"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0001","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0001-assets-workspace-execution-wave-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0002","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0002-bank-composition-editor-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0003","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0003-mental-model-asset-mutations-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0004","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0004-mental-model-assets-workspace-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0005","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0005-mental-model-studio-events-and-components-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0006","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0006-mental-model-studio-shell-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0007","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0007-pack-wizard-shell-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0008","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0008-project-scoped-state-and-activity-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0016","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0016-studio-docs-import-pattern.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"}]} +{"type":"discussion","id":"DSC-0002","status":"open","ticket":"palette-management-in-studio","title":"Palette Management in Studio","created_at":"2026-03-26","updated_at":"2026-03-26","tags":["studio","legacy-import","palette-management","tile-bank","packer-boundary"],"agendas":[{"id":"AGD-0002","file":"AGD-0002-palette-management-in-studio.md","status":"open","created_at":"2026-03-26","updated_at":"2026-03-26"}],"decisions":[],"plans":[],"lessons":[]} +{"type":"discussion","id":"DSC-0003","status":"done","ticket":"packer-docs-import","title":"Import docs/packer into discussion-framework artifacts","created_at":"2026-03-26","updated_at":"2026-03-26","tags":["packer","migration","discussion-framework","docs-import"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0009","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0009-mental-model-packer-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0010","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0010-asset-identity-and-runtime-contract-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0011","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0011-foundations-workspace-runtime-and-build-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0012","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0012-runtime-ownership-and-studio-boundary-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0013","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0013-metadata-convergence-and-runtime-sink-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0014","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0014-pack-wizard-summary-validation-and-pack-execution-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0015","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0015-tile-bank-packing-contract-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0017","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0017-packer-docs-import-pattern.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"}]} +{"type":"discussion","id":"DSC-0004","status":"open","ticket":"tilemap-and-metatile-runtime-binary-layout","title":"Tilemap and Metatile Runtime Binary Layout","created_at":"2026-03-26","updated_at":"2026-03-26","tags":["packer","legacy-import","tilemap","metatile","runtime-layout"],"agendas":[{"id":"AGD-0004","file":"AGD-0004-tilemap-and-metatile-runtime-binary-layout.md","status":"open","created_at":"2026-03-26","updated_at":"2026-03-26"}],"decisions":[],"plans":[],"lessons":[]} +{"type":"discussion","id":"DSC-0005","status":"open","ticket":"variable-tile-bank-palette-serialization","title":"Variable Tile Bank Palette Serialization","created_at":"2026-03-26","updated_at":"2026-03-26","tags":["packer","legacy-import","tile-bank","palette-serialization","versioning"],"agendas":[{"id":"AGD-0005","file":"AGD-0005-variable-tile-bank-palette-serialization.md","status":"open","created_at":"2026-03-26","updated_at":"2026-03-26"}],"decisions":[],"plans":[],"lessons":[]} +{"type":"discussion","id":"DSC-0006","status":"done","ticket":"pbs-game-facing-asset-refs-and-call-result-discard","title":"PBS Game-Facing Asset References and Ignored Call Result Lowering","created_at":"2026-03-27","updated_at":"2026-03-30","tags":["compiler","pbs","ergonomics","lowering","runtime","asset-identity","expression-statements"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0024","file":"discussion/lessons/DSC-0006-pbs-game-facing-asset-refs-and-call-result-discard/LSN-0024-addressable-surface-host-metadata-and-ignored-value-discipline.md","status":"done","created_at":"2026-03-30","updated_at":"2026-03-30"}]} +{"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":"review","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":"review","created_at":"2026-03-30","updated_at":"2026-03-30","ref_agenda":"AGD-0010"}],"plans":[],"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/index.ndjson b/discussion/index.ndjson index b81ff8f0..dea9de50 100644 --- a/discussion/index.ndjson +++ b/discussion/index.ndjson @@ -1,4 +1,4 @@ -{"type":"meta","next_id":{"DSC":12,"AGD":12,"DEC":8,"PLN":12,"LSN":26,"CLSN":1}} +{"type":"meta","next_id":{"DSC":12,"AGD":12,"DEC":9,"PLN":15,"LSN":26,"CLSN":1}} {"type":"discussion","id":"DSC-0001","status":"done","ticket":"studio-docs-import","title":"Import docs/studio into discussion-framework artifacts","created_at":"2026-03-26","updated_at":"2026-03-26","tags":["studio","migration","discussion-framework","docs-import"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0001","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0001-assets-workspace-execution-wave-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0002","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0002-bank-composition-editor-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0003","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0003-mental-model-asset-mutations-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0004","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0004-mental-model-assets-workspace-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0005","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0005-mental-model-studio-events-and-components-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0006","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0006-mental-model-studio-shell-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0007","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0007-pack-wizard-shell-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0008","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0008-project-scoped-state-and-activity-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0016","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0016-studio-docs-import-pattern.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"}]} {"type":"discussion","id":"DSC-0002","status":"open","ticket":"palette-management-in-studio","title":"Palette Management in Studio","created_at":"2026-03-26","updated_at":"2026-03-26","tags":["studio","legacy-import","palette-management","tile-bank","packer-boundary"],"agendas":[{"id":"AGD-0002","file":"AGD-0002-palette-management-in-studio.md","status":"open","created_at":"2026-03-26","updated_at":"2026-03-26"}],"decisions":[],"plans":[],"lessons":[]} {"type":"discussion","id":"DSC-0003","status":"done","ticket":"packer-docs-import","title":"Import docs/packer into discussion-framework artifacts","created_at":"2026-03-26","updated_at":"2026-03-26","tags":["packer","migration","discussion-framework","docs-import"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0009","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0009-mental-model-packer-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0010","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0010-asset-identity-and-runtime-contract-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0011","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0011-foundations-workspace-runtime-and-build-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0012","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0012-runtime-ownership-and-studio-boundary-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0013","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0013-metadata-convergence-and-runtime-sink-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0014","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0014-pack-wizard-summary-validation-and-pack-execution-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0015","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0015-tile-bank-packing-contract-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0017","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0017-packer-docs-import-pattern.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"}]} @@ -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":"open","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":"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-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/agendas/AGD-0010-studio-code-editor-workspace-foundations.md b/discussion/workflow/agendas/AGD-0010-studio-code-editor-workspace-foundations.md index 14207816..672ae040 100644 --- a/discussion/workflow/agendas/AGD-0010-studio-code-editor-workspace-foundations.md +++ b/discussion/workflow/agendas/AGD-0010-studio-code-editor-workspace-foundations.md @@ -4,8 +4,8 @@ ticket: studio-code-editor-workspace-foundations title: Iniciar foundations do Code Editor no Studio sem LSP status: open created: 2026-03-30 -resolved: -decision: +resolved: 2026-03-30 +decision: DEC-0008 tags: - studio - editor @@ -16,14 +16,15 @@ tags: ## Pain -O shell do Studio ja assume `Code Editor` como parte do baseline workspace set, mas a implementacao atual do `EditorWorkspace` ainda e apenas um `CodeArea` com texto hardcoded e botoes sem modelo real de documento, tabs, arquivos, dirty state ou sessao de projeto. +O shell do Studio ja assume `Code Editor` como parte do baseline workspace set, mas a implementacao atual do `EditorWorkspace` ainda e apenas um `CodeArea` com texto hardcoded e botoes sem modelo real de documento, tabs, arquivos, modo read-only organizado ou sessao de projeto. -Ao mesmo tempo, queremos iniciar os trabalhos do editor agora, com foco em UI e infraestrutura robusta para varios frontends, mas sem cair em uma dependencia prematura de LSP. +Ao mesmo tempo, queremos iniciar os trabalhos do editor agora, com foco em UI e infraestrutura robusta para varios frontends, mas sem cair em uma dependencia prematura de LSP e sem fechar a porta para ele como provedor semantico futuro. -Sem fechar a boundary agora, a implementacao pode desviar para dois extremos ruins: +Sem fechar a boundary agora, a implementacao pode desviar para tres extremos ruins: - o Studio virar uma casca quase vazia que depende de cada frontend ate para abrir, salvar e manter buffers; - ou o Studio absorver semantica demais e virar uma segunda autoridade sobre parsing, diagnosticos e modelo de compilacao. +- ou a primeira wave endurecer a arquitetura em torno de uma implementacao local que depois conflita com a integracao de LSP. ## Context @@ -38,31 +39,39 @@ Superficies relevantes hoje: - `prometeu-studio/src/main/java/p/studio/workspaces/editor/EditorWorkspace.java` hoje monta um `CodeArea` simples sem modelo de arquivos do projeto; - `prometeu-studio/src/main/java/p/studio/projects/ProjectLanguageCatalogService.java` ja consome `FrontendRegistryService` e `FrontendSpec`, o que mostra que o Studio ja reconhece multiplos frontends e source roots por linguagem; - `prometeu-compiler/.../FrontendSpec.java` ja modela `languageId`, `allowedExtensions`, `sourceRoots`, `caseSensitive` e versoes de stdlib; -- o compiler hoje ainda descobre e le fontes diretamente do filesystem: `LoadSourcesPipelineStage` faz `walkFileTree(...)` nos `sourceRoots`, `BuilderPipelineContext.compilerContext(...)` instancia `SourceProviderFactory.filesystem()`, e `SourceHandle` le bytes com `Files.readAllBytes(path)`; +- `DSC-0011` acabou de fechar que o compiler possui entrypoints canonicos `analyze`, `compile` e `build`, com `analyze` como superficie sem write side effects e `AnalysisSnapshot` como contrato minimo de resultado; - `docs/roadmaps/lsp/` ja existe como trilha separada, mas esta wave quer editor sem depender de LSP; - o precedente do packer fixa uma boa disciplina de ownership, mas ele nao deve ser copiado mecanicamente para o editor sem discutir a diferenca entre semantica de dominio e sessao generica de edicao. O ponto mais sensivel desta agenda e justamente essa diferenca: - no packer, Studio nao deve reinventar semantica de asset, snapshots operacionais ou write lanes de dominio; -- no editor, leitura/escrita de arquivos fonte, dirty tracking, buffers em memoria e snapshots documentais fazem parte da propria experiencia do workspace e nao sao, por si so, semantica de linguagem. +- no editor, leitura de arquivos fonte, buffers em memoria para arquivos abertos e snapshots documentais/estruturais fazem parte da propria experiencia do workspace e nao sao, por si so, semantica de linguagem. Direcao adicional ja explicitada para a UX: - o editor deve seguir um baseline proximo ao modelo do IntelliJ; -- a ala esquerda deve ser um `Project Navigator` com arquivos/pastas relevantes do projeto; +- a ala esquerda deve ser uma stack vertical com `Project Navigator` funcional no topo e uma regiao de `Outline` ja delimitada abaixo, ainda apenas como placeholder estrutural nesta wave; +- o `Project Navigator` deve mostrar todos os arquivos e diretorios do projeto, com tagging visual dos source roots relevantes para o frontend selecionado em `prometeu.json`; +- o `Project Navigator` deve ordenar pastas antes de arquivos, em ordem alfabetica, sem filtros sofisticados nesta wave, incluindo arquivos ocultos por padrao; - a area central deve ter tabs de arquivos abertos no topo e o editor rico no corpo principal; -- a regiao inferior deve ser um helper persistente para prompts, tips e feedback contextual sobre o codigo atual, funcionando mais como `advanced editor log` do que como console cru. +- a regiao inferior deve ser um helper persistente apenas para demarcar espaco nesta wave, funcionando como placeholder passivo; +- a primeira wave tambem pode incluir um `status bar` passivo: breadcrumb do arquivo ativo na esquerda e, na direita, `L:C`, line separator, modo de tabs/espacos, extensao/linguagem e um cadeado de `read-only` apenas visual, sem efeito funcional ainda; `L:C` pode nascer como placeholder visual nesta wave. ## Open Questions -- [ ] Qual e o seam normativo para ligar `document snapshots` do editor ao compiler: substituir `SourceProviderFactory.filesystem()` por provider de sessao, ou introduzir uma etapa explicita que materializa uma visao congelada de documentos antes do pipeline? -- [ ] O primeiro wave do editor deve nascer com tabs multiplas e sessao multi-documento completa, ou tabs multiplas com uma politica mais simples de documentos ativos/carregados? -- [ ] Como o `EditorWorkspace` descobre quais arquivos e source roots sao editaveis a partir de `ProjectReference.languageId` e `FrontendSpec`? -- [ ] Quem detecta modificacoes externas em arquivos abertos e como o conflito entre disco e buffer em memoria deve aparecer para o usuario? -- [ ] Alem do baseline ja aceito (`Project Navigator`, tabs, editor central, helper inferior), a primeira wave tambem deve incluir `outline` ou `status bar`, ou esses elementos ficam explicitamente para depois? -- [ ] Como preservar uma UI consistente entre linguagens diferentes sem forcar cada frontend a carregar seu proprio mini-editor completo? -- [ ] O que fica explicitamente fora desta wave por ausencia de LSP: autocomplete, go to definition, semantic diagnostics ao digitar, symbols, rename, code actions? +- [x] O primeiro wave do editor deve nascer com tabs multiplas e sessao multi-documento completa, ou tabs multiplas com uma politica mais simples de documentos ativos/carregados? + Fechamento: todo arquivo ainda nao aberto deve abrir em nova tab; a primeira wave tera uma faixa de tabs responsiva, mostrando quantas tabs couberem na largura disponivel e mandando o restante para um controle de overflow no estilo IntelliJ; a tab ativa deve permanecer visivel; comportamento mais rico pode ser adicionado depois. +- [x] Como o `EditorWorkspace` descobre quais arquivos e source roots sao editaveis a partir de `ProjectReference.languageId` e `FrontendSpec`? + Fechamento: o editor pode abrir todos os arquivos do projeto; `prometeu.json` define o frontend selecionado e serve para taggear corretamente os source roots/diretorios fonte no `Project Navigator`; a wave continua read-only. +- [x] Quem detecta modificacoes externas em arquivos abertos e como o conflito entre disco e buffer em memoria deve aparecer para o usuario? + Fechamento: o projeto recebe um refresh inicial ao abrir e aceita refresh manual a qualquer momento por um botao proprio no `Project Navigator`; como a wave e read-only, nao existe resolucao de merge local ainda. +- [x] Alem do baseline ja aceito (`Project Navigator`, tabs, editor central, helper inferior), a primeira wave tambem deve incluir `outline` ou `status bar`, ou esses elementos ficam explicitamente para depois? + Fechamento: `status bar` entra nesta wave; `outline` fica fora como componente funcional, mas sua regiao ja deve ficar delimitada visualmente abaixo do `Project Navigator` como placeholder estrutural. +- [x] Qual e o modelo de eventos editoriais minimo desta wave: arquivo aberto/fechado, troca de tab ativa, dirty state, save, reload externo, erro de IO e mudanca de selecao no navigator? + Fechamento: esta agenda nao vai fechar um contrato formal de eventos agora; se necessario, deixar apenas comentarios de implementacao, nao requisitos normativos. +- [x] O que fica explicitamente fora desta wave por ausencia de LSP: autocomplete, go to definition, semantic diagnostics ao digitar, symbols, rename, code actions? + Fechamento: esta wave nao lida com codigo em si, apenas com gerenciamento de arquivos, abertura de tabs e composicao editorial do workspace. ## Options @@ -72,10 +81,10 @@ Direcao adicional ja explicitada para a UX: - **Con:** Duplica infraestrutura generica em cada frontend, acopla UX basica a backend de linguagem e torna dificil sustentar uma experiencia coerente multi-FE sem LSP. - **Maintainability:** Fraca. A boundary fica formalmente limpa, mas o custo reaparece como fragmentacao de sessao, inconsistencias de UX e adaptadores repetidos. -### Option B - Studio possui sessao generica de documentos; frontends possuem semantica -- **Approach:** O Studio passa a possuir uma camada generica de editor para descoberta de arquivos, open/save, dirty tracking, tabs, estado ativo, deteccao de mudanca externa e snapshots imutaveis de documento em memoria; frontends consomem essa camada como entrada para highlighting, parsing, diagnosticos e outras features atuais ou futuras. +### Option B - Studio possui sessao generica de documentos; semantica vem depois por integracao +- **Approach:** O Studio passa a possuir uma camada generica de editor para descoberta de arquivos, leitura, tabs, estado ativo, refresh manual, snapshot estrutural da arvore e gerenciamento dos documentos abertos em memoria em modo read-only; provedores semanticos futuros, incluindo LSP, consomem essa base depois por uma seam explicita. - **Pro:** Cria uma base robusta para varios frontends mesmo sem LSP, evita duplicacao de infra generica e mantem a semantica de linguagem fora do workspace visual. -- **Con:** Exige disciplina para nao confundir `snapshot documental` com `snapshot semantico` do compiler e para nao deixar a camada generica vazar regras de linguagem. +- **Con:** Exige disciplina para nao confundir `snapshot documental` com resultado semantico e para nao deixar a camada generica vazar regras de linguagem ou hardcodes anti-LSP. - **Maintainability:** Forte. A separacao entre sessao de edicao e semantica de linguagem fica clara e expansivel. ### Option C - Cada frontend possui seu proprio stack de editor end-to-end @@ -108,8 +117,6 @@ No editor de codigo, porem, existe uma camada anterior a qualquer semantica de l - abrir arquivo; - manter buffer em memoria; -- controlar dirty state; -- salvar em disco; - alternar tabs; - versionar snapshots documentais; - reagir a mudancas externas; @@ -124,41 +131,92 @@ Do ponto de vista de UX, a direcao mais solida e assumir um baseline de tres reg 2. `Editor Workarea` no centro, com tabs acima e editor no corpo 3. `Editor Helper Panel` na base, para tips, prompts, hints e feedback contextual -Esse painel inferior merece cuidado de nomenclatura e ownership. -Ele nao deve nascer como "console generico" nem como dumping ground de logs tecnicos. -Melhor trata-lo como uma superficie editorial guiada pelo contexto do documento ativo. +Dentro da coluna esquerda, o layout ja deve nascer preparado para a composicao futura: -Sugestao de papel para esse helper: +1. `Project Navigator` funcional no topo; +2. regiao de `Outline` reservada abaixo; +3. `Outline` ainda sem comportamento real, sem arvore fake e sem semantica local nesta wave. -- mostrar hints sobre arquivo, linguagem e estado do documento; -- receber mensagens de parse/local validation quando existirem; -- explicar bloqueios de save, conflitos de disco e prompts do editor; -- no futuro, acomodar saidas de LSP ou FE sem acoplar a shell global a isso. - -Em outras palavras: ele deve ser um `assistant/log` de workspace, nao um substituto do painel global `Activity` e nao um terminal cru. +Esse painel inferior ainda nao precisa nascer com funcao real. +Nesta wave ele existe apenas para demarcar o espaco futuro da composicao, como placeholder passivo. O boundary mais saudavel parece ser: 1. o Studio possui a sessao generica de documentos e a UX editorial comum; -2. os frontends recebem snapshots documentais imutaveis como entrada; +2. essa sessao cobre organizacao de componentes, buffers abertos em memoria, tabs, refresh/reload e o minimo necessario para gerenciamento editorial read-only dos arquivos; 3. parsing, name resolution, diagnostics, semantic tokens, completions e afins continuam fora da camada generica do editor; -4. LSP, quando existir, entra como um consumidor/provedor de semantica sobre essa base, nao como substituto da base. +4. LSP, quando existir, entra como um provedor de semantica sobre essa base, nao como substituto da base e nao como dependencia obrigatoria desta wave. -O estado atual do compiler reforca essa necessidade. -Hoje o build pipeline ainda assume filesystem como source of truth imediata: - -- os arquivos sao descobertos por crawl direto nos `sourceRoots`; -- o `BuilderPipelineContext` nasce com `SourceProviderFactory.filesystem()`; -- cada `SourceHandle` le bytes do `Path` canonico. - -Isso significa que, se quisermos uniformizar Studio, FE services e LSP futuro em torno de uma mesma visao documental, precisamos introduzir explicitamente uma camada de `document snapshot` antes do consumo pelo pipeline. -O lado bom e que ja existe um seam util: `SourceProviderFactory` nao esta hardcoded em todos os callsites e ja sugere providers alternativos, inclusive `in-memory`. +O estado atual do compiler ajuda a nao exagerar o escopo desta agenda. +`DSC-0011` fechou o pipeline canonico e os entrypoints publicos do compiler. +Isso e suficiente, por enquanto, para esta agenda assumir apenas que o editor nao deve bloquear integracoes semanticas futuras. +Esta discussion nao precisa decidir agora o contrato final entre `document snapshots` e `analyze`, nem substituir LSP por uma semantica local improvisada no Studio. Isso tambem ajuda com a meta de varios FEs: - `FrontendSpec` ja informa roots e extensoes; - o `EditorWorkspace` pode montar a superficie a partir disso; -- e cada linguagem fica livre para plugar servicos sem destruir o modelo editorial comum. +- e cada linguagem ou integracao futura fica livre para plugar semantica sem destruir o modelo editorial comum. + +Com isso, o foco desta agenda fica mais limpo: + +1. composicao visual do workspace editor; +2. gerenciamento de arquivos abertos em memoria; +3. modelo de tabs e documento ativo; +4. refresh em modo read-only; +5. `Project Navigator` completo sobre o projeto com tagging de source roots relevantes; +6. `status bar` passivo com informacoes editoriais basicas; +7. reserva de seams para providers semanticos futuros, sem acoplamento prematuro. + +Tabs precisam nascer de forma pragmatica nesta wave. +O objetivo nao e fechar ainda persistencia de sessao, drag-and-drop, pinning, grupos, split view ou navegacao avancada. +O que fica fechado e o baseline visual e operacional: + +1. arquivos ainda nao abertos entram em nova tab; +2. a faixa de tabs deve ser responsiva e mostrar quantas tabs couberem na largura disponivel; +3. tabs adicionais devem ficar acessiveis por um controle de overflow estilo IntelliJ; +4. a tab ativa deve permanecer visivel; +5. o rotulo da tab usa apenas o nome do arquivo com extensao; +6. comportamento mais rico pode ser adicionado depois sem mudar o contrato visual inicial. + +O `Project Navigator` tambem fica mais claro: + +1. ele nao deve limitar a edicao apenas aos arquivos fonte tagged; +2. ele deve mostrar todos os arquivos e diretorios do projeto; +3. `prometeu.json` e o frontend selecionado servem para destacar roots relevantes, nao para esconder o restante do projeto. +4. ele deve manter um snapshot estrutural em memoria da arvore do projeto para navegacao e estado visual; +5. esse snapshot estrutural nao substitui o filesystem como source of truth; +6. snapshots de conteudo continuam restritos aos arquivos abertos no editor; +7. a arvore faz um refresh inicial ao abrir o projeto e permite refresh manual a qualquer momento por um botao proprio; +8. arquivos ocultos entram por padrao; +9. arquivos nao-textuais ou nao suportados podem aparecer no navigator, mas devem abrir um modal simples avisando que o arquivo nao e suportado nesta wave. + +A regiao de `Outline` deve entrar apenas como reserva estrutural. +Ela ajuda a estabilizar a composicao da coluna esquerda agora, sem puxar semantica prematura para dentro desta agenda. +Se houver texto placeholder, ele deve ser discreto e claramente nao funcional. + +O `status bar` entra como componente editorial passivo nesta primeira wave. +Na esquerda ele mostra o breadcrumb do arquivo ativo, por exemplo `proj > src > file.pbs`. +Na direita ele mostra: + +1. posicao atual em `L:C`; +2. line separator; +3. modo de tabs/espacos, por exemplo `Spaces: 2` ou `Spaces: 4`; +4. extensao ou linguagem do arquivo ativo; +5. um cadeado de `read-only` apenas visual, reservado para funcionalidade futura do editor, sem efeito nesta wave. + +Como a primeira wave e read-only, ela nao fecha agora dirty tracking, save ou merge entre buffer local e disco. +O comportamento minimo fica reduzido a: + +1. abrir arquivos em memoria para leitura; +2. atualizar a visao a partir de refresh manual e refresh inicial; +3. deixar escrita, dirty state e resolucao de conflitos para wave posterior. + +Tambem nao vale persistir estado de sessao agora. +Expansao da arvore, tabs abertas e qualquer outro estado visual vivem apenas na sessao atual; persistencia entre execucoes fica para depois. + +Nao vale a pena transformar esta agenda em contrato detalhado de eventos agora. +Se algum evento precisar aparecer durante implementacao, ele deve entrar apenas como comentario/local detail e nao como fechamento normativo desta discussion. ## Resolution @@ -167,12 +225,22 @@ Recommended direction: seguir com **Option B**. A agenda deve convergir para uma decisao com os seguintes fechamentos: 1. o Studio deve possuir uma camada generica de `document/session` para o Code Editor; -2. essa camada pode ler e escrever arquivos fonte e manter snapshots documentais em memoria; -3. essa camada nao deve possuir semantica de linguagem, parsing autoritativo ou diagnosticos como responsabilidade primaria; -4. frontends devem consumir snapshots documentais do editor por um contrato explicito, imutavel e versionado; -5. como o compiler hoje ainda le do filesystem, a decisao precisa fechar uma etapa/seam concreta para injetar `document snapshots` antes do pipeline, uniformizando a entrada de Studio, FE services e LSP futuro; -6. LSP fica explicitamente fora do primeiro wave, mas a modelagem precisa deixar caminho limpo para ele; -7. a primeira wave do editor deve normatizar explicitamente o baseline visual do workspace: `Project Navigator` na esquerda, tabs no topo da area central, editor rico no corpo e `Editor Helper Panel` inferior reservado; -8. o `Editor Helper Panel` nasce passivo na primeira wave, como espaco reservado para prompts, tips e feedback contextual, sem obrigar interatividade imediata. +2. essa camada deve operar em modo read-only nesta primeira wave, podendo abrir arquivos fonte e manter snapshots documentais em memoria apenas para leitura; +3. essa camada deve ser responsavel por organizacao de componentes, tabs, buffers abertos, refresh/reload e snapshot estrutural do projeto, sem dirty tracking, save ou merge local nesta wave; +4. essa camada nao deve possuir semantica de linguagem, parsing autoritativo, diagnosticos ou ownership de comportamento tipico de LSP; +5. a primeira wave deve reservar um seam explicito para provedores semanticos futuros, incluindo LSP, sem torna-los dependencia imediata e sem endurecer o editor contra eles; +6. a primeira wave do editor deve normatizar explicitamente o baseline visual do workspace: `Project Navigator` na esquerda, tabs no topo da area central, editor rico no corpo, `Editor Helper Panel` inferior reservado e `status bar` passivo; +7. a coluna esquerda deve reservar uma regiao de `Outline` abaixo do `Project Navigator`, mas sem comportamento funcional nesta wave; +8. o `Project Navigator` deve mostrar todos os arquivos e diretorios do projeto, incluindo arquivos ocultos por padrao, ordenando pastas antes de arquivos em ordem alfabetica e usando `prometeu.json` apenas para taggear corretamente roots/fontes relevantes ao frontend selecionado; +9. o `Project Navigator` deve manter um snapshot estrutural em memoria da arvore do projeto para navegacao e estado visual, sem substituir o filesystem como source of truth; +10. a arvore do projeto deve fazer refresh inicial ao abrir o projeto e permitir refresh manual a qualquer momento por um botao proprio no `Project Navigator`; +11. snapshots de conteudo em memoria ficam restritos aos arquivos abertos no editor; +12. arquivos nao-textuais ou nao suportados podem aparecer no navigator, mas devem abrir um modal simples avisando que o arquivo nao e suportado nesta wave; +13. a primeira wave de tabs deve abrir todo arquivo novo em nova tab, usar uma faixa responsiva com overflow no estilo IntelliJ, manter a tab ativa visivel e usar apenas o nome do arquivo com extensao como rotulo da tab; +14. o `status bar` deve mostrar breadcrumb do arquivo ativo na esquerda e, na direita, `L:C`, line separator, modo de tabs/espacos, extensao/linguagem e um cadeado visual de `read-only` sem efeito funcional ainda; `L:C` pode nascer como placeholder visual nesta wave; +15. o `Editor Helper Panel` nasce passivo na primeira wave apenas para demarcar espaco, sem funcao real ainda; +16. expansao da arvore, tabs abertas e demais estados visuais vivem apenas na sessao atual; persistencia entre execucoes fica para depois; +17. ficam explicitamente fora desta wave escrita, save, dirty tracking, merge de conflitos, autocomplete, go to definition, semantic diagnostics ao digitar, symbols, rename, code actions e qualquer decisao detalhada de integracao com LSP; +18. esta agenda nao fecha agora um contrato normativo de eventos editoriais; qualquer necessidade imediata pode aparecer apenas como detalhe de implementacao ou comentario. -Next step suggestion: converter esta agenda em uma `decision` que feche o boundary entre `EditorWorkspace`, sessao documental do Studio e servicos de frontend, incluindo o escopo exato da primeira wave de UI sem LSP. +Next step suggestion: converter esta agenda em uma `decision` que feche o escopo da primeira wave read-only do `EditorWorkspace`, incluindo composicao visual, tabs, `Project Navigator`, `status bar`, snapshot estrutural da arvore, buffers abertos em memoria e o que fica explicitamente fora da wave por ausencia de escrita/semantica/LSP. diff --git a/discussion/workflow/decisions/DEC-0008-studio-code-editor-read-only-workspace-foundations.md b/discussion/workflow/decisions/DEC-0008-studio-code-editor-read-only-workspace-foundations.md new file mode 100644 index 00000000..8279e118 --- /dev/null +++ b/discussion/workflow/decisions/DEC-0008-studio-code-editor-read-only-workspace-foundations.md @@ -0,0 +1,216 @@ +--- +id: DEC-0008 +ticket: studio-code-editor-workspace-foundations +title: Read-only foundations for the Studio Code Editor workspace +status: accepted +created: 2026-03-30 +accepted: 2026-03-30 +agenda: AGD-0010 +plans: + - PLN-0012 + - PLN-0013 + - PLN-0014 +tags: + - studio + - editor + - workspace + - read-only + - lsp-deferred +--- + +## Context + +The Studio shell already treats `Code Editor` as part of the baseline workspace set, but the current `EditorWorkspace` is still only a hardcoded text area. + +AGD-0010 closed the scope of the first editor wave around structural workspace foundations only. +This decision does not close language semantics, compiler integration details, or LSP behavior. +Its job is to define the first stable Studio-owned editor shell that can host real project navigation and file opening without prematurely absorbing semantic ownership. + +This decision depends on the current Studio shell and UI foundations: + +1. `docs/specs/studio/1. Studio Shell and Workspace Layout Specification.md` +2. `docs/specs/studio/2. Studio UI Foundations Specification.md` + +It is also compatible with DEC-0007/DSC-0011, which keeps compiler semantics behind explicit entrypoints and therefore does not force this editor wave to own semantic behavior now. + +## Decision + +The `studio` domain SHALL implement the first `Code Editor` workspace wave as a read-only editorial foundation. + +This wave SHALL establish: + +1. the baseline visual composition of the editor workspace, +2. project-tree navigation over the full project, +3. opening project files into responsive tabs, +4. in-memory buffers for opened files in read-only mode, +5. passive placeholder regions for future `Outline` and helper surfaces, +6. a passive status bar with baseline editor metadata, +7. and a future-safe seam for semantic providers such as LSP without making them a dependency of this wave. + +This wave SHALL NOT implement: + +1. file saving or other write behavior, +2. dirty tracking, +3. local merge/conflict resolution, +4. semantic diagnostics, autocomplete, go-to-definition, symbols, rename, code actions, or other LSP-like features, +5. an active `Outline`, +6. a functional helper panel, +7. or persistence of editor session state across Studio executions. + +## Rationale + +The correct ownership boundary for this wave is editorial, not semantic. +Studio should own the common workspace composition, project navigation, tabs, and passive file presentation layer. +It should not, in this wave, become the authority for parsing, diagnostics, or language behavior. + +This decision also intentionally keeps the first implementation smaller and more stable: + +1. read-only mode avoids premature decisions about saving, dirty state, and merge behavior, +2. structural placeholders avoid future layout churn when `Outline`, helper features, and semantic integrations arrive, +3. and a full-project navigator avoids hiding relevant project files behind frontend-only views while still allowing frontend-aware tagging from `prometeu.json`. + +## Technical Specification + +### 1. Workspace Layout + +The `Code Editor` workspace MUST expose the following baseline layout: + +1. a left column, +2. a central editor work area, +3. a bottom helper region, +4. and a bottom status bar. + +The left column MUST be a vertical stack containing: + +1. a functional `Project Navigator` at the top, +2. and a reserved `Outline` region below it. + +The `Outline` region MUST exist structurally in this wave, but MUST NOT provide real outline behavior yet. +It MAY show a discreet placeholder state, but it MUST NOT fake semantic structure. + +The bottom helper region MUST exist structurally in this wave, but MUST remain passive. +It exists only to stabilize layout and reserve space for future contextual/editor-owned assistance. + +### 2. Project Navigator + +The `Project Navigator` MUST: + +1. show all files and directories in the project, +2. include hidden files by default, +3. order folders before files, +4. order items alphabetically within those groups, +5. and use `prometeu.json` plus the selected frontend only to tag relevant source roots or source directories. + +The `Project Navigator` MUST NOT hide non-source project files simply because they are not part of the selected frontend roots. + +The `Project 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. + +Refresh rules for this wave are: + +1. the tree MUST perform one initial refresh when the project opens, +2. the tree MUST allow manual refresh at any time, +3. the manual refresh control MUST be exposed directly on the `Project Navigator`, +4. and filesystem watching MUST NOT be baseline behavior in this wave. + +### 3. File Opening and Tabs + +The workspace MUST allow project files to be opened into editor tabs. + +Tab rules are: + +1. selecting a file that is not already open MUST open it in a new tab, +2. the tab strip MUST be responsive, +3. the visible tab count MUST be driven by available width rather than a fixed numeric limit, +4. overflow tabs MUST remain reachable through an IntelliJ-style overflow control, +5. the active tab MUST remain visible, +6. and the tab label MUST use only the file name with extension. + +This wave MUST NOT define pinning, drag-and-drop tab reordering, grouped tabs, split editors, or session-persistent tab restoration. + +### 4. Read-only File Model + +This wave MUST operate in read-only mode. + +Opened files MAY be loaded into in-memory buffers for display and navigation, but those buffers MUST remain read-only in this wave. + +Consequences: + +1. the editor MUST NOT write files, +2. the editor MUST NOT provide save behavior, +3. the editor MUST NOT define dirty tracking, +4. and the editor MUST NOT define local merge behavior against disk changes. + +Unsupported or non-text files MAY still appear in the `Project Navigator`, but attempting to open them MUST show a simple modal stating that the file is not supported in this wave. + +### 5. Status Bar + +The workspace MUST include a passive status bar. + +Its left side MUST show the breadcrumb path of the active file, such as `proj > src > file.pbs`. + +Its right side MUST show: + +1. `L:C`, +2. line separator, +3. tabs/spaces mode, +4. file extension or language, +5. and a read-only lock icon. + +For this wave: + +1. `L:C` MAY remain a visual placeholder, +2. and the lock icon MUST be visual only, with no functional enforcement beyond signaling read-only intent. + +### 6. Placeholder Surfaces + +The `Outline` region and the helper region MUST remain passive in this wave. + +Rules: + +1. they exist to stabilize composition and reserve future workspace surfaces, +2. they MUST NOT claim semantic capabilities they do not yet have, +3. and they MUST NOT become dumping grounds for global shell logging. + +### 7. Session State + +Any visual/editorial state in this wave is session-local only. + +This includes at minimum: + +1. open tabs, +2. active tab selection, +3. tree expansion state, +4. and similar visual workspace state. + +This decision MUST NOT require persistence of that state across Studio executions. + +### 8. Deferred Scope + +The following are explicitly deferred and MUST NOT be treated as part of this wave: + +1. write/save behavior, +2. dirty state, +3. merge/conflict resolution, +4. watcher-driven automatic filesystem synchronization, +5. semantic analysis surfaces, +6. LSP integration details, +7. autocomplete, go-to-definition, symbols, rename, code actions, and semantic diagnostics while typing, +8. active outline behavior, +9. helper panel functionality, +10. and a normative editor event contract. + +If implementation needs local events internally, they MAY exist as implementation detail, but they MUST NOT be treated as the normative output of this decision. + +## Constraints + +1. This decision is Studio-owned and applies to the `studio` domain, not to compiler semantic ownership. +2. This decision MUST remain compatible with future semantic providers, including LSP. +3. This decision MUST NOT infer or hardcode a semantic provider contract prematurely. +4. This decision MUST preserve compatibility with existing Studio shell and UI foundations specs. +5. Any future move from read-only mode to editable mode MUST occur through a new explicit decision or an explicit revision of this decision. + +## Revision Log + +- 2026-03-30: Initial draft from AGD-0010. +- 2026-03-30: Accepted and decomposed into PLN-0012, PLN-0013, and PLN-0014. 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 new file mode 100644 index 00000000..59aa5008 --- /dev/null +++ b/discussion/workflow/plans/PLN-0012-studio-code-editor-spec-propagation.md @@ -0,0 +1,130 @@ +--- +id: PLN-0012 +ticket: studio-code-editor-workspace-foundations +title: Propagate DEC-0008 into Studio shell and workspace specs +status: open +created: 2026-03-30 +completed: +tags: + - studio + - editor + - specs + - read-only +--- + +## Objective + +Propagate DEC-0008 into the normative Studio spec surface so the read-only first wave of the `Code Editor` workspace is explicit before or alongside implementation. + +## Background + +DEC-0008 locks the first `Code Editor` wave as a read-only editorial foundation with: + +- `Project Navigator` over the full project, +- reserved `Outline` region, +- responsive tab strip with overflow, +- read-only file opening, +- passive helper region, +- passive status bar, +- manual refresh only, +- and explicit deferral of save/dirty/LSP/semantic behavior. + +The current Studio spec corpus defines shell-level workspace presence and shared UI foundations, but it does not yet define the concrete contract of the `Code Editor` workspace itself. + +## Scope + +### Included +- Add a dedicated `Code Editor` workspace specification to the Studio spec corpus. +- Update Studio spec navigation so the new chapter is discoverable. +- Align shell/foundations references so DEC-0008 terminology is consistent with existing Studio norms. + +### Excluded +- Java implementation changes in `prometeu-studio`. +- LSP or semantic-provider contract design. +- Editable-mode design, save behavior, or conflict-resolution policy. + +## Execution Steps + +### Step 1 - Add a dedicated Code Editor workspace specification + +**What:** +Create a new Studio spec chapter that normatively defines the read-only `Code Editor` workspace baseline from DEC-0008. + +**How:** +Add a new chapter under `docs/specs/studio/` covering: +1. workspace layout, +2. `Project Navigator` ownership and full-project visibility, +3. reserved `Outline` region, +4. responsive tabs with overflow, +5. read-only file opening, +6. unsupported-file modal behavior, +7. passive helper region, +8. passive status bar fields, +9. manual refresh, +10. and deferred scope for save/LSP/semantic features. + +**File(s):** +- `docs/specs/studio/5. Code Editor Workspace Specification.md` + +### Step 2 - Update Studio spec navigation and cross-references + +**What:** +Make the new spec reachable from the Studio spec index and aligned with the current corpus order. + +**How:** +Update the Studio README reading order and current-corpus list to include the new chapter. +Add or adjust cross-references where shell/foundations specs should point to workspace-local ownership rather than implying global responsibility. + +**File(s):** +- `docs/specs/studio/README.md` +- `docs/specs/studio/1. Studio Shell and Workspace Layout Specification.md` +- `docs/specs/studio/2. Studio UI Foundations Specification.md` + +### Step 3 - Align terminology and deferred-scope language + +**What:** +Ensure the spec corpus consistently uses DEC-0008 language for the first editor wave. + +**How:** +Normalize references to: +1. read-only first wave, +2. passive helper and `Outline` placeholder, +3. manual refresh, +4. and explicit deferral of semantic/LSP features and save/write behavior. + +**File(s):** +- `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` + +## Test Requirements + +### Unit Tests + +- No Java unit tests are required for this editorial plan. + +### Integration Tests + +- No runtime integration tests are required for this editorial plan. + +### Manual Verification + +- Verify the new spec chapter is listed in `docs/specs/studio/README.md`. +- Verify the new chapter matches DEC-0008 exactly on read-only scope, manual refresh, and deferred LSP/save behavior. +- Verify shell/foundations wording does not contradict workspace-local ownership defined by the new chapter. + +## Acceptance Criteria + +- [ ] The Studio spec corpus contains a dedicated `Code Editor` workspace specification. +- [ ] The spec explicitly states that the first wave is read-only and excludes save/dirty/LSP/semantic behavior. +- [ ] The spec defines the baseline layout: navigator, reserved outline region, responsive tabs, editor body, passive helper, passive status bar. +- [ ] Studio spec navigation and cross-references are updated to make the new chapter discoverable and consistent. + +## Dependencies + +- DEC-0008 accepted content. + +## Risks + +- A too-light writeup could leave implementation inventing behavior that DEC-0008 already closed. +- Over-editing shell/foundations docs could blur shell-owned versus workspace-owned responsibilities. diff --git a/discussion/workflow/plans/PLN-0013-editor-workspace-layout-and-passive-surfaces.md b/discussion/workflow/plans/PLN-0013-editor-workspace-layout-and-passive-surfaces.md new file mode 100644 index 00000000..f9a7bd89 --- /dev/null +++ b/discussion/workflow/plans/PLN-0013-editor-workspace-layout-and-passive-surfaces.md @@ -0,0 +1,123 @@ +--- +id: PLN-0013 +ticket: studio-code-editor-workspace-foundations +title: Implement the read-only Code Editor workspace shell and passive surfaces +status: open +created: 2026-03-30 +completed: +tags: + - studio + - editor + - implementation + - layout + - ui +--- + +## Objective + +Replace the current hardcoded `EditorWorkspace` with the DEC-0008 read-only workspace shell: left navigator column with reserved `Outline` region, central tab/editor area, passive helper region, and passive status bar. + +## Background + +The current `EditorWorkspace` is only a `CodeArea` mounted under a toolbar. +DEC-0008 requires a stable read-only composition that reserves future surfaces without implementing semantic or writable behavior yet. + +## Scope + +### Included +- Recompose `EditorWorkspace` into the DEC-0008 structural layout. +- Introduce passive placeholder surfaces for `Outline`, helper, and status bar. +- Replace write-oriented/editorially misleading controls with a first-wave read-only shell. +- Keep the central editor body ready to host read-only opened file content. + +### Excluded +- Project-tree scanning and refresh logic. +- Actual file opening/session state orchestration beyond the minimum shell integration points. +- Save, dirty tracking, write controls, or semantic/LSP behavior. + +## Execution Steps + +### Step 1 - Replace the current EditorWorkspace composition root + +**What:** +Turn `EditorWorkspace` into a composition root that mounts the DEC-0008 layout instead of a single hardcoded `CodeArea`. + +**How:** +Refactor the current border-pane structure into explicit regions: +1. left column for navigator + reserved outline region, +2. central work area for tab strip + read-only editor body, +3. bottom helper placeholder, +4. bottom status bar. +Prefer dedicated controls/panels over one large monolithic workspace class. + +**File(s):** +- `prometeu-studio/src/main/java/p/studio/workspaces/editor/EditorWorkspace.java` +- `prometeu-studio/src/main/java/p/studio/workspaces/editor/` + +### Step 2 - Introduce passive placeholder controls + +**What:** +Add concrete passive UI surfaces for the reserved regions required by DEC-0008. + +**How:** +Create lightweight controls/panels for: +1. reserved `Outline` region, +2. passive helper region, +3. passive status bar, +4. and the tab-strip shell. +These controls should be visually real, but functionally passive where DEC-0008 says behavior is deferred. + +**File(s):** +- `prometeu-studio/src/main/java/p/studio/workspaces/editor/` + +### Step 3 - Align editor chrome with read-only first-wave scope + +**What:** +Remove or neutralize UI affordances that imply writable/editor-semantic behavior not present in this wave. + +**How:** +Review the current toolbar and shell-level controls so the first-wave editor does not imply: +1. save, +2. run/build from inside the editor, +3. active outline, +4. or helper-driven functionality that does not exist yet. +If a control must remain for layout reasons, make it visually passive and consistent with DEC-0008. + +**File(s):** +- `prometeu-studio/src/main/java/p/studio/workspaces/editor/EditorToolbar.java` +- `prometeu-studio/src/main/java/p/studio/workspaces/editor/` + +## Test Requirements + +### Unit Tests + +- Add focused tests for any pure layout/session-state model extracted from the workspace shell composition. +- If dedicated status/tab placeholder models are introduced, cover their default state with unit tests. + +### Integration Tests + +- No JavaFX full integration harness is required as a prerequisite for this plan. + +### Manual Verification + +- Verify the workspace visually matches DEC-0008 layout. +- Verify the left column contains navigator + reserved outline region. +- Verify the helper and status bar are present but passive. +- Verify no visible control implies save/write behavior in the first wave. + +## Acceptance Criteria + +- [ ] `EditorWorkspace` is no longer a single hardcoded `CodeArea` view. +- [ ] The workspace visibly contains navigator, reserved outline region, central tab/editor area, helper placeholder, and status bar. +- [ ] The first-wave shell is visually coherent with DEC-0008 read-only scope. +- [ ] Placeholder surfaces are present without implying semantic or writable functionality. + +## Dependencies + +- DEC-0008 accepted. +- PLN-0012 should land first or in parallel if the wording is stable. + +## Risks + +- If the composition stays monolithic, later navigator/session work will be harder to integrate cleanly. +- Leaving write-oriented controls visible would immediately contradict DEC-0008 and confuse later implementation waves. diff --git a/discussion/workflow/plans/PLN-0014-project-navigator-snapshot-and-read-only-file-opening.md b/discussion/workflow/plans/PLN-0014-project-navigator-snapshot-and-read-only-file-opening.md new file mode 100644 index 00000000..413d2a2f --- /dev/null +++ b/discussion/workflow/plans/PLN-0014-project-navigator-snapshot-and-read-only-file-opening.md @@ -0,0 +1,148 @@ +--- +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.