migration shell screen

Migration — the shell boots from its own screen

Who this affects: anything that keyed shell behaviour on the admin screen the shell happened to be painted over — $pagenow === 'index.php', get_current_screen()->id === 'dashboard', a load-index.php hook, or a script enqueued "on the Dashboard" that only reached the desktop because the desktop was the Dashboard. Also anything that built a desktop URL by hand as wp-admin/index.php?desktop_mode_portal=1.

What to do: gate on openstation_is_shell_request() instead of a screen id, and build desktop URLs with openstation_shell_url() (or openstation_portal_url()). Nothing else changes: every openstation_register_* call, the payload shape, wp.os.*, the events and openStationConfig are untouched.

What changed

The desktop shell used to be injected on top of whichever admin screen the /openstation/ portal forwarded to: the Dashboard by default, the last-focused window's URL otherwise, edit.php or post.php if that is where the user had been. The shell document therefore inherited that screen's whole script and style queue, its server-side render, and its hidden HTML — and then loaded the same screen again inside a window.

On a site running the Gutenberg plugin the cost was the whole editor closure: Gutenberg's experimental Dashboard page enqueues its loader on index.php, the loader depends on wp-editor, and since the shell document was index.php, 162 requests / 20 MB raw printed, parsed and executed in the shell's realm where nothing ever rendered them.

The shell now boots from a screen OpenStation owns:

admin.php?page=openstation[&target=<admin path>][&intent=1]

It is registered under an empty parent, so it appears in no menu, and its capability is read — the same floor the portal applies. Its screen id is admin_page_openstation; $hook_suffix on admin_enqueue_scripts is the same string.

is_admin() is true there and admin_menu / admin_enqueue_scripts fire exactly as before, which is why it is an admin page rather than a standalone document: those hooks are the contract behind every openstation_register_* call and every plugin that gates registration on is_admin() at load time.

Routing

Request	Before	Now
/openstation/	302 → index.php?desktop_mode_portal=1 (or the focused window's URL)	302 → admin.php?page=openstation; the screen resolves the entry itself
/openstation/?target=/wp-admin/edit.php	302 → edit.php?desktop_mode_portal=1&desktop_mode_portal_intent=1	302 → admin.php?page=openstation&target=%2Fwp-admin%2Fedit.php&intent=1
/wp-admin/edit.php (plain GET, user enabled)	rendered in place with the shell over it	302 → the shell screen with target=/wp-admin/edit.php&intent=1 (one hop)
/wp-admin/network/sites.php (not allowlisted)	302 → /openstation/?target=… → focused window	unchanged, ending on the shell screen
index.php?desktop_mode_portal=1 (old bookmark, PWA start URL)	rendered in place	302 → the shell screen with that URL as target

desktop_mode_portal and desktop_mode_portal_intent stay frozen (see AGENTS.md). They are aliases now: a URL carrying them is the desktop's pre-screen address and redirects to the screen. Nothing that emits them breaks; nothing new should emit them.

currentPage, fromPortal and fromPortalIntent in openStationConfig keep their meaning. currentPage is the validated target (else the session's focused window, the default window, the Dashboard); fromPortal is true on the screen by construction; fromPortalIntent is the intent arg. The auto-open matrix in src/boot/auto-open.ts is unchanged.

The symptoms

A script that only reached the desktop because the desktop was the Dashboard. Something enqueued when $hook_suffix === 'index.php', or inside load-index.php, or behind get_current_screen()->id === 'dashboard', used to print in the shell document. It now prints in the Dashboard window and nowhere else — which is where it was always meant to run. If it genuinely needs to run in the shell's own realm (it publishes a window.openStation* global the shell reads, say), enqueue it when openstation_is_shell_request() is true.

A hand-built desktop URL. admin_url( 'index.php?desktop_mode_portal=1' ) still works through the alias, at the cost of one redirect. Build the URL with openstation_shell_url() (bare, or with a target and an intent flag) or link to openstation_portal_url().

openstation_admin_redirect_to_portal returning false. That filter used to keep the shell on the page the user asked for; it now keeps the user on a classic page, because the shell has no way to render there any more. With the redirect disabled the desktop lives at /openstation/ and its screen only. The frozen-flag alias still redirects: a URL naming the desktop is not a plain admin page.

$pagenow / get_current_screen() inside a shell-only hook. On a shell boot they now report admin.php and admin_page_openstation. Inside windows (chromeless requests) they report the window's page, as always.

Predicates

• openstation_is_shell_request() — true when this request paints the shell: the shell screen for a user with OpenStation enabled, or a solo boot (?openstation_solo=<id>, which renders in place). Never inside a window, never on a classic-flagged request. Every render hook that used to spell out "enabled, not chromeless, not classic" reads this now.
• openstation_is_shell_screen_request() — true on the shell screen regardless of whether the shell renders there (a disabled user, a window, a classic-flagged request can all address it).
• openstation_url_is_shell_screen( $url ) — whether a URL names the screen. The shell never opens itself: the portal sanitiser, the session entry resolver, the iframe URL builder, session restore, hover prewarming and the service worker's speculative documents all refuse it.

Trimming what still prints

With no host screen, the shell document carries OpenStation's own assets, Core's every-admin-page set, and whatever plugins enqueue on every admin page. The framework does not guess which of the last group belongs in the shell; the site says so:

add_filter( 'openstation_shell_dequeue_handles', function ( $handles, $kind ) {
    if ( 'script' === $kind ) {
        $handles[] = 'acme-upsell-nag';
    }
    return $handles;
}, 10, 2 );

A handle that a surviving script or style still depends on is refused with a _doing_it_wrong() rather than dropped. See hooks-reference.md.