@ofidj/generator-fidj 3.10.1 → 3.11.0

package/README.md

@@ -51,19 +51,28 @@ one.
 - `--logo <image>` and `--favicon <image>`: the app's own marks, copied into `public/brand/`. The logo sits beside the app name at the top of the sign-in panel; the favicon goes in the browser tab. Both fall back to the Fidj mark, so neither is ever blank. Accepts `.png`, `.svg`, `.gif`, `.jpg`, `.webp` or `.ico` under 512KB — an animated GIF works as a logo, and as a favicon in the browsers that animate one.
 - `--api-endpoint`: select the API (default: hosted sandbox).
 - `--sdk-path` or `FIDJ_SDK_DIR`: use a built local SDK during coordinated development.
+- `--entry-path` or `FIDJ_ENTRY_DIR`: same, for a built local `@ofidj/entry` — the sign-in and account screens, the agreement and the design system. Point it at that package's `dist`, as with the SDK.
 - `--local` or `FIDJ_LOCAL=true`: use the loopback API/console. Test credentials stay in the validation guide, outside the content app UI. Supply the matching local app ID; `FIDJ_APP_ID` can override it.
 - `--replace`: regenerate only a destination containing `.fidj-generated`; unmarked projects are protected.
 
-The generated shell paints from one design system: `src/tokens.css` holds every
-colour, family and radius, and `src/style.css` may not introduce a literal of
-its own. Fonts are self-hosted under `public/fonts` and served from the build
-manifest, so a generated site stays statically hostable and makes no
-third-party request on sign-in. fidj-app consumes the same tokens, which is why
-a style change lands here first.
+**The entry is a dependency, not a copy.** `@ofidj/entry` carries the sign-in
+and account screens, the service agreement, the provider window, the version
+badge and the design system; the generated app imports them the way it imports
+the SDK. They used to be files in this template, which meant the only way to
+ship a fix was to regenerate every app — and meant Fidj's own console had to be
+generated to reach them. A style change now lands in that package, and this
+template is what remains genuinely the generator's: the shells that hold the
+screens, the content app and the Notes app.
+
+The design system is `@ofidj/entry`'s `tokens.css` — every colour, family and
+radius — and its `style.css`, which may not introduce a literal of its own.
+Fonts are self-hosted under `public/fonts` and served from the build manifest,
+so a generated site stays statically hostable and makes no third-party request
+on sign-in.
 
 Generation writes `.env.example`, `.env` and public `app.config.json`. Static configuration is embedded at build time: regenerate/rebuild when changing endpoints. Notes server configuration is read at runtime. Do not place secrets in any public configuration or content input.
 
-For unpublished coordinated changes, build the sibling SDK and pass `--sdk-path` with its absolute `dist` path. Committed templates use registry dependency `@ofidj/node ^3.7.3`; a registry-only install is not validated until coordinated versions are published.
+For unpublished coordinated changes, build the sibling SDK and entry packages and pass `--sdk-path` and `--entry-path` with their absolute `dist` paths. Committed templates name registry ranges for both; a registry-only install is not validated until coordinated versions are published.
 
 Every generated app carries a fixed bottom-right badge naming the Fidj it runs:
 `fidj@<version>`, taken from the SDK it was generated with — the `--sdk-path`
@@ -106,10 +115,11 @@ The generated content app opens on `/#/signin`. Sign in, or choose **Enter anony
 is the one control on the screen wearing `--fidj-accent`, because it is the one
 that belongs to Fidj rather than to the app — and it is the path where the app
 never sees a password. An app generated with `--signin both` keeps its own
-email-and-password form under an *Inline form* disclosure, with its service
-agreement: opening it folds the Fidj door away, because the two are alternatives
-rather than a list. That agreement gates the app's own door and nothing else, so
-an agreement that fails to load never shuts the Fidj door.
+email-and-password form under an *Inline form* disclosure: opening it folds the
+Fidj door away, because the two are alternatives rather than a list. Whichever
+door is taken runs the same two screens — credentials, with the verification
+wait appearing beneath them on the create path, and then the agreement — so the
+button is a shortcut to the flow, not a different one.
 
 Pressing it opens Fidj in a browser window of its own rather than navigating
 away. Fidj's screens are served from another origin and refuse to be framed, so
@@ -161,11 +171,26 @@ A compatible issuer, REST API and registered callback without a fragment are pre
 
 ## Required service agreement
 
-All generated sign-in and account-creation forms (content, composed Fidj and
-Notes) share an unchecked required agreement checkbox. Both submit buttons stay
-disabled until it is checked. Reading the agreement opens an in-app dialog;
-failed agreement loading keeps sign-in blocked. Anonymous entry, when enabled,
-is not a login and does not record agreement acceptance.
+[The workspace README](../README.md#entry-one-flow-the-same-everywhere) defines
+the flow every Fidj sign-in surface follows, and this generator owns the
+implementation the others render. In short: the first screen asks for an email,
+a password, **Sign in** and **Create an account**, and gates neither; creating an
+account grows a verification wait beneath that same form rather than replacing
+it; and the agreement is its own screen, shown whenever the version recorded for
+this person and this app is not the current one, with its submit button
+read-only until the box is ticked.
+
+The agreement screen's markup, its loading and its disabled-button rule live in
+`@ofidj/entry` — one implementation for the app's own form, the composed Fidj
+console and the Fidj-hosted consent page of the beta OIDC provider — so an owner
+who publishes a new version changes one thing and every surface asks again.
+Anonymous entry, when enabled, is not a login and records no acceptance.
+
+Both generated entries render this. The content app and the Notes starter lost
+their checkbox beside the credentials and their local gate; each calls `login`,
+and the API's `409 agreement_required` is what puts the agreement screen on
+screen, carrying the version it compared against. `--signin button` delegates
+the whole question to Fidj and never had one.
 
 The text and version come from the app's public API metadata, not copied generator
 settings. The API records acceptance before issuing the app token, preserves

package/bin/create-fidj.cjs

@@ -9,6 +9,7 @@ try {
       "api-endpoint": { type: "string" },
       "oidc-issuer": { type: "string" },
       "sdk-path": { type: "string" },
+      "entry-path": { type: "string" },
       title: { type: "string" },
       welcome: { type: "string" },
       description: { type: "string" },
@@ -39,6 +40,7 @@ try {
       apiEndpoint: values["api-endpoint"],
       oidcIssuer: values["oidc-issuer"],
       sdkPath: values["sdk-path"] || process.env.FIDJ_SDK_DIR,
+      entryPath: values["entry-path"] || process.env.FIDJ_ENTRY_DIR,
       title: values.title,
       welcome: values.welcome,
       description: values.description,

package/generators/app/index.js

@@ -9,6 +9,7 @@ const TEXT_OPTIONS = [
   "api-endpoint",
   "oidc-issuer",
   "sdk-path",
+  "entry-path",
   "title",
   "welcome",
   "description",
@@ -99,6 +100,7 @@ module.exports = class extends Generator {
       moduleEntry: this.options["module-entry"],
       domain: this.options.domain,
       sdkPath: this.options["sdk-path"] || process.env.FIDJ_SDK_DIR,
+      entryPath: this.options["entry-path"] || process.env.FIDJ_ENTRY_DIR,
       oidcIssuer: this.options["oidc-issuer"],
       local: this.options.local || process.env.FIDJ_LOCAL === "true",
       replace: this.options.replace,

package/generators/app/templates/typescript/package.json

@@ -15,7 +15,8 @@
     "privacy:rehearse": "npm run build && node --test test/server.test.mjs"
   },
   "dependencies": {
-    "@ofidj/node": "^3.10.0"
+    "@ofidj/entry": "^3.11.0",
+    "@ofidj/node": "^3.11.0"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",

package/generators/app/templates/typescript/src/content.ts

@@ -1,9 +1,9 @@
-import {agreementMarkup, bindAgreement, acceptedAgreement, signInErrorMessage, providerEntry, rememberSignIn, forgetSignIn, signInHint, showEmailEntry, type SigninShape} from "./service-agreement";
-import {openProviderWindow, relayProviderAnswer, type ProviderWindow} from "./provider-window";
+import {signInErrorMessage, agreementRequired, agreementFromRefusal, verificationPending, pollVerification, rememberSignIn, forgetSignIn, signInHint, type SigninShape} from "@ofidj/entry";
+import {agreementScreen, bindAgreementScreen, acceptedAgreement, verificationWait, providerEntry, showEmailEntry, showVersionBadge, escape, masthead, highlightCells, badgeStrip, credentialFields, accountForm, returnNotice} from "@ofidj/entry/dom";
+import {openProviderWindow, relayProviderAnswer, type ProviderWindow} from "@ofidj/entry/window";
 import { FidjNodeService, FidjOidcClient } from "@ofidj/node";
 import config from "../app.config.json";
-import "./style.css";
-import { showVersionBadge } from "./version";
+import "@ofidj/entry/style.css";
 
 const sdk = new FidjNodeService();
 const oidc = config.oidcIssuer ? new FidjOidcClient({issuer: config.oidcIssuer, clientId: config.appId, redirectUri: window.location.origin + window.location.pathname, apiEndpoint: config.apiEndpoint, storage: sessionStorage}) : null;
@@ -29,7 +29,13 @@ let busy = false;
 let leaving = false;
 let signInEmail = "";
 let signInPassword = "";
-let signInAgreementAccepted = false;
+// The agreement this app is owed, once the API has said so, and the address a
+// just-created account is waiting on. Only one of them is ever set.
+let pendingAgreement: {version: string; text: string} | null = null;
+let awaitingVerification = "";
+let verificationResent = false;
+let verificationNotice = "";
+let stopWatchingVerification: (() => void) | null = null;
 // Who is signed in, as this app's own membership answers it. The bar names them
 // and the account screen says it again where it can be checked; the ID token of
 // a code flow carries only a subject, so this comes from the membership.
@@ -51,23 +57,8 @@ function currentRoute() {
   }
   return route;
 }
-const escape = (value: unknown) =>
-  String(value ?? "").replace(
-    /[&<>"']/g,
-    (char) =>
-      ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[
-        char
-      ]!,
-  );
 const element = <T extends HTMLElement>(id: string) =>
   document.getElementById(id) as T | null;
-function badges() {
-  const entries: string[] = config.badges;
-  if (!entries?.length) return "";
-  return `<footer class="signin-badges">${entries
-    .map((entry) => `<span>${escape(entry)}</span>`)
-    .join("")}</footer>`;
-}
 // Signing out of this app revokes this app's access and nothing else: the Fidj
 // session survives, which is what makes the next app free to enter. That is a
 // good design and a bad surprise, so the notice says what actually happened and
@@ -145,16 +136,6 @@ function wireSignOut() {
   );
 }
 
-function highlights() {
-  const entries: Array<{ heading: string; body: string }> = config.highlights;
-  if (!entries?.length) return "";
-  return `<div class="signin-highlights">${entries
-    .map(
-      (entry, index) =>
-        `<article><p class="eyebrow">${String(index + 1).padStart(2, "0")}</p><h2>${escape(entry.heading)}</h2><p>${escape(entry.body)}</p></article>`,
-    )
-    .join("")}</div>`;
-}
 async function request(path: string, method = "GET", data?: unknown) {
   const token = await sdk.fidjGetIdToken();
   const response = await fetch(config.apiEndpoint + path, {
@@ -325,10 +306,52 @@ const RECOGNITION_ASKED = "fidj.oidc.recognition-asked";
 // for. Asking there sent an anonymous visitor to the provider and back, and what
 // they had asked to read never rendered.
 const PUBLIC_ROUTE = "pub";
+// Whether the question is still outstanding. Drawing the credential form and
+// then navigating to the provider loses whatever somebody had begun typing, so
+// the entry waits instead — the answer takes one redirect, not a wait worth a
+// spinner's worth of ceremony, and it says what it is doing.
+let recognising = false;
+function mightBeRecognised() {
+  if (!oidc || !isFidjItself) return false;
+  if ((moduleRoute() || "").split("/")[0] === PUBLIC_ROUTE) return false;
+  // Not on a screen somebody was sent to by a link.
+  //
+  // Asking the provider is a navigation: it leaves this address and comes back
+  // at the redirect URI, without the hash the link carried. On these routes the
+  // hash is the point — it holds a token that works once — so asking spent the
+  // link and dropped the person on the entry, with nothing to show for having
+  // opened their mail.
+  //
+  // It hid well. Every other way of reaching these screens comes from a page
+  // that already asked once and recorded it below, and the ask is once per
+  // document; only a tab that has never seen Fidj fires it here, which is
+  // exactly the tab a mail client opens and the one nothing exercised.
+  if (["forgot", "reset", "verify"].includes(currentRoute())) return false;
+  if (oidc.signedOutHere()) return false;
+  try {
+    return sessionStorage.getItem(RECOGNITION_ASKED) !== "true";
+  } catch {
+    return false;
+  }
+}
+
 async function askWhetherFidjKnowsThisBrowser() {
   if (!oidc || !isFidjItself || sdk.isLoggedIn() || oidc.signedOutHere())
     return false;
   if ((moduleRoute() || "").split("/")[0] === PUBLIC_ROUTE) return false;
+  // Not on a screen somebody was sent to by a link.
+  //
+  // Asking the provider is a navigation: it leaves this address and comes back
+  // at the redirect URI, without the hash the link carried. On these routes the
+  // hash is the point — it holds a token that works once — so asking spent the
+  // link and dropped the person on the entry, with nothing to show for having
+  // opened their mail.
+  //
+  // It hid well. Every other way of reaching these screens comes from a page
+  // that already asked once and recorded it below, and the ask is once per
+  // document; only a tab that has never seen Fidj fires it here, which is
+  // exactly the tab a mail client opens and the one nothing exercised.
+  if (["forgot", "reset", "verify"].includes(currentRoute())) return false;
   // Once per document: the answer comes back as a redirect to this same page,
   // so without this a refusal would ask again, and again.
   try {
@@ -411,11 +434,6 @@ function navigate(route: string) {
   if (route !== currentRoute()) window.history.pushState(null, "", "#/" + route);
   if (!busy) render();
 }
-// The credential fields, in one place because the entry now shows them beside
-// the Fidj door rather than instead of it.
-function credentialFields() {
-  return `<label for="email">Email</label><input id="email" type="email" value="${escape(signInEmail)}" placeholder="you@company.com" autocomplete="username"><div class="field-head"><label for="password">Password</label><a href="#/forgot">Forgot?</a></div><div class="password-field"><input id="password" type="password" value="${escape(signInPassword)}" placeholder="••••••••••" autocomplete="current-password"><button type="button" id="reveal" aria-controls="password">Show</button></div><button class="primary" type="submit" name="entry" value="credentials">Continue</button><button class="secondary" type="submit" name="signup" value="true">Create an account</button>`;
-}
 
 function moduleRoute() {
   const route = window.location.hash.slice(2).split("?")[0];
@@ -565,7 +583,7 @@ function render() {
     // The two ways out, last and together: back to the app, or out of this
     // session. Leaving the app itself is a different decision and stays where
     // the things it erases are listed.
-    root.innerHTML = `<section class="card content-account">${banner()}${accountForm("account")}${privacyBlock()}<div class="account-actions"><button id="continue-app" class="primary">Continue to ${escape(config.title)}</button><button id="exit">Sign out</button></div></section>`;
+    root.innerHTML = `<section class="card content-account">${banner()}${accountForm("account", {linkToken, verificationConfirmed, emailVerified, accountEmail})}${privacyBlock()}<div class="account-actions"><button id="continue-app" class="primary">Continue to ${escape(config.title)}</button><button id="exit">Sign out</button></div></section>`;
     renderNav("account");
     wireAccount("account");
     wireSignOut();
@@ -582,14 +600,18 @@ function render() {
     renderNav("content");
     return;
   }
+  if (recognising) {
+    root.innerHTML = `<section class="signin-shell"><div class="signin-form"><p role="status">Checking whether you are already signed in to Fidj…</p></div></section>`;
+    return;
+  }
   // Only the entry reaches here now: the privacy screen and the account
   // screen became one, and that one is drawn above.
-  root.innerHTML = `<section class="signin-shell"><div class="signin-intro${config.highlights?.length ? "" : " is-plain"}"><header class="signin-masthead"><img class="app-mark" src="${escape(config.logo)}" alt=""><strong>${escape(config.title)}</strong></header>
+  root.innerHTML = `<section class="signin-shell"><div class="signin-intro${config.highlights?.length ? "" : " is-plain"}">${masthead(config.logo, config.title)}
   <div class="signin-identity"><h1>${escape(config.welcome)}</h1><p class="signin-description">${escape(config.description)}</p></div>
-  ${highlights()}</div>
-  <div class="signin-form"><div>${banner()}<h2>Sign in to ${escape(config.title)}</h2><form id="signin"><label for="email">Email</label><input id="email" type="email" value="${escape(signInEmail)}" placeholder="you@company.com" autocomplete="username" required><div class="field-head"><label for="password">Password</label><a href="#/forgot">Forgot?</a></div><div class="password-field"><input id="password" type="password" value="${escape(signInPassword)}" placeholder="••••••••••" autocomplete="current-password" required><button type="button" id="reveal" aria-controls="password">Show</button></div>${agreementMarkup()}<button class="primary" type="submit">Continue</button><button class="secondary" type="submit" name="signup" value="true">Create an account</button></form>${config.allowAnonymous ? `<div class="signin-divider"><span>or explore first</span></div><button class="anonymous-entry" id="anonymous">Enter anonymously <span aria-hidden="true">→</span></button><p class="signin-footnote">No account needed to view the content.</p>` : ""}
+  ${highlightCells(config.highlights)}</div>
+  <div class="signin-form"><div>${banner()}<h2>Sign in to ${escape(config.title)}</h2><form id="signin"><label for="email">Email</label><input id="email" type="email" value="${escape(signInEmail)}" placeholder="you@company.com" autocomplete="username" required><div class="field-head"><label for="password">Password</label><a href="#/forgot">Forgot?</a></div><div class="password-field"><input id="password" type="password" value="${escape(signInPassword)}" placeholder="••••••••••" autocomplete="current-password" required><button type="button" id="reveal" aria-controls="password">Show</button></div><button class="primary" type="submit">Sign in</button><button class="secondary" type="submit" name="signup" value="true">Create an account</button></form>${config.allowAnonymous ? `<div class="signin-divider"><span>or explore first</span></div><button class="anonymous-entry" id="anonymous">Enter anonymously <span aria-hidden="true">→</span></button><p class="signin-footnote">No account needed to view the content.</p>` : ""}
   <div class="signin-trust"><p class="signin-trust-head"><img class="signin-logo" src="./fidj-logo.png" alt="Fidj"><strong>Your account, with Fidj</strong></p><p>Signing in creates one Fidj account you keep across every app that uses Fidj.</p><p>You choose what this app may store — and can export or erase it at any moment.</p></div></div>
-  ${badges()}</div></section>`;
+  ${badgeStrip(config.badges)}</div></section>`;
   wireNav();
   element("reveal")?.addEventListener("click", () => {
     const field = element<HTMLInputElement>("password");
@@ -615,14 +637,23 @@ function render() {
     element("signin")!.innerHTML = providerEntry(
       config.title,
       config.appId,
-      config.signin === "button" ? "" : credentialFields(),
+      config.signin === "button"
+        ? ""
+        : credentialFields({email: signInEmail, password: signInPassword}),
       isFidjItself,
       config.signin as SigninShape,
     );
+  // The agreement, when the API has said this app is owed one. It takes the
+  // form's place rather than sitting under it: the credentials were accepted,
+  // and what is left is a decision about this app.
+  if (pendingAgreement && element("signin")) {
+    element("signin")!.innerHTML = agreementScreen(config.title, pendingAgreement);
+    bindAgreementScreen(element<HTMLFormElement>("signin"));
+  }
   // The app's own form, for whoever came to type a password. Folded away rather
   // than removed: the door above it is the one to take, and the person who
   // wants this one is one click from it.
-  if (emailEntryOpen) showEmailEntry(true);
+  if (!pendingAgreement && emailEntryOpen) showEmailEntry(true);
   element("use-email")?.addEventListener("click", () => {
     emailEntryOpen = !emailEntryOpen;
     showEmailEntry(emailEntryOpen, true);
@@ -642,31 +673,61 @@ function render() {
     }
     render();
   });
-  void bindAgreement(element<HTMLFormElement>("signin"), config.title, config.apiEndpoint, config.appId, signInAgreementAccepted);
+  // The wait a just-created account owes its address, under the form that
+  // created it — not a screen, because nobody was taken anywhere.
+  if (awaitingVerification)
+    element("signin")?.insertAdjacentHTML(
+      "beforeend",
+      verificationWait({
+        email: awaitingVerification,
+        resent: verificationResent,
+        error: verificationNotice,
+      }),
+    );
+  element("resend-verification")?.addEventListener("click", () =>
+    void action(async () => {
+      verificationResent = false;
+      verificationNotice = "";
+      try {
+        await sdk.resendVerification();
+        verificationResent = true;
+      } catch {
+        // No session yet — the account was created and never signed in, which
+        // is the whole point of this screen. Creating it again with the same
+        // address is what sends another link.
+        verificationNotice =
+          "Press Create an account again to send another link.";
+      }
+    }),
+  );
   element<HTMLFormElement>("signin")?.addEventListener("submit", (event) => {
     event.preventDefault();
     const email = element<HTMLInputElement>("email")?.value || "";
     const password = element<HTMLInputElement>("password")?.value || "";
-    const agreement = element<HTMLInputElement>("service-agreement");
+    const submitter = event.submitter as HTMLButtonElement | null;
+    // Answering the agreement screen. The credentials are the ones already
+    // accepted, so they are not re-read from a form that no longer shows them.
+    if (pendingAgreement) {
+      const acceptance = acceptedAgreement(
+        event.currentTarget as HTMLFormElement,
+      );
+      if (!acceptance) return;
+      submitter?.setAttribute("data-busy", "true");
+      void action(async () => {
+        if (
+          await refusedBeforeSignIn(signInEmail, signInPassword, false, acceptance)
+        )
+          return;
+        await completeSignIn();
+      });
+      return;
+    }
     signInEmail = email;
     signInPassword = password;
-    signInAgreementAccepted = agreement?.checked === true;
-    const acceptance = acceptedAgreement(event.currentTarget as HTMLFormElement);
-    const submitter = event.submitter as HTMLButtonElement | null;
     const signup = submitter?.name === "signup";
     // Which door was used. The Fidj one leaves for the provider; the credential
     // one signs in here, which is why it is the app's own form and not Fidj's.
     const throughFidj = submitter?.name === "entry" && submitter.value === "fidj";
-    // Only the credential door is gated here. The Fidj one is about to be asked
-    // the same question on the screen that names this app, where the answer is
-    // recorded with its version — so asking first cost a second click and kept
-    // nothing.
-    if (!throughFidj && !acceptance) {
-      failed = true;
-      message = "Please accept the service agreement before continuing.";
-      render();
-      return;
-    }
     if (oidc && throughFidj) {
       // "Continue as <them>" promises to carry on as that person, and handed
       // them over to an empty email field — so the promise cost a second
@@ -684,11 +745,69 @@ function render() {
       if (oidc && (!email || !password)) {
         throw new Error("Enter your email and password, or sign in with Fidj.");
       }
-      try {
-        await sdk.login(email, password, { autoSignup: signup, ...acceptance });
-      } catch (error) {
-        throw new Error(signInErrorMessage(error));
+      if (await refusedBeforeSignIn(email, password, signup)) return;
+      await completeSignIn();
+    });
+  });
+}
+
+// The API decides what the entry owes somebody next: a session, the agreement it
+// has not recorded for this app, or a wait on an address nobody has proved they
+// own. Returns true when it answered with a screen rather than a session.
+async function refusedBeforeSignIn(
+  email: string,
+  password: string,
+  signup: boolean,
+  acceptance?: {termsAccepted: boolean; termsVersion: string},
+): Promise<boolean> {
+  try {
+    await sdk.login(email, password, {autoSignup: signup, ...acceptance});
+    pendingAgreement = null;
+    awaitingVerification = "";
+    return false;
+  } catch (error) {
+    const created = verificationPending(error);
+    if (created) {
+      awaitingVerification = created.email || email;
+      verificationResent = false;
+      verificationNotice = "";
+      return true;
+    }
+    if (agreementRequired(error)) {
+      pendingAgreement = agreementFromRefusal(error) || (await readAgreement());
+      if (!pendingAgreement) {
+        throw new Error("We cannot reach Fidj right now. Please try again.");
       }
+      return true;
+    }
+    throw new Error(signInErrorMessage(error));
+  }
+}
+
+// An API that refused without saying which agreement it wanted. Older ones
+// cannot say, so the app is asked directly; it is the same agreement unless the
+// owner published between the two calls.
+async function readAgreement() {
+  try {
+    const response = await fetch(
+      `${config.apiEndpoint}/apps/${encodeURIComponent(config.appId)}`,
+      {signal: AbortSignal.timeout(10000)},
+    );
+    if (!response.ok) return null;
+    const agreement = (await response.json()).app?.agreement;
+    return typeof agreement?.version === "string" &&
+      agreement.version &&
+      typeof agreement?.text === "string" &&
+      agreement.text
+      ? {version: agreement.version, text: agreement.text}
+      : null;
+  } catch {
+    return null;
+  }
+}
+
+function completeSignIn() {
+  return (async () => {
       // Fidj collects the credential on its own page rather than sending itself
       // through its own door, and that sign-in created no session the provider
       // could see: the first app opened afterwards asked for the password again,
@@ -714,12 +833,11 @@ function render() {
       }
       await refresh();
       anonymous = false;
-      // A new account belongs where a returning one lands: inside the app.
-      // Sending it to the account card instead dropped people who had just
-      // signed up on the shell, one click short of the app they came for.
-      navigate("content");
-    });
-  });
+    // A new account belongs where a returning one lands: inside the app.
+    // Sending it to the account card instead dropped people who had just
+    // signed up on the shell, one click short of the app they came for.
+    navigate("content");
+  })();
 }
 
 // Everything the account screen lets a person do about what this app holds:
@@ -809,8 +927,8 @@ function wirePrivacy() {
   });
 }
 
-// The four account screens. My account is shown inside the app; the recovery
-// and verification ones are reached without a session and stand alone.
+
+
 // What this app holds about the person signed in, and what they can do
 // about it. It used to be a screen of its own called My privacy, one tab
 // away from the account it was about — so a person looking for their own
@@ -838,17 +956,6 @@ function privacyBlock() {
   <p class="leaving"><a href="${escape(config.dashboardUrl)}/#/my" target="_blank" rel="noopener">Open Fidj to manage every app you use ↗</a><br><small>Fidj is the account provider behind ${escape(config.title)}. This opens it in a new tab; you stay signed in here.</small></p>`;
 }
 
-function accountForm(route: string) {
-  return    route === "forgot"
-      ? `<h2>Reset your password</h2><p>We’ll email you a link to choose a new password for your shared Fidj account.</p><form id="recovery"><label for="recovery-email">Email address</label><input id="recovery-email" type="email" autocomplete="email" required><button class="primary">Send reset link</button></form>`
-      : route === "reset"
-        ? `<h2>Choose a new password</h2><p>This changes your Fidj password across all your apps and signs out existing sessions.</p>${linkToken ? '<form id="recovery"><label for="new-password">New password</label><input id="new-password" type="password" autocomplete="new-password" minlength="12" required><label for="confirm-password">Confirm password</label><input id="confirm-password" type="password" autocomplete="new-password" minlength="12" required><p>Use at least 12 characters (up to 72 UTF-8 bytes).</p><button class="primary">Save new password</button></form>' : '<p>Request a new link if you no longer have an active reset link.</p><a href="#/forgot">Request a reset link</a>'}`
-        : route === "verify"
-          ? `<h2>${verificationConfirmed ? "Email verified" : "Verify your email"}</h2>${verificationConfirmed ? "<p>Your account is ready. Return to your app to continue.</p>" : "<p>Confirm that this email address belongs to you.</p>"}${verificationConfirmed ? "" : linkToken ? '<form id="recovery"><button class="primary">Confirm email address</button></form>' : "<p>Sign in to your account to request a new verification email.</p>"}`
-          : `<h2>My Fidj account</h2><p class="account-identity">Signed in as <strong>${escape(accountEmail)}</strong></p><p>Your identity is shared across your apps. Privacy choices remain separate for each app.</p><p id="verification-status">${emailVerified ? "Your email address is verified." : "Your email is not verified yet."}</p><button id="check-verification">Refresh verification status</button>${emailVerified ? "" : '<button id="resend-verification">Send verification email</button>'}<p><a href="#/forgot">Reset my password</a></p>`;
-}
-
-
 // ------------------------------------------------ signing in, for the provider
 //
 // When Fidj's provider needs a person to identify themselves it hands them to a
@@ -941,13 +1048,6 @@ async function loadInteraction() {
   interaction = (await response.json()) as Interaction;
 }
 
-// A window that opened on its own, over the page somebody was on, owes them the
-// way out before it asks for anything. Naming the app they came from is also the
-// only thing on this screen that they can check against what they were doing a
-// second ago — which is exactly what a page asking for a password should offer.
-function returnNotice(asking: string) {
-  return `<p class="signin-return" role="note">When you are done, this window closes and takes you back to ${escape(asking)}.</p>`;
-}
 
 function interactionScreen() {
   const details = interaction!;
@@ -999,12 +1099,12 @@ function interactionScreen() {
     <button class="quiet" type="submit" name="action" value="cancel" formnovalidate>Cancel and go back</button>
   </form>`;
 
-  root.innerHTML = `<section class="signin-shell"><div class="signin-intro is-plain"><header class="signin-masthead"><img class="app-mark" src="${escape(config.logo)}" alt=""><strong>${escape(config.title)}</strong></header>
+  root.innerHTML = `<section class="signin-shell"><div class="signin-intro is-plain">${masthead(config.logo, config.title)}
   <div class="signin-identity"><h1>Your identity.<br>Your choices.</h1><p class="signin-description">One account across every app that uses Fidj, and a separate set of choices for each one.</p></div>
-  ${highlights()}</div>
+  ${highlightCells(config.highlights)}</div>
   <div class="signin-form"><div>${body}</div>
   <div class="signin-trust"><p class="signin-trust-head"><img class="signin-logo" src="./fidj-logo.png" alt="Fidj"><strong>What Fidj is</strong></p><p>Fidj holds your account so each app does not have to. You can see every app you use, what it holds, and take it back — at any time.</p></div></div>
-  ${badges()}</section>`;
+  ${badgeStrip(config.badges)}</section>`;
 
   element("reveal")?.addEventListener("click", () => {
     const field = element<HTMLInputElement>("password");
@@ -1037,10 +1137,10 @@ function interactionScreen() {
 }
 
 function renderAccount(route: string) {
-  root.innerHTML = `<section class="signin-shell"><div class="signin-intro is-plain"><header class="signin-masthead"><img class="app-mark" src="${escape(config.logo)}" alt=""><strong>${escape(config.title)}</strong></header>
+  root.innerHTML = `<section class="signin-shell"><div class="signin-intro is-plain">${masthead(config.logo, config.title)}
   <div class="signin-identity"><h1>Your account.<br>Your control.</h1><p class="signin-description">Secure access to the apps you use, with one Fidj identity.</p></div>
   </div>
-  <div class="signin-form"><div>${banner()}${accountForm(route)}</div><footer class="signin-badges"><a href="#/signin">Back to sign in</a></footer></div></section>`;
+  <div class="signin-form"><div>${banner()}${accountForm(route, {linkToken, verificationConfirmed, emailVerified, accountEmail})}</div><footer class="signin-badges"><a href="#/signin">Back to sign in</a></footer></div></section>`;
   wireAccount(route);
 }
 
@@ -1119,6 +1219,7 @@ if (relayProviderAnswer()) {
 
 function boot() {
   window.addEventListener("hashchange", render);
+  recognising = mightBeRecognised();
   render();
   if (readInteraction()) {
     render();
@@ -1167,6 +1268,7 @@ function boot() {
       apiEndpoint: config.apiEndpoint,
       prod: !config.localDemo,
     });
+    recognising = recognising && !sdk.isLoggedIn();
     if (sdk.isLoggedIn()) {
       await refresh();
       if (!moduleRoute() && !accountRoutes.includes(currentRoute()))
@@ -1174,6 +1276,8 @@ function boot() {
       return;
     }
     // Nothing held here. Fidj may still know this browser from an app.
-    await askWhetherFidjKnowsThisBrowser();
+    if (await askWhetherFidjKnowsThisBrowser()) return;
+    recognising = false;
+    render();
   });
 }