prometeu-studio/discussion/lessons/DSC-0022-studio-play-stop-and-debugger-integration/LSN-0022-studio-play-stop-and-debugger-integration.md

id	ticket	title	status	created	tags
LSN-0022	studio-play-stop-cartridge-flow	Studio Play/Stop and Debugger Workspace Integration	done	2026-04-07	studio play-stop debugger runtime shipper

Summary

This lesson covers the implementation of the first wave of the Play/Stop flow in Studio and its integration with a native DebugWorkspace.

The feature enables developers to:

• Press Play to build, pack, and run the current project in the configured runtime.
• Automatically navigate to a DebugWorkspace that shows merged preparation and runtime logs.
• Press Stop to kill the active runtime process.

Key Decisions

Based on DEC-0020, DEC-0021, and DEC-0022:

1. Preparation Pipeline: The Play flow orchestrates existing domain operations: build -> validate pack -> pack -> manifest generation. All artifacts are kept in build/, avoiding a redundant cartridge/ directory for this wave.
2. Runtime Command: The runtime is executed externally as "<runtimePath>" run build with the project root as its working directory.
3. Process Ownership: Studio owns exactly one active runtime process handle per project shell.
4. Merged Logs: Preparation logs (build, pack validation, pack) and runtime logs (stdout/stderr) are merged into a single execution-session stream.
5. Native Debugger Workspace: A native DebugWorkspace hosts the execution session and acts as the primary log sink. It is not an external launcher but a real Studio workspace.
6. Shared Session State: The execution state (idle, preparing, connecting, running, etc.) lives outside the visual workspace lifecycle in a shared StudioExecutionSessionService.

Implementation Details

StudioPlayStopCoordinator

The main orchestrator for the Play and Stop actions. It:

• Manages the preparing -> connecting -> running state machine.
• Invokes the StudioShipperService for preparation.
• Spawns the external runtime process using StudioExternalRuntimeProcessLauncher.
• Merges log streams from both preparation and runtime into the StudioExecutionSessionService.

DebugWorkspace

A Studio Workspace implementation that reflects the StudioExecutionSnapshot. It uses DebugWorkspaceProjection to transform the session logs into a display-ready format.

StudioShipperService

Aggregates the domain-specific tasks (compiler build, packer pack) and generates the mandatory manifest.json in the build/ directory.

Common Pitfalls & Anti-Patterns

• Redundant Checks: Do not add manual manifest.json existence checks before spawning. The success of the preparation pipeline already guarantees its presence according to the contract.
• State Duplication: Avoid tracking execution state in both the shell and the workspace. The shared StudioExecutionSessionService is the single source of truth.
• Technical Linkage: Do not hard-link the Studio codebase with the legacy ../debugger repository. Selective migration of protocol/session logic is preferred.

References

• DEC-0020: Build and pack preparation.
• DEC-0021: External runtime execution.
• DEC-0022: Native DebugWorkspace integration.
• PLN-0045: End-to-end execution flow.