@owlmeans/client-flow 0.1.18-rc.33 → 0.1.18-rc.35

package/README.md

@@ -12,7 +12,7 @@ Client-side flow orchestration service for managing multi-step workflows in brow
 ## Installation
 
 ```bash
-bun add @owlmeans/client-flow@^0.1.18-rc.33
+bun add @owlmeans/client-flow@^0.1.18-rc.35
 ```
 
 ## Usage
@@ -75,7 +75,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@^0.1.18-rc.28
+npx @owlmeans/agent-skills@^0.1.18-rc.30
 ```
 
 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/client-flow",
-  "version": "0.1.18-rc.33",
-  "generatedAt": "2026-09-17T08:16:11.177Z",
+  "version": "0.1.18-rc.35",
+  "generatedAt": "2026-09-19T13:42:56.208Z",
   "canonicalRepo": "https://github.com/owlmeans/common",
   "entries": [
     {

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

@@ -1,6 +1,6 @@
 ---
 name: client-flow
-description: How to use @owlmeans/client-flow — the platform-agnostic flow service (makeBasicFlowService) that loads @owlmeans/flow definitions from config records, and createFlowClient(context, nav), the runner a screen drives to advance a flow and navigate to each step. Auto-invoked when importing client flow primitives, registering a flow service, or moving a screen to the next flow step.
+description: How to use @owlmeans/client-flow — the platform-agnostic flow service (makeBasicFlowService) that loads @owlmeans/flow definitions from config records, createFlowClient(context, nav), the runner a screen drives to advance a flow and navigate to each step, and suspendFlow/resumeSuspendedFlow, the side-band landing that returns a person to where they started after sign-in. Auto-invoked when importing client flow primitives, registering a flow service, or moving a screen to the next flow step.
 user-invocable: false
 ---
 <!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
@@ -8,7 +8,7 @@ user-invocable: false
 # @owlmeans/client-flow
 
 **Layer:** Client
-**Install:** `"@owlmeans/client-flow": "^0.1.18-rc.33"` in `dependencies`
+**Install:** `"@owlmeans/client-flow": "^0.1.18-rc.35"` in `dependencies`
 
 Two objects, with different lifetimes. The **service** lives on the context and owns the flow
 definitions and the one live `FlowModel`. The **client** is built per screen, wraps that model with
@@ -26,6 +26,8 @@ a `Navigator`, and is what a component actually calls.
 | `ResolvePair` | The `{ resolve, reject }` behind `service.supplied` |
 | `DEFAULT_ALIAS` (`flow`) | The service alias |
 | `FLOW_STATE` (`state:flow`) | Alias of the client resource the state is persisted in, and the record id inside it |
+| `suspendFlow(context, model, { expiresAt })` · `resumeSuspendedFlow(context)` · `RESUME_FLOW` (`resume-flow`) | The suspended landing: park where a flow was headed before sign-in, read it back once after |
+| `SuspendedLanding` `{ entrypoint, query }` · `SuspendedLandingRecord` | What resumes / what is stored |
 | `EXTRA_FLOW` (`extra-flow`) · `REHACK_MOD` (`__redirect`) | Id of the second, side-band state record kept in the same resource, and the alias of the entrypoint synthesized to address a target service |
 
 ## Wiring
@@ -117,6 +119,31 @@ to the service's own `proceed`.
 `persist()` saves the state under `FLOW_STATE` and answers `false` when no such resource is
 registered, so persistence is opt-in rather than a hard requirement.
 
+## The suspended landing returns a person to where they started
+
+The single live `FlowService.flow`, the `?flow=` query parameter on `/dispatcher` and the `FLOW_STATE`
+record all belong to the OIDC sign-in machinery, so a flow that must leave for sign-in and come back
+(an OAuth consent screen reached by a signed-out person) cannot use them. It parks a **landing** in a
+side-band record under `RESUME_FLOW` in the same `FLOW_STATE` resource — the `EXTRA_FLOW` precedent —
+which is IndexedDB in a browser and so survives a full-page Google round trip.
+
+- `suspendFlow(context, model, { expiresAt })` asks the model's own `next()` where the current step
+  leads and stores that destination step's **`module`** (an entrypoint alias), the model's `payload()`
+  as `query`, and `expiresAt` (epoch ms). It answers `false` — and stores nothing — when `FLOW_STATE`
+  is not registered, the step has no forward transition, or the destination has no `module`; the
+  caller then lands on `HOME` as before. The record is not a serialized flow token: the destination
+  is a screen the app can enter fresh, reading its own parameters from the query.
+- `resumeSuspendedFlow(context)` returns `{ entrypoint, query }` or `null`, and is **delete-on-read** —
+  a landing answers exactly one sign-in, so a stale tab's record never resurrects on someone else's
+  later sign-in. `null` covers no resource, no record, a failed read and an expired record.
+- **Destinations are entrypoint aliases from a registered flow definition, never stored URLs**, so a
+  landing cannot become an open redirect. Consumers navigate to the alias with the query.
+
+Every sign-in completion asks `resumeSuspendedFlow` before it navigates home: `DispatcherHOC`'s HOME
+branch (`@owlmeans/client-auth`, so the `/dispatcher?token=` and resume paths are covered) and the
+supervisor and Google login plugins (`web-auth`, `web-oidc-rp`) — see [[login-plugins]].
+`bun test ./tests` covers suspend, resume, expiry and the empty cases.
+
 ## Depends On
 
 - `@owlmeans/flow` — the definitions, the model and the error family

package/build/index.d.ts

@@ -2,4 +2,5 @@ export type * from './types.js';
 export * from './consts.js';
 export * from './client.js';
 export * from './service.js';
+export * from './landing.js';
 //# sourceMappingURL=index.d.ts.map

package/build/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,mBAAmB,YAAY,CAAA;AAC/B,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA;AAC3B,cAAc,cAAc,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,mBAAmB,YAAY,CAAA;AAC/B,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA;AAC3B,cAAc,cAAc,CAAA;AAC5B,cAAc,cAAc,CAAA"}

package/build/index.js

@@ -1,4 +1,5 @@
 export * from './consts.js';
 export * from './client.js';
 export * from './service.js';
+export * from './landing.js';
 //# sourceMappingURL=index.js.map

package/build/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA;AAC3B,cAAc,cAAc,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA;AAC3B,cAAc,cAAc,CAAA;AAC5B,cAAc,cAAc,CAAA"}

package/build/landing.d.ts

@@ -0,0 +1,48 @@
+import type { ClientContext } from '@owlmeans/client';
+import type { ClientConfig } from '@owlmeans/client-context';
+import type { ResourceRecord } from '@owlmeans/resource';
+import type { FlowModel, FlowPayload } from '@owlmeans/flow';
+/** The record id a suspended landing is stored under, in the SAME resource `EXTRA_FLOW` uses —
+ * a side-band slot, never the live `FlowService.flow` and never the `?flow=` query parameter. */
+export declare const RESUME_FLOW = "resume-flow";
+export interface SuspendedLandingRecord extends ResourceRecord {
+    /** The entrypoint alias to navigate to once sign-in completes. */
+    entrypoint: string;
+    /** The flow's payload at the moment it was suspended — carried along as the destination's query. */
+    query: FlowPayload;
+    expiresAt: number;
+}
+export interface SuspendedLanding {
+    entrypoint: string;
+    query: FlowPayload;
+}
+/**
+ * Suspend a flow that is about to leave for the platform's own sign-in dispatcher, so whichever
+ * sign-in method completes can send the person back to where they started instead of `HOME`.
+ *
+ * Driven by the flow model rather than a raw URL: `model.next()` is the flow's own answer to
+ * "where does this step lead", so a caller never re-derives a destination the flow already knows,
+ * and a flow whose current step offers no way forward (`next()` throws) suspends nothing rather
+ * than persisting a landing that can never be reached. The persisted record is deliberately NOT a
+ * serialized flow token — the destination step is always one this application can enter fresh (an
+ * `initial`-marked screen reading its own `ref`/`kind` from the query), so nothing needs to
+ * reconstruct the exact `FlowModel` instance on the other side of a sign-in redirect, and this
+ * helper stays usable by any flow, not only one particular package's.
+ *
+ * Returns `false` when there is nowhere to persist this (no `FLOW_STATE` resource registered) or
+ * nothing to suspend to (the current step has no forward transition, or its destination has no
+ * `module`) — the caller falls back to its own default landing (ordinarily `HOME`).
+ */
+export declare const suspendFlow: <C extends ClientConfig, T extends ClientContext<C>>(context: T, model: FlowModel, opts: {
+    expiresAt: number;
+}) => Promise<boolean>;
+/**
+ * Read back a suspended landing, once. Delete-on-read: the record answers exactly one sign-in,
+ * because a landing a stale browser tab left behind must never resurrect on somebody else's
+ * sign-in later in the same session.
+ *
+ * `null` covers every reason there is nothing to resume: no resource, no record, or a record
+ * whose window has closed — the caller's own default landing is exactly as safe an answer.
+ */
+export declare const resumeSuspendedFlow: <C extends ClientConfig, T extends ClientContext<C>>(context: T) => Promise<SuspendedLanding | null>;
+//# sourceMappingURL=landing.d.ts.map

package/build/landing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"landing.d.ts","sourceRoot":"","sources":["../src/landing.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAA;AACrD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAA;AAE5D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAA;AACxD,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAA;AAG5D;iGACiG;AACjG,eAAO,MAAM,WAAW,gBAAgB,CAAA;AAExC,MAAM,WAAW,sBAAuB,SAAQ,cAAc;IAC5D,kEAAkE;IAClE,UAAU,EAAE,MAAM,CAAA;IAClB,oGAAoG;IACpG,KAAK,EAAE,WAAW,CAAA;IAClB,SAAS,EAAE,MAAM,CAAA;CAClB;AAED,MAAM,WAAW,gBAAgB;IAC/B,UAAU,EAAE,MAAM,CAAA;IAClB,KAAK,EAAE,WAAW,CAAA;CACnB;AAOD;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,WAAW,GAAU,CAAC,SAAS,YAAY,EAAE,CAAC,SAAS,aAAa,CAAC,CAAC,CAAC,WACzE,CAAC,SAAS,SAAS,QAAQ;IAAE,SAAS,EAAE,MAAM,CAAA;CAAE,KACxD,OAAO,CAAC,OAAO,CAkBjB,CAAA;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,mBAAmB,GAAU,CAAC,SAAS,YAAY,EAAE,CAAC,SAAS,aAAa,CAAC,CAAC,CAAC,WACjF,CAAC,KACT,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAgBjC,CAAA"}

package/build/landing.js

@@ -0,0 +1,68 @@
+import { FLOW_STATE } from './consts.js';
+/** The record id a suspended landing is stored under, in the SAME resource `EXTRA_FLOW` uses —
+ * a side-band slot, never the live `FlowService.flow` and never the `?flow=` query parameter. */
+export const RESUME_FLOW = 'resume-flow';
+const landingResource = (context) => context.hasResource(FLOW_STATE) ? context.resource(FLOW_STATE) : null;
+/**
+ * Suspend a flow that is about to leave for the platform's own sign-in dispatcher, so whichever
+ * sign-in method completes can send the person back to where they started instead of `HOME`.
+ *
+ * Driven by the flow model rather than a raw URL: `model.next()` is the flow's own answer to
+ * "where does this step lead", so a caller never re-derives a destination the flow already knows,
+ * and a flow whose current step offers no way forward (`next()` throws) suspends nothing rather
+ * than persisting a landing that can never be reached. The persisted record is deliberately NOT a
+ * serialized flow token — the destination step is always one this application can enter fresh (an
+ * `initial`-marked screen reading its own `ref`/`kind` from the query), so nothing needs to
+ * reconstruct the exact `FlowModel` instance on the other side of a sign-in redirect, and this
+ * helper stays usable by any flow, not only one particular package's.
+ *
+ * Returns `false` when there is nowhere to persist this (no `FLOW_STATE` resource registered) or
+ * nothing to suspend to (the current step has no forward transition, or its destination has no
+ * `module`) — the caller falls back to its own default landing (ordinarily `HOME`).
+ */
+export const suspendFlow = async (context, model, opts) => {
+    const resource = landingResource(context);
+    if (resource == null)
+        return false;
+    let destinationModule;
+    try {
+        const transition = model.next();
+        destinationModule = model.step(transition.step).module;
+    }
+    catch {
+        return false;
+    }
+    if (destinationModule == null)
+        return false;
+    await resource.save({
+        id: RESUME_FLOW, entrypoint: destinationModule, query: model.payload(), expiresAt: opts.expiresAt,
+    });
+    return true;
+};
+/**
+ * Read back a suspended landing, once. Delete-on-read: the record answers exactly one sign-in,
+ * because a landing a stale browser tab left behind must never resurrect on somebody else's
+ * sign-in later in the same session.
+ *
+ * `null` covers every reason there is nothing to resume: no resource, no record, or a record
+ * whose window has closed — the caller's own default landing is exactly as safe an answer.
+ */
+export const resumeSuspendedFlow = async (context) => {
+    const resource = landingResource(context);
+    if (resource == null)
+        return null;
+    let record;
+    try {
+        record = await resource.load(RESUME_FLOW);
+    }
+    catch {
+        return null;
+    }
+    if (record == null)
+        return null;
+    await resource.delete(RESUME_FLOW).catch(() => undefined);
+    if (record.expiresAt < Date.now())
+        return null;
+    return { entrypoint: record.entrypoint, query: record.query };
+};
+//# sourceMappingURL=landing.js.map

package/build/landing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"landing.js","sourceRoot":"","sources":["../src/landing.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAExC;iGACiG;AACjG,MAAM,CAAC,MAAM,WAAW,GAAG,aAAa,CAAA;AAexC,MAAM,eAAe,GAAG,CACtB,OAAU,EACqC,EAAE,CACjD,OAAO,CAAC,WAAW,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAyC,UAAU,CAAC,CAAC,CAAC,CAAC,IAAI,CAAA;AAE/G;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,KAAK,EAC9B,OAAU,EAAE,KAAgB,EAAE,IAA2B,EACvC,EAAE;IACpB,MAAM,QAAQ,GAAG,eAAe,CAAC,OAAO,CAAC,CAAA;IACzC,IAAI,QAAQ,IAAI,IAAI;QAAE,OAAO,KAAK,CAAA;IAElC,IAAI,iBAAqC,CAAA;IACzC,IAAI,CAAC;QACH,MAAM,UAAU,GAAG,KAAK,CAAC,IAAI,EAAE,CAAA;QAC/B,iBAAiB,GAAG,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,MAAM,CAAA;IACxD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAA;IACd,CAAC;IACD,IAAI,iBAAiB,IAAI,IAAI;QAAE,OAAO,KAAK,CAAA;IAE3C,MAAM,QAAQ,CAAC,IAAI,CAAC;QAClB,EAAE,EAAE,WAAW,EAAE,UAAU,EAAE,iBAAiB,EAAE,KAAK,EAAE,KAAK,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,IAAI,CAAC,SAAS;KAClG,CAAC,CAAA;IAEF,OAAO,IAAI,CAAA;AACb,CAAC,CAAA;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,KAAK,EACtC,OAAU,EACwB,EAAE;IACpC,MAAM,QAAQ,GAAG,eAAe,CAAC,OAAO,CAAC,CAAA;IACzC,IAAI,QAAQ,IAAI,IAAI;QAAE,OAAO,IAAI,CAAA;IAEjC,IAAI,MAAqC,CAAA;IACzC,IAAI,CAAC;QACH,MAAM,GAAG,MAAM,QAAQ,CAAC,IAAI,CAAC,WAAW,CAAC,CAAA;IAC3C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAA;IACb,CAAC;IACD,IAAI,MAAM,IAAI,IAAI;QAAE,OAAO,IAAI,CAAA;IAE/B,MAAM,QAAQ,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAA;IACzD,IAAI,MAAM,CAAC,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE;QAAE,OAAO,IAAI,CAAA;IAE9C,OAAO,EAAE,UAAU,EAAE,MAAM,CAAC,UAAU,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,EAAE,CAAA;AAC/D,CAAC,CAAA"}

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@owlmeans/client-flow",
-  "version": "0.1.18-rc.33",
+  "version": "0.1.18-rc.35",
   "license": "MIT",
   "type": "module",
   "scripts": {
     "build": "tsc -b",
     "dev": "sleep 90 && nodemon -e ts,tsx,json --watch src --exec \"tsc -p ./tsconfig.json\"",
-    "watch": "tsc -b -w --preserveWatchOutput --pretty"
+    "watch": "tsc -b -w --preserveWatchOutput --pretty",
+    "test": "bun test ./tests"
   },
   "main": "build/index.js",
   "module": "build/index.js",
@@ -21,24 +22,26 @@
     }
   },
   "dependencies": {
-    "@owlmeans/auth-common": "^0.1.18-rc.29",
-    "@owlmeans/client": "^0.1.18-rc.32",
-    "@owlmeans/client-context": "^0.1.18-rc.30",
-    "@owlmeans/client-entrypoint": "^0.1.18-rc.29",
-    "@owlmeans/client-resource": "^0.1.18-rc.29",
-    "@owlmeans/config": "^0.1.18-rc.29",
-    "@owlmeans/context": "^0.1.18-rc.25",
-    "@owlmeans/error": "^0.1.18-rc.27",
-    "@owlmeans/flow": "^0.1.18-rc.30",
-    "@owlmeans/entrypoint": "^0.1.18-rc.28",
-    "@owlmeans/resource": "^0.1.18-rc.27",
-    "@owlmeans/route": "^0.1.18-rc.26"
+    "@owlmeans/auth-common": "^0.1.18-rc.30",
+    "@owlmeans/client": "^0.1.18-rc.33",
+    "@owlmeans/client-context": "^0.1.18-rc.31",
+    "@owlmeans/client-entrypoint": "^0.1.18-rc.30",
+    "@owlmeans/client-resource": "^0.1.18-rc.30",
+    "@owlmeans/config": "^0.1.18-rc.30",
+    "@owlmeans/context": "^0.1.18-rc.26",
+    "@owlmeans/error": "^0.1.18-rc.28",
+    "@owlmeans/flow": "^0.1.18-rc.31",
+    "@owlmeans/entrypoint": "^0.1.18-rc.29",
+    "@owlmeans/resource": "^0.1.18-rc.28",
+    "@owlmeans/route": "^0.1.18-rc.27"
   },
   "peerDependencies": {
     "react": "*"
   },
   "devDependencies": {
     "@owlmeans/dep-config": "workspace:*",
+    "@owlmeans/static-resource": "^0.1.18-rc.26",
+    "@types/bun": "^1.4.0",
     "nodemon": "^3.1.14",
     "typescript": "^7.0.2"
   },

package/src/index.ts

@@ -2,3 +2,4 @@ export type * from './types.js'
 export * from './consts.js'
 export * from './client.js'
 export * from './service.js'
+export * from './landing.js'

package/src/landing.ts

@@ -0,0 +1,95 @@
+import type { ClientContext } from '@owlmeans/client'
+import type { ClientConfig } from '@owlmeans/client-context'
+import type { ClientResource } from '@owlmeans/client-resource'
+import type { ResourceRecord } from '@owlmeans/resource'
+import type { FlowModel, FlowPayload } from '@owlmeans/flow'
+import { FLOW_STATE } from './consts.js'
+
+/** The record id a suspended landing is stored under, in the SAME resource `EXTRA_FLOW` uses —
+ * a side-band slot, never the live `FlowService.flow` and never the `?flow=` query parameter. */
+export const RESUME_FLOW = 'resume-flow'
+
+export interface SuspendedLandingRecord extends ResourceRecord {
+  /** The entrypoint alias to navigate to once sign-in completes. */
+  entrypoint: string
+  /** The flow's payload at the moment it was suspended — carried along as the destination's query. */
+  query: FlowPayload
+  expiresAt: number
+}
+
+export interface SuspendedLanding {
+  entrypoint: string
+  query: FlowPayload
+}
+
+const landingResource = <C extends ClientConfig, T extends ClientContext<C>>(
+  context: T
+): ClientResource<SuspendedLandingRecord> | null =>
+  context.hasResource(FLOW_STATE) ? context.resource<ClientResource<SuspendedLandingRecord>>(FLOW_STATE) : null
+
+/**
+ * Suspend a flow that is about to leave for the platform's own sign-in dispatcher, so whichever
+ * sign-in method completes can send the person back to where they started instead of `HOME`.
+ *
+ * Driven by the flow model rather than a raw URL: `model.next()` is the flow's own answer to
+ * "where does this step lead", so a caller never re-derives a destination the flow already knows,
+ * and a flow whose current step offers no way forward (`next()` throws) suspends nothing rather
+ * than persisting a landing that can never be reached. The persisted record is deliberately NOT a
+ * serialized flow token — the destination step is always one this application can enter fresh (an
+ * `initial`-marked screen reading its own `ref`/`kind` from the query), so nothing needs to
+ * reconstruct the exact `FlowModel` instance on the other side of a sign-in redirect, and this
+ * helper stays usable by any flow, not only one particular package's.
+ *
+ * Returns `false` when there is nowhere to persist this (no `FLOW_STATE` resource registered) or
+ * nothing to suspend to (the current step has no forward transition, or its destination has no
+ * `module`) — the caller falls back to its own default landing (ordinarily `HOME`).
+ */
+export const suspendFlow = async <C extends ClientConfig, T extends ClientContext<C>>(
+  context: T, model: FlowModel, opts: { expiresAt: number }
+): Promise<boolean> => {
+  const resource = landingResource(context)
+  if (resource == null) return false
+
+  let destinationModule: string | undefined
+  try {
+    const transition = model.next()
+    destinationModule = model.step(transition.step).module
+  } catch {
+    return false
+  }
+  if (destinationModule == null) return false
+
+  await resource.save({
+    id: RESUME_FLOW, entrypoint: destinationModule, query: model.payload(), expiresAt: opts.expiresAt,
+  })
+
+  return true
+}
+
+/**
+ * Read back a suspended landing, once. Delete-on-read: the record answers exactly one sign-in,
+ * because a landing a stale browser tab left behind must never resurrect on somebody else's
+ * sign-in later in the same session.
+ *
+ * `null` covers every reason there is nothing to resume: no resource, no record, or a record
+ * whose window has closed — the caller's own default landing is exactly as safe an answer.
+ */
+export const resumeSuspendedFlow = async <C extends ClientConfig, T extends ClientContext<C>>(
+  context: T
+): Promise<SuspendedLanding | null> => {
+  const resource = landingResource(context)
+  if (resource == null) return null
+
+  let record: SuspendedLandingRecord | null
+  try {
+    record = await resource.load(RESUME_FLOW)
+  } catch {
+    return null
+  }
+  if (record == null) return null
+
+  await resource.delete(RESUME_FLOW).catch(() => undefined)
+  if (record.expiresAt < Date.now()) return null
+
+  return { entrypoint: record.entrypoint, query: record.query }
+}

package/tests/context.ts

@@ -0,0 +1,26 @@
+import { AppType, makeBasicContext } from '@owlmeans/context'
+import type { BasicConfig, BasicContext } from '@owlmeans/context'
+import { createStaticResource } from '@owlmeans/static-resource'
+import type { ClientContext } from '@owlmeans/client'
+import type { ClientConfig } from '@owlmeans/client-context'
+import { FLOW_STATE } from '../src/consts.js'
+import type { SuspendedLandingRecord } from '../src/landing.js'
+
+/**
+ * The smallest context `suspendFlow`/`resumeSuspendedFlow` need: a `FLOW_STATE` resource and
+ * nothing else. A static resource is a real `Resource` implementation, so this exercises the
+ * actual save/load/delete contract rather than a stand-in for it — the same pattern
+ * `@owlmeans/client-auth`'s own tests use for a client-side resource.
+ */
+export const makeTestContext = (withResource: boolean = true): ClientContext<ClientConfig> => {
+  const cfg: BasicConfig = {
+    ready: false, service: 'client-flow-tests', type: AppType.Frontend, services: {},
+  }
+  const context = makeBasicContext(cfg) as BasicContext<BasicConfig>
+
+  if (withResource) {
+    context.registerResource(createStaticResource<SuspendedLandingRecord>(FLOW_STATE, 'client-flow-landing-tests'))
+  }
+
+  return context as unknown as ClientContext<ClientConfig>
+}

package/tests/landing.spec.ts

@@ -0,0 +1,73 @@
+import { describe, expect, test } from 'bun:test'
+import { makeFlowModel } from '@owlmeans/flow'
+import type { ShallowFlow } from '@owlmeans/flow'
+import { resumeSuspendedFlow, suspendFlow } from '../src/landing.js'
+import { makeTestContext } from './context.js'
+
+const testFlow: ShallowFlow = {
+  flow: 'test-landing',
+  initialStep: 'a',
+  steps: {
+    a: {
+      index: 0, step: 'a', service: '', initial: true,
+      transitions: { next: { transition: 'next', step: 'b' } },
+    },
+    b: {
+      index: 1, step: 'b', service: '', module: 'target-entrypoint',
+      transitions: {},
+    },
+    dead: {
+      // No transitions and no `module` — used to exercise the two ways suspending can fail.
+      index: 2, step: 'dead', service: '', transitions: {},
+    },
+  },
+}
+
+describe('suspendFlow / resumeSuspendedFlow', () => {
+  test('suspends the flow model\'s NEXT destination and resumes it once, with its payload', async () => {
+    const context = makeTestContext()
+    const model = await makeFlowModel(testFlow)
+    model.updatePayload({ ref: 'abc-123' })
+
+    expect(await suspendFlow(context, model, { expiresAt: Date.now() + 60_000 })).toBe(true)
+
+    const landing = await resumeSuspendedFlow(context)
+    expect(landing).toEqual({ entrypoint: 'target-entrypoint', query: { ref: 'abc-123' } })
+  })
+
+  test('resuming is single-use — a second call finds nothing', async () => {
+    const context = makeTestContext()
+    const model = await makeFlowModel(testFlow)
+    await suspendFlow(context, model, { expiresAt: Date.now() + 60_000 })
+
+    await resumeSuspendedFlow(context)
+    expect(await resumeSuspendedFlow(context)).toBeNull()
+  })
+
+  test('an expired landing resumes to nothing', async () => {
+    const context = makeTestContext()
+    const model = await makeFlowModel(testFlow)
+    await suspendFlow(context, model, { expiresAt: Date.now() - 1 })
+
+    expect(await resumeSuspendedFlow(context)).toBeNull()
+  })
+
+  test('a step with no forward transition suspends nothing', async () => {
+    const context = makeTestContext()
+    const deadModel = await makeFlowModel(testFlow)
+    // Stand the model on the dead-end step directly — it declares no transitions, so `next()`
+    // has nothing to offer and suspending must decline rather than persist a landing to nowhere.
+    deadModel.setState({ ...deadModel.state(), step: 'dead' })
+
+    expect(await suspendFlow(context, deadModel, { expiresAt: Date.now() + 60_000 })).toBe(false)
+    expect(await resumeSuspendedFlow(context)).toBeNull()
+  })
+
+  test('with no FLOW_STATE resource registered, both are safe no-ops', async () => {
+    const context = makeTestContext(false)
+    const model = await makeFlowModel(testFlow)
+
+    expect(await suspendFlow(context, model, { expiresAt: Date.now() + 60_000 })).toBe(false)
+    expect(await resumeSuspendedFlow(context)).toBeNull()
+  })
+})

package/tests/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "extends": [
+    "@owlmeans/dep-config/tsconfig.base.json",
+    "@owlmeans/dep-config/tsconfig.node.json"
+  ],
+  "compilerOptions": {
+    "types": ["bun"],
+    "rootDir": "../",
+    "noEmit": true
+  },
+  "include": ["./**/*", "../src/**/*"]
+}

package/tsconfig.json

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