Studio Engine Model

This file keeps its historical filename for existing doc links, but the model is now the Studio Engine Model.

The Studio Engine Model lets Prox OS describe how one App capability can appear across different Studio renderers without hardcoding every renderer inside the Shell. Prox OS moves from a single windowed desktop toward a Studio System where users create and enter Studios, while developers implement Studio Engines and Studio Surfaces.

Why It Exists

Desktop Runtime is the primary host because it gives users windows, folders, widgets, a dock, app lifecycle control, and runtime Scenes. It is not the platform itself, and it is not a normal Studio option. Other workflows need different Studio renderers: knowledge landscapes, dashboard grids, operator workspaces, and local-only development experiments for pages, webviews, device previews, CLI previews, admin workspaces, block documents, node-edge flows, freeform boards, IDE panes, and single-app workspaces.

The engine model keeps those renderers from becoming unrelated demos. An App can declare or receive support for:

• a window in Desktop Runtime;
• an Atlas card;
• an Ops Studio record, metric, or review panel;
• a Grid Studio widget;
• a local-only page in Site Studio;
• a local-only frame in Webview Studio;
• a local-only mobile screen in Device Studio;
• a local-only admin section in Admin Studio;
• a Block Studio app block;
• a Flow Studio node;
• a Board Studio card or thumbnail;
• an IDE panel;
• a local-only primary app surface.

Package Boundary

packages/contracts/studio-contract owns implementation-neutral Studio terms:

• StudioEngineId
• StudioSurface
• ProjectionSurface
• ProjectionContract
• maxNestedInteractiveDepth
• StudioContext
• StudioManifest
• shared Studio metadata

packages/runtime/studio-registry owns Studio Engine definitions and command provider composition. It can describe every Studio Engine, but it is not the Shell runtime. It should expose metadata, dev routes, supported surfaces, and command providers without owning Zustand state, browser routing, window instances, Alma state, or command palette UI.

packages/studio-engines/* owns extracted Studio Engine implementations when the engine has a real dependency or reuse boundary:

• @prox-os/block-studio-engine owns Block Studio and BlockNote.
• @prox-os/board-studio-engine owns Board Studio and Excalidraw.
• @prox-os/cli-studio-engine owns CLI Studio and safe xterm-based previews.
• @prox-os/flow-studio-engine owns Flow Studio and React Flow / xyflow.

These packages may import @prox-os/studio-contract, command types, browser UI primitives, and their engine dependency. They must not import apps/os-shell, Shell stores, or private window-manager modules.

packages/os-surface owns current shell-facing surface capabilities and placement helpers:

• WorkspaceLayoutMode
• SurfaceKind
• SurfaceCapability
• GridWidgetSize
• FlowNodeKind
• IdePanelRegion
• WorkspaceSurfaceManifest
• placement types and capability helpers
• v0 mock capability overrides for representative apps

None of the contract or shared surface packages imports apps/os-shell, owns Zustand state, or renders Shell UI. Shell runtime glue stays in apps/os-shell.

packages/contracts/app-contract exposes optional surfaceCapabilities?: SurfaceCapability[] on app manifests. The Shell can use that field directly, or use adapter overrides while existing manifests migrate.

Current Renderers

apps/os-shell hosts Studio Engine demo renderers. Some engines still live in the Shell, and the heavy engines now load from extracted packages:

apps/os-shell/src/surfaces/DesktopSurfaceRoot.tsx is the host adapter. It lazy-loads extracted engine components only for their Studio routes and passes host callbacks such as app opening and workspace context menus. Engine packages receive callbacks; they do not import Shell app ids or window-manager types.

Layout Mode vs App Type

Studio Engine mode is not the same thing as an app implementation type.

An App may be a local module, OS package app, iframe app, route app, or future isolated app. Separately, that App can advertise which surfaces it supports.

For example, the Weather app can appear as:

• a Desktop Runtime window;
• a Site Studio card on a public page;
• a Device Studio screen preview;
• a Grid Studio widget;
• a Block Studio weather block;
• a Board Studio card;
• a Flow Studio node;
• an Alma suggestion;
• a Cmd+K command.

Current v0 Adapter

The Shell uses apps/os-shell/src/surfaces/surfaceManifestAdapter.ts to convert the composed app registry into WorkspaceSurfaceManifest[]. It prefers manifest surfaceCapabilities when present and falls back to surfaceCapabilityOverridesByAppId from @prox-os/os-surface.

This lets the product prove the renderer model before editing every app manifest. Future migration should move app-specific declarations into app manifests or a projection registry.

Placement Model

The v0 package defines placement objects for Atlas, Block, Flow, Board, Grid, IDE, and App Studio surfaces. The current Shell does not persist these placements to a backend. Grid and IDE layout changes are local runtime state only.

Future persistence can store:

• user or team Studio engine selection;
• per-engine placement;
• installed App surface entries;
• app-specific widget settings;
• Studio-scoped or organization-scoped presets.

Projection Limit

Interactive nesting is capped by the Studio contract:

export const maxNestedInteractiveDepth = 1

Beyond that depth, an embedded App or Studio should render as a card or thumbnail and expose an Open as Studio action instead of recursively embedding more full interactive runtimes.

Studio Switching And Scenes

The old virtual desktop vocabulary is replaced by two layers:

• Studio switching is the Shell-level switch between open, recent, and pinned Studio resources.
• Scene switching is the current Studio's internal layout or work-state switch.

Desktop Runtime keeps windowed workspace behavior, but the user-facing model is still Scene. Other engines can expose their own Scenes without implementing a separate virtual desktop system.

Non-Goals

• No backend layout persistence in this slice.
• No browser extension or desktop client.
• No hardware OS or bootable image.
• No rewrite of the window manager.
• No complete recursive Studio-in-Studio runtime.
• No claim that all apps already provide production-ready widgets, blocks, nodes, cards, or panels.