@owlmeans/web-client 0.1.18-rc.9 → 0.1.18

package/src/components/dispatcher/component.tsx

@@ -1,16 +1,32 @@
 import { DispatcherHOC } from '@owlmeans/client-auth'
-import { useEffect } from 'react'
+import { useEffect, useState } from 'react'
 import { useI18nLib } from '@owlmeans/client-i18n'
 import { AUTH_QUERY } from '@owlmeans/auth'
+import { FallbackLoginScreen, LoginIntent, LoginOutcome, ResumeAction, loginResumeHelper } from '@owlmeans/client-auth/login'
+import { LoginSurrogateView } from '../../login/view.js'
+import { SurrogateStage } from '../../login/consts.js'
 import { useContext } from '../../context.js'
 
-export const Dispatcher = DispatcherHOC(({ provideToken }) => {
+export const Dispatcher = DispatcherHOC(({ provideToken, navigate }) => {
   const context = useContext()
   const [query] = context.router().useSearchParams()
 
   const t = useI18nLib('auth', 'dispatcher')
+  const tAuth = useI18nLib('auth')
+
+  // Read in the component body, not in the effect: `window.name` is set by `window.open` before
+  // this document loads and `sessionStorage` carries the marker across the provider round trip, so
+  // the answer is already correct at first paint — and a first paint that showed the application
+  // before an effect corrected it is the defect this exists to prevent.
+  const [env] = useState(() => context.login().env())
+  const [outcome, setOutcome] = useState<LoginOutcome | null>(null)
+  // Nothing to return from and nobody signed in: offer the choice rather than starting a flow.
+  const [choose, setChoose] = useState(false)
 
   useEffect(() => {
+    // First statement of the effect on purpose: everything below can navigate this window away.
+    context.login().enter()
+
     const token = query.get(AUTH_QUERY)
     if (token != null) {
       const params: Record<string, string> = {}
@@ -21,15 +37,62 @@ export const Dispatcher = DispatcherHOC(({ provideToken }) => {
       })
 
       provideToken({ token }, params)
-    } else {
-      context.auth().authenticated().then(authzToken => {
-        if (authzToken == null) {
-          provideToken({ token: '' }, undefined)
-        }
-      })
+
+      return
     }
+
+    void context.auth().authenticated().then(async authzToken => {
+      if (authzToken == null || authzToken === '') {
+        setChoose(true)
+
+        return
+      }
+      // A session already exists in THIS document. Whether it is useful here, or belongs to the
+      // window that opened this one, is the plugin's call — the dispatcher reads no environment.
+      const settled = await context.login().resume(authzToken)
+      switch (loginResumeHelper.resumeAction(settled)) {
+        case ResumeAction.Stop:
+          return
+        case ResumeAction.Render:
+          setOutcome(settled)
+
+          return
+        default:
+          await navigate()
+      }
+    })
   }, [])
 
+  // A surrogate window never renders the application, whatever else is true. Checked ahead of
+  // every other return for exactly that reason.
+  //
+  // `choose` is the one state this must NOT mask, and it is not an exception to the rule: the
+  // login chooser is not the application. A login window with nothing to return from and nobody
+  // signed in has exactly one thing left that can move it forward, and that is asking which
+  // provider. The surrogate URL normally carries `?method=` so the question is already settled,
+  // but a window opened from a bare "Log in" — the framed application's own header button — has no
+  // method to send. Returning the "working" panel there left the popup on "Signing you in…"
+  // permanently, because nothing was ever going to start.
+  if (env.surrogate && !choose) {
+    return <LoginSurrogateView
+      intent={LoginIntent.Login}
+      stage={
+        outcome === LoginOutcome.Orphaned ? SurrogateStage.Orphaned
+          : outcome === LoginOutcome.Failed ? SurrogateStage.Failed
+            : outcome === LoginOutcome.Gesture ? SurrogateStage.Gesture
+              : SurrogateStage.Working
+      }
+      onAction={() => window.close()}
+      translate={(key, defaultValue) => tAuth(key, { defaultValue })}
+    />
+  }
+
+  if (choose) {
+    const Screen = context.login().screen() ?? FallbackLoginScreen
+
+    return <Screen translate={(key, defaultValue) => tAuth(key, { defaultValue })} />
+  }
+
   return query.has(AUTH_QUERY) ? <div style={{
     width: '100%', // Makes the div occupy the full width
     display: 'flex', // Enables flexbox layout

package/src/components/dispatcher/parametrise.tsx

@@ -6,9 +6,7 @@ import { Dispatcher } from "./component.js"
 import { ParametrisedProps } from "./types.js"
 
 export const parametriseDispatcher = (def: Partial<ParametrisedProps>, Com?: RoutedComponent<DispatcherProps> ) => {
-  console.log('Parametrising dispatcher with', def)
   return (props: ParametrisedProps) => {
-    console.log('Rendering parametrised dispatcher with', props)
     const _props = useMemo(() => {
       let payload: FlowPayload | undefined = undefined
       if (def.payload != null) {
@@ -20,7 +18,6 @@ export const parametriseDispatcher = (def: Partial<ParametrisedProps>, Com?: Rou
       }
       return { ...def, ...props, payload }
     }, [props])
-    console.log('Computed dispatcher props', _props)
     Com ??= Dispatcher
     return <Com {..._props} />
   }

package/src/components/dispatcher/types.ts

@@ -1,6 +1,6 @@
-import type { ModuleContextParams } from "@owlmeans/client"
+import type { EntrypointContextParams } from "@owlmeans/client"
 import type { DispatcherProps } from "@owlmeans/client-auth"
 import type { PropsWithChildren } from "react"
 
-export interface ParametrisedProps extends PropsWithChildren<ModuleContextParams & DispatcherProps> {
+export interface ParametrisedProps extends PropsWithChildren<EntrypointContextParams & DispatcherProps> {
 }

package/src/context.ts

@@ -22,8 +22,6 @@ export const makeContext = <C extends AppConfig = AppConfig, T extends AppContex
   appendWebRouter<C, T>(context)
   appendWebLogin<C, T>(context)
 
-  context.makeContext = makeContext as typeof context.makeContext
-
   return context
 }
 

package/src/entrypoints.ts

@@ -0,0 +1,20 @@
+import { authProtocols } from '@owlmeans/auth-common'
+import { entrypoints as authBindings } from '@owlmeans/client-auth'
+import { bindScreen } from '@owlmeans/client-entrypoint'
+import { handler } from '@owlmeans/client'
+import { Dispatcher } from './components/dispatcher/component.js'
+import { SurrogateScreen } from './login/screen.js'
+
+/**
+ * Bound here rather than in a relying-party package on purpose.
+ *
+ * The surrogate mechanic is not OIDC-specific — it is "run the login route one window up and hand
+ * the result back" — and every web application already spreads this list. Putting the screen here
+ * means `web-panel`, `mui-panel` and every generated target gain a working login window with no
+ * edit of their own, which is the only way an application that is already deployed can get it.
+ */
+export const entrypoints = [
+  ...authBindings,
+  bindScreen(authProtocols.dispatcher, handler(Dispatcher)),
+  bindScreen(authProtocols.surrogate, handler(SurrogateScreen)),
+]

package/src/exports.ts

@@ -1,9 +1,14 @@
 
-export { handler } from '@owlmeans/client'
+export {
+  handler, lazyHandler, lazyComponent, lazyRetryHelper, recoverFromChunkError,
+} from '@owlmeans/client'
+export type {
+  LazyComponent, LazyComponentOptions, LazyErrorRenderer, LazyHandler, LazyRetryHelper, RetryImportOptions
+} from '@owlmeans/client'
 export { config } from '@owlmeans/client-context'
 export { service } from '@owlmeans/config'
 export { AppType, HOME, ROOT, BASE, GUEST } from '@owlmeans/context'
-export { entrypoint, elevate, provideRequest, stab } from '@owlmeans/client-entrypoint'
+export { bind, bindAll, bindScreen, clientRequestHelper, provideRequest, stab } from '@owlmeans/client-entrypoint'
 export { route, frontend } from '@owlmeans/route'
 export type { ClientEntrypoint } from '@owlmeans/client-entrypoint'
 export type { ClientEntrypoint as Module } from '@owlmeans/client-entrypoint'

package/src/i18n/auth-be.json

@@ -2,5 +2,37 @@
   "dispatcher": {
     "loading": "Загрузка...",
     "error": "Не ўдалося прайсці аўтэнтыфікацыю: {{error}}"
+  },
+  "surrogate": {
+    "login": {
+      "working": "Выконваем уваход…",
+      "gesture": {
+        "title": "Працягніце, каб увайсці.",
+        "action": "Увайсці"
+      },
+      "handing": "Гатова. Вяртаемся ў праграму…",
+      "orphaned": "Уваход выкананы. Можаце закрыць гэтае акно і вярнуцца ў праграму.",
+      "failed": "Не ўдалося завяршыць. Закрыйце гэтае акно і паспрабуйце зноў.",
+      "standalone": {
+        "title": "Гэтая старонка выкарыстоўваецца для ўваходу з іншага акна.",
+        "action": "Адкрыць праграму"
+      },
+      "close": "Закрыць"
+    },
+    "logout": {
+      "working": "Выконваем выхад…",
+      "gesture": {
+        "title": "Працягніце, каб выйсці.",
+        "action": "Выйсці"
+      },
+      "handing": "Выхад выкананы. Вяртаемся ў праграму…",
+      "orphaned": "Выхад выкананы. Можаце закрыць гэтае акно.",
+      "failed": "Выхад тут не завершаны. Можаце закрыць гэтае акно.",
+      "standalone": {
+        "title": "Гэтая старонка выкарыстоўваецца для выхаду з іншага акна.",
+        "action": "Адкрыць праграму"
+      },
+      "close": "Закрыць"
+    }
   }
 }

package/src/i18n/auth-de.json

@@ -2,5 +2,37 @@
   "dispatcher": {
     "loading": "Wird geladen...",
     "error": "Authentifizierung fehlgeschlagen: {{error}}"
+  },
+  "surrogate": {
+    "login": {
+      "working": "Anmeldung läuft…",
+      "gesture": {
+        "title": "Fortfahren, um sich anzumelden.",
+        "action": "Anmelden"
+      },
+      "handing": "Fertig. Zurück zur Anwendung…",
+      "orphaned": "Angemeldet. Sie können dieses Fenster schließen und in der Anwendung fortfahren.",
+      "failed": "Das wurde nicht abgeschlossen. Schließen Sie dieses Fenster und versuchen Sie es erneut.",
+      "standalone": {
+        "title": "Diese Seite dient der Anmeldung aus einem anderen Fenster.",
+        "action": "Anwendung öffnen"
+      },
+      "close": "Schließen"
+    },
+    "logout": {
+      "working": "Abmeldung läuft…",
+      "gesture": {
+        "title": "Fortfahren, um sich abzumelden.",
+        "action": "Abmelden"
+      },
+      "handing": "Abgemeldet. Zurück zur Anwendung…",
+      "orphaned": "Abgemeldet. Sie können dieses Fenster schließen.",
+      "failed": "Die Abmeldung wurde hier nicht abgeschlossen. Sie können dieses Fenster schließen.",
+      "standalone": {
+        "title": "Diese Seite dient der Abmeldung aus einem anderen Fenster.",
+        "action": "Anwendung öffnen"
+      },
+      "close": "Schließen"
+    }
   }
 }

package/src/i18n/auth-en.json

@@ -2,5 +2,37 @@
   "dispatcher": {
     "loading": "Loading...",
     "error": "Authentication failed: {{error}}"
+  },
+  "surrogate": {
+    "login": {
+      "working": "Signing you in…",
+      "gesture": {
+        "title": "Continue to sign in.",
+        "action": "Sign in"
+      },
+      "handing": "Done. Returning to the application…",
+      "orphaned": "Signed in. You can close this window and continue in the application.",
+      "failed": "That did not complete. You can close this window and try again.",
+      "standalone": {
+        "title": "This page is used to sign in from another window.",
+        "action": "Open the application"
+      },
+      "close": "Close"
+    },
+    "logout": {
+      "working": "Signing you out…",
+      "gesture": {
+        "title": "Continue to sign out.",
+        "action": "Sign out"
+      },
+      "handing": "Signed out. Returning to the application…",
+      "orphaned": "Signed out. You can close this window.",
+      "failed": "Sign-out did not complete here. You can close this window.",
+      "standalone": {
+        "title": "This page is used to sign out from another window.",
+        "action": "Open the application"
+      },
+      "close": "Close"
+    }
   }
 }

package/src/i18n/auth-es.json

@@ -2,5 +2,37 @@
   "dispatcher": {
     "loading": "Cargando...",
     "error": "Error de autenticación: {{error}}"
+  },
+  "surrogate": {
+    "login": {
+      "working": "Iniciando sesión…",
+      "gesture": {
+        "title": "Continúa para iniciar sesión.",
+        "action": "Iniciar sesión"
+      },
+      "handing": "Listo. Volviendo a la aplicación…",
+      "orphaned": "Sesión iniciada. Puedes cerrar esta ventana y continuar en la aplicación.",
+      "failed": "No se completó. Cierra esta ventana e inténtalo de nuevo.",
+      "standalone": {
+        "title": "Esta página se usa para iniciar sesión desde otra ventana.",
+        "action": "Abrir la aplicación"
+      },
+      "close": "Cerrar"
+    },
+    "logout": {
+      "working": "Cerrando sesión…",
+      "gesture": {
+        "title": "Continúa para cerrar sesión.",
+        "action": "Cerrar sesión"
+      },
+      "handing": "Sesión cerrada. Volviendo a la aplicación…",
+      "orphaned": "Sesión cerrada. Puedes cerrar esta ventana.",
+      "failed": "El cierre de sesión no se completó aquí. Puedes cerrar esta ventana.",
+      "standalone": {
+        "title": "Esta página se usa para cerrar sesión desde otra ventana.",
+        "action": "Abrir la aplicación"
+      },
+      "close": "Cerrar"
+    }
   }
 }

package/src/i18n/auth-fr.json

@@ -0,0 +1,38 @@
+{
+  "dispatcher": {
+    "loading": "Chargement…",
+    "error": "Échec de l’authentification : {{error}}"
+  },
+  "surrogate": {
+    "login": {
+      "working": "Connexion en cours…",
+      "gesture": {
+        "title": "Continuez pour vous connecter.",
+        "action": "Se connecter"
+      },
+      "handing": "Terminé. Retour à l’application…",
+      "orphaned": "Vous êtes connecté. Vous pouvez fermer cette fenêtre et continuer dans l’application.",
+      "failed": "Cela n’a pas abouti. Vous pouvez fermer cette fenêtre et réessayer.",
+      "standalone": {
+        "title": "Cette page sert à vous connecter depuis une autre fenêtre.",
+        "action": "Ouvrir l’application"
+      },
+      "close": "Fermer"
+    },
+    "logout": {
+      "working": "Déconnexion en cours…",
+      "gesture": {
+        "title": "Continuez pour vous déconnecter.",
+        "action": "Se déconnecter"
+      },
+      "handing": "Déconnecté. Retour à l’application…",
+      "orphaned": "Vous êtes déconnecté. Vous pouvez fermer cette fenêtre.",
+      "failed": "La déconnexion n’a pas abouti ici. Vous pouvez fermer cette fenêtre.",
+      "standalone": {
+        "title": "Cette page sert à vous déconnecter depuis une autre fenêtre.",
+        "action": "Ouvrir l’application"
+      },
+      "close": "Fermer"
+    }
+  }
+}

package/src/i18n/auth-pl.json

@@ -2,5 +2,37 @@
   "dispatcher": {
     "loading": "Ładowanie...",
     "error": "Uwierzytelnianie nie powiodło się: {{error}}"
+  },
+  "surrogate": {
+    "login": {
+      "working": "Trwa logowanie…",
+      "gesture": {
+        "title": "Kontynuuj, aby się zalogować.",
+        "action": "Zaloguj się"
+      },
+      "handing": "Gotowe. Wracamy do aplikacji…",
+      "orphaned": "Zalogowano. Możesz zamknąć to okno i kontynuować w aplikacji.",
+      "failed": "Nie udało się ukończyć. Zamknij to okno i spróbuj ponownie.",
+      "standalone": {
+        "title": "Ta strona służy do logowania z innego okna.",
+        "action": "Otwórz aplikację"
+      },
+      "close": "Zamknij"
+    },
+    "logout": {
+      "working": "Trwa wylogowywanie…",
+      "gesture": {
+        "title": "Kontynuuj, aby się wylogować.",
+        "action": "Wyloguj się"
+      },
+      "handing": "Wylogowano. Wracamy do aplikacji…",
+      "orphaned": "Wylogowano. Możesz zamknąć to okno.",
+      "failed": "Wylogowanie nie zostało tu ukończone. Możesz zamknąć to okno.",
+      "standalone": {
+        "title": "Ta strona służy do wylogowania z innego okna.",
+        "action": "Otwórz aplikację"
+      },
+      "close": "Zamknij"
+    }
   }
 }

package/src/i18n/auth-ru.json

@@ -2,5 +2,37 @@
   "dispatcher": {
     "loading": "Загрузка...",
     "error": "Не удалось выполнить аутентификацию: {{error}}"
+  },
+  "surrogate": {
+    "login": {
+      "working": "Выполняем вход…",
+      "gesture": {
+        "title": "Продолжите, чтобы войти.",
+        "action": "Войти"
+      },
+      "handing": "Готово. Возвращаемся в приложение…",
+      "orphaned": "Вход выполнен. Можете закрыть это окно и вернуться в приложение.",
+      "failed": "Не удалось завершить. Закройте это окно и попробуйте снова.",
+      "standalone": {
+        "title": "Эта страница используется для входа из другого окна.",
+        "action": "Открыть приложение"
+      },
+      "close": "Закрыть"
+    },
+    "logout": {
+      "working": "Выполняем выход…",
+      "gesture": {
+        "title": "Продолжите, чтобы выйти.",
+        "action": "Выйти"
+      },
+      "handing": "Выход выполнен. Возвращаемся в приложение…",
+      "orphaned": "Выход выполнен. Можете закрыть это окно.",
+      "failed": "Выход здесь не завершён. Можете закрыть это окно.",
+      "standalone": {
+        "title": "Эта страница используется для выхода из другого окна.",
+        "action": "Открыть приложение"
+      },
+      "close": "Закрыть"
+    }
   }
 }

package/src/i18n/auth-uk.json

@@ -2,5 +2,37 @@
   "dispatcher": {
     "loading": "Завантаження...",
     "error": "Не вдалося пройти автентифікацію: {{error}}"
+  },
+  "surrogate": {
+    "login": {
+      "working": "Виконуємо вхід…",
+      "gesture": {
+        "title": "Продовжте, щоб увійти.",
+        "action": "Увійти"
+      },
+      "handing": "Готово. Повертаємось до застосунку…",
+      "orphaned": "Вхід виконано. Можете закрити це вікно й повернутися до застосунку.",
+      "failed": "Не вдалося завершити. Закрийте це вікно та спробуйте ще раз.",
+      "standalone": {
+        "title": "Ця сторінка використовується для входу з іншого вікна.",
+        "action": "Відкрити застосунок"
+      },
+      "close": "Закрити"
+    },
+    "logout": {
+      "working": "Виконуємо вихід…",
+      "gesture": {
+        "title": "Продовжте, щоб вийти.",
+        "action": "Вийти"
+      },
+      "handing": "Вихід виконано. Повертаємось до застосунку…",
+      "orphaned": "Вихід виконано. Можете закрити це вікно.",
+      "failed": "Вихід тут не завершено. Можете закрити це вікно.",
+      "standalone": {
+        "title": "Ця сторінка використовується для виходу з іншого вікна.",
+        "action": "Відкрити застосунок"
+      },
+      "close": "Закрити"
+    }
   }
 }

package/src/i18n.ts

@@ -1,4 +1,4 @@
-import { addI18nLib } from '@owlmeans/i18n'
+import { i18nHelper } from '@owlmeans/i18n'
 
 import authEn from './i18n/auth-en.json' with { type: 'json' }
 import authPl from './i18n/auth-pl.json' with { type: 'json' }
@@ -7,11 +7,13 @@ import authBe from './i18n/auth-be.json' with { type: 'json' }
 import authUk from './i18n/auth-uk.json' with { type: 'json' }
 import authEs from './i18n/auth-es.json' with { type: 'json' }
 import authDe from './i18n/auth-de.json' with { type: 'json' }
+import authFr from './i18n/auth-fr.json' with { type: 'json' }
 
-addI18nLib('en', 'auth', authEn)
-addI18nLib('pl', 'auth', authPl)
-addI18nLib('ru', 'auth', authRu)
-addI18nLib('be', 'auth', authBe)
-addI18nLib('uk', 'auth', authUk)
-addI18nLib('es', 'auth', authEs)
-addI18nLib('de', 'auth', authDe)
+i18nHelper.addI18nLib('en', 'auth', authEn)
+i18nHelper.addI18nLib('pl', 'auth', authPl)
+i18nHelper.addI18nLib('ru', 'auth', authRu)
+i18nHelper.addI18nLib('be', 'auth', authBe)
+i18nHelper.addI18nLib('uk', 'auth', authUk)
+i18nHelper.addI18nLib('es', 'auth', authEs)
+i18nHelper.addI18nLib('de', 'auth', authDe)
+i18nHelper.addI18nLib('fr', 'auth', authFr)

package/src/index.ts

@@ -4,7 +4,7 @@ export * from './types.js'
 export * from './main.js'
 export * from './router.js'
 export * from './components/index.js'
-export * from './modules.js'
+export * from './entrypoints.js'
 export * from './exports.js'
 export * from './context.js'
 export * from './helper.js'

package/src/login/consts.local.ts

@@ -0,0 +1,52 @@
+import type { CSSProperties } from 'react'
+import { SurrogateStage } from './consts.js'
+
+/**
+ * The whole of what a login window shows.
+ *
+ * Plain elements and inline styles on purpose. This renders in a popup opened by a `web-panel` app,
+ * a `mui-panel` app and a generated Tailwind app alike, and none of their stylesheets is loaded
+ * here — a class name would simply do nothing. It is also the reason this component carries no
+ * dependency on a UI family at all.
+ */
+export const box: CSSProperties = {
+  maxWidth: '22rem', margin: '15vh auto', padding: '1.5rem', textAlign: 'center',
+  fontFamily: 'system-ui, sans-serif', lineHeight: 1.5,
+}
+
+export const action: CSSProperties = {
+  marginTop: '1rem', padding: '.625rem 1.25rem', fontSize: '1rem',
+  cursor: 'pointer', borderRadius: '.375rem', border: '1px solid currentColor',
+}
+
+export const COPY: Record<SurrogateStage, { key: string, en: string, action?: [string, string] }> = {
+  [SurrogateStage.Working]: { key: 'working', en: 'Signing you in…' },
+  [SurrogateStage.Gesture]: {
+    key: 'gesture.title', en: 'Continue to sign in.', action: ['gesture.action', 'Sign in'],
+  },
+  [SurrogateStage.Handing]: { key: 'handing', en: 'Done. Returning to the application…' },
+  [SurrogateStage.Orphaned]: {
+    key: 'orphaned', en: 'Signed in. You can close this window and continue in the application.',
+    action: ['close', 'Close'],
+  },
+  [SurrogateStage.Failed]: {
+    key: 'failed', en: 'That did not complete. You can close this window and try again.',
+    action: ['close', 'Close'],
+  },
+  [SurrogateStage.Standalone]: {
+    key: 'standalone.title', en: 'This page is used to sign in from another window.',
+    action: ['standalone.action', 'Open the application'],
+  },
+}
+
+export const LOGOUT_COPY: Partial<Record<SurrogateStage, { key: string, en: string }>> = {
+  [SurrogateStage.Working]: { key: 'working', en: 'Signing you out…' },
+  [SurrogateStage.Gesture]: { key: 'gesture.title', en: 'Continue to sign out.' },
+  [SurrogateStage.Handing]: { key: 'handing', en: 'Signed out. Returning to the application…' },
+  [SurrogateStage.Orphaned]: {
+    key: 'orphaned', en: 'Signed out. You can close this window.',
+  },
+  [SurrogateStage.Failed]: {
+    key: 'failed', en: 'Sign-out did not complete here. You can close this window.',
+  },
+}

package/src/login/consts.ts

@@ -10,3 +10,41 @@ export const SURROGATE_LOGIN = 'owlmeans-surrogate-login'
  * ordinary tab.
  */
 export const SURROGATE_LOGIN_PRIORITY = 100
+
+/** What the surrogate window is doing, from the point of view of the person watching it. */
+export enum SurrogateStage {
+  /** Working. No control — there is nothing for the user to do but wait. */
+  Working = 'working',
+  /** Needs a click: the flow cannot continue without a fresh gesture. */
+  Gesture = 'gesture',
+  /** Done here; handing the result back and closing. */
+  Handing = 'handing',
+  /** Acted, but with no channel back to the window that asked. */
+  Orphaned = 'orphaned',
+  /** Ended with nothing. */
+  Failed = 'failed',
+  /** Not a surrogate at all — someone opened this address directly. */
+  Standalone = 'standalone',
+}
+
+/**
+ * The login window an embedded application opens one level up.
+ *
+ * It is NOT wrapped in `DispatcherHOC`, and that is the point: the HOC's continuation navigates to
+ * `HOME` when it has nothing else to do, which is how a popup ended up rendering the whole
+ * application, with its navigation, inside itself. This screen has no continuation at all — it
+ * either hands something back and closes, or it says what it is waiting for.
+ *
+ * It also never runs the authorization machine itself: it forwards to the dispatcher (`next`),
+ * which owns that flow, and hands back what the dispatcher issued — see {@link surrogateLoginStep}
+ * for why a session already stored in this window is not simply handed back.
+ */
+/** What a surrogate window opened to SIGN IN does with the session it may already hold. */
+export enum SurrogateLoginStep {
+  /** Drop the stored session and authenticate afresh through the dispatcher. */
+  Forget = 'forget',
+  /** Hand the stored session to the opener — there is no dispatcher to authenticate through. */
+  Resume = 'resume',
+  /** Nothing stored: authenticate through the dispatcher. */
+  Authenticate = 'authenticate',
+}

package/src/login/index.ts

@@ -1,4 +1,8 @@
 export * from './consts.js'
+export * from './pump.js'
 export * from './redirect.js'
 export * from './surrogate.js'
+export * from './view.js'
+export type * from './types.js'
+export * from './screen.js'
 export * from './service.js'