@rightkit/onboarding 0.6.1 → 0.6.3

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,9 @@
-import type { OnboardingProps, PersistedOnboardingState } from "./types.js";
+import type { LegalAcceptanceRecord, OnboardingProps, PersistedOnboardingState } 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;
 export declare function onboardingStateKey(): string;
-export declare function Onboarding({ settings, legal, legalMode, appName, steps, permissions, models, license, onComplete, onSkip, className, 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 }: 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,6 +46,7 @@ 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") } : {}),
     };
 }
@@ -56,6 +59,9 @@ function withReceipt(state, record) {
 }
 /** 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,
@@ -104,7 +110,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, 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 }) {
     if (legalMode === "gate" && !legal)
         throw new Error("Onboarding: `legal` is required when legalMode is \"gate\"");
     const L = { ...DEFAULT_LABELS, ...labelOverrides };
@@ -121,6 +127,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);
@@ -183,8 +191,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 +225,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,36 +275,65 @@ 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);
     if (error && !state)
-        return _jsxs("div", { className: cx("rk-onboarding", className), children: [_jsx("p", { className: "rk-onboarding__error", role: "alert", children: error }), _jsx(Button, { onClick: () => window.location.reload(), children: "Retry" })] });
+        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)
-        return _jsxs("main", { className: cx("rk-onboarding", className), "data-testid": "onboarding", children: [_jsx("p", { className: "rk-onboarding__muted", children: "Nothing to set up." }), _jsx(Button, { variant: "primary", onClick: () => void runCallback(() => onComplete(resultOf(activeState.completed, activeState.skippedSteps ?? []))), children: L.finish })] });
+        return _jsxs("main", { className: rootClass, "data-testid": "onboarding", children: [_jsx("p", { className: "rk-onboarding__muted", children: "Nothing to set up." }), _jsx(Button, { variant: "primary", onClick: () => void runCallback(() => onComplete(resultOf(activeState.completed, activeState.skippedSteps ?? []))), children: L.finish })] });
     if (!state || !active)
-        return _jsx("div", { className: cx("rk-onboarding", className), "aria-busy": "true", children: _jsx("p", { className: "rk-onboarding__muted", children: L.loading }) });
+        return _jsx("div", { className: rootClass, "aria-busy": "true", children: _jsx("p", { className: "rk-onboarding__muted", children: L.loading }) });
     if (needsGate) {
         if (!gateCleared)
-            return _jsxs("div", { className: cx("rk-onboarding", className), "aria-busy": "true", children: [_jsx(TitleStrip, { titlebar: titlebar, dragRegion: legalDragRegion }), _jsx("p", { className: "rk-onboarding__muted", children: L.loading })] });
+            return _jsxs("div", { className: rootClass, "aria-busy": "true", children: [_jsx(TitleStrip, { titlebar: titlebar, dragRegion: legalDragRegion }), _jsx("p", { className: "rk-onboarding__muted", children: L.loading })] });
         if (!legal)
             return null;
         const reacceptance = activeState.legalAccepted || activeState.legalAcceptance !== undefined;
-        return _jsxs("div", { className: cx("rk-onboarding rk-onboarding--legal", className), "data-testid": "onboarding-legal", "data-variant": reacceptance ? "re-acceptance" : "first-run", children: [_jsx(TitleStrip, { titlebar: titlebar, dragRegion: legalDragRegion }), _jsx(LegalGate, { ...legal, 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;
-                            }
+        /** 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 }) => {
+                        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);
-    return _jsxs("main", { className: cx("rk-onboarding", className), "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))
+    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 { 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, reopenLegalAcceptance, resetLegalAcceptance } from "./legal-receipt.js";
+export type { 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 { licenseStep, modelsStep, permissionsStep, signInStep } from "./steps.js";
+export { licenseBackendFromView, licenseStateFromView, signInBackendFromOAuth } from "./adapters.js";
+export { LEGAL_RECEIPT_COMMANDS, createNativeLegalReceiptPort, reopenLegalAcceptance, resetLegalAcceptance } from "./legal-receipt.js";

package/dist/legal-receipt.d.ts

@@ -0,0 +1,45 @@
+import type { 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";
+}>;
+/** 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.
+ * - `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;
+/**
+ * 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,91 @@
+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",
+});
+/** 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);
+    }
+}
+/**
+ * `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.
+ * - `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);
+            return value === null || value === undefined ? null : readAcceptance(value) ?? null;
+        },
+        async create(request) {
+            const created = readAcceptance(await call(invoke, names.create, {
+                request: {
+                    version: request.version,
+                    documentsHash: request.documentsHash,
+                    documents: request.documents,
+                    eligibilityBasis: request.eligibilityBasis,
+                    surface: request.surface,
+                },
+            }));
+            if (!created)
+                throw new Error("The legal receipt service returned an invalid record.");
+            return created;
+        },
+        async reset() { await call(invoke, names.reset); },
+    };
+}
+/**
+ * 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,56 @@ 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.
  */
 export interface LegalReceiptPort {
     read(): LegalAcceptanceRecord | null | Promise<LegalAcceptanceRecord | null>;
-    write(record: LegalAcceptanceRecord): void | Promise<void>;
+    /** 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 +149,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[];
 }
@@ -178,6 +224,8 @@ export interface LegalStepConfig extends Omit<LegalGateProps, "variant" | "onAgr
  */
 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";
     settings: SettingsBackend;
     /** Required when `legalMode` is `gate` (default). Optional for `notice` (the documents shown) and `none`. */
     legal?: LegalStepConfig;
@@ -190,6 +238,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>;
@@ -228,7 +283,10 @@ export interface OnboardingProps {
     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

@@ -1,5 +1,6 @@
 /* @rightkit/onboarding — uses app-shell tokens and legal-ui's locked light gate. */
 .rk-onboarding { position: relative; min-height: 100vh; display: grid; grid-template-columns: 220px minmax(0, 1fr); background: var(--rk-plane, #fffcf5); color: var(--rk-ink, #231f1a); font: 13px/1.45 -apple-system, BlinkMacSystemFont, "Segoe UI", system-ui, sans-serif; }
+.rk-onboarding--contained { min-height: 0; }
 .rk-onboarding *, .rk-onboarding *::before, .rk-onboarding *::after { box-sizing: border-box; }
 .rk-onboarding__rail { display: flex; flex-direction: column; gap: 22px; padding: 28px 14px; background: var(--rk-chrome, #eee9df); border-right: .5px solid var(--rk-hairline, rgba(35,31,26,.11)); }
 .rk-onboarding__brand { padding: 0 10px; font-size: 19px; font-weight: 650; letter-spacing: -.02em; }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rightkit/onboarding",
-  "version": "0.6.1",
+  "version": "0.6.3",
   "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",
@@ -25,13 +25,13 @@
   ],
   "peerDependencies": {
     "@rightkit/react-shell": ">=0.2.0 <1",
-    "@rightkit/legal-ui": ">=0.1.2 <1",
+    "@rightkit/legal-ui": ">=0.4.1 <1",
     "react": ">=18 <21"
   },
   "devDependencies": {
-    "@rightkit/react-shell": "0.7.1",
-    "@rightkit/legal-ui": "0.4.0",
-    "@rightkit/qa-chrome": "0.1.8",
+    "@rightkit/react-shell": "0.7.2",
+    "@rightkit/legal-ui": "0.4.1",
+    "@rightkit/qa-chrome": "0.1.9",
     "@testing-library/jest-dom": "^7.0.1",
     "@testing-library/dom": "^10.4.2",
     "@testing-library/react": "^16.3.3",