@secmia/openui-flow 4.2.1 → 4.2.5

package/README.md

@@ -1,995 +1,338 @@
-# @secmia/openui-flow
-
-Production-ready adaptive workflow and onboarding flow engine for React.
-
-If you are evaluating quickly, you can get first success in under 3 minutes.
-
-## For AI agents
-
-Use [AGENTS.md](openui-flow/AGENTS.md) for a complete package debrief, API map, customization levels, and recommended implementation workflow.
-
-## 3-minute onboarding path
-
-1. Install package.
-2. Paste the starter component.
-3. Confirm `onComplete` fires.
-
-```bash
-npm install @secmia/openui-flow
-```
-
-```tsx
-'use client';
-
-import {
-  AdaptiveFlow,
-  DefaultAppRequirements,
-  type AdaptiveFlowAdapter,
-} from '@secmia/openui-flow';
-
-type AppRequirement =
-  | (typeof DefaultAppRequirements)[keyof typeof DefaultAppRequirements]
-  | 'selected_plan';
-
-const requirements: AppRequirement[] = [
-  DefaultAppRequirements.HAS_EMAIL,
-  DefaultAppRequirements.EMAIL_VERIFIED,
-  DefaultAppRequirements.HAS_PASSWORD,
-  DefaultAppRequirements.HAS_FIRST_NAME,
-  DefaultAppRequirements.ACCEPTED_TOS,
-  'selected_plan',
-];
-
-const adapter: AdaptiveFlowAdapter = {
-  async lookupByEmail(email) {
-    const exists = email.endsWith('@company.com');
-    return {
-      accountExists: exists,
-      hasPassword: exists,
-      isVerified: false,
-      agreedToTos: false,
-      profile: { firstName: null, lastName: null, jobTitle: null },
-    };
-  },
-  async requestOtp(email) {
-    console.log('request otp', email);
-  },
-  async verifyOtp(email, code) {
-    console.log('verify otp', email, code);
-  },
-};
-
-export default function FlowPage() {
-  return (
-    <AdaptiveFlow
-      requirements={requirements}
-      adapter={adapter}
-      persistence={{ key: 'flow-state:v1', storage: 'session' }}
-      onComplete={(context) => {
-        console.log('flow complete', context);
-      }}
-    />
-  );
-}
-```
-
-Expected result:
-- User progresses through required steps.
-- Flow ends at complete state.
-- `onComplete` receives final context.
-
-Peer dependencies:
-- `react` `^18 || ^19`
-- `react-dom` `^18 || ^19`
-
----
-
-## Quick answers
-
-Can users add their own flows?
-- Yes. This is first-class.
-- Define your own requirements, graph, step keys, resolver logic, and UI rendering.
-
-When should I use requirements vs requirementGraph?
-- Use `requirements` for the fastest start.
-- Use `requirementGraph` when you need priorities, conditions, or dependencies.
-
-How do I keep onboarding logic local to my app?
-- Create an app-specific requirement union near your flow module.
-- Include defaults and your custom requirements in one list.
-
----
-
-## First customization: local requirement contract
-
-```ts
-import { DefaultAppRequirements } from '@secmia/openui-flow';
-
-type DefaultRequirement =
-  (typeof DefaultAppRequirements)[keyof typeof DefaultAppRequirements];
-
-type ProductRequirement =
-  | DefaultRequirement
-  | 'selected_plan'
-  | 'connected_slack'
-  | 'has_workspace_name';
-
-export const requirements: ProductRequirement[] = [
-  DefaultAppRequirements.HAS_EMAIL,
-  DefaultAppRequirements.EMAIL_VERIFIED,
-  DefaultAppRequirements.HAS_PASSWORD,
-  DefaultAppRequirements.HAS_FIRST_NAME,
-  DefaultAppRequirements.ACCEPTED_TOS,
-  'selected_plan',
-  'connected_slack',
-];
-```
-
----
-
-## Next level: graph mode
-
-Use this when you need priority routing, conditional activation, dependency gates, or async resolvers.
-
-```tsx
-import {
-  AdaptiveFlow,
-  DefaultAdaptiveSteps,
-  createRequirementGraph,
-  type AdaptiveContextBase,
-  type RequirementResolver,
-} from '@secmia/openui-flow';
-
-type AppContext = AdaptiveContextBase & {
-  riskLevel: 'low' | 'high';
-  useSso: boolean;
-  selectedPlan: 'starter' | 'pro' | null;
-};
-
-type Req =
-  | 'has_email'
-  | 'email_verified'
-  | 'has_password'
-  | 'accepted_tos'
-  | 'selected_plan';
-
-type Step =
-  | 'COLLECT_EMAIL'
-  | 'VERIFY_OTP'
-  | 'COLLECT_PASSWORD'
-  | 'COLLECT_TOS'
-  | 'SELECT_PLAN'
-  | 'COMPLETE';
-
-const requirements: Req[] = [
-  'has_email',
-  'email_verified',
-  'has_password',
-  'accepted_tos',
-  'selected_plan',
-];
-
-const resolvers: Partial<Record<Req, RequirementResolver<AppContext, Step>>> = {
-  has_email: { step: 'COLLECT_EMAIL', isMet: (ctx) => Boolean(ctx.email) },
-  email_verified: { step: 'VERIFY_OTP', isMet: async (ctx) => ctx.isVerified },
-  has_password: { step: 'COLLECT_PASSWORD', isMet: (ctx) => ctx.hasPassword },
-  accepted_tos: { step: 'COLLECT_TOS', isMet: (ctx) => ctx.agreedToTos },
-  selected_plan: { step: 'SELECT_PLAN', isMet: (ctx) => Boolean(ctx.selectedPlan) },
-};
-
-const graph = createRequirementGraph(requirements, resolvers, {
-  priorities: {
-    email_verified: 20,
-    has_password: 10,
-    selected_plan: 5,
-  },
-  conditions: {
-    has_password: (ctx) => !ctx.useSso,
-    email_verified: (ctx) => ctx.riskLevel === 'high',
-  },
-  dependencies: {
-    selected_plan: ['accepted_tos'],
-  },
-});
-
-<AdaptiveFlow<AppContext, Req, Step>
-  requirementGraph={graph}
-  completeStep={DefaultAdaptiveSteps.COMPLETE}
-/>;
-```
-
----
-
-## Advanced: maximum configuration
-
-This demonstrates almost every major capability in one setup.
-
-```tsx
-'use client';
-
-import {
-  AdaptiveFlow,
-  DefaultAdaptiveSteps,
-  createDefaultRequirementGraph,
-  type AdaptiveContextBase,
-  type AdaptiveFlowAdapter,
-  type AdaptiveFlowValidators,
-  type RequirementResolver,
-} from '@secmia/openui-flow';
-
-type ProductContext = AdaptiveContextBase & {
-  selectedPlan: 'starter' | 'pro' | null;
-  workspaceName: string | null;
-  riskScore: number;
-  useSso: boolean;
-};
-
-type ProductRequirement =
-  | 'has_email'
-  | 'email_verified'
-  | 'has_password'
-  | 'has_first_name'
-  | 'accepted_tos'
-  | 'selected_plan'
-  | 'has_workspace_name';
-
-type ProductStep =
-  | 'COLLECT_EMAIL'
-  | 'VERIFY_OTP'
-  | 'COLLECT_PASSWORD'
-  | 'COLLECT_PROFILE'
-  | 'COLLECT_TOS'
-  | 'SELECT_PLAN'
-  | 'COLLECT_WORKSPACE'
-  | 'COMPLETE';
-
-const resolvers: Partial<Record<ProductRequirement, RequirementResolver<ProductContext, ProductStep>>> = {
-  selected_plan: {
-    step: 'SELECT_PLAN',
-    isMet: (ctx) => Boolean(ctx.selectedPlan),
-  },
-  has_workspace_name: {
-    step: 'COLLECT_WORKSPACE',
-    isMet: (ctx) => Boolean(ctx.workspaceName),
-  },
-};
-
-const graph = createDefaultRequirementGraph<ProductContext, ProductRequirement, ProductStep>({
-  requirements: [
-    'has_email',
-    'email_verified',
-    'has_password',
-    'has_first_name',
-    'accepted_tos',
-    'selected_plan',
-    'has_workspace_name',
-  ],
-  resolvers,
-  priorities: {
-    email_verified: 50,
-    has_password: 40,
-    selected_plan: 30,
-  },
-  conditions: {
-    has_password: (ctx) => !ctx.useSso,
-    email_verified: (ctx) => ctx.riskScore >= 70,
-  },
-  dependencies: {
-    has_workspace_name: ['selected_plan'],
-  },
-});
-
-const adapter: AdaptiveFlowAdapter<ProductContext> = {
-  async lookupByEmail(email) {
-    const response = await fetch('/api/identity/lookup', {
-      method: 'POST',
-      headers: { 'content-type': 'application/json' },
-      body: JSON.stringify({ email }),
-    });
-    if (!response.ok) {
-      throw new Error('Lookup failed.');
-    }
-    return response.json();
-  },
-  async requestOtp(email) {
-    await fetch('/api/identity/request-otp', {
-      method: 'POST',
-      headers: { 'content-type': 'application/json' },
-      body: JSON.stringify({ email }),
-    });
-  },
-  async verifyOtp(email, code) {
-    await fetch('/api/identity/verify-otp', {
-      method: 'POST',
-      headers: { 'content-type': 'application/json' },
-      body: JSON.stringify({ email, code }),
-    });
-  },
-  async saveProfile(context) {
-    await fetch('/api/profile', {
-      method: 'PATCH',
-      headers: { 'content-type': 'application/json' },
-      body: JSON.stringify(context.profile),
-    });
-  },
-  async acceptTos() {
-    await fetch('/api/legal/accept', { method: 'POST' });
-  },
-  async startOAuth(provider) {
-    window.location.href = `/api/identity/${provider}`;
-  },
-  async completeOAuth() {
-    return {
-      isVerified: true,
-      hasPassword: true,
-    };
-  },
-};
-
-const validators: AdaptiveFlowValidators<ProductContext> = {
-  email: (value) => {
-    if (!value.endsWith('@company.com')) {
-      return 'Company email is required.';
-    }
-  },
-  password: (value, { hasPassword }) => {
-    if (!hasPassword && value.length < 12) {
-      return 'Password must be at least 12 characters.';
-    }
-  },
-};
-
-export default function EnterpriseFlow() {
-  return (
-    <AdaptiveFlow<ProductContext, ProductRequirement, ProductStep>
-      requirementGraph={graph}
-      completeStep={DefaultAdaptiveSteps.COMPLETE}
-      adapter={adapter}
-      validators={validators}
-      persistence={{
-        key: 'enterprise-flow-state:v1',
-        storage: 'session',
-        clearOnComplete: true,
-      }}
-      stepTitles={{
-        SELECT_PLAN: 'Choose your plan',
-        COLLECT_WORKSPACE: 'Name your workspace',
-      }}
-      stepRegistry={{
-        SELECT_PLAN: ({ setContextPatch }) => (
-          <button onClick={() => setContextPatch({ selectedPlan: 'pro' })}>Select Pro Plan</button>
-        ),
-        COLLECT_WORKSPACE: ({ setContextPatch }) => (
-          <button onClick={() => setContextPatch({ workspaceName: 'Acme HQ' })}>Set Workspace</button>
-        ),
-      }}
-      renderStep={({ defaultView, transitions }) => (
-        <div>
-          <p>Transitions so far: {transitions.length}</p>
-          {defaultView}
-        </div>
-      )}
-      onStepTransition={(transition) => {
-        console.log('transition', transition);
-      }}
-      onError={(error) => {
-        console.error('flow error', error);
-      }}
-      onComplete={(context) => {
-        console.log('complete context', context);
-      }}
-      classNames={{
-        shell: 'rounded-xl border p-6 bg-white',
-        title: 'text-xl font-semibold',
-      }}
-      styles={{
-        shell: { maxWidth: 720 },
-      }}
-      unstyled={false}
-      initialValue={{
-        selectedPlan: null,
-        workspaceName: null,
-        riskScore: 80,
-        useSso: false,
-      }}
-    />
-  );
-}
-```
-
----
-
-## Custom UI: full control options
-
-You have 4 UI customization levels, from quick theming to complete headless control.
-
-### Level 1: style and class overrides
-
-Keep built-in UI structure, but override styles/classes for all slots.
-
-```tsx
-<AdaptiveFlow
-  classNames={{
-    shell: 'rounded-2xl border border-zinc-200 p-8',
-    title: 'text-2xl font-bold tracking-tight',
-    oauthButton: 'h-11 rounded-lg border px-4',
-    error: 'text-sm text-red-700 bg-red-50 rounded p-3',
-  }}
-  styles={{
-    shell: { maxWidth: 680, margin: '0 auto' },
-    title: { letterSpacing: '-0.01em' },
-  }}
-/>
-```
-
-Configure OAuth button list in default footer:
-
-```tsx
-<AdaptiveFlow
-  oauthProviders={[
-    { id: 'google', label: 'Continue with Google' },
-    { id: 'github', label: 'Continue with GitHub' },
-    { id: 'microsoft', label: 'Continue with Microsoft' },
-  ]}
-/>
-```
-
-Use `unstyled` to disable built-in inline defaults.
-
-```tsx
-<AdaptiveFlow unstyled classNames={{ shell: 'my-own-layout-root' }} />
-```
-
-### Level 2: custom UI for specific steps
-
-Use `stepRegistry` to replace selected steps with your own components while leaving other steps on defaults.
-
-```tsx
-<AdaptiveFlow
-  stepRegistry={{
-    SELECT_PLAN: ({ setContextPatch, run }) => (
-      <div>
-        <h3>Choose a plan</h3>
-        <button
-          onClick={() => {
-            void run(async () => {
-              setContextPatch({ selectedPlan: 'starter' });
-            });
-          }}
-        >
-          Starter
-        </button>
-        <button
-          onClick={() => {
-            void run(async () => {
-              setContextPatch({ selectedPlan: 'pro' });
-            });
-          }}
-        >
-          Pro
-        </button>
-      </div>
-    ),
-  }}
-/>
-```
-
-`run(job)` semantics in custom renderers:
-- sets `busy=true` during the async job
-- clears previous global/field errors before execution
-- catches and normalizes thrown errors into flow error state
-- reverts `busy=false` on completion
-
-Use it for custom step actions to keep consistent loading/error behavior.
-
-### Level 3: custom renderer for all steps
-
-Use `renderStep` for full step-body ownership. You can still reuse `defaultView` when useful.
-
-```tsx
-<AdaptiveFlow
-  renderStep={({ step, defaultView, transitions, context, setContextPatch }) => (
-    <section>
-      <header>
-        <h2>Current step: {step}</h2>
-        <p>Transitions: {transitions.length}</p>
-      </header>
-
-      <aside>
-        <button onClick={() => setContextPatch({ locale: 'en-US' } as Partial<typeof context>)}>
-          Set locale
-        </button>
-      </aside>
-
-      <main>{defaultView}</main>
-    </section>
-  )}
-/>
-```
-
-### Level 4: fully custom UI for everything (headless mode)
-
-If you want total control over shell, header, footer, button layout, and every interaction, use `useAdaptiveFlow` (or engine APIs directly).
-
-### Headless hook (`useAdaptiveFlow`)
-
-`useAdaptiveFlow` exposes the flow lifecycle without rendering any UI.
-
-```tsx
-'use client';
-
-import { useAdaptiveFlow, type AdaptiveContextBase } from '@secmia/openui-flow';
-
-type Ctx = AdaptiveContextBase & {
-  selectedPlan: 'starter' | 'pro' | null;
-};
-
-export default function FullyCustomFlow() {
-  const {
-    step,
-    context,
-    missingRequirements,
-    busy,
-    fieldErrors,
-    handleEmail,
-    handleOtp,
-    handlePassword,
-    handleProfile,
-    handleTos,
-    setContextPatch,
-  } = useAdaptiveFlow<Ctx>({
-    requirements: ['has_email', 'email_verified', 'has_password', 'has_first_name', 'accepted_tos', 'selected_plan'],
-    completeStep: 'COMPLETE',
-    initialValue: { selectedPlan: null },
-  });
-
-  return (
-    <div>
-      <h2>Step: {step}</h2>
-      <p>Pending: {missingRequirements.length}</p>
-      {fieldErrors.email ? <p>{fieldErrors.email}</p> : null}
-
-      <button disabled={busy} onClick={() => handleEmail('user@company.com')}>Submit Email</button>
-      <button disabled={busy} onClick={() => handleOtp('123456')}>Submit OTP</button>
-      <button disabled={busy} onClick={() => handlePassword('secure-password')}>Submit Password</button>
-      <button disabled={busy} onClick={() => handleProfile({ firstName: 'A', lastName: 'B', jobTitle: null })}>Save Profile</button>
-      <button disabled={busy} onClick={() => handleTos()}>Accept TOS</button>
-      <button onClick={() => setContextPatch({ selectedPlan: 'pro' })}>Select Plan</button>
-      <pre>{JSON.stringify(context, null, 2)}</pre>
-    </div>
-  );
-}
-```
-
-You can still bypass the hook and use pure engine APIs if you need lower-level control.
-
-### Optional schema validation (Zod-friendly)
-
-`AdaptiveFlow` and `useAdaptiveFlow` accept a `schemas` object. Any schema with `safeParse` or `parse` is supported (including Zod schemas).
-
-```tsx
-import { z } from 'zod';
-
-const emailSchema = z.string().email();
-const profileSchema = z.object({
-  firstName: z.string().min(1),
-  lastName: z.string().min(1),
-  jobTitle: z.string().nullable(),
-});
-
-<AdaptiveFlow
-  schemas={{
-    email: emailSchema,
-    profile: profileSchema,
-  }}
-/>
-```
-
-### Field-level validation errors
-
-Validators can return either a string or `{ field, message }`.
-
-```ts
-const validators = {
-  password: (value: string) => {
-    if (value.length < 12) {
-      return { field: 'password', message: 'Password must be at least 12 characters.' };
-    }
-  },
-};
-```
-
-Default UI now binds field errors to the matching input and sets `aria-invalid` automatically.
-
-```tsx
-'use client';
-
-import { useEffect, useMemo, useState } from 'react';
-import {
-  createRequirementGraph,
-  evaluateNextStep,
-  getMissingRequirements,
-  DefaultAdaptiveSteps,
-  type AdaptiveContextBase,
-  type RequirementResolver,
-} from '@secmia/openui-flow';
-
-type Ctx = AdaptiveContextBase & {
-  selectedPlan: 'starter' | 'pro' | null;
-};
-
-type Req = 'has_email' | 'email_verified' | 'selected_plan';
-type Step = 'COLLECT_EMAIL' | 'VERIFY_OTP' | 'SELECT_PLAN' | 'COMPLETE';
-
-const resolvers: Partial<Record<Req, RequirementResolver<Ctx, Step>>> = {
-  has_email: { step: 'COLLECT_EMAIL', isMet: (ctx) => Boolean(ctx.email) },
-  email_verified: { step: 'VERIFY_OTP', isMet: (ctx) => ctx.isVerified },
-  selected_plan: { step: 'SELECT_PLAN', isMet: (ctx) => Boolean(ctx.selectedPlan) },
-};
-
-export default function FullyCustomAuth() {
-  const [context, setContext] = useState<Ctx>({
-    email: null,
-    isVerified: false,
-    hasPassword: false,
-    agreedToTos: false,
-    profile: null,
-    selectedPlan: null,
-  });
-  const [step, setStep] = useState<Step>('COLLECT_EMAIL');
-  const [missing, setMissing] = useState<Req[]>([]);
-
-  const graph = useMemo(
-    () => createRequirementGraph<Ctx, Req, Step>(['has_email', 'email_verified', 'selected_plan'], resolvers),
-    [],
-  );
-
-  useEffect(() => {
-    void (async () => {
-      const [nextStep, missingReqs] = await Promise.all([
-        evaluateNextStep(context, graph, DefaultAdaptiveSteps.COMPLETE as Step),
-        getMissingRequirements(context, graph),
-      ]);
-      setStep(nextStep);
-      setMissing(missingReqs);
-    })();
-  }, [context, graph]);
-
-  return (
-    <div>
-      <header>
-        <h1>My Brand Auth</h1>
-        <p>
-          Progress: {3 - missing.length}/3
-        </p>
-      </header>
-
-      {step === 'COLLECT_EMAIL' ? (
-        <button onClick={() => setContext((prev) => ({ ...prev, email: 'user@company.com' }))}>
-          Mock email submit
-        </button>
-      ) : null}
-
-      {step === 'VERIFY_OTP' ? (
-        <button onClick={() => setContext((prev) => ({ ...prev, isVerified: true }))}>
-          Mock verify
-        </button>
-      ) : null}
-
-      {step === 'SELECT_PLAN' ? (
-        <button onClick={() => setContext((prev) => ({ ...prev, selectedPlan: 'pro' }))}>
-          Choose Pro
-        </button>
-      ) : null}
-
-      {step === 'COMPLETE' ? <p>All done.</p> : null}
-    </div>
-  );
-}
-```
-
-Precedence rule inside `AdaptiveFlow`:
-- `renderStep` wins first.
-- If `renderStep` is not provided, `stepRegistry[step]` is used.
-- If neither is provided, built-in default step UI is rendered.
-
-This gives you a clean path from quick defaults to complete custom UI ownership.
-
----
-
-## Integration recipes
-
-### Next.js App Router
-
-```tsx
-'use client';
-
-import { useRouter } from 'next/navigation';
-import {
-  AdaptiveFlow,
-  DefaultAppRequirements,
-  type AdaptiveFlowAdapter,
-} from '@secmia/openui-flow';
-
-type AppRequirement =
-  | (typeof DefaultAppRequirements)[keyof typeof DefaultAppRequirements]
-  | 'has_workspace_name';
-
-const requirements: AppRequirement[] = [
-  DefaultAppRequirements.HAS_EMAIL,
-  DefaultAppRequirements.EMAIL_VERIFIED,
-  DefaultAppRequirements.HAS_PASSWORD,
-  DefaultAppRequirements.HAS_FIRST_NAME,
-  DefaultAppRequirements.ACCEPTED_TOS,
-];
-
-const adapter: AdaptiveFlowAdapter = {
-  async lookupByEmail(email) {
-    const response = await fetch('/api/identity/lookup', {
-      method: 'POST',
-      headers: { 'content-type': 'application/json' },
-      body: JSON.stringify({ email }),
-    });
-    if (!response.ok) {
-      throw new Error('Lookup failed.');
-    }
-    return response.json();
-  },
-};
-
-export default function SignInClient() {
-  const router = useRouter();
-
-  return (
-    <AdaptiveFlow
-      adapter={adapter}
-      requirements={requirements}
-      persistence={{ key: 'next-flow-state:v1', storage: 'session' }}
-      onComplete={() => router.replace('/dashboard')}
-    />
-  );
-}
-```
-
-### Supabase
-
-```tsx
-'use client';
-
-import { createClient } from '@supabase/supabase-js';
-import { AdaptiveFlow, type AdaptiveFlowAdapter } from '@secmia/openui-flow';
-
-const supabase = createClient(
-  process.env.NEXT_PUBLIC_SUPABASE_URL!,
-  process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,
-);
-
-const adapter: AdaptiveFlowAdapter = {
-  async requestOtp(email) {
-    const { error } = await supabase.auth.signInWithOtp({ email });
-    if (error) {
-      throw new Error(error.message);
-    }
-  },
-  async verifyOtp(email, code) {
-    const { error } = await supabase.auth.verifyOtp({ email, token: code, type: 'email' });
-    if (error) {
-      throw new Error(error.message);
-    }
-  },
-  async startOAuth(provider) {
-    const { error } = await supabase.auth.signInWithOAuth({
-      provider,
-      options: { redirectTo: `${window.location.origin}/auth/callback` },
-    });
-    if (error) {
-      throw new Error(error.message);
-    }
-  },
-};
-
-export default function SupabaseAuth() {
-  return <AdaptiveFlow adapter={adapter} persistence={{ key: 'supabase-auth:v1' }} />;
-}
-```
-
-### Firebase
-
-```tsx
-'use client';
-
-import { getAuth, GoogleAuthProvider, OAuthProvider, signInWithPopup } from 'firebase/auth';
-import { AdaptiveFlow, type AdaptiveFlowAdapter } from '@secmia/openui-flow';
-import { app } from './firebase';
-
-const auth = getAuth(app);
-
-const adapter: AdaptiveFlowAdapter = {
-  async startOAuth(provider) {
-    if (provider === 'google') {
-      await signInWithPopup(auth, new GoogleAuthProvider());
-      return;
-    }
-    await signInWithPopup(auth, new OAuthProvider('apple.com'));
-  },
-};
-
-export default function FirebaseAuth() {
-  return <AdaptiveFlow adapter={adapter} persistence={{ key: 'firebase-auth:v1' }} />;
-}
-```
-
----
-
-## Engine-only usage
-
-```ts
-import {
-  createRequirementGraph,
-  evaluateNextStep,
-  getMissingRequirements,
-  DefaultAdaptiveSteps,
-} from '@secmia/openui-flow';
-
-const nextStep = await evaluateNextStep(context, graph, DefaultAdaptiveSteps.COMPLETE);
-const missing = await getMissingRequirements(context, graph);
-```
-
----
-
-## Core concepts
-
-- Context: current auth and profile state.
-- Requirement: business condition that must be satisfied.
-- Resolver: checker function for one requirement.
-- Step: current UI state for unmet requirement.
-- RequirementGraph: graph nodes with optional priority, condition, and dependency metadata.
-
-Graph behavior:
-- Dependency-aware ordering uses topological sorting.
-- Priority is used as tie-breaker among currently available nodes.
-- Circular dependencies and unknown dependencies are rejected during graph creation.
-
-Evaluation loop:
-1. Build graph.
-2. Evaluate active nodes.
-3. Select highest-priority unmet node.
-4. Render mapped step.
-5. Update context.
-6. Repeat until complete step.
-
----
-
-## API reference
-
-Primary exports:
-- `AdaptiveFlow`
-- `useAdaptiveFlow`
-- `defaultRequirements`
-- `initialContext`
-- `defaultRequirementResolvers`
-- `createDefaultRequirementGraph`
-- `createRequirementGraph`
-- `evaluateNextStep`
-- `getMissingRequirements`
-- `DefaultAdaptiveSteps`
-- `DefaultAppRequirements`
-
-Important types:
-- `AdaptiveFlowProps`
-- `AdaptiveFlowAdapter`
-- `UseAdaptiveFlowOptions`
-- `UseAdaptiveFlowResult`
-- `AdaptiveFlowValidators`
-- `AdaptiveFlowValidationResult`
-- `AdaptiveFlowValidationIssue`
-- `AdaptiveFlowFieldErrors`
-- `AdaptiveFlowSchemas`
-- `AdaptiveFlowSchema`
-- `AdaptiveFlowPersistence`
-- `AdaptiveFlowOAuthProvider`
-- `AdaptiveStepRegistry`
-- `AdaptiveStepRendererArgs`
-- `AdaptiveStepRenderArgs`
-- `AdaptiveStepTransition`
-- `RequirementResolver`
-- `RequirementGraph`
-- `RequirementGraphNode`
-- `AdaptiveContext`
-- `AdaptiveContextBase`
-
----
-
-## SSR and hydration notes
-
-- Storage persistence only runs in the browser (`window` guard).
-- On SSR, the flow starts from `initialValue`/defaults and then hydrates persisted browser state on mount.
-- For App Router and other SSR setups, pass server-known session hints in `initialValue` to minimize client-side step flash.
-
-Example:
-
-```tsx
-<AdaptiveFlow
-  initialValue={{
-    email: user.email ?? null,
-    isVerified: Boolean(user.emailVerifiedAt),
-    hasPassword: Boolean(user.hasPassword),
-  }}
-  persistence={{ key: 'flow-state:v1', storage: 'session' }}
-/>
-```
-
-### Retry policy
-
-Use `retryPolicy` to retry transient adapter failures with configurable backoff.
-
-```tsx
-<AdaptiveFlow
-  retryPolicy={{
-    maxAttempts: 4,
-    initialDelayMs: 200,
-    factor: 2,
-    maxDelayMs: 2000,
-    jitter: true,
-    shouldRetry: (error) => error.name !== 'FlowValidationError',
-  }}
-/>
-```
-
-Default behavior:
-- adapter calls are retried with exponential backoff
-- non-adapter validation errors are not retried unless `shouldRetry` allows them
-- retries use the browser/Node timer API, so no extra dependency is required
-
----
-
-## Release checklist
-
-- Ensure adapter methods return clear, user-safe errors.
-- Version persistence keys (example: `flow-state:v1`).
-- Track analytics with `onStepTransition`.
-- Keep requirements and graph definitions local to each product module.
-- Add integration tests for all flow branches.
-- Run `npm run typecheck` and `npm run build` before every publish.
-
----
-
-## Troubleshooting
-
-Step not appearing:
-- Cause: priority, condition, or dependency suppresses node activation.
-- Fix: inspect graph `priorities`, `conditions`, and `dependencies`.
-
-State resets on refresh:
-- Cause: persistence missing or wrong key.
-- Fix: set `persistence.key` and chosen storage.
-
-OAuth return does not resume:
-- Cause: missing `completeOAuth` or persistence disabled.
-- Fix: implement `completeOAuth` and enable persistence.
-
-Persistence write/read failures:
-- Cause: storage quota, blocked storage, malformed persisted payload.
-- Fix: pass `persistence.onError` to capture and report storage failures.
-
-Custom nested context fields collapsing after patch:
-- Cause: patching with a shallow object update.
-- Fix: the flow now performs a recursive object merge for plain nested objects. Arrays are replaced, not merged.
-
-```tsx
-<AdaptiveFlow
-  persistence={{
-    key: 'flow-state:v1',
-    storage: 'local',
-    onError: (error, phase) => {
-      console.error('persistence failure', phase, error);
-    },
-  }}
-/>
-```
-
----
-
-## License
-
-MIT
+# @secmia/openui-flow
+
+Adaptive, graph-driven multi-step flow orchestration for React.
+
+Build authentication, onboarding, compliance, setup, and gating flows with one engine:
+- requirement-based routing
+- dependency-aware graph evaluation
+- headless hook + default UI
+- adapter-driven backend integration
+- persistence, validation, retry/backoff
+
+## For AI agents
+
+Use [AGENTS.md](AGENTS.md) for implementation debrief, architecture notes, and workflow guidance.
+
+## Install
+
+```bash
+npm install @secmia/openui-flow
+```
+
+Peer dependencies:
+- `react` `^18 || ^19`
+- `react-dom` `^18 || ^19`
+
+## 3-minute quickstart (Next.js App Router safe)
+
+> Important: in Next.js App Router, functions cannot be passed from Server Components to Client Components. Keep `AdaptiveFlow`, adapter functions, and handlers inside a Client Component.
+
+```tsx
+// app/flow-demo.tsx
+'use client';
+
+import {
+  AdaptiveFlow,
+  DefaultAppRequirements,
+  type AdaptiveFlowAdapter,
+} from '@secmia/openui-flow';
+
+type AppRequirement =
+  | (typeof DefaultAppRequirements)[keyof typeof DefaultAppRequirements]
+  | 'selected_plan';
+
+const requirements: AppRequirement[] = [
+  DefaultAppRequirements.HAS_EMAIL,
+  DefaultAppRequirements.EMAIL_VERIFIED,
+  DefaultAppRequirements.HAS_PASSWORD,
+  DefaultAppRequirements.HAS_FIRST_NAME,
+  DefaultAppRequirements.HAS_LAST_NAME,
+  DefaultAppRequirements.HAS_JOB_TITLE,
+  DefaultAppRequirements.ACCEPTED_TOS,
+  'selected_plan',
+];
+
+const adapter: AdaptiveFlowAdapter = {
+  async lookupByEmail(email) {
+    const exists = email.endsWith('@company.com');
+    return {
+      accountExists: exists,
+      hasPassword: exists,
+      isVerified: false,
+      agreedToTos: false,
+      profile: { firstName: null, lastName: null, jobTitle: null },
+    };
+  },
+  async requestOtp(email) {
+    console.log('request otp', email);
+  },
+  async verifyOtp(email, code) {
+    console.log('verify otp', email, code);
+  },
+};
+
+export default function FlowDemo() {
+  return (
+    <AdaptiveFlow
+      requirements={requirements}
+      adapter={adapter}
+      persistence={{ key: 'flow-state:v1', storage: 'session' }}
+      onComplete={(context) => {
+        console.log('flow complete', context);
+      }}
+    />
+  );
+}
+```
+
+```tsx
+// app/page.tsx (Server Component)
+import FlowDemo from './flow-demo';
+
+export default function Page() {
+  return <FlowDemo />;
+}
+```
+
+## What this package is
+
+`@secmia/openui-flow` is a generic flow engine with a React-first API.
+
+You define:
+- requirements (conditions that must be met)
+- resolvers (how each requirement is evaluated)
+- graph metadata (priority, dependency, conditional activation)
+
+The engine decides the next step; UI can be default, partially custom, or fully headless.
+
+## Core model
+
+- `Context`: current user/product/session state.
+- `Requirement`: business condition (`has_email`, `accepted_tos`, etc.).
+- `Resolver`: maps requirement to `isMet(context)` + fallback step.
+- `RequirementGraph`: ordered nodes with `priority`, `dependsOn`, `when`.
+
+Graph guarantees:
+- cycle detection at graph creation
+- dependency validation
+- dependency-aware topological ordering
+- deterministic tie-breaking
+
+## API overview
+
+Primary exports:
+- `AdaptiveFlow`
+- `useAdaptiveFlow`
+- `createRequirementGraph`
+- `createDefaultRequirementGraph`
+- `evaluateNextStep`
+- `getMissingRequirements`
+- `defaultRequirements`
+- `defaultRequirementResolvers`
+- `initialContext`
+- `DefaultAppRequirements`
+- `DefaultAdaptiveSteps`
+
+High-value types:
+- `AdaptiveFlowProps`
+- `AdaptiveFlowAdapter`
+- `UseAdaptiveFlowOptions`
+- `UseAdaptiveFlowResult`
+- `AdaptiveFlowValidators`
+- `AdaptiveFlowSchemas`
+- `AdaptiveFlowPersistence`
+- `AdaptiveFlowRetryPolicy`
+- `AdaptiveFlowOAuthProvider`
+- `RequirementGraph`
+- `RequirementResolver`
+
+## UI customization levels
+
+### Level 1: style/class overrides
+
+```tsx
+<AdaptiveFlow
+  classNames={{
+    shell: 'rounded-xl border p-6',
+    title: 'text-xl font-semibold',
+    oauthButton: 'h-10 rounded border px-3',
+  }}
+  styles={{
+    shell: { maxWidth: 720 },
+  }}
+/>
+```
+
+Use `unstyled` to disable default inline styles.
+
+### Level 2: per-step overrides (`stepRegistry`)
+
+```tsx
+<AdaptiveFlow
+  stepRegistry={{
+    SELECT_PLAN: ({ setContextPatch }) => (
+      <button onClick={() => setContextPatch({ selectedPlan: 'pro' })}>Select Pro</button>
+    ),
+  }}
+/>
+```
+
+### Level 3: full step renderer (`renderStep`)
+
+```tsx
+<AdaptiveFlow
+  renderStep={({ step, defaultView, transitions }) => (
+    <section>
+      <h2>{step}</h2>
+      <p>Transitions: {transitions.length}</p>
+      {defaultView}
+    </section>
+  )}
+/>
+```
+
+### Level 4: fully headless (`useAdaptiveFlow`)
+
+```tsx
+'use client';
+
+import { useAdaptiveFlow } from '@secmia/openui-flow';
+
+export default function HeadlessFlow() {
+  const {
+    step,
+    busy,
+    fieldErrors,
+    handleEmail,
+    handleOtp,
+    setContextPatch,
+  } = useAdaptiveFlow({
+    requirements: ['has_email', 'email_verified', 'accepted_tos'],
+    completeStep: 'COMPLETE',
+  });
+
+  return (
+    <div>
+      <p>Step: {step}</p>
+      {fieldErrors.email ? <p>{fieldErrors.email}</p> : null}
+      <button disabled={busy} onClick={() => handleEmail('user@company.com')}>Submit Email</button>
+      <button disabled={busy} onClick={() => handleOtp('123456')}>Submit OTP</button>
+      <button onClick={() => setContextPatch({ agreedToTos: true })}>Accept TOS</button>
+    </div>
+  );
+}
+```
+
+## Validation and schemas
+
+Validators can return:
+- `string`
+- `{ field, message }`
+- `void`
+- async variants of the same
+
+```ts
+const validators = {
+  password: (value: string) => {
+    if (value.length < 12) {
+      return { field: 'password', message: 'Password must be at least 12 characters.' };
+    }
+  },
+};
+```
+
+Schema adapters are Zod-friendly (`safeParse` or `parse`):
+
+```tsx
+import { z } from 'zod';
+
+<AdaptiveFlow
+  schemas={{
+    email: z.string().email(),
+  }}
+/>
+```
+
+## Persistence
+
+```tsx
+<AdaptiveFlow
+  persistence={{
+    key: 'flow-state:v1',
+    storage: 'local',
+    clearOnComplete: true,
+    onError: (error, phase) => {
+      console.error('persistence', phase, error);
+    },
+  }}
+/>
+```
+
+## Retry/backoff (adapter calls)
+
+```tsx
+<AdaptiveFlow
+  retryPolicy={{
+    maxAttempts: 4,
+    initialDelayMs: 200,
+    factor: 2,
+    maxDelayMs: 2000,
+    jitter: true,
+    shouldRetry: (error) => error.name !== 'FlowValidationError',
+  }}
+/>
+```
+
+Notes:
+- retries apply to adapter calls (`lookupByEmail`, `requestOtp`, `verifyOtp`, etc.)
+- validation errors are not retried unless your `shouldRetry` allows them
+
+## OAuth
+
+- Default footer shows Google and Apple.
+- Override provider buttons with `oauthProviders`.
+- Redirect URL is owned by your adapter�s `startOAuth` implementation.
+
+```tsx
+<AdaptiveFlow
+  oauthProviders={[
+    { id: 'google', label: 'Continue with Google' },
+    { id: 'github', label: 'Continue with GitHub' },
+  ]}
+/>
+```
+
+```ts
+const adapter = {
+  async startOAuth(provider: string) {
+    window.location.href = `/api/identity/${provider}?redirectTo=${encodeURIComponent(`${window.location.origin}/auth/callback`)}`;
+  },
+  async completeOAuth() {
+    return { isVerified: true };
+  },
+};
+```
+
+## SSR and hydration
+
+- Storage reads/writes run only in the browser.
+- On SSR, flow starts with defaults/`initialValue` and hydrates client state on mount.
+- For minimal UI flash, seed `initialValue` from server-known session hints.
+
+## Troubleshooting
+
+- Next.js "Functions cannot be passed to Client Components": keep adapter and handlers in a Client Component.
+- Step not appearing: verify `priority`, `dependsOn`, and `when`.
+- State reset: check `persistence.key` and storage mode.
+- OAuth not resuming: implement `completeOAuth` and enable persistence.
+
+## Release checklist
+
+- `npm run typecheck`
+- `npm run build`
+- Verify adapter errors are user-safe and actionable
+- Use versioned persistence keys (for example `flow-state:v1`)
+
+## License
+
+MIT