@rightkit/onboarding 0.6.2 → 0.6.4

package/README.md

@@ -13,7 +13,7 @@ First-run onboarding framework for Right Suite apps. The legal agreement gate co
 
 | Import | Contents |
 |---|---|
-| `@rightkit/onboarding` | `Onboarding`, `isLegalAccepted`, `onboardingStateKey`, `licenseStep`, `modelsStep`, `permissionsStep`, `signInStep` (Google/Apple/OAuth buttons that call the shared `rightkit-oauth` owner; copy says "Opens your browser"; never an in-app webview, bogusyogi/rightkit#279); types from `types.ts`, `ModelsStepOptions` |
+| `@rightkit/onboarding` | `Onboarding`, `isLegalAccepted`, `onboardingStateKey`, `licenseStep`, `modelsStep`, `permissionsStep`, `signInStep` (Google/Apple/OAuth buttons that call the shared `rightkit-oauth` owner; copy says "Opens your browser"; never an in-app webview, bogusyogi/rightkit#279); native receipt: `createNativeLegalReceiptPort`, `LEGAL_RECEIPT_COMMANDS`, `reopenLegalAcceptance`, `resetLegalAcceptance`; adapters: `licenseBackendFromView`, `licenseStateFromView`, `signInBackendFromOAuth`; types from `types.ts` (including `LegalReceiptPort`, `LegalReceiptCreateRequest`, `DeclaredLegalDocument`), `LicenseStepCopy`, `LicenseStepOptions`, `ModelsStepOptions`, `LicenseViewClient`, `LicenseViewLike`, `LicenseViewBackendOptions`, `OAuthSignInPort`, `LegalReceiptInvoke`, `NativeLegalReceiptPortOptions` |
 | `@rightkit/onboarding/onboarding.css` | Stylesheet |
 
 ## Peer dependencies
@@ -21,7 +21,7 @@ First-run onboarding framework for Right Suite apps. The legal agreement gate co
 | Peer | Range |
 |---|---|
 | `@rightkit/react-shell` | `>=0.2.0 <1` |
-| `@rightkit/legal-ui` | `>=0.1.2 <1` |
+| `@rightkit/legal-ui` | `>=0.4.1 <1` |
 | `react` | `>=18 <21` |
 
 ## Example
@@ -45,7 +45,37 @@ import "@rightkit/onboarding/onboarding.css";
 
 Free or open-source apps without a legal gate pass `legalMode="none"` (no legal step, `legal` not needed, `appName` for the rail) or `legalMode="notice"` (no gate or acceptance; a first Notice step lists `legal.documents` as links). The default is `"gate"`.
 
-Acceptance is stored as `legalAcceptance: { version, documentsHash, acceptedAt, eligibilityBasis }`. An app that already keeps its own acceptance receipt can pass `legalReceipt` (`read()` and `write(record)`) and keep that store as the source of truth. Steps can set `canContinue(context)`, `onContinue(context)` (a veto: `false` or a throw keeps the step), `continueLabel`, and `skippable` (a per-step Skip button). `ctx.setResult(value)` stores a value that `onComplete({ completed, skipped, steps })` receives. `labels` overrides the button and status text, and `licenseStep(backend, { copy })` overrides the licence copy.
+`layout` is `"window"` by default (the surface fills the viewport, as in a dedicated onboarding window). `layout="contained"` removes the viewport minimum height so the host sizes the surface; it is passed to the legal gate as well (`@rightkit/legal-ui` `>=0.4.1`).
+
+Acceptance is stored as `legalAcceptance: { version, documentsHash, acceptedAt, eligibilityBasis }`. An app can pass `legalReceipt` and keep its own receipt as the source of truth (`read()` is consulted on load and overrides the settings copy). The receipt is recorded one of two ways:
+
+- **Native (preferred): `create(request)`.** The renderer declares `{ version, documentsHash, documents, eligibilityBasis, surface: "first_run" }` and no time; the native service stamps its own UTC `acceptedAt`, compares the declaration with the manifest it embeds, stores the receipt and returns the record. `receiptDocuments` sets the declared document set (default: the gate's titles and URLs; document bodies are never sent). Build the declaration with `acceptanceDeclaration(manifest)` and the digest with `materialAcceptanceDigestAsync(manifest)` from `@rightkit/legal/browser`. A throw, an invalid record, or a record for another version, digest or eligibility keeps the gate closed with an alert; if only the settings save failed afterwards, a retry reuses the receipt already created instead of stamping a second one.
+- **Legacy: `write(record)` (deprecated).** The renderer builds the record, including `acceptedAt` from the webview clock, and the app stores it. It is used only when the port has no `create`. A port with neither cannot accept.
+
+`createNativeLegalReceiptPort({ invoke })` is the port over the host's legal-receipt service (`rightkit_legal_receipt_read`, `rightkit_legal_receipt_create`, `rightkit_legal_receipt_reset`; `LEGAL_RECEIPT_COMMANDS`, override with `commands`). The native side registers those commands once under the host caller policy (`rightkit-tauri-shell` host services, trusted for the window that shows the gate) and stores the receipt under the app root. Command names are provisional until that service is published. A persistence failure, in any path, keeps the gate closed, and a bare legacy `legalAccepted` flag with no record never passes.
+
+`reopenLegalAcceptance({ settings })` makes the gate show again as a re-acceptance on the next mount (the old record stays until the user agrees; progress is kept). `resetLegalAcceptance({ settings, legalReceipt? })` clears the receipt first (`legalReceipt.reset`, required when a port is given) and then the settings copy, so the next mount shows the first-run gate.
+
+```tsx
+import { createNativeLegalReceiptPort } from "@rightkit/onboarding";
+import { acceptanceDeclaration, materialAcceptanceDigestAsync } from "@rightkit/legal/browser";
+import { invoke } from "@tauri-apps/api/core";
+
+const declaration = acceptanceDeclaration(manifest);
+<Onboarding
+  legalReceipt={createNativeLegalReceiptPort({ invoke })}
+  requiredVersion={declaration.acceptanceVersion}
+  requiredDocumentsHash={await materialAcceptanceDigestAsync(manifest)}
+  receiptDocuments={declaration.documents}
+  /* ... */
+/>
+```
+
+### Licence and sign-in adapters
+
+`licenseBackendFromView(client, options)` turns the native licence client (`createLicenseClient` from `@rightkit/license` 0.3.0, structurally: this package does not import it) into the `LicenseBackend` the licence step takes. The lifecycle decides the status (`grace`, `lifetime` and `verification_required` show as active; `migration_required`, `clock_repair_required`, `revoked` and `invalid` as invalid; anything unknown is invalid, never active). Pass `messageText: licenseMessage` for the detail text, `trialEmail` (where the trial email comes from; a trial is offered only with it and `client.requestTrial`), and optionally `purchaseUrl`, `openExternal`, `labels`. The step displays what the native service reports and decides nothing.
+
+`signIn` adds the built-in sign-in step after the licence step and is handed to every step as `ctx.signIn`. `signInBackendFromOAuth(port, providers)` builds it over the app's `rightkit-oauth` commands (`port.status()` and `port.signIn(provider)`, which call `OAuthClient::sign_in_with_browser` and open the default browser); only `signedIn` and `account` are read from the answers, and a sign-in that resolves without `signedIn: true` rejects so the step shows its retry message. `signInStep(backend)` still works as an app step. Steps can set `canContinue(context)`, `onContinue(context)` (a veto: `false` or a throw keeps the step), `continueLabel`, and `skippable` (a per-step Skip button). `ctx.setResult(value)` stores a value that `onComplete({ completed, skipped, steps })` receives. `labels` overrides the button and status text, and `licenseStep(backend, { copy })` overrides the licence copy.
 
 ## When the legal gate re-prompts
 

package/dist/Onboarding.d.ts

@@ -1,5 +1,23 @@
-import type { OnboardingProps, PersistedOnboardingState } from "./types.js";
+import type { LegalAcceptanceRecord, OnboardingProps, PersistedOnboardingState, SettingsBackend } from "./types.js";
+/** @internal Validates one stored or returned acceptance record; `undefined` when it is not a well-formed record. */
+export declare function readAcceptance(value: unknown): LegalAcceptanceRecord | undefined;
+/** @internal Normalises the persisted `onboarding.state` value. */
+export declare function readState(value: unknown): PersistedOnboardingState;
 /** True when the stored acceptance satisfies the host's requirement. */
 export declare function isLegalAccepted(state: PersistedOnboardingState, requiredVersion?: string, custom?: (state: PersistedOnboardingState) => boolean, requiredDocumentsHash?: string): boolean;
+/**
+ * True when the setup step `stepId` is settled in a persisted onboarding state: the step is completed or skipped, or the
+ * whole setup was set aside ("Set up later", `skipped: true`). Reads the raw persisted value, so callers need no cast.
+ * Missing or malformed input is false; it never throws. Which steps gate an app stays with the app.
+ */
+export declare function isStepSettled(state: unknown, stepId: string): boolean;
+/**
+ * Restarts the setup at its first step ("Show onboarding again"). The setup progress (completed and skipped steps, the
+ * set-aside flag) is cleared, but the legal acceptance is kept: the agreement is not asked again, and `legal` stays
+ * completed. Reads the stored value first, so the rest of the settings are untouched.
+ */
+export declare function restartOnboardingSetup({ settings }: {
+    settings: SettingsBackend;
+}): Promise<void>;
 export declare function onboardingStateKey(): string;
-export declare function Onboarding({ settings, legal, legalMode, appName, steps, permissions, models, license, onComplete, onSkip, className, layout, requiredVersion, requiredDocumentsHash, isAccepted, documentsHash, beforeLegalGate, requireModel, autoStartDownload, shouldAutoStart, onModelsStepEnter, modelsIntro, allowSkip, titlebar, dragRegion, legalDragRegion, legalReceipt, labels: labelOverrides }: OnboardingProps): import("react").JSX.Element | null;
+export declare function Onboarding({ settings, legal, legalMode, appName, steps, permissions, models, license, signIn, receiptDocuments, onComplete, onSkip, className, layout, requiredVersion, requiredDocumentsHash, isAccepted, documentsHash, beforeLegalGate, requireModel, autoStartDownload, shouldAutoStart, onModelsStepEnter, modelsIntro, allowSkip, titlebar, dragRegion, legalDragRegion, legalReceipt, labels: labelOverrides, frame, density, trafficLightInset }: OnboardingProps): import("react").JSX.Element | null;

package/dist/Onboarding.js

@@ -3,7 +3,7 @@ import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { LegalGate } from "@rightkit/legal-ui";
 import { Button } from "@rightkit/react-shell/react";
 import { cx } from "./ui.js";
-import { licenseStep, modelsStep, permissionsStep } from "./steps.js";
+import { licenseStep, modelsStep, permissionsStep, signInStep } from "./steps.js";
 const KEY = "onboarding.state";
 const INITIAL = { version: 1, currentStep: 0, completed: [], skipped: false, legalAccepted: false };
 const DEFAULT_LABELS = { skip: "Set up later", skipStep: "Skip", back: "Back", continue: "Continue", finish: "Finish setup", loading: "Loading setup…" };
@@ -14,7 +14,8 @@ function isCanonicalUtc(value) {
     const parsed = Date.parse(value);
     return Number.isFinite(parsed) && new Date(parsed).toISOString() === value;
 }
-function readAcceptance(value) {
+/** @internal Validates one stored or returned acceptance record; `undefined` when it is not a well-formed record. */
+export function readAcceptance(value) {
     if (!value || typeof value !== "object" || Array.isArray(value))
         return undefined;
     const r = value;
@@ -28,7 +29,8 @@ function readAcceptance(value) {
         return undefined;
     return { version: r.version, documentsHash: r.documentsHash, acceptedAt: r.acceptedAt, eligibilityBasis: r.eligibilityBasis };
 }
-function readState(value) {
+/** @internal Normalises the persisted `onboarding.state` value. */
+export function readState(value) {
     if (!value || typeof value !== "object")
         return INITIAL;
     const candidate = value;
@@ -44,18 +46,34 @@ function readState(value) {
         legalAccepted: legalAcceptance !== undefined || (!hasStoredAcceptance && candidate.legalAccepted === true),
         eligibilityBasis: legalAcceptance?.eligibilityBasis ?? (candidate.eligibilityBasis === "individual" || candidate.eligibilityBasis === "enterprise" ? candidate.eligibilityBasis : undefined),
         ...(legalAcceptance ? { legalAcceptance } : {}),
+        ...(candidate.legalReopened === true ? { legalReopened: true } : {}),
         ...(Array.isArray(candidate.skippedSteps) ? { skippedSteps: candidate.skippedSteps.filter((x) => typeof x === "string") } : {}),
     };
 }
-/** Replace the acceptance in `state` with the one from the app's receipt (`undefined`: not accepted). */
-function withReceipt(state, record) {
+/**
+ * Replace the acceptance in `state` with the one from the app's receipt (`undefined`: not accepted). A `historical` record
+ * (`HistoricalLegalReceipt`) is kept as the acceptance for the re-acceptance variant but never counts as accepted: it is
+ * flagged reopened, so the gate shows again and the setup progress is left alone.
+ */
+function withReceipt(state, record, historical = false) {
     const { legalAcceptance: _drop, eligibilityBasis: _basis, ...rest } = state;
     void _drop;
     void _basis;
-    return record ? { ...rest, legalAccepted: true, eligibilityBasis: record.eligibilityBasis, legalAcceptance: record } : { ...rest, legalAccepted: false };
+    if (!record)
+        return { ...rest, legalAccepted: false };
+    if (historical)
+        return { ...rest, legalAccepted: false, legalReopened: true, eligibilityBasis: record.eligibilityBasis, legalAcceptance: record };
+    return { ...rest, legalAccepted: true, eligibilityBasis: record.eligibilityBasis, legalAcceptance: record };
+}
+/** True when a `LegalReceiptPort.read()` value is a historical receipt (`{ record, current: false }`). */
+function isHistoricalReceipt(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value) && "record" in value && value.current === false;
 }
 /** True when the stored acceptance satisfies the host's requirement. */
 export function isLegalAccepted(state, requiredVersion, custom, requiredDocumentsHash) {
+    // A reopened agreement (`reopenLegalAcceptance`) is not accepted until the user agrees again, whatever the host's check says.
+    if (state.legalReopened === true)
+        return false;
     if (custom)
         return custom(state);
     // A stored record whose timestamp is not canonical UTC is not an acceptance,
@@ -72,6 +90,39 @@ export function isLegalAccepted(state, requiredVersion, custom, requiredDocument
     // `legalAccepted` flag carries no version, time or basis, so it re-prompts once (as re-acceptance).
     return state.legalAcceptance !== undefined;
 }
+/**
+ * True when the setup step `stepId` is settled in a persisted onboarding state: the step is completed or skipped, or the
+ * whole setup was set aside ("Set up later", `skipped: true`). Reads the raw persisted value, so callers need no cast.
+ * Missing or malformed input is false; it never throws. Which steps gate an app stays with the app.
+ */
+export function isStepSettled(state, stepId) {
+    try {
+        if (typeof state !== "object" || state === null || typeof stepId !== "string")
+            return false;
+        const candidate = state;
+        if (candidate.skipped === true)
+            return true;
+        const completed = Array.isArray(candidate.completed) && candidate.completed.includes(stepId);
+        const skipped = Array.isArray(candidate.skippedSteps) && candidate.skippedSteps.includes(stepId);
+        return completed || skipped;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Restarts the setup at its first step ("Show onboarding again"). The setup progress (completed and skipped steps, the
+ * set-aside flag) is cleared, but the legal acceptance is kept: the agreement is not asked again, and `legal` stays
+ * completed. Reads the stored value first, so the rest of the settings are untouched.
+ */
+export async function restartOnboardingSetup({ settings }) {
+    const key = onboardingStateKey();
+    const snapshot = await settings.load();
+    const state = readState(snapshot.values[key]);
+    await settings.patch({
+        [key]: { ...state, currentStep: 0, skipped: false, skippedSteps: [], completed: state.completed.filter((id) => id === "legal") },
+    }, snapshot.revision);
+}
 /** FNV-1a fallback when SubtleCrypto is unavailable. */
 function fnv(text) {
     let h = 0x811c9dc5;
@@ -104,7 +155,7 @@ function NoticeList({ documents }) {
         return _jsx("p", { className: "rk-onboarding__muted", children: "No notices to show." });
     return _jsx("ul", { className: "rk-onboarding__notices", children: documents.map((d) => _jsx("li", { children: d.onOpen ? _jsx("button", { type: "button", onClick: d.onOpen, children: d.title }) : d.url ? _jsx("a", { href: d.url, target: "_blank", rel: "noreferrer", children: d.title }) : d.title }, d.title)) });
 }
-export function Onboarding({ settings, legal, legalMode = "gate", appName, steps = [], permissions, models, license, onComplete, onSkip, className, layout = "window", requiredVersion, requiredDocumentsHash, isAccepted, documentsHash, beforeLegalGate, requireModel, autoStartDownload, shouldAutoStart, onModelsStepEnter, modelsIntro, allowSkip = true, titlebar, dragRegion, legalDragRegion = false, legalReceipt, labels: labelOverrides }) {
+export function Onboarding({ settings, legal, legalMode = "gate", appName, steps = [], permissions, models, license, signIn, receiptDocuments, onComplete, onSkip, className, layout = "window", requiredVersion, requiredDocumentsHash, isAccepted, documentsHash, beforeLegalGate, requireModel, autoStartDownload, shouldAutoStart, onModelsStepEnter, modelsIntro, allowSkip = true, titlebar, dragRegion, legalDragRegion = false, legalReceipt, labels: labelOverrides, frame = "rail", density = "default", trafficLightInset = false }) {
     if (legalMode === "gate" && !legal)
         throw new Error("Onboarding: `legal` is required when legalMode is \"gate\"");
     const L = { ...DEFAULT_LABELS, ...labelOverrides };
@@ -121,6 +172,8 @@ export function Onboarding({ settings, legal, legalMode = "gate", appName, steps
     /** Values passed to `ctx.setResult`, keyed by step id; handed to `onComplete`. */
     const stepResults = useRef({});
     const [continuing, setContinuing] = useState(false);
+    /** A receipt the native service already created for this agreement when saving the settings failed; a retry reuses it instead of stamping a second one. */
+    const createdReceipt = useRef(null);
     /** Persists a patch; throws when the settings backend rejects it. */
     const persist = useCallback(async (patch) => {
         setSaving(true);
@@ -161,14 +214,22 @@ export function Onboarding({ settings, legal, legalMode = "gate", appName, steps
                 }
                 // The app's receipt is the source of truth for acceptance; an unreadable receipt counts as none.
                 let record;
+                let historical = false;
                 try {
-                    record = readAcceptance(await legalReceipt.read());
+                    const value = await legalReceipt.read();
+                    if (isHistoricalReceipt(value)) {
+                        record = readAcceptance(value.record);
+                        historical = record !== undefined;
+                    }
+                    else
+                        record = readAcceptance(value);
                 }
                 catch {
                     record = undefined;
+                    historical = false;
                 }
                 if (live)
-                    setState(withReceipt(loaded, record));
+                    setState(withReceipt(loaded, record, historical));
             }
             catch (e) {
                 if (live)
@@ -183,8 +244,9 @@ export function Onboarding({ settings, legal, legalMode = "gate", appName, steps
         ...(permissions ? [permissionsStep(permissions)] : []),
         ...(models ? [modelsStep(models, { required: requireModel, autoStartDownload, shouldAutoStart, onModelsStepEnter, intro: modelsIntro, startGuard: modelsStarted })] : []),
         ...(license ? [licenseStep(license)] : []),
+        ...(signIn ? [signInStep(signIn)] : []),
         ...steps,
-    ], [gated, legalMode, legal?.documents, license, models, permissions, steps, requireModel, autoStartDownload, shouldAutoStart, onModelsStepEnter, modelsIntro]);
+    ], [gated, legalMode, legal?.documents, license, signIn, models, permissions, steps, requireModel, autoStartDownload, shouldAutoStart, onModelsStepEnter, modelsIntro]);
     const activeState = state ?? INITIAL;
     const accepted = !gated || isLegalAccepted(activeState, requiredVersion, isAccepted, requiredDocumentsHash);
     const needsGate = state !== null && !accepted;
@@ -216,7 +278,7 @@ export function Onboarding({ settings, legal, legalMode = "gate", appName, steps
         return () => { live = false; };
     }, [needsGate, gateCleared, beforeLegalGate]);
     const setResult = useCallback((value) => { stepResults.current[activeId] = value; }, [activeId]);
-    const context = { state: activeState, settings, setState: saveStep, permissions, models, license, ready: readyMap, setReady, setResult };
+    const context = { state: activeState, settings, setState: saveStep, permissions, models, license, signIn, ready: readyMap, setReady, setResult };
     const canContinue = active?.canContinue ? active.canContinue(context) : true;
     const runCallback = async (callback) => {
         try {
@@ -266,7 +328,7 @@ export function Onboarding({ settings, legal, legalMode = "gate", appName, steps
         }
         await markAndMove(index + 1, { completed: active.id });
     };
-    const rootClass = cx("rk-onboarding", layout === "contained" && "rk-onboarding--contained", className);
+    const rootClass = cx("rk-onboarding", layout === "contained" && "rk-onboarding--contained", density === "compact" && "rk-onboarding--compact", trafficLightInset && "rk-onboarding--lights", frame === "card" && "rk-onboarding--card", className);
     if (error && !state)
         return _jsxs("div", { className: rootClass, children: [_jsx("p", { className: "rk-onboarding__error", role: "alert", children: error }), _jsx(Button, { onClick: () => window.location.reload(), children: "Retry" })] });
     if (state && !active)
@@ -279,24 +341,57 @@ export function Onboarding({ settings, legal, legalMode = "gate", appName, steps
         if (!legal)
             return null;
         const reacceptance = activeState.legalAccepted || activeState.legalAcceptance !== undefined;
+        /** Records the acceptance and returns the record to mirror into the settings state. A throw keeps the gate closed. */
+        const recordAcceptance = async (gate, basis) => {
+            const version = requiredVersion ?? "1";
+            const hash = documentsHash ?? requiredDocumentsHash ?? await hashDocuments(gate.documents);
+            if (legalReceipt?.create) {
+                // Native path: the service stamps the time and stores the receipt; nothing is built in the renderer.
+                const key = [version, hash, basis].join("\n");
+                if (createdReceipt.current?.key === key)
+                    return createdReceipt.current.record;
+                const declared = receiptDocuments ?? gate.documents.map((d) => ({ title: d.title, ...(d.url ? { url: d.url } : {}) }));
+                const created = readAcceptance(await legalReceipt.create({ version, documentsHash: hash, documents: declared, eligibilityBasis: basis, surface: "first_run" }));
+                if (!created)
+                    throw new Error("The legal receipt service returned an invalid record.");
+                // Bind the response to the declaration sent and any independent required hash.
+                if (created.eligibilityBasis !== basis || created.version !== version || created.documentsHash !== hash || (requiredDocumentsHash !== undefined && created.documentsHash !== requiredDocumentsHash)) {
+                    throw new Error("The legal receipt does not match the agreement that was shown.");
+                }
+                createdReceipt.current = { key, record: created };
+                return created;
+            }
+            // LEGACY: the renderer builds the record with the webview clock. Deprecated; implement `legalReceipt.create`.
+            const record = { version, documentsHash: hash, acceptedAt: new Date().toISOString(), eligibilityBasis: basis };
+            if (legalReceipt) {
+                if (!legalReceipt.write)
+                    throw new Error("The legal receipt can neither create nor write an acceptance.");
+                await legalReceipt.write(record);
+            }
+            return record;
+        };
         return _jsxs("div", { className: cx("rk-onboarding rk-onboarding--legal", layout === "contained" && "rk-onboarding--contained", className), "data-testid": "onboarding-legal", "data-variant": reacceptance ? "re-acceptance" : "first-run", children: [_jsx(TitleStrip, { titlebar: titlebar, dragRegion: legalDragRegion }), _jsx(LegalGate, { ...legal, layout: layout, variant: reacceptance ? "re-acceptance" : "first-run", onQuit: () => void legal.onQuit?.(), onAgree: async ({ eligibilityBasis }) => {
-                        const legalAcceptance = { version: requiredVersion ?? "1", documentsHash: documentsHash ?? requiredDocumentsHash ?? await hashDocuments(legal.documents), acceptedAt: new Date().toISOString(), eligibilityBasis };
-                        if (legalReceipt) {
-                            try {
-                                await legalReceipt.write(legalAcceptance);
-                            }
-                            catch (e) {
-                                setError(e instanceof Error ? e.message : String(e));
-                                throw e;
-                            }
+                        let legalAcceptance;
+                        try {
+                            legalAcceptance = await recordAcceptance(legal, eligibilityBasis);
+                        }
+                        catch (e) {
+                            setError(e instanceof Error ? e.message : String(e));
+                            throw e;
                         }
                         const progress = reacceptance ? {} : { completed: ["legal"], currentStep: builtins.length > 1 ? 1 : 0 };
-                        await persist({ legalAccepted: true, eligibilityBasis, legalAcceptance, ...progress });
+                        await persist({ legalAccepted: true, legalReopened: false, eligibilityBasis, legalAcceptance, ...progress });
+                        createdReceipt.current = null;
                         if (!reacceptance && builtins.length === 1)
                             await onComplete(resultOf(["legal"], []));
                     } })] });
     }
     const body = active.render(context);
+    if (frame === "card") {
+        // The HeardRight v5 frame: one centred card, the app name on top, a dot pager and no step rail.
+        return _jsxs("main", { className: rootClass, "data-testid": "onboarding", "data-step-id": active.id, "data-frame": "card", children: [_jsx(TitleStrip, { titlebar: titlebar, dragRegion: dragRegion }), _jsxs("section", { className: "rk-onboarding__main rk-onboarding__main--card", children: [_jsx("div", { className: "rk-onboarding__brand rk-onboarding__brand--card", children: appName ?? legal?.appName }), _jsxs("div", { className: "rk-onboarding__frame", children: [active.title ? _jsx("h1", { children: active.title }) : null, active.description ? _jsx("p", { className: "rk-onboarding__description", children: active.description }) : null, _jsx("div", { className: "rk-onboarding__content", children: body }), error ? _jsx("p", { className: "rk-onboarding__error", role: "alert", children: error }) : null, _jsxs("footer", { children: [_jsx(Button, { variant: "secondary", disabled: index <= lead || saving || continuing, onClick: () => void save({ currentStep: index - 1 }), children: L.back }), _jsx("nav", { className: "rk-onboarding__dots", "aria-label": "Setup progress", children: builtins.map((step, i) => _jsx("button", { type: "button", className: cx("rk-onboarding__dot", i === index && "is-active", activeState.completed.includes(step.id) && "is-done"), "aria-label": `Step ${i + 1}: ${step.label}`, "aria-current": i === index ? "step" : undefined, disabled: (gated && i === 0 && builtins.length > 1) || continuing, onClick: () => { if (!continuing && i >= lead && (i <= index || canContinue))
+                                                    void save({ currentStep: i }); } }, step.id)) }), _jsx("span", { className: "rk-onboarding__hint", children: !canContinue && active.blockedHint ? active.blockedHint : null }), allowSkip ? _jsx(Button, { variant: "ghost", disabled: saving || continuing, onClick: () => { void save({ currentStep: index, skipped: true }).then((ok) => ok ? runCallback(onSkip) : undefined); }, children: L.skip }) : null, active.skippable ? _jsx(Button, { variant: "ghost", disabled: saving || continuing, onClick: () => void markAndMove(index + 1, { skipped: active.id }), children: L.skipStep }) : null, _jsx(Button, { variant: "primary", disabled: saving || continuing || !canContinue, onClick: () => void advance(), children: active.continueLabel ?? (index === builtins.length - 1 ? L.finish : L.continue) })] })] })] })] });
+    }
     return _jsxs("main", { className: rootClass, "data-testid": "onboarding", "data-step-id": active.id, children: [_jsx(TitleStrip, { titlebar: titlebar, dragRegion: dragRegion }), _jsxs("aside", { className: "rk-onboarding__rail", children: [_jsx("div", { className: "rk-onboarding__brand", children: appName ?? legal?.appName }), _jsx("nav", { "aria-label": "Setup progress", children: builtins.map((step, i) => _jsxs("button", { type: "button", className: cx("rk-onboarding__step", i === index && "is-active", activeState.completed.includes(step.id) && "is-done"), "aria-current": i === index ? "step" : undefined, disabled: (gated && i === 0 && builtins.length > 1) || continuing, onClick: () => { if (!continuing && i >= lead && (i <= index || canContinue))
                                 void save({ currentStep: i }); }, children: [_jsx("span", { children: activeState.completed.includes(step.id) ? "✓" : i + 1 }), step.label] }, step.id)) })] }), _jsxs("section", { className: "rk-onboarding__main", children: [_jsxs("header", { children: [_jsxs("p", { className: "rk-onboarding__eyebrow", children: ["Step ", index + 1, " of ", builtins.length] }), active.title ? _jsx("h1", { children: active.title }) : null, active.description ? _jsx("p", { className: "rk-onboarding__description", children: active.description }) : null] }), _jsx("div", { className: "rk-onboarding__content", children: body }), error ? _jsx("p", { className: "rk-onboarding__error", role: "alert", children: error }) : null, _jsxs("footer", { children: [allowSkip ? _jsx(Button, { variant: "ghost", disabled: saving || continuing, onClick: () => { void save({ currentStep: index, skipped: true }).then((ok) => ok ? runCallback(onSkip) : undefined); }, children: L.skip }) : null, active.skippable ? _jsx(Button, { variant: "ghost", disabled: saving || continuing, onClick: () => void markAndMove(index + 1, { skipped: active.id }), children: L.skipStep }) : null, _jsx("span", { className: "rk-onboarding__hint", children: !canContinue && active.blockedHint ? active.blockedHint : null }), _jsx(Button, { variant: "secondary", disabled: index <= lead || saving || continuing, onClick: () => void save({ currentStep: index - 1 }), children: L.back }), _jsx(Button, { variant: "primary", disabled: saving || continuing || !canContinue, onClick: () => void advance(), children: active.continueLabel ?? (index === builtins.length - 1 ? L.finish : L.continue) })] })] })] });
 }

package/dist/adapters.d.ts

@@ -0,0 +1,59 @@
+import type { LicenseBackend, LicenseState, SignInBackend, SignInProvider } from "./types.js";
+/**
+ * The fields of `@rightkit/license` 0.3.0 `LicenseView` that the adapter reads. Structural on purpose: this package does not
+ * import the licence package, so `createLicenseClient(...)` output is accepted as it is and an app that has no licence step
+ * never loads it.
+ */
+export interface LicenseViewLike {
+    status: string;
+    lifecycle?: string;
+    tier?: string | null;
+    /** Unix milliseconds. */
+    validUntil?: number | null;
+    /** A closed `MessageCode`; text comes from `messageText`. */
+    message?: string;
+}
+/** The slice of `createLicenseClient(...)` the licence step needs. */
+export interface LicenseViewClient {
+    status(): Promise<LicenseViewLike>;
+    activate(key: string): Promise<LicenseViewLike>;
+    /** Present on the real client. A trial needs `trialEmail` as well. */
+    requestTrial?(email: string): Promise<{
+        accepted: boolean;
+        message?: string;
+    }>;
+}
+export interface LicenseViewBackendOptions {
+    /** Text for a `MessageCode`: pass `licenseMessage` from `@rightkit/license`. Without it the step shows no detail text. */
+    messageText?: (code: string) => string;
+    /**
+     * Where the trial email comes from (an input the app renders, or the signed-in account). A trial is offered only when this
+     * and the client's `requestTrial` both exist. Returning nothing refuses the trial with a message.
+     */
+    trialEmail?: () => string | undefined | Promise<string | undefined>;
+    purchaseUrl?: string;
+    openExternal?: (url: string) => void | Promise<void>;
+    /** Replaces the English status labels. */
+    labels?: Partial<Record<LicenseState["status"], string>>;
+}
+/** Maps a native `LicenseView` to the step's `LicenseState`. The lifecycle decides; the coarse status is the fallback. An unknown value is `invalid`, never `active`. */
+export declare function licenseStateFromView(view: LicenseViewLike, options?: Pick<LicenseViewBackendOptions, "messageText" | "labels">): LicenseState;
+/**
+ * `LicenseBackend` over a native licence client (`@rightkit/license` 0.3.0 `createLicenseClient`). The step shows the state
+ * the native service reports and never decides entitlement itself; errors from the client reach the step unchanged (they are
+ * closed, fixed-text `LicenseClientError`s).
+ */
+export declare function licenseBackendFromView(client: LicenseViewClient, options?: LicenseViewBackendOptions): LicenseBackend;
+/**
+ * The app's `rightkit-oauth` commands as a typed port. Both calls go to the shared owner
+ * (`OAuthClient::sign_in_with_browser` through the app's command): the default browser opens, no in-app webview, and no token
+ * reaches the renderer. Results are untrusted `unknown`; only `signedIn` and `account` are read.
+ */
+export interface OAuthSignInPort {
+    /** Account already signed in, if any. */
+    status(): Promise<unknown>;
+    /** Open the default browser for `provider`; resolves when the sign-in finishes. */
+    signIn(provider: SignInProvider): Promise<unknown>;
+}
+/** `SignInBackend` over `port`. A sign-in that resolves without `signedIn: true` (closed browser tab, cancel) rejects, so the step shows its retry message. */
+export declare function signInBackendFromOAuth(port: OAuthSignInPort, providers: SignInBackend["providers"]): SignInBackend;

package/dist/adapters.js

@@ -0,0 +1,93 @@
+const BY_LIFECYCLE = {
+    unlicensed: "none",
+    migration_required: "invalid",
+    trial: "trial",
+    expired_trial: "expired",
+    active: "active",
+    grace: "active",
+    lifetime: "active",
+    lifetime_provisional: "active",
+    verification_required: "active",
+    expired: "expired",
+    clock_repair_required: "invalid",
+    revoked: "invalid",
+    invalid: "invalid",
+};
+const BY_STATUS = {
+    none: "none",
+    active: "active",
+    grace: "active",
+    expired: "expired",
+    revoked: "invalid",
+    invalid: "invalid",
+    unverifiable: "invalid",
+};
+const DEFAULT_LABELS = {
+    none: "No licence",
+    trial: "Trial",
+    active: "Active",
+    expired: "Expired",
+    invalid: "Needs attention",
+};
+/** Maps a native `LicenseView` to the step's `LicenseState`. The lifecycle decides; the coarse status is the fallback. An unknown value is `invalid`, never `active`. */
+export function licenseStateFromView(view, options = {}) {
+    const status = (view.lifecycle !== undefined ? BY_LIFECYCLE[view.lifecycle] : undefined) ?? BY_STATUS[view.status] ?? "invalid";
+    const text = view.message !== undefined && view.message !== "none" ? options.messageText?.(view.message) : undefined;
+    const validUntil = typeof view.validUntil === "number" && Number.isFinite(view.validUntil) ? new Date(view.validUntil).toISOString() : null;
+    return {
+        status,
+        label: options.labels?.[status] ?? DEFAULT_LABELS[status],
+        ...(text ? { detail: text } : {}),
+        ...(typeof view.tier === "string" && view.tier ? { tier: view.tier } : {}),
+        validUntil,
+    };
+}
+/**
+ * `LicenseBackend` over a native licence client (`@rightkit/license` 0.3.0 `createLicenseClient`). The step shows the state
+ * the native service reports and never decides entitlement itself; errors from the client reach the step unchanged (they are
+ * closed, fixed-text `LicenseClientError`s).
+ */
+export function licenseBackendFromView(client, options = {}) {
+    const state = (view) => licenseStateFromView(view, options);
+    const { requestTrial } = client;
+    const { trialEmail } = options;
+    return {
+        load: async () => state(await client.status()),
+        activate: async (key) => state(await client.activate(key)),
+        ...(requestTrial && trialEmail ? {
+            startTrial: async () => {
+                const email = (await trialEmail())?.trim();
+                if (!email)
+                    throw new Error("An email address is needed to start a trial.");
+                const outcome = await requestTrial.call(client, email);
+                const current = state(await client.status());
+                const text = outcome.message !== undefined && outcome.message !== "none" ? options.messageText?.(outcome.message) : undefined;
+                if (!outcome.accepted)
+                    throw new Error(text ?? "A trial could not be started.");
+                return text ? { ...current, detail: text } : current;
+            },
+        } : {}),
+        ...(options.purchaseUrl ? { purchaseUrl: options.purchaseUrl } : {}),
+        ...(options.openExternal ? { openExternal: options.openExternal } : {}),
+    };
+}
+function accountOf(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return { signedIn: false };
+    const v = value;
+    const account = typeof v.account === "string" && v.account.trim() ? v.account.trim().slice(0, 320) : undefined;
+    return v.signedIn === true ? { signedIn: true, ...(account ? { account } : {}) } : { signedIn: false };
+}
+/** `SignInBackend` over `port`. A sign-in that resolves without `signedIn: true` (closed browser tab, cancel) rejects, so the step shows its retry message. */
+export function signInBackendFromOAuth(port, providers) {
+    return {
+        providers,
+        load: async () => accountOf(await port.status()),
+        start: async (provider) => {
+            const result = accountOf(await port.signIn(provider));
+            if (!result.signedIn)
+                throw new Error("Sign-in did not finish. Try again.");
+            return result;
+        },
+    };
+}

package/dist/index.d.ts

@@ -1,4 +1,8 @@
-export { Onboarding, isLegalAccepted, onboardingStateKey } from "./Onboarding.js";
+export { Onboarding, isLegalAccepted, isStepSettled, onboardingStateKey, restartOnboardingSetup } from "./Onboarding.js";
 export { licenseStep, modelsStep, permissionsStep, signInStep } from "./steps.js";
-export type { ModelsStepOptions } from "./steps.js";
+export type { LicenseStepCopy, LicenseStepOptions, ModelsStepOptions } from "./steps.js";
+export { licenseBackendFromView, licenseStateFromView, signInBackendFromOAuth } from "./adapters.js";
+export type { LicenseViewBackendOptions, LicenseViewClient, LicenseViewLike, OAuthSignInPort } from "./adapters.js";
+export { LEGAL_RECEIPT_COMMANDS, createNativeLegalReceiptPort, importLegacyAcceptance, reopenLegalAcceptance, resetLegalAcceptance } from "./legal-receipt.js";
+export type { LegacyAcceptanceImportOptions, LegalReceiptInvoke, NativeLegalReceiptPortOptions } from "./legal-receipt.js";
 export type * from "./types.js";

package/dist/index.js

@@ -1,2 +1,4 @@
-export { Onboarding, isLegalAccepted, onboardingStateKey } from "./Onboarding.js";
+export { Onboarding, isLegalAccepted, isStepSettled, onboardingStateKey, restartOnboardingSetup } from "./Onboarding.js";
 export { licenseStep, modelsStep, permissionsStep, signInStep } from "./steps.js";
+export { licenseBackendFromView, licenseStateFromView, signInBackendFromOAuth } from "./adapters.js";
+export { LEGAL_RECEIPT_COMMANDS, createNativeLegalReceiptPort, importLegacyAcceptance, reopenLegalAcceptance, resetLegalAcceptance } from "./legal-receipt.js";

package/dist/legal-receipt.d.ts

@@ -0,0 +1,70 @@
+import type { LegalAcceptanceRecord, LegalReceiptCreateRequest, LegalReceiptPort, SettingsBackend } from "./types.js";
+/**
+ * The commands of the native legal-receipt host service. The native side registers them once under the host caller policy
+ * (`rightkit-tauri-shell` host services); the trusted window is the one that shows the legal gate. Names are provisional
+ * until the host service is published; an app whose host registers other names passes `commands`.
+ */
+export declare const LEGAL_RECEIPT_COMMANDS: Readonly<{
+    read: "rightkit_legal_receipt_read";
+    create: "rightkit_legal_receipt_create";
+    reset: "rightkit_legal_receipt_reset";
+    /** Imports a renderer-held legacy acceptance once (see `importLegacyAcceptance`). */
+    import: "rightkit_legal_receipt_import";
+}>;
+/** Tauri's `invoke`, structurally (`@tauri-apps/api/core`). No import, so the package stays free of Tauri. */
+export type LegalReceiptInvoke = (command: string, args?: Record<string, unknown>) => Promise<unknown>;
+export interface NativeLegalReceiptPortOptions {
+    invoke: LegalReceiptInvoke;
+    commands?: Partial<typeof LEGAL_RECEIPT_COMMANDS>;
+}
+/**
+ * `LegalReceiptPort` over the native legal-receipt service.
+ *
+ * - `read` returns the stored record, or `null` when there is none or the stored value is not a well-formed record. A
+ *   historical receipt (a version or digest that no longer matches) comes back as `{ record, current: false }`, which keeps
+ *   the re-acceptance variant and the setup progress; the native service offers it that way.
+ * - `create` sends the declaration (`version`, `documentsHash`, `documents`, `eligibilityBasis`, `surface`) and NO time. The
+ *   service compares it with the manifest it embeds, stamps native UTC time, stores the receipt and returns the record; a
+ *   refusal or a malformed answer throws, which keeps the gate closed.
+ * - `reset` clears the receipt.
+ * There is no `write`: the renderer never supplies a stored record.
+ */
+export declare function createNativeLegalReceiptPort({ invoke, commands }: NativeLegalReceiptPortOptions): LegalReceiptPort;
+export interface LegacyAcceptanceImportOptions {
+    invoke: LegalReceiptInvoke;
+    /** Key of the renderer-held legacy receipt, for example `scraperight.legal-acceptance.v1`. */
+    storageKey: string;
+    /**
+     * Maps the stored text to the declaration the native service verifies against its manifest (hashes, versions, documents).
+     * `null`: not an importable record; nothing is sent and the legacy key stays in place.
+     */
+    parse: (raw: string) => LegalReceiptCreateRequest | null;
+    /** Storage that holds the legacy key. Default `localStorage` when present. `null`: no legacy storage to read. */
+    storage?: Pick<Storage, "getItem" | "removeItem"> | null;
+    commands?: Partial<typeof LEGAL_RECEIPT_COMMANDS>;
+}
+/**
+ * One-time import of a renderer-held (legacy) acceptance into the native receipt. The legacy record is submitted once to the
+ * native `import` command, which verifies it against the manifest and stamps the import with its own clock. Only after the
+ * native service confirms the record is the legacy key removed. A refusal or a failed call throws and leaves the key in place,
+ * so the next launch retries; no acceptance is invented here. Returns the imported record, or `null` when there is nothing to
+ * import.
+ */
+export declare function importLegacyAcceptance({ invoke, storageKey, parse, storage, commands }: LegacyAcceptanceImportOptions): Promise<LegalAcceptanceRecord | null>;
+/**
+ * Re-opens the agreement: the stored acceptance stops counting, so the gate shows as a re-acceptance on the next mount of
+ * `Onboarding`. The old record (and the app's receipt) stays until the user agrees again; agreeing creates the new receipt and
+ * clears the flag. Progress through the other steps is kept.
+ */
+export declare function reopenLegalAcceptance({ settings }: {
+    settings: SettingsBackend;
+}): Promise<void>;
+/**
+ * Forgets the acceptance entirely: the app's receipt is cleared first (`legalReceipt.reset`, required when a receipt port is
+ * given, so a failed reset cannot leave the receipt accepted), then the settings copy, so the next mount shows the first-run
+ * gate. Other steps' progress is kept.
+ */
+export declare function resetLegalAcceptance({ settings, legalReceipt }: {
+    settings: SettingsBackend;
+    legalReceipt?: LegalReceiptPort;
+}): Promise<void>;

package/dist/legal-receipt.js

@@ -0,0 +1,148 @@
+import { onboardingStateKey, readAcceptance, readState } from "./Onboarding.js";
+/**
+ * The commands of the native legal-receipt host service. The native side registers them once under the host caller policy
+ * (`rightkit-tauri-shell` host services); the trusted window is the one that shows the legal gate. Names are provisional
+ * until the host service is published; an app whose host registers other names passes `commands`.
+ */
+export const LEGAL_RECEIPT_COMMANDS = Object.freeze({
+    read: "rightkit_legal_receipt_read",
+    create: "rightkit_legal_receipt_create",
+    reset: "rightkit_legal_receipt_reset",
+    /** Imports a renderer-held legacy acceptance once (see `importLegacyAcceptance`). */
+    import: "rightkit_legal_receipt_import",
+});
+/** Host commands reject with `{ code, message }`; the gate and steps show `Error#message`. */
+function hostError(error) {
+    if (error instanceof Error)
+        return error;
+    const message = error && typeof error === "object" ? error.message : error;
+    return new Error(typeof message === "string" && message.trim() ? message : "The legal receipt service failed.");
+}
+async function call(invoke, command, args) {
+    try {
+        return await invoke(command, args);
+    }
+    catch (error) {
+        throw hostError(error);
+    }
+}
+/** The declaration the native service compares with its manifest: never a time. */
+function declaration(request) {
+    return {
+        version: request.version,
+        documentsHash: request.documentsHash,
+        documents: request.documents,
+        eligibilityBasis: request.eligibilityBasis,
+        surface: request.surface,
+    };
+}
+/** True for a historical receipt value (`{ record, current: false }`) as the native read may return it. */
+function isHistoricalValue(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value) && "record" in value && value.current === false;
+}
+/**
+ * `LegalReceiptPort` over the native legal-receipt service.
+ *
+ * - `read` returns the stored record, or `null` when there is none or the stored value is not a well-formed record. A
+ *   historical receipt (a version or digest that no longer matches) comes back as `{ record, current: false }`, which keeps
+ *   the re-acceptance variant and the setup progress; the native service offers it that way.
+ * - `create` sends the declaration (`version`, `documentsHash`, `documents`, `eligibilityBasis`, `surface`) and NO time. The
+ *   service compares it with the manifest it embeds, stamps native UTC time, stores the receipt and returns the record; a
+ *   refusal or a malformed answer throws, which keeps the gate closed.
+ * - `reset` clears the receipt.
+ * There is no `write`: the renderer never supplies a stored record.
+ */
+export function createNativeLegalReceiptPort({ invoke, commands }) {
+    const names = { ...LEGAL_RECEIPT_COMMANDS, ...commands };
+    return {
+        async read() {
+            const value = await call(invoke, names.read);
+            if (value === null || value === undefined)
+                return null;
+            if (isHistoricalValue(value)) {
+                const record = readAcceptance(value.record);
+                return record ? { record, current: false } : null;
+            }
+            return readAcceptance(value) ?? null;
+        },
+        async create(request) {
+            const created = readAcceptance(await call(invoke, names.create, { request: declaration(request) }));
+            if (!created)
+                throw new Error("The legal receipt service returned an invalid record.");
+            return created;
+        },
+        async reset() { await call(invoke, names.reset); },
+    };
+}
+function browserStorage() {
+    try {
+        return typeof localStorage === "undefined" ? null : localStorage;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * One-time import of a renderer-held (legacy) acceptance into the native receipt. The legacy record is submitted once to the
+ * native `import` command, which verifies it against the manifest and stamps the import with its own clock. Only after the
+ * native service confirms the record is the legacy key removed. A refusal or a failed call throws and leaves the key in place,
+ * so the next launch retries; no acceptance is invented here. Returns the imported record, or `null` when there is nothing to
+ * import.
+ */
+export async function importLegacyAcceptance({ invoke, storageKey, parse, storage, commands }) {
+    const names = { ...LEGAL_RECEIPT_COMMANDS, ...commands };
+    const backing = storage === undefined ? browserStorage() : storage;
+    let raw;
+    try {
+        raw = backing?.getItem(storageKey) ?? null;
+    }
+    catch {
+        raw = null;
+    }
+    if (raw === null)
+        return null;
+    const request = parse(raw);
+    if (!request)
+        return null;
+    const imported = readAcceptance(await call(invoke, names.import, { request: declaration(request) }));
+    if (!imported)
+        throw new Error("The legal receipt service returned an invalid record.");
+    try {
+        backing?.removeItem(storageKey);
+    }
+    catch {
+        /* the native receipt is stored; the native import is idempotent, so a later run only repeats the confirmation */
+    }
+    return imported;
+}
+/**
+ * Re-opens the agreement: the stored acceptance stops counting, so the gate shows as a re-acceptance on the next mount of
+ * `Onboarding`. The old record (and the app's receipt) stays until the user agrees again; agreeing creates the new receipt and
+ * clears the flag. Progress through the other steps is kept.
+ */
+export async function reopenLegalAcceptance({ settings }) {
+    const key = onboardingStateKey();
+    const snapshot = await settings.load();
+    const state = readState(snapshot.values[key]);
+    await settings.patch({ [key]: { ...state, legalReopened: true } }, snapshot.revision);
+}
+/**
+ * Forgets the acceptance entirely: the app's receipt is cleared first (`legalReceipt.reset`, required when a receipt port is
+ * given, so a failed reset cannot leave the receipt accepted), then the settings copy, so the next mount shows the first-run
+ * gate. Other steps' progress is kept.
+ */
+export async function resetLegalAcceptance({ settings, legalReceipt }) {
+    if (legalReceipt) {
+        if (!legalReceipt.reset)
+            throw new Error("The legal receipt cannot be reset.");
+        await legalReceipt.reset();
+    }
+    const key = onboardingStateKey();
+    const snapshot = await settings.load();
+    const next = { ...readState(snapshot.values[key]), legalAccepted: false };
+    delete next.legalAcceptance;
+    delete next.eligibilityBasis;
+    delete next.legalReopened;
+    next.completed = next.completed.filter((id) => id !== "legal");
+    await settings.patch({ [key]: next }, snapshot.revision);
+}

package/dist/steps.js

@@ -24,7 +24,7 @@ function PermissionsBody({ backend }) {
     const [error, setError] = useState(null);
     const reload = useCallback(() => backend.list().then(setItems, (e) => setError(e instanceof Error ? e.message : String(e))), [backend]);
     useEffect(() => void reload(), [reload]);
-    return (_jsxs("div", { className: "rk-onboarding__card", "data-testid": "onboarding-permissions", children: [error ? _jsx("p", { className: "rk-onboarding__error", role: "alert", children: error }) : null, items.length === 0 && !error ? _jsx("p", { className: "rk-onboarding__muted", children: "Checking permissions\u2026" }) : null, items.map((item) => (_jsxs("div", { className: "rk-onboarding__row", "data-permission-id": item.id, children: [_jsxs("div", { children: [_jsx("strong", { children: item.label }), _jsx("p", { children: item.description ?? item.detail })] }), _jsxs("div", { className: "rk-onboarding__row-actions", children: [_jsx(Badge, { tone: permissionTone(item.state), children: item.state }), item.state === "needed" || item.state === "denied" ? (_jsx(Button, { size: "sm", variant: "secondary", disabled: busy === item.id, onClick: () => { setBusy(item.id); setError(null); void backend.request(item.id).then((next) => setItems((current) => current.map((x) => x.id === next.id ? next : x)), (e) => setError(e instanceof Error ? e.message : String(e))).finally(() => setBusy(null)); }, children: item.state === "denied" ? "Try again" : "Allow" })) : null] })] }, item.id)))] }));
+    return (_jsxs("div", { className: "rk-onboarding__card", "data-testid": "onboarding-permissions", children: [error ? _jsx("p", { className: "rk-onboarding__error", role: "alert", children: error }) : null, items.length === 0 && error ? _jsx(Button, { size: "sm", variant: "secondary", onClick: () => { setError(null); void reload(); }, children: "Try again" }) : null, items.length === 0 && !error ? _jsx("p", { className: "rk-onboarding__muted", children: "Checking permissions\u2026" }) : null, items.map((item) => (_jsxs("div", { className: "rk-onboarding__row", "data-permission-id": item.id, children: [_jsxs("div", { children: [_jsx("strong", { children: item.label }), _jsx("p", { children: item.description ?? item.detail })] }), _jsxs("div", { className: "rk-onboarding__row-actions", children: [_jsx(Badge, { tone: permissionTone(item.state), children: item.state }), item.state === "needed" || item.state === "denied" ? (_jsx(Button, { size: "sm", variant: "secondary", disabled: busy === item.id, onClick: () => { setBusy(item.id); setError(null); void backend.request(item.id).then((next) => setItems((current) => current.map((x) => x.id === next.id ? next : x)), (e) => setError(e instanceof Error ? e.message : String(e))).finally(() => setBusy(null)); }, children: item.state === "denied" ? "Try again" : "Allow" })) : null] })] }, item.id)))] }));
 }
 export function permissionsStep(backend, options = {}) {
     return { id: "permissions", label: options.label ?? "Permissions", title: options.title ?? "Allow what this app needs", description: options.description ?? "You can change these permissions later in System Settings.", skippable: true, render: () => _jsx(PermissionsBody, { backend: backend }) };
@@ -82,7 +82,7 @@ function ModelsBody({ backend, onReady, autoStartDownload, shouldAutoStart, onMo
         // run is intentionally omitted: it only closes over setters.
         // eslint-disable-next-line react-hooks/exhaustive-deps
     }, [autoStartDownload, shouldAutoStart, onModelsStepEnter, loaded, models, backend]);
-    return (_jsxs("div", { className: "rk-onboarding__card", "data-testid": "onboarding-models", children: [intro ? _jsx("div", { className: "rk-onboarding__intro", "data-testid": "onboarding-models-intro", children: intro }) : null, error ? _jsx("p", { className: "rk-onboarding__error", role: "alert", children: error }) : null, models.map((model) => {
+    return (_jsxs("div", { className: "rk-onboarding__card", "data-testid": "onboarding-models", children: [intro ? _jsx("div", { className: "rk-onboarding__intro", "data-testid": "onboarding-models-intro", children: intro }) : null, error ? _jsx("p", { className: "rk-onboarding__error", role: "alert", children: error }) : null, error && !loaded ? _jsx(Button, { size: "sm", variant: "secondary", onClick: () => { setError(null); void reload(); }, children: "Try again" }) : null, models.map((model) => {
                 const progress = model.progress ?? (model.state === "installed" ? 1 : 0);
                 const active = model.state === "downloading" || model.state === "verifying";
                 const cancel = backend.cancel;

package/dist/types.d.ts

@@ -88,15 +88,65 @@ export interface LegalAcceptanceRecord {
     acceptedAt: string;
     eligibilityBasis: EligibilityBasis;
 }
+/** One document of the set the user was shown. Shaped so `@rightkit/legal`'s `acceptanceDeclaration(manifest).documents` fits as is. */
+export interface DeclaredLegalDocument {
+    id?: string;
+    role?: string;
+    title?: string;
+    url?: string;
+    version?: string;
+    sha256?: string;
+    treatment?: string;
+    material?: boolean;
+}
+/**
+ * What the renderer declares to a native receipt service when the user agrees. It carries no time: the service stamps its
+ * own UTC `acceptedAt`, compares `version`, `documentsHash` and `documents` with the manifest it embeds, and refuses a
+ * declaration that does not match.
+ */
+export interface LegalReceiptCreateRequest {
+    /** Acceptance version the app requires (`requiredVersion`, else "1"). */
+    version: string;
+    /** Digest of the document set shown (`documentsHash`, else `requiredDocumentsHash`, else a hash of titles and URLs). */
+    documentsHash: string;
+    /** The declared set (`receiptDocuments`, else the gate's documents as `{ title, url }`). */
+    documents: readonly DeclaredLegalDocument[];
+    eligibilityBasis: EligibilityBasis;
+    /** Always "first_run": onboarding is the first-run and re-acceptance surface. */
+    surface: "first_run";
+}
 /**
  * App-owned persistence for the legal acceptance. Lets an app keep its existing receipt (any shape, any store) and map it
  * to and from the package's record. When supplied it is the source of truth: `read()` is consulted on load and overrides
- * whatever acceptance the settings backend holds (`null` means "not accepted", so the gate shows), and `write()` is
- * awaited when the user agrees, before the settings backend is patched.
+ * whatever acceptance the settings backend holds (`null` means "not accepted", so the gate shows).
+ *
+ * Recording the acceptance, in order of preference:
+ * - `create(request)`: the NATIVE path. The service owns the time and the stored receipt and returns the record it stored;
+ *   the renderer builds nothing. A throw, or a record that does not match the required version or hash, keeps the gate
+ *   closed. When `create` exists, `write` is not called.
+ * - `write(record)`: LEGACY. The renderer builds the record, including its `acceptedAt` from the webview clock, and the app
+ *   stores it. Kept for apps that have not moved to a native receipt service.
+ *
+ * `reset()` clears the stored receipt (used by `resetLegalAcceptance`). A port needs `create` or `write`; with neither,
+ * agreeing fails and the gate stays closed.
+ */
+/**
+ * A receipt that exists but no longer counts: its version or documents differ from the current agreement. `read()` may
+ * return it so the gate shows as a re-acceptance and the setup progress is kept (`current: false`). Any other return
+ * value is a current record or `null`.
  */
+export interface HistoricalLegalReceipt {
+    record: LegalAcceptanceRecord;
+    current: false;
+}
 export interface LegalReceiptPort {
-    read(): LegalAcceptanceRecord | null | Promise<LegalAcceptanceRecord | null>;
-    write(record: LegalAcceptanceRecord): void | Promise<void>;
+    read(): LegalAcceptanceRecord | HistoricalLegalReceipt | null | Promise<LegalAcceptanceRecord | HistoricalLegalReceipt | null>;
+    /** Native receipt creation: returns the stored record, stamped with native time. Preferred over `write`. */
+    create?(request: LegalReceiptCreateRequest): LegalAcceptanceRecord | Promise<LegalAcceptanceRecord>;
+    /** @deprecated Renderer-built record with webview time. Implement `create` on a native receipt service instead. */
+    write?(record: LegalAcceptanceRecord): void | Promise<void>;
+    /** Clear the stored receipt so the gate shows again as a first run. */
+    reset?(): void | Promise<void>;
 }
 export interface PersistedOnboardingState {
     version: 1;
@@ -108,6 +158,11 @@ export interface PersistedOnboardingState {
     /** Legacy mirror of `legalAcceptance.eligibilityBasis`. */
     eligibilityBasis?: EligibilityBasis;
     legalAcceptance?: LegalAcceptanceRecord;
+    /**
+     * Set by `reopenLegalAcceptance`: the stored acceptance no longer counts, so the gate shows as a re-acceptance. The old
+     * record stays until a new acceptance replaces it, which clears the flag.
+     */
+    legalReopened?: boolean;
     /** Step ids the user skipped with the per-step Skip button (not marked complete). */
     skippedSteps?: string[];
 }
@@ -180,6 +235,19 @@ export type LegalMode = "gate" | "notice" | "none";
 export interface OnboardingProps {
     /** Window-sized by default; use `contained` when the host sizes the setup surface. */
     layout?: "window" | "contained";
+    /**
+     * Setup chrome. `rail` (default): a left step rail with a "Step n of N" eyebrow. `card`: one centred card with the app
+     * name on top and a dot pager, no rail (the HeardRight v5 onboarding mock). Applies to the setup steps only; the legal
+     * gate keeps its own layout.
+     */
+    frame?: "rail" | "card";
+    /** Vertical density of the setup steps. `compact` (rail frame): main padding 18px top, content 8px, rail 188px wide. Default `default`. */
+    density?: "default" | "compact";
+    /**
+     * Clears the macOS traffic lights: the rail (or card brand row) and the titlebar strip start past them. Use with a
+     * `titlebar` or `dragRegion` on macOS windows with overlay title bars. Default false.
+     */
+    trafficLightInset?: boolean;
     settings: SettingsBackend;
     /** Required when `legalMode` is `gate` (default). Optional for `notice` (the documents shown) and `none`. */
     legal?: LegalStepConfig;
@@ -192,6 +260,13 @@ export interface OnboardingProps {
     permissions?: PermissionsBackend;
     models?: ModelsBackend;
     license?: LicenseBackend;
+    /**
+     * Adds the built-in sign-in step after the licence step and hands the backend to every step as `ctx.signIn`. Build it
+     * with `signInBackendFromOAuth` over the app's `rightkit-oauth` commands.
+     */
+    signIn?: SignInBackend;
+    /** The document set declared to `legalReceipt.create`. Default: the gate's documents as `{ title, url }`. */
+    receiptDocuments?: readonly DeclaredLegalDocument[];
     /** Called once when setup finishes, with the completed and skipped step ids and the step results. */
     onComplete: (result: OnboardingResult) => void | Promise<void>;
     onSkip?: () => void | Promise<void>;
@@ -224,13 +299,16 @@ export interface OnboardingProps {
     modelsIntro?: ReactNode;
     /** Show "Set up later". Default true. */
     allowSkip?: boolean;
-    /** Optional titlebar content rendered in a strip along the top. */
+    /** Optional titlebar content rendered in a strip along the top. On macOS with `trafficLightInset`, the strip starts past the lights. */
     titlebar?: ReactNode;
     /** Render a `data-tauri-drag-region` strip at the top of the setup steps. Default false. Never applied to the legal stage; see `legalDragRegion`. */
     dragRegion?: boolean;
     /** Also render the drag region on the legal stage (loading and gate). Default false: the legal gate has no strip. */
     legalDragRegion?: boolean;
-    /** Read and write the legal acceptance in the app's own receipt instead of (overriding) the settings backend's copy. */
+    /**
+     * Read and record the legal acceptance in the app's own (preferably native) receipt instead of (overriding) the settings
+     * backend's copy. See `LegalReceiptPort`; `createNativeLegalReceiptPort` builds one over the host's receipt commands.
+     */
     legalReceipt?: LegalReceiptPort;
 }
 export type { LegalGateDocument, LegalGateTheme };

package/onboarding.css

@@ -40,3 +40,23 @@
 .rk-onboarding__titlebar { position: absolute; inset: 0 0 auto 0; z-index: 2; display: flex; align-items: center; height: var(--rk-onboarding-titlebar-h, 32px); padding: 0 12px; }
 .rk-onboarding__hint { color: var(--rk-ink-2, #6b655c); font-size: 12px; text-align: right; }
 .rk-onboarding__intro { margin-bottom: 12px; color: var(--rk-ink-2, #6b655c); }
+/* Density (HeardRight: onboarding too tall). compact: rail 188px, main 18px top, content 8px. */
+.rk-onboarding--compact { grid-template-columns: 188px minmax(0, 1fr); }
+.rk-onboarding--compact .rk-onboarding__main { padding-top: 18px; }
+.rk-onboarding--compact .rk-onboarding__content { padding: 8px 0; }
+/* macOS traffic lights: the rail and the titlebar strip start past them (lights-top: rail top; lights width from shell.css). */
+.rk-onboarding--lights .rk-onboarding__rail { padding-top: var(--rk-onboarding-lights-top, 40px); }
+.rk-onboarding--lights .rk-onboarding__titlebar { padding-left: calc(var(--rk-lights-width, 72px) + 6px); }
+.rk-onboarding--lights .rk-onboarding__brand--card { padding-left: calc(var(--rk-lights-width, 72px) + 6px); }
+/* card frame (HeardRight v5 mock): one centred card, the app name on top, a dot pager and no rail. */
+.rk-onboarding--card { display: flex; flex-direction: column; align-items: stretch; }
+.rk-onboarding--card .rk-onboarding__main--card { flex: 1; display: flex; flex-direction: column; align-items: center; max-width: none; width: 100%; padding: 0 clamp(24px, 5vw, 56px) 24px; }
+.rk-onboarding__brand--card { align-self: stretch; padding: 18px 20px; font-size: 18px; font-weight: 900; letter-spacing: -.03em; }
+.rk-onboarding__frame { display: flex; flex-direction: column; flex: 1; width: min(860px, 100%); min-height: 0; padding-top: 24px; }
+.rk-onboarding--card .rk-onboarding__content { flex: 1; }
+.rk-onboarding--card footer .rk-onboarding__hint { flex: none; }
+.rk-onboarding__dots { display: flex; align-items: center; justify-content: center; gap: 10px; flex: 1; }
+.rk-onboarding__dot { width: 10px; height: 10px; padding: 0; border: 0; border-radius: 999px; background: var(--rk-line-strong, rgba(35,31,26,.18)); cursor: pointer; transition: width .2s ease, background .2s ease; }
+.rk-onboarding__dot.is-done { background: var(--rk-ok, #1e7f3c); }
+.rk-onboarding__dot.is-active { width: 42px; background: var(--rk-accent, #7040c4); }
+.rk-onboarding__dot:disabled { cursor: not-allowed; }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rightkit/onboarding",
-  "version": "0.6.2",
+  "version": "0.6.4",
   "description": "First-run onboarding framework: ordered steps, progress, skip/resume, legal gate first, permissions, model download and licence/trial steps.",
   "license": "MIT OR Apache-2.0",
   "type": "module",
@@ -29,21 +29,11 @@
     "react": ">=18 <21"
   },
   "devDependencies": {
-    "@rightkit/react-shell": "0.7.1",
-    "@rightkit/legal-ui": "0.4.1",
-    "@rightkit/qa-chrome": "0.1.8",
-    "@testing-library/jest-dom": "^7.0.1",
-    "@testing-library/dom": "^10.4.2",
-    "@testing-library/react": "^16.3.3",
-    "@testing-library/user-event": "^14.6.8",
+    "@rightkit/react-shell": "0.7.3",
+    "@rightkit/legal-ui": "0.4.2",
     "@types/react": "^19.3.0",
-    "@types/react-dom": "^19.3.0",
-    "jsdom": "^30.1.3",
     "react": "^19.3.1",
-    "react-dom": "^19.3.1",
-    "typescript": "^7.0.2",
-    "vite": "^8.3.4",
-    "vitest": "^5.0.5"
+    "typescript": "^7.0.2"
   },
   "publishConfig": {
     "registry": "https://registry.npmjs.org",
@@ -56,8 +46,6 @@
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",
-    "typecheck": "tsc -p tsconfig.json --noEmit",
-    "pretest": "pnpm --filter \"@rightkit/onboarding^...\" run build",
-    "test": "vitest run"
+    "typecheck": "tsc -p tsconfig.json --noEmit"
   }
 }