@owlmeans/web-client 0.1.18-rc.32 → 0.1.18-rc.33

package/README.md

@@ -1,84 +1,285 @@
 # @owlmeans/web-client
 
-React web application bootstrap — context factory, entrypoint/routing utilities, and app renderer for OwlMeans web apps.
-
-## Overview
-
-- `makeContext(cfg)` — creates the web application context (includes auth, router, and DB services)
-- `renderApp(context)` — mounts the React app to the DOM
-- Re-exports entrypoint/routing helpers: `bind`, `bindAll`, `bindScreen`, `route`, `frontend`, `handler`
-- Re-exports route constants: `BASE`, `HOME`, `ROOT`, `GUEST`
-- `entrypoints` — the base client entrypoints (dispatcher, login surrogate) every web app spreads
-- `ClientProtocolEntrypoint<Protocol>` — the context-bound entrypoint interface inferred from a
-  shared protocol declaration; it exposes `call()` / `invoke()` / `url()`
+Browser application bootstrap for OwlMeans: the web context factory (auth service, IndexedDB, the
+default OwlMeans router and the login host already appended), the React mount helpers, the
+framework entrypoint list (dispatcher, login surrogate) and the browser login plugins. An app uses
+it directly when it renders its own UI and wants only the framework plumbing. An app that wants the
+shadcn panel shell, forms, the styled sign-in screen and the socket reload prompt builds on
+[`@owlmeans/web-panel`](../web-panel), whose `makeContext` composes this one. `@owlmeans/mui-panel`
+is the legacy MUI layer — start nothing new there. React Native apps use the `native` monorepo.
 
 ## Installation
 
 ```bash
-bun add @owlmeans/web-client@^0.1.18-rc.23
+bun add @owlmeans/web-client@^0.1.18-rc.32
 ```
 
+## Concepts
+
+- **Web context** — `makeContext(cfg)` builds the page's one client context: `makeClientContext`,
+  `extractPrimaryHost` (host and port from `window.location`), the web auth service
+  (`context.auth()`), the IndexedDB service, the `AUTH_RESOURCE` client resource, the default router
+  plugin from `@owlmeans/web-router`, and the login host (`context.login()`) with the redirect and
+  surrogate plugins. An app factory calls it and appends its own idempotent `append*` mixins.
+- **Framework entrypoints** — `entrypoints` is `@owlmeans/client-auth`'s list plus the
+  `authProtocols.dispatcher` screen (`Dispatcher`) and the `authProtocols.surrogate` screen
+  (`SurrogateScreen`). Every app spreads it into the one list it registers.
+- **Dispatcher** — the return leg of authentication. It adopts a token carried in `AUTH_QUERY`,
+  lets the login plugin `resume` an existing session, or renders the registered sign-in screen
+  (`context.login().screen()`, falling back to `FallbackLoginScreen`). It never starts a flow itself.
+- **Login plugins** — `makeRedirectLoginPlugin` (every ordinary tab, priority 0) and
+  `makeSurrogateLoginPlugin` (a framed app or the surrogate window itself,
+  `SURROGATE_LOGIN_PRIORITY`) decide *where* the sign-in round trip runs.
+- **Session loss** — `appendWebAuthService` wraps every guarded backend entrypoint: an `AuthUnknown`
+  ending in `:invalid` clears the token, and clearing the token sends the document to the
+  dispatcher URL.
+- **Global overlay slot** — `children` of `renderApp` / `WebApp` render inside the context provider
+  and before the router, so a dialog or toast surface mounted there survives navigation.
+
 ## Usage
 
-Bootstrap the app:
+### 1. Config, types and the context factory
+
+```ts
+// src/types.ts
+import type { AppConfig, AppContext } from '@owlmeans/web-client'
+
+export interface Config extends AppConfig {}
+export interface Context<C extends Config = Config> extends AppContext<C> {}
+```
+
+```ts
+// src/config.ts
+import { config } from '@owlmeans/web-client'
+import { commonConfig, MY_APP_WEB } from 'my-app-common'
+import type { Config } from './types.js'
+
+export default config<Config>(MY_APP_WEB, commonConfig as Partial<Config>)
+```
+
+```ts
+// src/context.ts
+import { makeContext as makeWebContext, useContext as useWebContext } from '@owlmeans/web-client'
+import { appendStateResource } from '@owlmeans/state'
+import { PROJECT_STATE } from './consts.js'
+import type { Config, Context } from './types.js'
+
+export const useContext = (): Context => useWebContext<Config, Context>()
+
+export const makeContext = <C extends Config, T extends Context<C>>(cfg: C): T => {
+  // Router, auth service, IndexedDB and the login host are already on the context.
+  const context = makeWebContext<C, T>(cfg)
+  appendStateResource<C, T>(context, PROJECT_STATE)
+
+  return context
+}
+```
+
+### 2. Shared screen declarations and the entrypoint list
+
+Screens are declared once in the shared package, next to the API protocols:
+
+```ts
+// my-app-common/src/protocols/web.ts
+import { DEFAULT_GUARD } from '@owlmeans/auth-common'
+import { BASE, HOME } from '@owlmeans/context'
+import { openProtocol } from '@owlmeans/entrypoint'
+import { frontend, route } from '@owlmeans/route'
 
-```typescript
-import { makeContext, renderApp } from '@owlmeans/web-client'
+const aliases = { projects: 'my-app-web:projects', project: 'my-app-web:project' } as const
+
+const base = openProtocol(route(BASE, '/', frontend()))
+const projects = openProtocol(route(aliases.projects, '/projects', frontend({ parent: base })), {
+  guards: DEFAULT_GUARD,
+})
+
+export const webProtocols = {
+  base,
+  // A parent frontend route needs a `default: true` child, or it renders blank at its own path.
+  home: openProtocol(route(HOME, '/', frontend({ parent: base, default: true }))),
+  projects,
+  project: openProtocol(route(aliases.project, '/:id', frontend({ parent: projects }))),
+}
+```
+
+The browser binds the whole API tree and attaches a component to each screen:
+
+```ts
+// src/entrypoints.ts
+import { bindAll, bindScreen, entrypoints as frameworkEntrypoints, handler } from '@owlmeans/web-client'
+import { apiProtocols, webProtocols } from 'my-app-common'
+import { PublicLayout } from './layout/public.js'
+import { HomeScreen } from './screens/home.js'
+import { ProjectsScreen } from './screens/projects.js'
+import { ProjectScreen } from './screens/project.js'
+
+export const appEntrypoints = [
+  ...frameworkEntrypoints,
+  ...bindAll(apiProtocols),
+  bindScreen(webProtocols.base, handler(PublicLayout)),
+  bindScreen(webProtocols.home, handler(HomeScreen)),
+  bindScreen(webProtocols.projects, handler(ProjectsScreen)),
+  bindScreen(webProtocols.project, handler(ProjectScreen)),
+]
+```
+
+### 3. Boot
+
+```tsx
+// src/index.tsx
+import './index.css'
+import { renderApp } from '@owlmeans/web-client'
+import { MY_APP_API, MY_APP_WEB } from 'my-app-common'
+import config from './config.js'
+import { makeContext } from './context.js'
+import { appEntrypoints } from './entrypoints.js'
+import { AppOverlays } from './components/overlays.js'
 
 const context = makeContext(config)
+
+// Before the first render: the router builds its route table once, from what is registered.
 context.registerEntrypoints(appEntrypoints)
-context.serviceRoute(MANAGER, true)
-renderApp<Config, Context>(context)
+context.serviceRoute(MY_APP_WEB, true)
+context.serviceRoute(MY_APP_API, true)
+
+// The third argument is the global overlay slot — rendered above the router, never torn down.
+renderApp(context, undefined, <AppOverlays />)
 ```
 
-Define entrypoints:
+`renderApp(context, opts?, children?)` mounts `WebApp` (i18n provider, context provider, router)
+into `#root` (`DEFAULT_ROOT`) once `DOMContentLoaded` fires. `RenderOptions` changes that:
+`domId`, `onReady: false` (mount immediately), `hydrate: true` (`hydrateRoot` instead of
+`createRoot`) and `debug`.
+
+### 4. Calling protocols from a view model
+
+```ts
+// src/screens/project.vm.ts
+import { EntrypointOutcome } from '@owlmeans/entrypoint'
+import { apiProtocols, webProtocols } from 'my-app-common'
+import type { Context } from '../types.js'
+
+export const loadProject = async (ctx: Context, id: string) => {
+  // Value only — an error in the reply is thrown.
+  const project = await ctx.entrypoint(apiProtocols.project.get).call({ params: { id } })
 
-```typescript
-import { bindScreen, bindAll } from '@owlmeans/client-entrypoint'
-import { handler } from '@owlmeans/client'
-import { appEntrypoints as protocols } from 'my-app-common'
+  // Value plus outcome, when the outcome decides what happens next.
+  const { value: slot, outcome } = await ctx.entrypoint(apiProtocols.project.slot)
+    .invoke({ params: { id } })
+  if (outcome !== EntrypointOutcome.Ok) {
+    return { project, slot: null }
+  }
 
-appEntrypoints.push(bindScreen(protocols.web.base, handler(PublicLayout)))
-appEntrypoints.push(bindScreen(protocols.web.home, handler(HomeScreen)))
-appEntrypoints.push(...bindAll(protocols.api))
+  // A screen is addressed, never called.
+  const shareUrl = await ctx.entrypoint(webProtocols.project).url({ params: { id } }, { absolute: true })
+
+  return { project, slot, shareUrl }
+}
 ```
 
-A screen entrypoint carries a renderer, so it is addressed by `url()` and never called over the
-wire. Call an API entrypoint from a component:
+### 5. File drop target
+
+`Uploader` wraps `react-dropzone`; its props are `DropzoneOptions` plus an optional `Root`
+component and `rootProps`. `ImageUploader` is the same control with `maxSize` defaulted to 5 MB.
 
-```typescript
-const result = await context.entrypoint(appEntrypoints.api.project)
-  .call({ params: { id }, body: data })
+```tsx
+import type { FC } from 'react'
+import { ImageUploader } from '@owlmeans/web-client'
+
+export const LogoDrop: FC<{ onFile: (file: File) => void }> = ({ onFile }) =>
+  <ImageUploader maxFiles={1} accept={{ 'image/*': [] }} onDrop={files => onFile(files[0])}>
+    <span>Drop a logo here or click to choose one</span>
+  </ImageUploader>
 ```
 
 ## API
 
-### `makeContext<C, T>(cfg): T`
+### Context, rendering and services
+
+| Symbol | Kind | Purpose |
+|---|---|---|
+| `makeContext<C, T>(cfg)` | function | Web context factory — see *Concepts* |
+| `useContext<C, T>()` | hook | The current context, from React |
+| `renderApp<C, T>(context, opts?, children?)` | function | Mount `WebApp` for a context; `children` are the global overlay slot |
+| `render(node, opts?)` | function | Mount any React node with the same readiness, root and hydration handling |
+| `WebApp` | component | `I18nContext` + `@owlmeans/client`'s `App` (context provider and router) |
+| `RenderOptions` | type | `domId?`, `onReady?`, `hydrate?`, `debug?` |
+| `AppConfig`, `AppContext` | type | Web config and context; the context carries `auth()` and `login()` |
+| `DEFAULT_ROOT` | const | `'root'` — the default mount element id |
+| `extractPrimaryHost(context)` | function | Copy `window.location` host and port into `cfg.primaryHost` / `cfg.primaryPort` |
+| `makeAuthWebService(alias?)` | function | `@owlmeans/client-auth`'s service whose `update(undefined)` redirects to the dispatcher |
+| `appendWebAuthService(ctx, alias?)` | function | Register that service, `authMiddleware` and the session-loss middleware; expose `context.auth()` |
+| `provide` | const | Deprecated, always `undefined`; routing resolves its compiler from the active router plugin |
+| `UploaderError`, `FileUploadingError` | class | Uploader errors registered with `ResilientError` |
 
-Creates a web app context. Automatically registers web router, IndexedDB, and auth services.
+### Entrypoints and authentication screens
 
-### `renderApp<C, T>(context): void`
+| Symbol | Kind | Purpose |
+|---|---|---|
+| `entrypoints` | const | Framework bindings: client-auth's list, the dispatcher screen, the surrogate screen |
+| `Dispatcher` | component | The dispatcher screen, built on `DispatcherHOC` |
+| `parametriseDispatcher(defaults, Component?)` | function | A dispatcher with default props (`payload`, `alias`, ...) merged under the routed ones |
+| `ParametrisedProps` | type | Routed entrypoint params plus `DispatcherProps` |
+| `SurrogateScreen` | component | The screen the surrogate login window renders |
+| `LoginSurrogateView`, `SurrogateStage`, `SurrogateViewProps` | component, enum, type | The surrogate window's status panel |
+| `appendWebLogin(ctx)` | function | `appendLogin` plus the redirect and surrogate plugins |
+| `makeRedirectLoginPlugin()`, `makeSurrogateLoginPlugin()` | function | The two shipped `LoginPlugin`s |
+| `awaitSurrogate(...)` | function | The single waiter for a surrogate window's hand-back |
+| `REDIRECT_LOGIN`, `SURROGATE_LOGIN`, `SURROGATE_LOGIN_PRIORITY` | const | Plugin aliases and the surrogate plugin's priority |
 
-Renders the React application to the DOM using the provided context.
+### Components
 
-### `useContext<C, T>(): T`
+| Symbol | Kind | Purpose |
+|---|---|---|
+| `Uploader` | component | `react-dropzone` root with a hidden input |
+| `ImageUploader` | component | `Uploader` with a 5 MB `maxSize` default |
+| `UploaderProps`, `UploaderRootProps` | type | Uploader props |
 
-React hook to access the current application context.
+### Re-exports
 
-### `makeAuthWebService(alias?)`, `appendWebAuthService(ctx, alias?)`
+| Symbol | From |
+|---|---|
+| `handler` | `@owlmeans/client` |
+| `config` | `@owlmeans/client-context` |
+| `service` | `@owlmeans/config` |
+| `AppType`, `HOME`, `ROOT`, `BASE`, `GUEST` | `@owlmeans/context` |
+| `bind`, `bindAll`, `bindScreen`, `provideRequest`, `stab`; types `ClientEntrypoint`, `Module` | `@owlmeans/client-entrypoint` |
+| `route`, `frontend` | `@owlmeans/route` |
+| type `Route` (`ClientRoute`) | `@owlmeans/client-route` |
 
-Auth service factory and appender — adds logout redirect handling for web environments.
+Importing the package also registers the `auth` library i18n namespace in all seven supported
+languages.
 
-### `Dispatcher`
+## Common pitfalls
 
-Component that handles authentication routing (redirect to login, etc.).
+- **Register entrypoints before rendering.** The router builds its route table once, from the
+  entrypoints the context knows about at mount.
+- **Spread the framework `entrypoints`.** Without them there is no dispatcher and no surrogate
+  screen, and `useLogin` throws `Entrypoint dispatcher not found`.
+- **Bind every API declaration the browser calls, including route parents.** An unbound protocol
+  throws "entrypoint not found" before any network call — `bindAll` over the whole tree avoids it.
+- **A parent frontend route needs a `default: true` child**, or it renders blank at its own path.
+- **Do not pass `provide`.** Routing comes from the router plugin (`@owlmeans/web-router` by
+  default); react-router is only available through the opt-in `@owlmeans/web-router-react-router`.
+- **Mount dialogs and toast surfaces in the overlay slot**, not inside a route — a dialog inside a
+  route closes itself on the first navigation.
+- **Use `renderApp`, not a hand-rolled `createRoot` in `StrictMode`.** The readiness handling is
+  lost, and `StrictMode` double-invokes effects the router is not written for.
+- **`onReady` waits for `DOMContentLoaded`.** A script that runs after the event has fired must pass
+  `{ onReady: false }`, or nothing mounts.
+- **One context per page, from one factory.** Build it with `makeContext` plus `append*` mixins;
+  never create a second context for a component tree.
 
-## Related Packages
+## Related packages
 
+- [`@owlmeans/web-panel`](../web-panel) — shadcn/Tailwind panel layer built on this context
 - [`@owlmeans/client-context`](../client-context) — `ClientContext` base extended by `makeContext`
-- [`@owlmeans/web-router`](../web-router) — default OwlMeans browser routing plugin registered by `makeContext`
+- [`@owlmeans/client-entrypoint`](../client-entrypoint) — protocol binding and `call` / `invoke` / `url`
+- [`@owlmeans/client-auth`](../client-auth) — auth service, dispatcher HOC and login host
+- [`@owlmeans/web-router`](../web-router) — default OwlMeans browser routing plugin
+- [`@owlmeans/web-router-react-router`](../web-router-react-router) — opt-in react-router plugin
 - [`@owlmeans/web-db`](../web-db) — IndexedDB service registered by `makeContext`
-- [`@owlmeans/client-entrypoint`](../client-entrypoint) — protocol binding helpers
+- [`@owlmeans/web-oidc-rp`](../web-oidc-rp) — OIDC relying party with its own dispatcher
 
 <!-- owlmeans:agent-guidance:start -->
 ## Agent guidance

package/agent-meta/manifest.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 2,
   "package": "@owlmeans/web-client",
-  "version": "0.1.18-rc.32",
-  "generatedAt": "2026-09-12T14:18:54.789Z",
+  "version": "0.1.18-rc.33",
+  "generatedAt": "2026-09-14T19:17:35.193Z",
   "canonicalRepo": "https://github.com/owlmeans/common",
   "entries": [
     {

package/agent-meta/skills/web-client/SKILL.md

@@ -6,27 +6,27 @@ description: Bind OwlMeans shared entrypoint protocols in a browser application.
 
 # Browser protocol entrypoints
 
-**Install:** `bun add @owlmeans/web-client@^0.1.18-rc.30`
+**Install:** `bun add @owlmeans/web-client@^0.1.18-rc.32`
 
 Shared protocol declarations are immutable. Bind a complete protocol tree for callable API routes,
 then bind frontend declarations to screens.
 
 ```ts
 import { bindAll, bindScreen, entrypoints as frameworkEntrypoints, handler } from '@owlmeans/web-panel'
-import { projectEntrypoints, webEntrypoints } from 'project-common'
+import { projectProtocols, webProtocols } from 'project-common'
 import { ProjectScreen } from './screens/project.js'
 
-export const appEntrypoints = [
+export const clientBindings = [
   ...frameworkEntrypoints,
-  ...bindAll(projectEntrypoints),
-  bindScreen(webEntrypoints.project, handler(ProjectScreen)),
+  ...bindAll(projectProtocols),
+  bindScreen(webProtocols.project, handler(ProjectScreen)),
 ]
 ```
 
 Call a protocol directly. Its request and response types come from its shared contract.
 
 ```ts
-const project = await context.entrypoint(projectEntrypoints.get).call({
+const project = await context.entrypoint(projectProtocols.get).call({
   params: { id: projectId },
 })
 ```

package/build/entrypoints.d.ts

@@ -8,9 +8,9 @@
  */
 export declare const entrypoints: (import("@owlmeans/client-entrypoint").ClientProtocolEntrypoint<import("@owlmeans/entrypoint").EntrypointProtocol<{
     query: import("@owlmeans/auth").AuthToken;
-}, import("@owlmeans/entrypoint").OpenValue>> | import("@owlmeans/client-entrypoint").ClientProtocolEntrypoint<import("@owlmeans/entrypoint").EntrypointProtocol<{
+}, undefined>> | import("@owlmeans/client-entrypoint").ClientProtocolEntrypoint<import("@owlmeans/entrypoint").EntrypointProtocol<{
     query: import("@owlmeans/auth-common").SurrogateQuery;
-}, import("@owlmeans/entrypoint").OpenValue>> | import("@owlmeans/client-entrypoint").ClientProtocolEntrypoint<import("@owlmeans/entrypoint").EntrypointProtocol<{
+}, undefined>> | import("@owlmeans/client-entrypoint").ClientProtocolEntrypoint<import("@owlmeans/entrypoint").EntrypointProtocol<{
     body: import("@owlmeans/auth").AuthToken;
 }, import("@owlmeans/auth").AuthToken>>)[];
 //# sourceMappingURL=entrypoints.d.ts.map

package/build/login/surrogate.d.ts

@@ -1,4 +1,20 @@
 import type { LoginPlugin } from '@owlmeans/client-auth/login';
+/**
+ * `window.open` features that size and CENTER the surrogate on the screen the browser window
+ * currently occupies.
+ *
+ * Computed fresh per call, never a constant: centering depends on where the browser window sits
+ * NOW, which can change between one login attempt and the next. `screenLeft`/`screenTop` and
+ * `outerWidth`/`outerHeight` describe the browser's own chrome rather than this document's
+ * viewport — and, unlike `innerWidth` or anything reached through `window.top`, they stay readable
+ * from a cross-origin iframe. That matters here specifically: a generated app's preview runs
+ * framed on a different origin than the manager that embeds it, so `env.embedded` is exactly the
+ * case where `window.top.innerWidth` would throw, and reading this document's own `innerWidth`
+ * instead would center the popup on the IFRAME's rectangle rather than on the actual window a
+ * person sees. Falling back to `window.screen` covers a window that reports no outer geometry at
+ * all (a headless test runner).
+ */
+export declare const centeredPopupFeatures: (width: number, height: number) => string;
 /**
  * Login for a document that cannot complete the flow where it is.
  *

package/build/login/surrogate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"surrogate.d.ts","sourceRoot":"","sources":["../../src/login/surrogate.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAA0B,WAAW,EAAE,MAAM,6BAA6B,CAAA;AAItF;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,wBAAwB,QAAO,WAoJ3C,CAAA"}
+{"version":3,"file":"surrogate.d.ts","sourceRoot":"","sources":["../../src/login/surrogate.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAA0B,WAAW,EAAE,MAAM,6BAA6B,CAAA;AAItF;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,qBAAqB,UAAW,MAAM,UAAU,MAAM,KAAG,MAUrE,CAAA;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,wBAAwB,QAAO,WA4J3C,CAAA"}

package/build/login/surrogate.js

@@ -1,6 +1,30 @@
-import { adoptToken, clearSurrogate, markSurrogate, revokeToken, surrogatePath, LoginIntent, LoginOutcome, LOGIN_LOGOUT_MESSAGE, LOGIN_SURROGATE_FEATURES, LOGIN_SURROGATE_NAME, LOGIN_TOKEN_MESSAGE, } from '@owlmeans/client-auth/login';
+import { adoptToken, clearSurrogate, markSurrogate, revokeToken, surrogatePath, LoginIntent, LoginOutcome, LOGIN_LOGOUT_MESSAGE, LOGIN_SURROGATE_HEIGHT, LOGIN_SURROGATE_NAME, LOGIN_SURROGATE_WIDTH, LOGIN_TOKEN_MESSAGE, } from '@owlmeans/client-auth/login';
 import { SURROGATE_LOGIN, SURROGATE_LOGIN_PRIORITY } from './consts.js';
 import { awaitSurrogate } from './pump.js';
+/**
+ * `window.open` features that size and CENTER the surrogate on the screen the browser window
+ * currently occupies.
+ *
+ * Computed fresh per call, never a constant: centering depends on where the browser window sits
+ * NOW, which can change between one login attempt and the next. `screenLeft`/`screenTop` and
+ * `outerWidth`/`outerHeight` describe the browser's own chrome rather than this document's
+ * viewport — and, unlike `innerWidth` or anything reached through `window.top`, they stay readable
+ * from a cross-origin iframe. That matters here specifically: a generated app's preview runs
+ * framed on a different origin than the manager that embeds it, so `env.embedded` is exactly the
+ * case where `window.top.innerWidth` would throw, and reading this document's own `innerWidth`
+ * instead would center the popup on the IFRAME's rectangle rather than on the actual window a
+ * person sees. Falling back to `window.screen` covers a window that reports no outer geometry at
+ * all (a headless test runner).
+ */
+export const centeredPopupFeatures = (width, height) => {
+    const screenLeft = window.screenLeft ?? window.screenX ?? 0;
+    const screenTop = window.screenTop ?? window.screenY ?? 0;
+    const outerWidth = window.outerWidth || window.screen.width;
+    const outerHeight = window.outerHeight || window.screen.height;
+    const left = Math.round(screenLeft + Math.max(0, (outerWidth - width) / 2));
+    const top = Math.round(screenTop + Math.max(0, (outerHeight - height) / 2));
+    return `popup=yes,width=${width},height=${height},left=${left},top=${top}`;
+};
 /**
  * Login for a document that cannot complete the flow where it is.
  *
@@ -66,9 +90,10 @@ export const makeSurrogateLoginPlugin = () => {
             const path = surrogatePath(ctx, {
                 intent: LoginIntent.Login, next: request.url,
             });
-            const surrogate = window.open(path ?? request.url, LOGIN_SURROGATE_NAME, LOGIN_SURROGATE_FEATURES);
+            const surrogate = window.open(path ?? request.url, LOGIN_SURROGATE_NAME, centeredPopupFeatures(LOGIN_SURROGATE_WIDTH, LOGIN_SURROGATE_HEIGHT));
             if (surrogate == null) {
-                return Promise.resolve(LoginOutcome.Failed);
+                // Distinct from `Failed` below: nothing ever opened, so there is nothing left to wait on.
+                return Promise.resolve(LoginOutcome.Blocked);
             }
             return awaitSurrogate(surrogate, LOGIN_TOKEN_MESSAGE, async (data) => {
                 if (data.token == null || data.token === '') {
@@ -109,16 +134,20 @@ export const makeSurrogateLoginPlugin = () => {
             const path = surrogatePath(ctx, { intent: LoginIntent.Logout });
             // Opened first and synchronously, for the same reason `begin` does.
             const surrogate = path != null
-                ? window.open(path, LOGIN_SURROGATE_NAME, LOGIN_SURROGATE_FEATURES)
+                ? window.open(path, LOGIN_SURROGATE_NAME, centeredPopupFeatures(LOGIN_SURROGATE_WIDTH, LOGIN_SURROGATE_HEIGHT))
                 : null;
             // The local session goes next, and UNCONDITIONALLY. A blocked window, a severed opener or a
             // user who closes the popup must never leave THIS document signed in: a logout that only
             // half happened is bad, and one that did not happen at all is worse.
             const local = revokeToken(ctx);
             if (surrogate == null) {
+                // `path == null` is an app whose entrypoint list predates the surrogate route — nothing a
+                // retry would do differently. A `window.open` the browser refused is the one case worth
+                // telling the user about, so only that one reports `Blocked`.
+                const outcome = path != null ? LoginOutcome.Blocked : LoginOutcome.Failed;
                 return local.then(async () => {
                     await request.navigate?.();
-                    return LoginOutcome.Failed;
+                    return outcome;
                 });
             }
             return local.then(async () => await awaitSurrogate(surrogate, LOGIN_LOGOUT_MESSAGE, async () => {

package/build/login/surrogate.js.map

@@ -1 +1 @@
-{"version":3,"file":"surrogate.js","sourceRoot":"","sources":["../../src/login/surrogate.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,UAAU,EAAE,cAAc,EAAE,aAAa,EAAE,WAAW,EAAE,aAAa,EAAE,WAAW,EAAE,YAAY,EAChG,oBAAoB,EAAE,wBAAwB,EAAE,oBAAoB,EAAE,mBAAmB,GAC1F,MAAM,6BAA6B,CAAA;AAEpC,OAAO,EAAE,eAAe,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAA;AACvE,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAA;AAE1C;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,GAAgB,EAAE;IACxD;;;;;OAKG;IACH,MAAM,QAAQ,GAAG,KAAK,EAAE,KAAa,EAAE,GAAa,EAAyB,EAAE;QAC7E,IAAI,CAAC,GAAG,CAAC,SAAS,EAAE,CAAC;YACnB,0FAA0F;YAC1F,OAAO,YAAY,CAAC,MAAM,CAAA;QAC5B,CAAC;QACD,IAAI,CAAC,GAAG,CAAC,SAAS,EAAE,CAAC;YACnB,4FAA4F;YAC5F,yFAAyF;YACzF,OAAO,YAAY,CAAC,QAAQ,CAAA;QAC9B,CAAC;QAED,cAAc,EAAE,CAAA;QAChB,6FAA6F;QAC7F,uFAAuF;QACvF,MAAM,CAAC,MAAM,CAAC,WAAW,CAAC,EAAE,IAAI,EAAE,mBAAmB,EAAE,KAAK,EAAE,EAAE,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAA;QACvF,MAAM,CAAC,KAAK,EAAE,CAAA;QAEd,OAAO,YAAY,CAAC,OAAO,CAAA;IAC7B,CAAC,CAAA;IAED,MAAM,MAAM,GAAgB;QAC1B,KAAK,EAAE,eAAe;QACtB,QAAQ,EAAE,wBAAwB;QAClC,IAAI,EAAE,WAAW;QACjB,KAAK,EAAE,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,SAAS,IAAI,CAAC,GAAG,CAAC,QAAQ,IAAI,GAAG,CAAC,SAAS,CAAC;QAE9D,KAAK,EAAE,GAAG,EAAE,GAAG,aAAa,EAAE,CAAA,CAAC,CAAC;QAEhC,KAAK,EAAE,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,EAAE;YAC3B,8DAA8D;YAC9D,IAAI,GAAG,CAAC,SAAS,EAAE,CAAC;gBAClB,MAAM,CAAC,QAAQ,CAAC,IAAI,GAAG,OAAO,CAAC,GAAG,CAAA;gBAElC,OAAO,OAAO,CAAC,OAAO,CAAC,YAAY,CAAC,UAAU,CAAC,CAAA;YACjD,CAAC;YAED,yFAAyF;YACzF,2FAA2F;YAC3F,oCAAoC;YACpC,EAAE;YACF,2FAA2F;YAC3F,6FAA6F;YAC7F,8FAA8F;YAC9F,0EAA0E;YAC1E,MAAM,IAAI,GAAG,aAAa,CAAC,GAAmB,EAAE;gBAC9C,MAAM,EAAE,WAAW,CAAC,KAAK,EAAE,IAAI,EAAE,OAAO,CAAC,GAAG;aAC7C,CAAC,CAAA;YACF,MAAM,SAAS,GAAG,MAAM,CAAC,IAAI,CAC3B,IAAI,IAAI,OAAO,CAAC,GAAG,EAAE,oBAAoB,EAAE,wBAAwB,CACpE,CAAA;YACD,IAAI,SAAS,IAAI,IAAI,EAAE,CAAC;gBACtB,OAAO,OAAO,CAAC,OAAO,CAAC,YAAY,CAAC,MAAM,CAAC,CAAA;YAC7C,CAAC;YAED,OAAO,cAAc,CAAC,SAAS,EAAE,mBAAmB,EAAE,KAAK,EAAC,IAAI,EAAC,EAAE;gBACjE,IAAI,IAAI,CAAC,KAAK,IAAI,IAAI,IAAI,IAAI,CAAC,KAAK,KAAK,EAAE,EAAE,CAAC;oBAC5C,OAAO,YAAY,CAAC,MAAM,CAAA;gBAC5B,CAAC;gBACD,MAAM,UAAU,CAAC,GAAmB,EAAE,IAAI,CAAC,KAAK,CAAC,CAAA;gBACjD,wFAAwF;gBACxF,wFAAwF;gBACxF,yFAAyF;gBACzF,yFAAyF;gBACzF,sEAAsE;gBACtE,MAAM,OAAO,CAAC,QAAQ,EAAE,EAAE,CAAA;gBAE1B,OAAO,YAAY,CAAC,OAAO,CAAA;YAC7B,CAAC,CAAC,CAAA;QACJ,CAAC;QAED,SAAS,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,EAAE,GAAG,EAAE,EAAE;YAClC,qEAAqE;YACrE,IAAI,GAAG,CAAC,SAAS,EAAE,CAAC;gBAClB,MAAM,CAAC,QAAQ,CAAC,IAAI,GAAG,GAAG,CAAA;gBAE1B,OAAO,YAAY,CAAC,UAAU,CAAA;YAChC,CAAC;YAED,yFAAyF;YACzF,6FAA6F;YAC7F,8DAA8D;YAC9D,OAAO,YAAY,CAAC,OAAO,CAAA;QAC7B,CAAC;QAED,QAAQ,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,EAAE,EAAE,CAAC,MAAM,QAAQ,CAAC,KAAK,EAAE,GAAG,CAAC;QAEhE,8FAA8F;QAC9F,0FAA0F;QAC1F,uFAAuF;QACvF,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,EAAE,EAAE,CAAC,MAAM,QAAQ,CAAC,KAAK,EAAE,GAAG,CAAC;QAE9D,MAAM,EAAE,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,EAAE;YAC5B,oEAAoE;YACpE,IAAI,GAAG,CAAC,SAAS,EAAE,CAAC;gBAClB,OAAO,WAAW,CAAC,GAAmB,CAAC;qBACpC,IAAI,CAAC,KAAK,IAAI,EAAE,CAAC,MAAM,MAAM,CAAC,cAAe,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,CAAA;YAC7D,CAAC;YAED,MAAM,IAAI,GAAG,aAAa,CAAC,GAAmB,EAAE,EAAE,MAAM,EAAE,WAAW,CAAC,MAAM,EAAE,CAAC,CAAA;YAC/E,oEAAoE;YACpE,MAAM,SAAS,GAAG,IAAI,IAAI,IAAI;gBAC5B,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,oBAAoB,EAAE,wBAAwB,CAAC;gBACnE,CAAC,CAAC,IAAI,CAAA;YAER,4FAA4F;YAC5F,yFAAyF;YACzF,qEAAqE;YACrE,MAAM,KAAK,GAAG,WAAW,CAAC,GAAmB,CAAC,CAAA;YAC9C,IAAI,SAAS,IAAI,IAAI,EAAE,CAAC;gBACtB,OAAO,KAAK,CAAC,IAAI,CAAC,KAAK,IAAI,EAAE;oBAC3B,MAAM,OAAO,CAAC,QAAQ,EAAE,EAAE,CAAA;oBAE1B,OAAO,YAAY,CAAC,MAAM,CAAA;gBAC5B,CAAC,CAAC,CAAA;YACJ,CAAC;YAED,OAAO,KAAK,CAAC,IAAI,CAAC,KAAK,IAAI,EAAE,CAAC,MAAM,cAAc,CAChD,SAAS,EAAE,oBAAoB,EAAE,KAAK,IAAI,EAAE;gBAC1C,MAAM,OAAO,CAAC,QAAQ,EAAE,EAAE,CAAA;gBAE1B,OAAO,YAAY,CAAC,OAAO,CAAA;YAC7B,CAAC,CACF,CAAC,CAAA;QACJ,CAAC;QAED,cAAc,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,EAAE,EAAE;YAClC,IAAI,CAAC,GAAG,CAAC,SAAS,EAAE,CAAC;gBACnB,OAAO,YAAY,CAAC,MAAM,CAAA;YAC5B,CAAC;YACD,IAAI,CAAC,GAAG,CAAC,SAAS,EAAE,CAAC;gBACnB,OAAO,YAAY,CAAC,QAAQ,CAAA;YAC9B,CAAC;YACD,cAAc,EAAE,CAAA;YAChB,MAAM,CAAC,MAAM,CAAC,WAAW,CAAC,EAAE,IAAI,EAAE,oBAAoB,EAAE,EAAE,EAAE,IAAI,EAAE,EAAE,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAA;YAC3F,MAAM,CAAC,KAAK,EAAE,CAAA;YAEd,OAAO,YAAY,CAAC,OAAO,CAAA;QAC7B,CAAC;KACF,CAAA;IAED,OAAO,MAAM,CAAA;AACf,CAAC,CAAA"}
+{"version":3,"file":"surrogate.js","sourceRoot":"","sources":["../../src/login/surrogate.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@owlmeans/web-client",
-  "version": "0.1.18-rc.32",
+  "version": "0.1.18-rc.33",
   "license": "MIT",
   "type": "module",
   "scripts": {
@@ -24,7 +24,7 @@
     "@owlmeans/auth": "^0.1.18-rc.17",
     "@owlmeans/auth-common": "^0.1.18-rc.21",
     "@owlmeans/client": "^0.1.18-rc.24",
-    "@owlmeans/client-auth": "^0.1.18-rc.28",
+    "@owlmeans/client-auth": "^0.1.18-rc.29",
     "@owlmeans/client-context": "^0.1.18-rc.21",
     "@owlmeans/client-i18n": "^0.1.18-rc.23",
     "@owlmeans/client-entrypoint": "^0.1.18-rc.21",

package/src/login/surrogate.ts

@@ -1,11 +1,39 @@
 import {
   adoptToken, clearSurrogate, markSurrogate, revokeToken, surrogatePath, LoginIntent, LoginOutcome,
-  LOGIN_LOGOUT_MESSAGE, LOGIN_SURROGATE_FEATURES, LOGIN_SURROGATE_NAME, LOGIN_TOKEN_MESSAGE,
+  LOGIN_LOGOUT_MESSAGE, LOGIN_SURROGATE_HEIGHT, LOGIN_SURROGATE_NAME, LOGIN_SURROGATE_WIDTH,
+  LOGIN_TOKEN_MESSAGE,
 } from '@owlmeans/client-auth/login'
 import type { LoginContext, LoginEnv, LoginPlugin } from '@owlmeans/client-auth/login'
 import { SURROGATE_LOGIN, SURROGATE_LOGIN_PRIORITY } from './consts.js'
 import { awaitSurrogate } from './pump.js'
 
+/**
+ * `window.open` features that size and CENTER the surrogate on the screen the browser window
+ * currently occupies.
+ *
+ * Computed fresh per call, never a constant: centering depends on where the browser window sits
+ * NOW, which can change between one login attempt and the next. `screenLeft`/`screenTop` and
+ * `outerWidth`/`outerHeight` describe the browser's own chrome rather than this document's
+ * viewport — and, unlike `innerWidth` or anything reached through `window.top`, they stay readable
+ * from a cross-origin iframe. That matters here specifically: a generated app's preview runs
+ * framed on a different origin than the manager that embeds it, so `env.embedded` is exactly the
+ * case where `window.top.innerWidth` would throw, and reading this document's own `innerWidth`
+ * instead would center the popup on the IFRAME's rectangle rather than on the actual window a
+ * person sees. Falling back to `window.screen` covers a window that reports no outer geometry at
+ * all (a headless test runner).
+ */
+export const centeredPopupFeatures = (width: number, height: number): string => {
+  const screenLeft = window.screenLeft ?? window.screenX ?? 0
+  const screenTop = window.screenTop ?? window.screenY ?? 0
+  const outerWidth = window.outerWidth || window.screen.width
+  const outerHeight = window.outerHeight || window.screen.height
+
+  const left = Math.round(screenLeft + Math.max(0, (outerWidth - width) / 2))
+  const top = Math.round(screenTop + Math.max(0, (outerHeight - height) / 2))
+
+  return `popup=yes,width=${width},height=${height},left=${left},top=${top}`
+}
+
 /**
  * Login for a document that cannot complete the flow where it is.
  *
@@ -79,10 +107,12 @@ export const makeSurrogateLoginPlugin = (): LoginPlugin => {
         intent: LoginIntent.Login, next: request.url,
       })
       const surrogate = window.open(
-        path ?? request.url, LOGIN_SURROGATE_NAME, LOGIN_SURROGATE_FEATURES
+        path ?? request.url, LOGIN_SURROGATE_NAME,
+        centeredPopupFeatures(LOGIN_SURROGATE_WIDTH, LOGIN_SURROGATE_HEIGHT)
       )
       if (surrogate == null) {
-        return Promise.resolve(LoginOutcome.Failed)
+        // Distinct from `Failed` below: nothing ever opened, so there is nothing left to wait on.
+        return Promise.resolve(LoginOutcome.Blocked)
       }
 
       return awaitSurrogate(surrogate, LOGIN_TOKEN_MESSAGE, async data => {
@@ -132,7 +162,8 @@ export const makeSurrogateLoginPlugin = (): LoginPlugin => {
       const path = surrogatePath(ctx as LoginContext, { intent: LoginIntent.Logout })
       // Opened first and synchronously, for the same reason `begin` does.
       const surrogate = path != null
-        ? window.open(path, LOGIN_SURROGATE_NAME, LOGIN_SURROGATE_FEATURES)
+        ? window.open(path, LOGIN_SURROGATE_NAME,
+          centeredPopupFeatures(LOGIN_SURROGATE_WIDTH, LOGIN_SURROGATE_HEIGHT))
         : null
 
       // The local session goes next, and UNCONDITIONALLY. A blocked window, a severed opener or a
@@ -140,10 +171,15 @@ export const makeSurrogateLoginPlugin = (): LoginPlugin => {
       // half happened is bad, and one that did not happen at all is worse.
       const local = revokeToken(ctx as LoginContext)
       if (surrogate == null) {
+        // `path == null` is an app whose entrypoint list predates the surrogate route — nothing a
+        // retry would do differently. A `window.open` the browser refused is the one case worth
+        // telling the user about, so only that one reports `Blocked`.
+        const outcome = path != null ? LoginOutcome.Blocked : LoginOutcome.Failed
+
         return local.then(async () => {
           await request.navigate?.()
 
-          return LoginOutcome.Failed
+          return outcome
         })
       }
 

package/tests/surrogate.spec.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=surrogate.spec.d.ts.map

package/tests/surrogate.spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"surrogate.spec.d.ts","sourceRoot":"","sources":["surrogate.spec.ts"],"names":[],"mappings":""}

package/tests/surrogate.spec.js

@@ -0,0 +1,43 @@
+import { describe, test, expect, afterEach } from 'bun:test';
+import { centeredPopupFeatures } from '../src/login/surrogate.js';
+/**
+ * A hand-written `window`, not jsdom: the function under test reads exactly four geometry
+ * properties, and a real DOM would prove a fixture behaves rather than that the math does.
+ */
+const stubWindow = (over) => {
+    globalThis.window = {
+        screenLeft: 0, screenTop: 0, screenX: 0, screenY: 0,
+        outerWidth: 1920, outerHeight: 1080,
+        screen: { width: 1920, height: 1080 },
+        ...over,
+    };
+};
+afterEach(() => {
+    delete globalThis.window;
+});
+describe('centeredPopupFeatures', () => {
+    test('centers on the browser window, at its current screen position', () => {
+        stubWindow({ screenLeft: 100, screenTop: 50, outerWidth: 1200, outerHeight: 800 });
+        expect(centeredPopupFeatures(520, 760)).toBe('popup=yes,width=520,height=760,left=440,top=70');
+    });
+    // A cross-origin iframe: `window.top.innerWidth` would throw, which is exactly why this reads
+    // `outerWidth`/`outerHeight` instead — they describe the browser's own chrome, not this
+    // document's viewport, and stay readable across the origin boundary.
+    test('falls back to screenX/screenY when the legacy aliases are unavailable', () => {
+        stubWindow({
+            screenLeft: undefined, screenTop: undefined, screenX: 20, screenY: 10,
+            outerWidth: 1200, outerHeight: 800,
+        });
+        expect(centeredPopupFeatures(520, 760)).toBe('popup=yes,width=520,height=760,left=360,top=30');
+    });
+    test('falls back to window.screen when outerWidth/outerHeight report zero', () => {
+        // A headless runner: no chrome geometry to report at all.
+        stubWindow({ outerWidth: 0, outerHeight: 0, screen: { width: 1600, height: 900 } });
+        expect(centeredPopupFeatures(520, 760)).toBe('popup=yes,width=520,height=760,left=540,top=70');
+    });
+    test('never places the popup off-screen when it is larger than the window', () => {
+        stubWindow({ outerWidth: 400, outerHeight: 400 });
+        expect(centeredPopupFeatures(520, 760)).toBe('popup=yes,width=520,height=760,left=0,top=0');
+    });
+});
+//# sourceMappingURL=surrogate.spec.js.map

package/tests/surrogate.spec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"surrogate.spec.js","sourceRoot":"","sources":["surrogate.spec.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,UAAU,CAAA;AAC5D,OAAO,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAA;AAEjE;;;GAGG;AACH,MAAM,UAAU,GAAG,CAAC,IAA6B,EAAQ,EAAE;IACxD,UAA6C,CAAC,MAAM,GAAG;QACtD,UAAU,EAAE,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC;QACnD,UAAU,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI;QACnC,MAAM,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE;QACrC,GAAG,IAAI;KACR,CAAA;AACH,CAAC,CAAA;AAED,SAAS,CAAC,GAAG,EAAE;IACb,OAAQ,UAAmC,CAAC,MAAM,CAAA;AACpD,CAAC,CAAC,CAAA;AAEF,QAAQ,CAAC,uBAAuB,EAAE,GAAG,EAAE;IACrC,IAAI,CAAC,+DAA+D,EAAE,GAAG,EAAE;QACzE,UAAU,CAAC,EAAE,UAAU,EAAE,GAAG,EAAE,SAAS,EAAE,EAAE,EAAE,UAAU,EAAE,IAAI,EAAE,WAAW,EAAE,GAAG,EAAE,CAAC,CAAA;QAElF,MAAM,CAAC,qBAAqB,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,gDAAgD,CAAC,CAAA;IAChG,CAAC,CAAC,CAAA;IAEF,8FAA8F;IAC9F,wFAAwF;IACxF,qEAAqE;IACrE,IAAI,CAAC,uEAAuE,EAAE,GAAG,EAAE;QACjF,UAAU,CAAC;YACT,UAAU,EAAE,SAAS,EAAE,SAAS,EAAE,SAAS,EAAE,OAAO,EAAE,EAAE,EAAE,OAAO,EAAE,EAAE;YACrE,UAAU,EAAE,IAAI,EAAE,WAAW,EAAE,GAAG;SACnC,CAAC,CAAA;QAEF,MAAM,CAAC,qBAAqB,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,gDAAgD,CAAC,CAAA;IAChG,CAAC,CAAC,CAAA;IAEF,IAAI,CAAC,qEAAqE,EAAE,GAAG,EAAE;QAC/E,0DAA0D;QAC1D,UAAU,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE,WAAW,EAAE,CAAC,EAAE,MAAM,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,EAAE,CAAC,CAAA;QAEnF,MAAM,CAAC,qBAAqB,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,gDAAgD,CAAC,CAAA;IAChG,CAAC,CAAC,CAAA;IAEF,IAAI,CAAC,qEAAqE,EAAE,GAAG,EAAE;QAC/E,UAAU,CAAC,EAAE,UAAU,EAAE,GAAG,EAAE,WAAW,EAAE,GAAG,EAAE,CAAC,CAAA;QAEjD,MAAM,CAAC,qBAAqB,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,6CAA6C,CAAC,CAAA;IAC7F,CAAC,CAAC,CAAA;AACJ,CAAC,CAAC,CAAA"}

package/tests/surrogate.spec.ts

@@ -0,0 +1,52 @@
+import { describe, test, expect, afterEach } from 'bun:test'
+import { centeredPopupFeatures } from '../src/login/surrogate.js'
+
+/**
+ * A hand-written `window`, not jsdom: the function under test reads exactly four geometry
+ * properties, and a real DOM would prove a fixture behaves rather than that the math does.
+ */
+const stubWindow = (over: Record<string, unknown>): void => {
+  (globalThis as unknown as { window: unknown }).window = {
+    screenLeft: 0, screenTop: 0, screenX: 0, screenY: 0,
+    outerWidth: 1920, outerHeight: 1080,
+    screen: { width: 1920, height: 1080 },
+    ...over,
+  }
+}
+
+afterEach(() => {
+  delete (globalThis as { window?: unknown }).window
+})
+
+describe('centeredPopupFeatures', () => {
+  test('centers on the browser window, at its current screen position', () => {
+    stubWindow({ screenLeft: 100, screenTop: 50, outerWidth: 1200, outerHeight: 800 })
+
+    expect(centeredPopupFeatures(520, 760)).toBe('popup=yes,width=520,height=760,left=440,top=70')
+  })
+
+  // A cross-origin iframe: `window.top.innerWidth` would throw, which is exactly why this reads
+  // `outerWidth`/`outerHeight` instead — they describe the browser's own chrome, not this
+  // document's viewport, and stay readable across the origin boundary.
+  test('falls back to screenX/screenY when the legacy aliases are unavailable', () => {
+    stubWindow({
+      screenLeft: undefined, screenTop: undefined, screenX: 20, screenY: 10,
+      outerWidth: 1200, outerHeight: 800,
+    })
+
+    expect(centeredPopupFeatures(520, 760)).toBe('popup=yes,width=520,height=760,left=360,top=30')
+  })
+
+  test('falls back to window.screen when outerWidth/outerHeight report zero', () => {
+    // A headless runner: no chrome geometry to report at all.
+    stubWindow({ outerWidth: 0, outerHeight: 0, screen: { width: 1600, height: 900 } })
+
+    expect(centeredPopupFeatures(520, 760)).toBe('popup=yes,width=520,height=760,left=540,top=70')
+  })
+
+  test('never places the popup off-screen when it is larger than the window', () => {
+    stubWindow({ outerWidth: 400, outerHeight: 400 })
+
+    expect(centeredPopupFeatures(520, 760)).toBe('popup=yes,width=520,height=760,left=0,top=0')
+  })
+})

package/tsconfig.json

@@ -7,5 +7,5 @@
     "rootDir": "./src/",
     "outDir": "./build/"
   },
-  "exclude": ["./dist/**/*", "./build/**/*", "./*.ts"]
+  "exclude": ["./dist/**/*", "./build/**/*", "./tests/**/*", "./*.ts"]
 }