@forgecart/cli 2.202610280649.0 → 2.202610280926.0

package/templates/storefront-blank/src/components/ForgecartDesigner.tsx

@@ -0,0 +1,43 @@
+'use client';
+
+import { useEffect } from 'react';
+
+/**
+ * Mounts the ForgeCart visual-editor guest runtime. Renders nothing.
+ *
+ * The runtime stays dormant until activated: it registers a single `message`
+ * listener and posts a READY beacon, then waits for the dashboard host to
+ * drive a nonce-gated handshake over `postMessage` (the activation nonce
+ * arrives via the `#fcd=` URL fragment — there is no env switch). On a page
+ * that is not embedded in an iframe it never even loads.
+ *
+ * Production builds ship zero bytes of this: the literal `NODE_ENV` check is
+ * inlined by the bundler, so the effect body — including the dynamic import
+ * and its chunk — is dead-code-eliminated from `next build` output.
+ */
+export function ForgecartDesigner() {
+  useEffect(() => {
+    if (process.env.NODE_ENV !== 'development') {
+      return;
+    }
+    // Top-level pages have no designer host; skip loading the chunk entirely.
+    if (window.parent === window) {
+      return;
+    }
+    let cancelled = false;
+    let dispose: (() => void) | undefined;
+    const install = async () => {
+      const mod = await import('@forgecart/designer-runtime');
+      if (cancelled) {
+        return;
+      }
+      dispose = mod.installDesignerRuntime();
+    };
+    void install();
+    return () => {
+      cancelled = true;
+      dispose?.();
+    };
+  }, []);
+  return null;
+}

package/templates/storefront-blank/src/components/LocaleLink.tsx

@@ -0,0 +1,49 @@
+import Link from 'next/link';
+import type { ComponentProps, ReactNode } from 'react';
+
+import { localizedPath } from '../lib/locale/localized-path';
+import type { LocaleBinding } from '../lib/locale/localized-path';
+
+/**
+ * An internal link that stays inside the request's locale cluster (#1346,
+ * W1-8 / S2).
+ *
+ * Every internal navigation goes through this instead of `next/link` directly.
+ * A German page whose links all point at the English cluster leaves every
+ * German page but the entry point unreachable by following links, so a crawler
+ * never discovers them and the locale is effectively unindexed.
+ *
+ * The locale arrives as a PROP and is never derived here. Under the middleware
+ * rewrite the browser's URL and the rendered route differ — `/de/products`
+ * renders the `/products` route — so `usePathname()` returns the REWRITTEN
+ * path, and a component that read the locale from it would emit English links
+ * on every German page while looking correct in review. Server components take
+ * the binding from `getRequestLocale()`; client components receive it from
+ * whichever server component renders them.
+ *
+ * `href` is the UNPREFIXED route path, always — the same string you would have
+ * written before the locale layer existed. Prefixing is this component's job.
+ */
+
+// `locale` is omitted because `next/link` HAS a prop by that name — the Pages
+// Router i18n feature, typed `string | false`. This storefront does its own
+// locale routing (App Router, middleware rewrite), so that prop is never the
+// one we want, and forwarding it would collide with the binding below: the
+// production build fails with TS2430, which `next dev` never reports.
+type ForwardedLinkProps = Omit<ComponentProps<typeof Link>, 'href' | 'children' | 'locale'>;
+
+export interface LocaleLinkProps extends ForwardedLinkProps {
+  /** The unprefixed route path, e.g. `/products`. */
+  href: string;
+  /** The request's locale binding, from `getRequestLocale()`. */
+  locale: LocaleBinding;
+  children: ReactNode;
+}
+
+export function LocaleLink({ href, locale, children, ...rest }: LocaleLinkProps): ReactNode {
+  return (
+    <Link href={localizedPath(href, locale)} {...rest}>
+      {children}
+    </Link>
+  );
+}

package/templates/storefront-blank/src/instrumentation.ts

@@ -0,0 +1,109 @@
+/**
+ * DEV-ONLY server-error beacon via Next's `onRequestError` instrumentation hook.
+ *
+ * This is the PRIMARY server-side crash-detection surface for the in-pod dev-server:
+ * when a Server Component, a server action, or a route handler THROWS while rendering
+ * a request under `next dev`, Next invokes `onRequestError` with the structured error
+ * + request + routing context. The hook POSTs that detail SERVER-side, straight to the
+ * in-pod workspace-manager loopback receiver at
+ * `http://127.0.0.1:<FORGE_BEACON_PORT>/__forge_beacon`, which folds it into the
+ * supervisor's runtime state so the shop's recovery brain can originate a fix for a
+ * crash the `/ping` liveness probe cannot see (the dev-server process stays up and
+ * `/ping` stays 200, but `/` 500s per request).
+ *
+ * This complements the browser beacon (`ForgeErrorBeacon`): that one catches
+ * CLIENT-component / hydration throws that surface only in the browser; this one
+ * catches SERVER render throws that surface only in the dev-server. Both POST the
+ * same `/__forge_beacon` shape — the only difference is `source` (`'browser'` vs
+ * `'server'`).
+ *
+ * Gated entirely on `NODE_ENV === 'development'`: a deployed `next start` storefront
+ * registers no beacon (the literal check is inlined by the bundler, so the body is
+ * dead-code-eliminated from a production build) and the loopback receiver does not
+ * exist outside the pod. Next compiles `instrumentation.ts` for BOTH the Node and Edge
+ * runtimes; the loopback POST is a Node-only concern, so the hook also gates on the
+ * Node runtime — the Edge bundle then carries an inert no-op.
+ *
+ * The hook NEVER throws out of itself: a failed delivery is swallowed (the beacon is a
+ * best-effort backstop, never a hard dependency of the request), so a flapping receiver
+ * can never mask or replace the underlying request error Next is already reporting.
+ *
+ * The error's own `code` rides along verbatim — a fact, never a verdict: a request
+ * that races a recompile evaluates Turbopack's stub for a module that no longer parses
+ * and throws `code: 'MODULE_UNPARSABLE'`, and the receiver reads that code to leave a
+ * BUILD failure to the build detectors instead of folding it as a render crash.
+ */
+
+const BEACON_PORT = process.env.FORGE_BEACON_PORT ?? '3002';
+
+/**
+ * Server-start hook: warm-boot the embedded NestJS backend (`src/server/`)
+ * so the first `sdk.backend` invocation doesn't pay the context creation.
+ *
+ * Warm-up ONLY — correctness never depends on it: the dispatch path's lazy
+ * `getBackend()` is what re-boots the context after dev-mode (HMR) edits,
+ * and a boot failure here is deliberately swallowed so a drifted api-map
+ * can never crash the server start — the first invocation (and the dev
+ * methods route) reports the same error as a typed envelope instead. The
+ * dynamic import keeps the Edge bundle inert (Nest is Node-only), and a
+ * no-env boot (image pre-warm) succeeds because clients are only built at
+ * invocation time.
+ */
+export async function register(): Promise<void> {
+  // POSITIVE if-block, never an early return: webpack's parser dead-code-
+  // eliminates a statically-false `if` BODY (NEXT_RUNTIME is DefinePlugin-
+  // substituted per bundle), but it does NOT track reachability past a
+  // `return` — with the guard inverted, the EDGE instrumentation bundle
+  // (compiled because middleware.ts exists) chases this import into
+  // @nestjs/*'s node-builtin requires and `next build --webpack` dies with
+  // five Module-not-found errors ('stream', 'os', 'perf_hooks'; every
+  // publish-button CI run since this import landed). Turbopack prunes the
+  // dead branch either way — only the webpack publish build sees the
+  // difference.
+  if (process.env.NEXT_RUNTIME === 'nodejs') {
+    try {
+      const { getBackend } = await import('./server/bootstrap');
+      await getBackend();
+    } catch {
+      // Surfaced by the first sdk.backend invocation and /api/__backend/methods.
+    }
+  }
+}
+
+interface OnRequestErrorRequest {
+  path: string;
+  method: string;
+  headers: { [key: string]: string | string[] | undefined };
+}
+
+interface OnRequestErrorContext {
+  routerKind: string;
+  routePath: string;
+  routeType: string;
+}
+
+export async function onRequestError(
+  error: unknown,
+  request: OnRequestErrorRequest,
+  context: OnRequestErrorContext,
+): Promise<void> {
+  if (process.env.NODE_ENV !== 'development' || process.env.NEXT_RUNTIME !== 'nodejs') {
+    return;
+  }
+
+  const err = error as { message?: string; digest?: string; code?: unknown } | undefined;
+  const body = JSON.stringify({
+    message: typeof err?.message === 'string' ? err.message : String(error),
+    digest: typeof err?.digest === 'string' ? err.digest : undefined,
+    code: typeof err?.code === 'string' ? err.code : undefined,
+    route: request.path,
+    routeType: context.routeType,
+    source: 'server',
+  });
+
+  await fetch(`http://127.0.0.1:${BEACON_PORT}/__forge_beacon`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body,
+  }).catch(() => undefined);
+}

package/templates/storefront-blank/src/lib/account/account-link.ts

@@ -0,0 +1,76 @@
+import type { RouteSearchParams } from '../seo/noindex';
+
+/**
+ * The anatomy of a ONE-SHOT account link (#1472).
+ *
+ * The platform mails a shopper two kinds of link and both have the same shape:
+ * this storefront's own origin, a fixed route, and a single-use token in the
+ * query — `<origin>/verify?token=…` and `<origin>/reset-password?token=…`. The
+ * `?token=` spelling is the CONTRACT between the mail templates and these
+ * pages (a merchant may have customized the mail body, so the parameter name
+ * cannot be changed on one side alone); the platform supplies the origin, this
+ * module reads what arrives.
+ *
+ * PURE BY CONTRACT: no Next imports, no `process.env`, no fetch, no I/O — the
+ * same constraint `lib/locale/grammar.ts` and `lib/seo/noindex.ts` carry, for
+ * the same reason. `tool/storefront-template-spec` imports this file directly
+ * by relative path from OUTSIDE the scaffold, so anything reachable from here
+ * must resolve without the template's Next toolchain. A rule that decides what
+ * a shopper sees after clicking a one-shot credential has to be a table of
+ * vectors rather than something only a running server can exercise. The
+ * `RouteSearchParams` import is type-only and names another pure module, so it
+ * erases and drags nothing in.
+ */
+
+/**
+ * The query parameter every account link carries.
+ *
+ * Named once so the two pages and their vectors cannot disagree about the
+ * spelling the platform's mail templates emit.
+ */
+export const ACCOUNT_TOKEN_PARAM = 'token';
+
+/** What the shop API answered when a token was actually presented to it. */
+export type AccountCallOutcome = { kind: 'ok' } | { kind: 'error'; code: string };
+
+/**
+ * Everything a link render has to account for: the API's answer, or the fact
+ * that there was no usable token to ask about in the first place.
+ *
+ * `no-token` is not an error the API returned — it is a property of the URL —
+ * and keeping it in the same union is what lets ONE total function decide the
+ * whole page, instead of a page-level branch plus a function that covers only
+ * the half of the cases that reached the network.
+ */
+export type AccountLinkOutcome = AccountCallOutcome | { kind: 'no-token' };
+
+/**
+ * The single usable token in this URL, or null.
+ *
+ * Three ways to get null, each deliberate:
+ *
+ *  - ABSENT — the page was opened without a link (a typed URL, or a mail
+ *    client that dropped the query).
+ *  - BLANK — `?token=` or `?token=%20`. Surrounding whitespace is trimmed
+ *    because a mail client wrapping a long URL can deliver it padded and the
+ *    platform's tokens never contain whitespace; a value that is nothing but
+ *    padding is not a token.
+ *  - REPEATED — `?token=a&token=b` arrives as an array, and is REFUSED rather
+ *    than resolved to the first value. This is a one-shot credential: picking
+ *    one of two candidates would SPEND a real token on a guess about which one
+ *    the shopper meant, and the one that loses the guess is unrecoverable.
+ *    Nothing legitimate produces a repeat, so the honest answer is that this
+ *    URL carries no token the page may act on.
+ */
+export function readLinkToken(searchParams: RouteSearchParams): string | null {
+  const raw = searchParams[ACCOUNT_TOKEN_PARAM];
+  if (typeof raw === 'string') return trimmedOrNull(raw);
+  if (!Array.isArray(raw)) return null;
+  if (raw.length !== 1) return null;
+  return trimmedOrNull(raw[0]);
+}
+
+function trimmedOrNull(value: string): string | null {
+  const trimmed = value.trim();
+  return trimmed === '' ? null : trimmed;
+}

package/templates/storefront-blank/src/lib/account/account-state.ts

@@ -0,0 +1,152 @@
+import type { AccountCallOutcome } from './account-link';
+
+/**
+ * What `/account` renders, as a value (#1093).
+ *
+ * PURE BY CONTRACT, for the reasons `account-link.ts` states. The panel owns the
+ * COPY; this module owns which view a given answer of the shop API IS, so every
+ * decision the sign-in surface makes is a table of vectors and the panel is a
+ * render.
+ *
+ * The page is a static shell and the session lives on the shopper's own socket,
+ * so nothing here is known at render time: the server paints `loading`, and the
+ * panel asks the socket who is signed in once the cart provider has armed it.
+ */
+
+/** The shopper a signed-in session belongs to, as the account page greets them. */
+export interface SignedInCustomer {
+  readonly firstName: string;
+  readonly lastName: string;
+  readonly emailAddress: string;
+}
+
+/**
+ * What the shop API answered when asked who this socket's session belongs to.
+ *
+ * `customer: null` is an ordinary answer, not an error: a socket carrying no
+ * session, and an anonymous cart session, both belong to nobody.
+ */
+export type ActiveCustomerOutcome =
+  | { kind: 'ok'; customer: SignedInCustomer | null }
+  | { kind: 'error'; code: string };
+
+/** The call a refusal answered — what the panel says went wrong. */
+export type AccountStep = 'greeting' | 'sign-in' | 'sign-out';
+
+/** A refusal the panel renders, with the call it answered. */
+export interface AccountRefusal {
+  readonly step: AccountStep;
+  readonly code: string;
+}
+
+/**
+ * The views of the account page — each `state` is the `data-fc-account-state`
+ * the panel stamps.
+ *
+ *  - `loading`    — the server render, and every client render until the
+ *                   socket has been asked. A skeleton, never the form: a
+ *                   returning customer must land on their greeting without a
+ *                   flash of the sign-in form first.
+ *  - `signed-out` — the sign-in form, with the refusal that put it there, if
+ *                   any.
+ *  - `signed-in`  — the greeting and the way out.
+ */
+export type AccountView =
+  | { readonly state: 'loading' }
+  | { readonly state: 'signed-out'; readonly refusal: AccountRefusal | null }
+  | { readonly state: 'signed-in'; readonly customer: SignedInCustomer };
+
+/** The view the server renders. */
+export const LOADING_VIEW: AccountView = { state: 'loading' };
+
+/**
+ * The codes that mean the session the socket presented is OVER: the API holds
+ * no session for the token (`SESSION_NOT_FOUND`), or the request carried none
+ * it could use (`UNAUTHORIZED` — the guard's answer for a token that resolves
+ * to no session).
+ *
+ * A session that is over is a shopper who is signed out, not a fault: the
+ * greeting renders the form without a message, and a sign-out that finds the
+ * session already gone has done what it was asked.
+ */
+const SESSION_GONE_CODES: ReadonlySet<string> = new Set(['UNAUTHORIZED', 'SESSION_NOT_FOUND']);
+
+/**
+ * The refusal of a sign-in whose session greets nobody: the credentials were
+ * accepted, but the session belongs to no customer of THIS store — the code
+ * `/verify`'s `wrong-store` state reads for the same situation.
+ */
+const NO_CUSTOMER_CODE = 'CUSTOMER_NOT_FOUND';
+
+/** The refusal that a confirmation mail answers. */
+const NOT_VERIFIED_CODE = 'NOT_VERIFIED';
+
+/** Whether a refusal says the session it was asked about no longer exists. */
+export function isSessionGone(code: string): boolean {
+  return SESSION_GONE_CODES.has(code);
+}
+
+/**
+ * The view the page lands in when it asks who is signed in on arrival.
+ *
+ * A session that greets nobody — none on the socket, an anonymous cart session,
+ * or one that is over — is the sign-in form with nothing to apologise for. Any
+ * other refusal is shown: the form still renders, because a shopper who cannot
+ * be greeted can still try to sign in.
+ */
+export function greetingView(outcome: ActiveCustomerOutcome): AccountView {
+  if (outcome.kind === 'ok' && outcome.customer !== null) {
+    return { state: 'signed-in', customer: outcome.customer };
+  }
+  if (outcome.kind === 'ok' || isSessionGone(outcome.code)) {
+    return { state: 'signed-out', refusal: null };
+  }
+  return { state: 'signed-out', refusal: { step: 'greeting', code: outcome.code } };
+}
+
+/**
+ * The view an ACCEPTED sign-in lands in, from the greeting asked right after it.
+ *
+ * Unlike {@link greetingView}, "nobody is signed in" is never a silent answer
+ * here: the shopper has just been told yes, so a session that greets nobody is
+ * a failed sign-in and is rendered as one. A session that is gone the moment it
+ * was minted is the #1089 signature — a socket still speaking for the session
+ * it opened with — and is shown with its code rather than folded away.
+ */
+export function signInView(outcome: ActiveCustomerOutcome): AccountView {
+  if (outcome.kind === 'error') {
+    return { state: 'signed-out', refusal: { step: 'sign-in', code: outcome.code } };
+  }
+  if (outcome.customer === null) {
+    return { state: 'signed-out', refusal: { step: 'sign-in', code: NO_CUSTOMER_CODE } };
+  }
+  return { state: 'signed-in', customer: outcome.customer };
+}
+
+/** The view a REFUSED sign-in lands in. */
+export function signInRefusedView(code: string): AccountView {
+  return { state: 'signed-out', refusal: { step: 'sign-in', code } };
+}
+
+/**
+ * The view a sign-out lands in. Always `signed-out` — the session helper has
+ * left this tab without a session whatever the API answered — and a refusal is
+ * shown only when the API could not confirm the session ended.
+ */
+export function signedOutView(outcome: AccountCallOutcome): AccountView {
+  if (outcome.kind === 'ok') return { state: 'signed-out', refusal: null };
+  return { state: 'signed-out', refusal: { step: 'sign-out', code: outcome.code } };
+}
+
+/**
+ * Whether the view offers to send the confirmation mail again: only after a
+ * sign-in the API refused because the account was never confirmed. Without it
+ * that shopper has nowhere to go — the mail they lost is the only key.
+ */
+export function offersVerificationResend(view: AccountView): boolean {
+  return (
+    view.state === 'signed-out' &&
+    view.refusal?.step === 'sign-in' &&
+    view.refusal.code === NOT_VERIFIED_CODE
+  );
+}

package/templates/storefront-blank/src/lib/account/register-state.ts

@@ -0,0 +1,133 @@
+import type { AccountCallOutcome } from './account-link';
+
+/**
+ * What `/register` renders, as a value (#1471).
+ *
+ * PURE BY CONTRACT, for the reasons `account-link.ts` states. The form owns the
+ * COPY for each state; this module owns which state a given outcome IS, so the
+ * decision is a table of vectors and the form is a render.
+ *
+ * Unlike `/verify` and `/reset-password`, this page is not reached with a
+ * credential — a shopper types into it, and may type into it twice. That is why
+ * the states below are not a success/failure pair: the same submit, repeated,
+ * is an ORDINARY thing to happen, and what it should render is a prompt rather
+ * than an error.
+ */
+
+/**
+ * The states of the register page.
+ *
+ *  - `form`               — the initial render, and every render after a
+ *                           refusal the shopper can act on.
+ *  - `verify-your-email`  — the account exists and awaits verification. This is
+ *                           the ONE state a successful registration lands in:
+ *                           registering never signs anyone in (the account is
+ *                           minted unverified and a mail is dispatched), and a
+ *                           storefront that called `login` here was refused
+ *                           NOT_VERIFIED 287 ms later (prod, 2026-09-06). A
+ *                           repeat submit of the same address from the same
+ *                           session lands here too — that is what the shop
+ *                           API's session-scoped idempotency buys: one account,
+ *                           one prompt, no error on a double-clicked button.
+ *  - `already-registered` — the address belongs to an account this session did
+ *                           not create. It carries the resend affordance, since
+ *                           a shopper who never confirmed their address cannot
+ *                           sign in and has nowhere else to go.
+ *  - `signed-in-already`  — the account is verified; nothing is pending.
+ *  - `failed`             — the shop API was unreachable, or answered a code
+ *                           this template does not model.
+ */
+export type RegisterState =
+  | 'form'
+  | 'verify-your-email'
+  | 'already-registered'
+  | 'signed-in-already'
+  | 'failed';
+
+/**
+ * The API's answer to a register submit, as a pure value.
+ *
+ * Wider than {@link AccountCallOutcome} by exactly one field, because this
+ * operation's success is not a bare yes: `verificationPending` is the shop API
+ * READING `user.verified` back, and it is the point of the #1471 contract —
+ * the two successful answers are two different screens.
+ */
+export type RegisterOutcome =
+  | { kind: 'ok'; verificationPending: boolean }
+  | { kind: 'error'; code: string };
+
+/**
+ * `ErrorCode` → state for `registerCustomerAccount`.
+ *
+ * Both refusals collapse into ONE state, and that is a correctness requirement
+ * rather than a simplification: `IDENTIFIER_ALREADY_EXISTS` is the login
+ * identity's refusal and `EMAIL_ADDRESS_CONFLICT` the customer row's, and which
+ * one a shopper receives is decided purely by TIMING — the duplicate-address
+ * pre-check runs before the identity claim, so a resubmit arriving after the
+ * winner's customer row committed gets the second code where an in-flight twin
+ * gets the first. Rendering them differently would show two screens for one
+ * situation.
+ *
+ * `NOT_VERIFIED` is deliberately absent. That is the refusal a LOGIN gets on an
+ * unverified account, and this page signs nobody in —
+ * `registerCustomerAccount` cannot answer with it, so an arm for it would be a
+ * branch no vector can reach.
+ *
+ * Everything absent lands in `failed`: an unrecognised code is a state this
+ * template has not been taught, and guessing a friendlier one would put words
+ * in the API's mouth.
+ */
+const REGISTER_ERROR_STATES: Readonly<Record<string, RegisterState>> = {
+  IDENTIFIER_ALREADY_EXISTS: 'already-registered',
+  EMAIL_ADDRESS_CONFLICT: 'already-registered',
+};
+
+/**
+ * The state a submitted registration lands in. Total over the outcome union.
+ *
+ * The successful answer splits on `verificationPending` rather than assuming
+ * it: a fresh registration carrying a password is always pending, but an
+ * idempotent repeat can find the shopper verified in the meantime (they opened
+ * the link in another tab between the two submits), and sending them to their
+ * inbox for a mail they have already used is a dead end.
+ */
+export function registerState(outcome: RegisterOutcome): RegisterState {
+  if (outcome.kind === 'ok') {
+    return outcome.verificationPending ? 'verify-your-email' : 'signed-in-already';
+  }
+  return REGISTER_ERROR_STATES[outcome.code] ?? 'failed';
+}
+
+/**
+ * The states a verification resend lands in (`idle` is pre-submit).
+ *
+ * TWO outcomes, and the missing third is the design. The shop API throttles
+ * this endpoint — it is public and it sends mail — but it throttles SILENTLY:
+ * inside the window it answers exactly what it answers outside it, and exactly
+ * what it answers for an address that has no account at all. A `throttled`
+ * state would therefore be an enumeration tell rather than a courtesy, because
+ * the only way this storefront could render one is if the API had told it that
+ * THIS address has a pending account waiting on a recently-sent mail — the one
+ * fact the neutral answer exists to withhold. A throttled resend renders as
+ * `sent`, which is also what is true for the shopper: the mail is in their
+ * inbox, from a minute ago.
+ *
+ * `sent` is neutral for the same reason `passwordResetRequestState`'s is, and
+ * `failed` means the same thing it does there: we could not ASK, which says
+ * nothing about any account and would otherwise be a sent-mail promise we know
+ * to be false.
+ */
+export type VerificationResendState = 'idle' | 'sent' | 'failed';
+
+/**
+ * The state a submitted resend lands in.
+ *
+ * Its own function rather than an alias of `passwordResetRequestState`: the two
+ * surfaces have different pre-submit members (`idle` here, `form` there), and
+ * aliasing them would make a change to one silently change the other — that
+ * these two answers have the same shape today is a fact about the platform's
+ * anti-enumeration posture, not a dependency between the pages.
+ */
+export function verificationResendState(outcome: AccountCallOutcome): VerificationResendState {
+  return outcome.kind === 'ok' ? 'sent' : 'failed';
+}

package/templates/storefront-blank/src/lib/account/reset-password-state.ts

@@ -0,0 +1,111 @@
+import type { AccountCallOutcome } from './account-link';
+
+/**
+ * What `/reset-password` renders, as a value (#1472).
+ *
+ * One route, two modes — the URL's token decides which. WITH a token the page
+ * sets a new password; WITHOUT one it asks for an e-mail address and has a new
+ * link sent. Both modes start on their form and move to a terminal state when
+ * the API answers, so each mode gets its own union rather than one flat set
+ * that would let a request-mode render claim a reset-mode state.
+ *
+ * PURE BY CONTRACT, for the reasons `account-link.ts` states.
+ */
+
+/** The states a SUBMITTED new password lands in (`form` is pre-submit). */
+export type ResetPasswordSubmitState = 'done' | 'link-invalid' | 'password-rejected' | 'failed';
+
+/**
+ * The set-a-new-password mode.
+ *
+ *  - `form`              — the initial render, and every render after a
+ *                          refusal the shopper can act on.
+ *  - `done`              — the password was changed.
+ *  - `link-invalid`      — the API refused the token: used, expired, or issued
+ *                          by another store. One state, same reasons as the
+ *                          verify page's.
+ *  - `password-rejected` — the API refused the PASSWORD. The form stays up:
+ *                          the token is still good and the shopper only has to
+ *                          choose again.
+ *  - `failed`            — unreachable, or a code this template does not model.
+ */
+export type ResetPasswordState = 'form' | ResetPasswordSubmitState;
+
+/** The states a SUBMITTED reset request lands in (`form` is pre-submit). */
+export type PasswordResetRequestSubmitState = 'sent' | 'failed';
+
+/**
+ * The ask-for-a-link mode.
+ *
+ * `sent` is deliberately NEUTRAL and covers both of the API's successful
+ * answers: it reports whether an account matched, and rendering that difference
+ * would turn this form into an account-enumeration oracle — type an address,
+ * read the page, learn whether that person shops here. `failed` is reserved for
+ * the case where we could not ASK at all, which tells a visitor nothing about
+ * any account and would otherwise be a lie dressed as a sent mail.
+ */
+export type PasswordResetRequestState = 'form' | PasswordResetRequestSubmitState;
+
+/** Why a new-password form cannot be submitted yet. */
+export type NewPasswordProblem = 'empty' | 'mismatch';
+
+/**
+ * `ErrorCode` → state for `resetPassword`.
+ *
+ * `CUSTOMER_NOT_FOUND` is NOT the wrong-store case here, unlike on the verify
+ * page: consuming a reset token is scoped to the principal class of the
+ * requesting store, so another store's token simply does not resolve and
+ * arrives as `PASSWORD_RESET_TOKEN_INVALID`. Reaching `CUSTOMER_NOT_FOUND`
+ * means the token DID resolve inside this store and the customer row behind it
+ * is missing — a platform-side inconsistency, not something a shopper can act
+ * on — so it belongs in `failed` with the rest of the unmodelled codes.
+ */
+const RESET_ERROR_STATES: Readonly<Record<string, ResetPasswordSubmitState>> = {
+  PASSWORD_RESET_TOKEN_INVALID: 'link-invalid',
+  PASSWORD_RESET_TOKEN_EXPIRED: 'link-invalid',
+  PASSWORD_VALIDATION_FAILED: 'password-rejected',
+};
+
+/** The state a submitted new password lands in. */
+export function resetPasswordState(outcome: AccountCallOutcome): ResetPasswordSubmitState {
+  if (outcome.kind === 'ok') return 'done';
+  return RESET_ERROR_STATES[outcome.code] ?? 'failed';
+}
+
+/**
+ * The state a submitted reset REQUEST lands in.
+ *
+ * Every answer the API gives is `sent`; only a failure to reach it is anything
+ * else. See {@link PasswordResetRequestState} for why the successful answers
+ * are collapsed.
+ */
+export function passwordResetRequestState(
+  outcome: AccountCallOutcome,
+): PasswordResetRequestSubmitState {
+  return outcome.kind === 'ok' ? 'sent' : 'failed';
+}
+
+/**
+ * Whether the two password fields may be submitted, and if not, why.
+ *
+ * A UX affordance, NOT a security boundary, and the distinction is the whole
+ * reason the confirmation never leaves the browser: the shop API is the only
+ * authority on whether a password is acceptable (it answers
+ * `PASSWORD_VALIDATION_FAILED`, which arrives here as `password-rejected`), and
+ * a Server Action is a public endpoint that a caller can reach without ever
+ * rendering this form. Checking the confirmation client-side saves a shopper a
+ * round-trip and a spent token; it decides nothing the server would not decide
+ * again.
+ *
+ * The password is compared UNTRIMMED. Leading and trailing spaces are legal
+ * characters in a password, so trimming here would silently accept two values
+ * the API will treat as different.
+ */
+export function checkNewPassword(
+  password: string,
+  confirmation: string,
+): NewPasswordProblem | null {
+  if (password.length === 0) return 'empty';
+  if (password !== confirmation) return 'mismatch';
+  return null;
+}