# SurfaceManager Window Runtime

Contract: `xtend.surface.window-runtime.v1`

`x-surface-manager` and `x-surface-window` form the owned Multi-Window Surface Runtime for XTend App Shells.

Gate:

```bash
node scripts/run_xtend_tests.js surface-manager --json
```

## Runtime Contract

The Window Runtime is the owned layer for free-positioned surfaces inside an XTend App Shell. `x-surface-manager` owns registration, active window state, stack order, focus handoff and snapshot data. `x-surface-window` provides the visible frame: title, region, slot content, state, resize signals and move signals. The two components belong together. A window without the manager loses orchestration, and a manager without window records cannot prove a usable multi-window app.

The `xtend.surface.window-runtime.v1` contract separates authoring from runtime. RMT describes that a surface exists, which resource it shows and which actions are allowed. The runtime decides how windows are registered, activated, minimized, restored or closed. This separation matters because RMT should not import DOM classes or XTend types. The host remains the owner of the concrete custom elements.

## Authoring Rules

A window record needs a stable id, a readable title, a surface type and state that fits into the manager snapshot. Actions such as `activate`, `close`, `focus` and `restore` are treated as events, not as direct DOM manipulation. When a host creates a window from RMT, it should validate the record first and then pass it to `x-surface-manager`. The manager can derive stack values, the active surface and the focus target from that record.

Windows should not be used as a general overlay solution. Modality, background inertness and Escape policy belong to the Stack Policy, not to individual windows. A window can own its internal focus path, but it does not decide alone whether the rest of the app becomes inert. That boundary prevents conflicts with `x-modal`, `x-dialog`, side panels and the Overlay Bridge.

## Evidence And Failure Modes

The `surface-manager` gate checks that window records are registered, activation is observable and snapshot data remains stable. Common failures are duplicate ids, a window without a title, a lost focus-restore target or an action that only affects the DOM and never reaches manager state. Those failures are release-relevant because multi-window apps become hard to reproduce without a reliable manager snapshot.

A change to `x-surface-window` is accepted when it strengthens the manager record and does not introduce a second registry. Manual HTML renderers, unnamespaced global helpers and framework-specific shortcuts are blocked. The Window Runtime remains a Native-First surface that RMT can describe but the XTend host executes.
