> For the complete documentation index, see [llms.txt](https://faction-os.gitbook.io/faction-os-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://faction-os.gitbook.io/faction-os-docs/.spec_system/archive/phases/phase_21/session_04_shortcut_and_overlay_layering.md).

# Session 04: Shortcut And Overlay Layering

**Session ID**: `phase21-session04-shortcut-and-overlay-layering` **Package**: apps/web **Status**: Not Started **Estimated Tasks**: \~14-22 **Estimated Duration**: 2-4 hours

***

## Objective

Align keyboard shortcuts and nested overlay behavior with the new expansion contract.

***

## Scope

### In Scope (MVP)

* Repoint `o d` / `command_center_details_open` so the primary shortcut opens the expanded Command Center surface.
* Rename or demote any retained summary-details shortcut so it is clearly secondary.
* Add or apply a small overlay-layer convention for expanded surfaces, retained detail portals, `TerminalRuntimeDrawer`, and `OrchestrationDrawer`.
* Ensure Escape closes the topmost relevant layer first.
* Ensure backdrop clicks close the expanded surface while inner-panel clicks do not.
* Update shortcut and keyboard modal tests.

### Out of Scope

* New global shortcut systems.
* Backend command execution changes.
* Removing secondary inspectors unless required by product behavior.

***

## Prerequisites

* [ ] Session 03 completed.
* [ ] Existing shortcut metadata and command-center shortcut dispatch reviewed.
* [ ] Nested Orchestration drawers and retained detail portals identified.

***

## Deliverables

1. Shortcut metadata and runtime behavior for the expanded Command Center.
2. Predictable Escape and overlay-layer close behavior.
3. Tests for shortcut routing, keyboard modal copy, nested drawer Escape, and backdrop/inner click behavior.

***

## Folded Source Details

The source plan identified shortcut drift and nested overlay close behavior as part of the same synchronization problem. This session owns making keyboard entry and Escape recovery match the new primary focused-surface contract.

Implementation details to preserve:

* Update `apps/web/src/lib/commandCenterShortcuts.ts` and `apps/web/src/lib/useKeyboardShortcuts.ts`.
* Repoint `o d` / `command_center_details_open` so the primary shortcut opens the expanded Command Center surface, not the summary details popup.
* If the old Orchestration state summary remains, give it a secondary name such as `Open orchestration state summary` and avoid making it the main discoverable route.
* The shared expansion host should own Escape for expanded bottom surfaces.
* Escape should close only the topmost relevant layer. Nested drawers or modals such as `TerminalRuntimeDrawer`, `OrchestrationDrawer`, or retained details inspectors must close before the expanded bottom surface closes.
* Prefer a small shared overlay-layer convention, such as stable `data-overlay-layer` markers, over scattered one-off checks.
* Backdrop clicks close the expanded surface; clicks inside the panel must not close it.

End-to-end delivery bar for this session:

* The product outcome is that keyboard users can open the same full Command Center surface that pointer users open.
* Recovery paths must be deterministic: nested overlay first, parent focused surface second.
* Tests must cover shortcut metadata, runtime dispatch, keyboard modal copy, nested drawer Escape behavior, backdrop close, and inner-panel click containment.

***

## Success Criteria

* [ ] The primary Orchestration shortcut opens the expanded Command Center.
* [ ] Any retained details shortcut is named as a secondary state summary or equivalent.
* [ ] Escape closes nested drawers before the expanded bottom-rail surface.
* [ ] Backdrop clicks close the expanded surface and inner clicks do not.
* [ ] Shortcut tests and keyboard modal tests pass with the new labels.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://faction-os.gitbook.io/faction-os-docs/.spec_system/archive/phases/phase_21/session_04_shortcut_and_overlay_layering.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.