ADR 0002: Window Instance Routing

Status

Accepted and partially implemented.

Context

The shell has global routes for opening app surfaces:

• /app/:appId
• /app-user/:appId
• /app-shell/:appId target route for shell-coupled apps
• /app-admin/:appId
• /app-dev/:appId
• /app-iframe/:appId
• /app-os/:appId
• /website variants for website mode
• /website variants for single-app website mode
• /spaces/:spaceId for historical OS-level fullscreen runtime Spaces

WindowInstance now stores optional route state with appPath, search, and hash for app-owned paths. It also stores windowId, appId, title, icon, z-index, layout, restore layout, spaceId, and minimized / desktop-maximized / fullscreen-Space / pinned state.

Decision

When app-internal navigation is needed, it belongs to the window instance as per-window route state: WindowInstance.route.

The browser URL identifies the shell-level app surface and may carry one active app-owned path below manifest.routing.routeBase. The shell still does not register every internal app route. In OS mode, window state remains the per-window source for internal route restoration.

Why Multiple Windows Cannot Own The Browser URL

In OS mode, multiple windows can be open at the same time. If every app window wrote its internal state to the browser URL:

• windows would fight for one global address bar
• background windows could overwrite the focused route
• restoring/minimizing windows would become coupled to browser history
• multiple instances of the same app would be hard to represent

The browser URL should answer: "Which shell surface or website-mode app is active?" The window instance should answer: "Where is this particular app window internally?"

Boundary

Global route owns:

• route group
• app id
• OS mode vs website mode
• active fullscreen runtime Space route (/spaces/:spaceId)

/spaces/:spaceId is preserved as a current Shell runtime route for dedicated fullscreen sessions. It is not the canonical URL model for new Studio resources.

• direct open/deep link into one app surface

Window instance route should own:

• app-internal tab/page
• local selection or document route
• restore point for that specific window

Current Implementation

Implemented:

• manifest.routing.routeBase
• WindowInstance.route
• AppRuntimeContext.route
• Shell parsing that finds an app by routing.routeBase and passes the remaining appPath

Still planned:

• durable persistence of per-window app routes
• iframe postMessage navigation protocol
• app-local navigation helpers that can request an internal route change without exposing a concrete router

See ../apps/app-routing.md for the current routing contract.