---
id: LSN-0022
ticket: studio-play-stop-cartridge-flow
title: Studio Play/Stop and Debugger Workspace Integration
status: done
created: 2026-04-07
tags: [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.