ADR 0002: Window Instance Routing

Status

Accepted as direction. Not fully implemented yet.

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-dev/:appId
• /app-iframe/:appId
• /app-os/:appId
• /website variants for website mode
• /website variants for single-app website mode
• /spaces/:spaceId for OS-level fullscreen Spaces

The current WindowInstance does not include appRoute. It 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 added, it should belong to the window instance as a per-window route, for example WindowInstance.appRoute.

The browser URL should identify the shell-level app surface and mode, not every internal route in every open window.

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 Space route (/spaces/:spaceId)
• 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 Gap

Planned / not implemented yet:

• WindowInstance.appRoute
• app route manifest fields
• app-local navigation API
• persistence of per-window app routes