@owlmeans/web-client 0.1.18-rc.6 → 0.1.18-rc.61

package/README.md

@@ -1,81 +1,285 @@
 # @owlmeans/web-client
 
-React web application bootstrap — context factory, module/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 module/routing helpers: `module`, `route`, `frontend`, `handler`, `elevate`
-- Re-exports route constants: `BASE`, `HOME`, `ROOT`, `GUEST`
-- `Module<T>` — typed client module interface for `.call()` API requests
+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
+bun add @owlmeans/web-client@^0.1.18-rc.61
 ```
 
+## 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
 
-```typescript
-import { makeContext, renderApp } from '@owlmeans/web-client'
+```ts
+// src/types.ts
+import type { AppConfig, AppContext } from '@owlmeans/web-client'
 
-const context = makeContext(config)
-context.registerModules(appModules)
-context.serviceRoute(MANAGER, true)
-renderApp<Config, Context>(context)
+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>)
 ```
 
-Define modules:
+```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>()
 
-```typescript
-import { BASE, HOME, elevate, frontend, handler, module, route } from '@owlmeans/web-client'
+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)
 
-modules.push(module(route(BASE, '/', frontend()), handler(PublicLayout)))
-modules.push(module(route(HOME, '/', frontend({ default: true, parent: BASE })), handler(HomeScreen)))
-elevate(modules, manager.back.account.base)
+  return context
+}
 ```
 
-Call an API module from a component:
+### 2. Shared screen declarations and the entrypoint list
+
+Screens are declared once in the shared package, next to the API protocols:
 
-```typescript
-import type { Module } from '@owlmeans/web-client'
+```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'
 
-const [result] = await context.module<Module<MyType>>(moduleAlias)
-  .call({ params: { id }, body: data })
+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 }))),
+}
 ```
 
-## API
+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(MY_APP_WEB, true)
+context.serviceRoute(MY_APP_API, true)
 
-### `makeContext<C, T>(cfg): T`
+// The third argument is the global overlay slot — rendered above the router, never torn down.
+renderApp(context, undefined, <AppOverlays />)
+```
+
+`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
 
-Creates a web app context. Automatically registers web router, IndexedDB, and auth services.
+```ts
+// src/screens/project.vm.ts
+import { EntrypointOutcome } from '@owlmeans/entrypoint'
+import { apiProtocols, webProtocols } from 'my-app-common'
+import type { Context } from '../types.js'
 
-### `renderApp<C, T>(context): void`
+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 } })
 
-Renders the React application to the DOM using the provided context.
+  // 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 }
+  }
 
-### `useContext<C, T>(): T`
+  // A screen is addressed, never called.
+  const shareUrl = await ctx.entrypoint(webProtocols.project).url({ params: { id } }, { absolute: true })
 
-React hook to access the current application context.
+  return { project, slot, shareUrl }
+}
+```
 
-### `makeAuthWebService(alias?)`, `appendWebAuthService(ctx, alias?)`
+### 5. File drop target
 
-Auth service factory and appender — adds logout redirect handling for web environments.
+`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.
 
-### `Dispatcher`
+```tsx
+import type { FC } from 'react'
+import { ImageUploader } from '@owlmeans/web-client'
 
-Component that handles authentication routing (redirect to login, etc.).
+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>
+```
 
-## Related Packages
+## API
 
+### 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` |
+
+### Entrypoints and authentication screens
+
+| 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 |
+
+### Components
+
+| 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 |
+
+### Re-exports
+
+| Symbol | From |
+|---|---|
+| `handler` | `@owlmeans/client` |
+| `config` | `@owlmeans/client-context` |
+| `service` | `@owlmeans/config` |
+| `AppType`, `HOME`, `ROOT`, `BASE`, `GUEST` | `@owlmeans/context` |
+| `bind`, `bindAll`, `bindScreen`, `clientRequestHelper`, `provideRequest` (deprecated, use `clientRequestHelper.provideRequest`), `stab`; types `ClientEntrypoint`, `Module` | `@owlmeans/client-entrypoint` |
+| `route`, `frontend` | `@owlmeans/route` |
+| type `Route` (`ClientRoute`) | `@owlmeans/client-route` |
+
+Importing the package also registers the `auth` library i18n namespace in all seven supported
+languages.
+
+## Common pitfalls
+
+- **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
+
+- [`@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-module`](../client-module) — `ClientModule<T>` / `Module<T>` implementation
+- [`@owlmeans/web-oidc-rp`](../web-oidc-rp) — OIDC relying party with its own dispatcher
 
 <!-- owlmeans:agent-guidance:start -->
 ## Agent guidance
@@ -85,7 +289,7 @@ This package ships embedded agent skills under `agent-meta/`. After installing y
 your project's skill store (`.agents/skills/`):
 
 ```sh
-npx @owlmeans/agent-skills
+npx @owlmeans/agent-skills@^0.1.18-rc.49
 ```
 
 The embedded files are version-matched to this package release. Do not edit them

package/agent-meta/manifest.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 2,
   "package": "@owlmeans/web-client",
-  "version": "0.1.18-rc.6",
-  "generatedAt": "2026-08-18T14:48:00.525Z",
+  "version": "0.1.18-rc.61",
+  "generatedAt": "2026-10-05T21:03:06.394Z",
   "canonicalRepo": "https://github.com/owlmeans/common",
   "entries": [
     {

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

@@ -1,59 +1,83 @@
 ---
 name: web-client
-description: How to use @owlmeans/web-client — browser entry point with renderApp(), elevate() to attach React components to entrypoint declarations, context.registerEntrypoints() and context.serviceRoute() for routing. Auto-invoked when working with the web app entry point or attaching React components to entrypoints.
-user-invocable: false
+description: Bind OwlMeans shared entrypoint protocols in a browser application. Use when registering client routes, attaching React screens (including lazily-loaded ones), calling API protocols, or configuring the browser context.
 ---
 <!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
 
-# @owlmeans/web-client
-
-**Layer:** Web (React)
-**Install:** `"@owlmeans/web-client": "^0.1.18-rc.6"` in `dependencies`
-
-## Key Exports
-
-| Export | Description |
-|--------|-------------|
-| `renderApp<C, T>(context)` | Mount the React app (routing via the active router plugin — OwlMeans by default) |
-| `elevate(modules, alias, handler)` | Attach a React component (or `handler(Component)`) to an entrypoint |
-| `handler(Component)` | Wrap a React component as an entrypoint handler |
-| `context.registerEntrypoints(modules)` | Register the full entrypoint list on the context |
-| `context.serviceRoute(alias, isDefault?)` | Mark a service's routing root |
-| `router`, `components`, `service`, `i18n`, `helpers`, `errors` | Web-specific helpers |
-| Constants | Default aliases (BASE, HOME) |
-
-## Usage
-
-### Entry point
-```typescript
-// index.tsx
-import { renderApp } from '@owlmeans/web-client'
-import { makeContext } from './context.js'
-import { appModules } from './modules.js'
-import { MANAGER, MANAGER_API } from 'my-common'
-import config from './config.js'
-
-const context = makeContext(config)
-context.registerEntrypoints(appModules)
-context.serviceRoute(MANAGER, true)
-context.serviceRoute(MANAGER_API, true)
-renderApp<Config, Context>(context)
+# Browser protocol entrypoints
+
+**Install:** `bun add @owlmeans/web-client@^0.1.18-rc.61`
+
+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 { projectProtocols, webProtocols } from 'project-common'
+import { ProjectScreen } from './screens/project.js'
+
+export const clientBindings = [
+  ...frameworkEntrypoints,
+  ...bindAll(projectProtocols),
+  bindScreen(webProtocols.project, handler(ProjectScreen)),
+]
 ```
 
-### Module elevation with React components
-```typescript
-import { elevate, route, frontend, handler, entrypoint, guard } from '@owlmeans/web-client'
-import { HomeScreen, ProjectDashboardScreen } from './screens/index.js'
+Call a protocol directly. Its request and response types come from its shared contract.
+
+```ts
+const project = await context.entrypoint(projectProtocols.get).call({
+  params: { id: projectId },
+})
+```
+
+## Lazily-loaded screens
+
+`lazyHandler` and `lazyComponent` (from `@owlmeans/client`) are re-exported here and by
+`@owlmeans/web-panel`, next to `handler`; so are, here only, the chunk-failure tools of
+`lazyRetryHelper` — `retryImport`, `isChunkLoadError`, `reloadOnce` and `recoverFromChunkError` (types
+`LazyErrorRenderer`, `RetryImportOptions`). A `lazyHandler(...)` result binds exactly like
+`handler(Component)`; declare it at module scope, where the bindings live — never inside a render.
+
+```tsx
+import { bindScreen, lazyHandler } from '@owlmeans/web-client'
+
+const reportsScreen = lazyHandler(() => import('./screens/reports.js'), 'ReportsScreen', {
+  fallback: <Spinner />,
+})
+
+export const clientBindings = [
+  bindScreen(webProtocols.reports, reportsScreen),
+]
+// reportsScreen.preload() on hover/focus of a link renders the screen without its fallback.
+```
+
+The fallback renders inside the screen's own `Suspense` boundary, so the layout around it stays
+mounted while the chunk loads, and the screen's own error boundary keeps a failed chunk from
+unmounting it: a fetch failure is retried, then `error` renders — or, without one, the guarded
+reload starts. Rules and options: the `client` skill, Code-splitting and Chunk failures.
+
+## Rendering after an async boot
+
+If your app awaits something (e.g. `i18nInstanceHelper.prepareI18n`) before calling `render()`, this is handled
+correctly — the render helper checks `document.readyState` rather than unconditionally waiting for
+an event that may already have fired. It waits for `DOMContentLoaded` only while the document is
+still `loading` and mounts at once otherwise; `renderApp` and `@owlmeans/web-panel`'s `render` both
+go through it.
 
-elevate(modules, manager.front.project.dashboard, handler(ProjectDashboardScreen))
+```ts
+import { i18nInstanceHelper } from '@owlmeans/client-i18n'
 
-modules.push(
-  entrypoint(route(HOME, '/', frontend({ default: true, parent: BASE })), handler(HomeScreen))
-)
+await i18nInstanceHelper.prepareI18n(context.cfg)
+renderApp(context)            // or @owlmeans/web-panel's render(context)
 ```
 
-## Depends On
+## Rules
 
-- `@owlmeans/client`, `@owlmeans/web-router` (default OwlMeans browser routing), `@owlmeans/web-panel` (typically), `@owlmeans/client-i18n`
-- `@owlmeans/entrypoint`, `@owlmeans/route`
-- `react`, `react-dom` (peer). No longer depends on `react-router` — opt into it with `@owlmeans/web-router-react-router` (`appendReactRouter`). The former `provide` export is a deprecated `undefined`.
+- Declare paths, guards, gates and contracts once in the shared protocol tree.
+- Bind every API declaration the browser calls, including route parents.
+- Use `bindScreen(protocol, handler(Component))` — or `lazyHandler(...)` — only for frontend route
+  declarations.
+- Do not replace request/response typing at a call site; update the shared contract instead.
+- Keep framework entrypoints and application entrypoints in one registered array, without mutating a
+  shared declaration collection.

package/build/components/dispatcher/component.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"component.d.ts","sourceRoot":"","sources":["../../../src/components/dispatcher/component.tsx"],"names":[],"mappings":"AAMA,eAAO,MAAM,UAAU,6FAmCrB,CAAA"}
+{"version":3,"file":"component.d.ts","sourceRoot":"","sources":["../../../src/components/dispatcher/component.tsx"],"names":[],"mappings":"AASA,eAAO,MAAM,UAAU,6FA+FrB,CAAA"}

package/build/components/dispatcher/component.js

@@ -1,14 +1,28 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 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(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 = {};
@@ -18,15 +32,47 @@ export const Dispatcher = DispatcherHOC(({ provideToken }) => {
                 }
             });
             provideToken({ token }, params);
+            return;
         }
-        else {
-            context.auth().authenticated().then(authzToken => {
-                if (authzToken == null) {
-                    provideToken({ token: '' }, undefined);
-                }
-            });
-        }
+        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 _jsx(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 _jsx(Screen, { translate: (key, defaultValue) => tAuth(key, { defaultValue }) });
+    }
     return query.has(AUTH_QUERY) ? _jsx("div", { style: {
             width: '100%', // Makes the div occupy the full width
             display: 'flex', // Enables flexbox layout

package/build/components/dispatcher/component.js.map

@@ -1 +1 @@
-{"version":3,"file":"component.js","sourceRoot":"","sources":["../../../src/components/dispatcher/component.tsx"],"names":[],"mappings":";AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAA;AACrD,OAAO,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AACjC,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAA;AAClD,OAAO,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAA;AAC3C,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAE7C,MAAM,CAAC,MAAM,UAAU,GAAG,aAAa,CAAC,CAAC,EAAE,YAAY,EAAE,EAAE,EAAE;IAC3D,MAAM,OAAO,GAAG,UAAU,EAAE,CAAA;IAC5B,MAAM,CAAC,KAAK,CAAC,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,eAAe,EAAE,CAAA;IAElD,MAAM,CAAC,GAAG,UAAU,CAAC,MAAM,EAAE,YAAY,CAAC,CAAA;IAE1C,SAAS,CAAC,GAAG,EAAE;QACb,MAAM,KAAK,GAAG,KAAK,CAAC,GAAG,CAAC,UAAU,CAAC,CAAA;QACnC,IAAI,KAAK,IAAI,IAAI,EAAE,CAAC;YAClB,MAAM,MAAM,GAA2B,EAAE,CAAA;YACzC,KAAK,CAAC,OAAO,CAAC,CAAC,KAAK,EAAE,GAAG,EAAE,EAAE;gBAC3B,IAAI,GAAG,KAAK,UAAU,EAAE,CAAC;oBACvB,MAAM,CAAC,GAAG,CAAC,GAAG,KAAK,CAAA;gBACrB,CAAC;YACH,CAAC,CAAC,CAAA;YAEF,YAAY,CAAC,EAAE,KAAK,EAAE,EAAE,MAAM,CAAC,CAAA;QACjC,CAAC;aAAM,CAAC;YACN,OAAO,CAAC,IAAI,EAAE,CAAC,aAAa,EAAE,CAAC,IAAI,CAAC,UAAU,CAAC,EAAE;gBAC/C,IAAI,UAAU,IAAI,IAAI,EAAE,CAAC;oBACvB,YAAY,CAAC,EAAE,KAAK,EAAE,EAAE,EAAE,EAAE,SAAS,CAAC,CAAA;gBACxC,CAAC;YACH,CAAC,CAAC,CAAA;QACJ,CAAC;IACH,CAAC,EAAE,EAAE,CAAC,CAAA;IAEN,OAAO,KAAK,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,cAAK,KAAK,EAAE;YACzC,KAAK,EAAE,MAAM,EAAE,sCAAsC;YACrD,OAAO,EAAE,MAAM,EAAE,yBAAyB;YAC1C,cAAc,EAAE,QAAQ,EAAE,+BAA+B;YACzD,UAAU,EAAE,QAAQ,EAAE,yCAAyC;YAC/D,SAAS,EAAE,QAAQ,EAAE,8BAA8B;YACnD,UAAU,EAAE,MAAM,EAAE,6BAA6B;YACjD,aAAa,EAAE,MAAM,EAAE,6BAA6B;SACrD,YAAG,CAAC,CAAC,SAAS,CAAC,GAAO,CAAC,CAAC,CAAC,SAAS,CAAA;AACrC,CAAC,CAAC,CAAA"}
+{"version":3,"file":"component.js","sourceRoot":"","sources":["../../../src/components/dispatcher/component.tsx"],"names":[],"mappings":"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"}

package/build/components/dispatcher/parametrise.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"parametrise.d.ts","sourceRoot":"","sources":["../../../src/components/dispatcher/parametrise.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAA;AACvD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAA;AAI5D,OAAO,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAA;AAE9C,eAAO,MAAM,qBAAqB,QAAS,OAAO,CAAC,iBAAiB,CAAC,QAAQ,eAAe,CAAC,eAAe,CAAC,aAE5F,iBAAiB,gCAiBjC,CAAA"}
+{"version":3,"file":"parametrise.d.ts","sourceRoot":"","sources":["../../../src/components/dispatcher/parametrise.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAA;AACvD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAA;AAI5D,OAAO,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAA;AAE9C,eAAO,MAAM,qBAAqB,QAAS,OAAO,CAAC,iBAAiB,CAAC,QAAQ,eAAe,CAAC,eAAe,CAAC,aAC5F,iBAAiB,gCAejC,CAAA"}

package/build/components/dispatcher/parametrise.js

@@ -2,9 +2,7 @@ import { jsx as _jsx } from "react/jsx-runtime";
 import { useMemo } from "react";
 import { Dispatcher } from "./component.js";
 export const parametriseDispatcher = (def, Com) => {
-    console.log('Parametrising dispatcher with', def);
     return (props) => {
-        console.log('Rendering parametrised dispatcher with', props);
         const _props = useMemo(() => {
             let payload = undefined;
             if (def.payload != null) {
@@ -16,7 +14,6 @@ export const parametriseDispatcher = (def, Com) => {
             }
             return { ...def, ...props, payload };
         }, [props]);
-        console.log('Computed dispatcher props', _props);
         Com ??= Dispatcher;
         return _jsx(Com, { ..._props });
     };

package/build/components/dispatcher/parametrise.js.map

@@ -1 +1 @@
-{"version":3,"file":"parametrise.js","sourceRoot":"","sources":["../../../src/components/dispatcher/parametrise.tsx"],"names":[],"mappings":";AAGA,OAAO,EAAE,OAAO,EAAE,MAAM,OAAO,CAAA;AAC/B,OAAO,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAA;AAG3C,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,GAA+B,EAAE,GAAsC,EAAG,EAAE;IAChH,OAAO,CAAC,GAAG,CAAC,+BAA+B,EAAE,GAAG,CAAC,CAAA;IACjD,OAAO,CAAC,KAAwB,EAAE,EAAE;QAClC,OAAO,CAAC,GAAG,CAAC,wCAAwC,EAAE,KAAK,CAAC,CAAA;QAC5D,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,EAAE;YAC1B,IAAI,OAAO,GAA4B,SAAS,CAAA;YAChD,IAAI,GAAG,CAAC,OAAO,IAAI,IAAI,EAAE,CAAC;gBACxB,OAAO,GAAG,GAAG,CAAC,OAAO,CAAA;YACvB,CAAC;YACD,IAAI,KAAK,CAAC,OAAO,IAAI,IAAI,EAAE,CAAC;gBAC1B,OAAO,KAAK,EAAE,CAAA;gBACd,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,KAAK,CAAC,OAAO,CAAC,CAAA;YACvC,CAAC;YACD,OAAO,EAAE,GAAG,GAAG,EAAE,GAAG,KAAK,EAAE,OAAO,EAAE,CAAA;QACtC,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,CAAA;QACX,OAAO,CAAC,GAAG,CAAC,2BAA2B,EAAE,MAAM,CAAC,CAAA;QAChD,GAAG,KAAK,UAAU,CAAA;QAClB,OAAO,KAAC,GAAG,OAAK,MAAM,GAAI,CAAA;IAC5B,CAAC,CAAA;AACH,CAAC,CAAA"}
+{"version":3,"file":"parametrise.js","sourceRoot":"","sources":["../../../src/components/dispatcher/parametrise.tsx"],"names":[],"mappings":";AAGA,OAAO,EAAE,OAAO,EAAE,MAAM,OAAO,CAAA;AAC/B,OAAO,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAA;AAG3C,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,GAA+B,EAAE,GAAsC,EAAG,EAAE;IAChH,OAAO,CAAC,KAAwB,EAAE,EAAE;QAClC,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,EAAE;YAC1B,IAAI,OAAO,GAA4B,SAAS,CAAA;YAChD,IAAI,GAAG,CAAC,OAAO,IAAI,IAAI,EAAE,CAAC;gBACxB,OAAO,GAAG,GAAG,CAAC,OAAO,CAAA;YACvB,CAAC;YACD,IAAI,KAAK,CAAC,OAAO,IAAI,IAAI,EAAE,CAAC;gBAC1B,OAAO,KAAK,EAAE,CAAA;gBACd,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,KAAK,CAAC,OAAO,CAAC,CAAA;YACvC,CAAC;YACD,OAAO,EAAE,GAAG,GAAG,EAAE,GAAG,KAAK,EAAE,OAAO,EAAE,CAAA;QACtC,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,CAAA;QACX,GAAG,KAAK,UAAU,CAAA;QAClB,OAAO,KAAC,GAAG,OAAK,MAAM,GAAI,CAAA;IAC5B,CAAC,CAAA;AACH,CAAC,CAAA"}

package/build/components/dispatcher/types.d.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> {
 }
 //# sourceMappingURL=types.d.ts.map

package/build/components/dispatcher/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/components/dispatcher/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAA;AAC3D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAA;AAC5D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,OAAO,CAAA;AAE9C,MAAM,WAAW,iBAAkB,SAAQ,iBAAiB,CAAC,mBAAmB,GAAG,eAAe,CAAC;CAClG"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/components/dispatcher/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,kBAAkB,CAAA;AAC/D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAA;AAC5D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,OAAO,CAAA;AAE9C,MAAM,WAAW,iBAAkB,SAAQ,iBAAiB,CAAC,uBAAuB,GAAG,eAAe,CAAC;CACtG"}