@rightkit/onboarding 0.3.2 → 0.5.0

package/README.md

@@ -13,16 +13,16 @@ First-run onboarding framework for Right Suite apps. The legal agreement gate co
 
 | Import | Contents |
 |---|---|
-| `@rightkit/onboarding` | `Onboarding`, `isLegalAccepted`, `onboardingStateKey`, `licenseStep`, `modelsStep`, `permissionsStep`; 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, Orthic-Labs/rightkit#279); types from `types.ts`, `ModelsStepOptions` |
 | `@rightkit/onboarding/onboarding.css` | Stylesheet |
 
 ## Peer dependencies
 
 | Peer | Range |
 |---|---|
-| `@rightkit/app-shell` | `>=0.2.0 <1` |
+| `@rightkit/react-shell` | `>=0.2.0 <1` |
 | `@rightkit/legal-ui` | `>=0.1.2 <1` |
-| `react` | `>=18 <20` |
+| `react` | `>=18 <21` |
 
 ## Example
 
@@ -43,8 +43,14 @@ 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)`.
 
+## When the legal gate re-prompts
+
+`isLegalAccepted(state, requiredVersion?, isAccepted?, requiredDocumentsHash?)` decides it, in this order: a custom `isAccepted` wins outright; a `requiredDocumentsHash` must equal the stored acceptance's `documentsHash`; a `requiredVersion` must equal its `version`; with neither, the stored `legalAccepted` flag is used. Pass `requiredDocumentsHash` (the hash of the material documents, from `@rightkit/legal`) to catch a text change that did not bump the version: without it only the version is compared. `documentsHash` is recorded with the acceptance and never compared; by default it covers document titles and URLs, not their text.
+
 ## Known issues
 
-- Peer React is `<20`, while `doc-render`, `i18n`, `media-ui` and `pdf-ui` accept `<21` (npm audit 2026-10-08).
+- Peer React is `<21`, the same range as `doc-render`, `i18n`, `media-ui` and `pdf-ui` (`package.json:29`).

package/dist/Onboarding.d.ts

@@ -1,5 +1,5 @@
 import type { OnboardingProps, PersistedOnboardingState } from "./types.js";
 /** True when the stored acceptance satisfies the host's requirement. */
-export declare function isLegalAccepted(state: PersistedOnboardingState, requiredVersion?: string, custom?: (state: PersistedOnboardingState) => boolean): boolean;
+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, steps, permissions, models, license, onComplete, onSkip, className, requiredVersion, isAccepted, documentsHash, beforeLegalGate, requireModel, autoStartDownload, shouldAutoStart, onModelsStepEnter, modelsIntro, allowSkip, titlebar, dragRegion, legalDragRegion, legalReceipt }: OnboardingProps): import("react").JSX.Element;
+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 }: OnboardingProps): import("react").JSX.Element | null;

package/dist/Onboarding.js

@@ -1,7 +1,7 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { LegalGate } from "@rightkit/legal-ui";
-import { Button } from "@rightkit/app-shell/react";
+import { Button } from "@rightkit/react-shell/react";
 import { cx } from "./ui.js";
 import { licenseStep, modelsStep, permissionsStep } from "./steps.js";
 const KEY = "onboarding.state";
@@ -39,11 +39,17 @@ function withReceipt(state, record) {
     return record ? { ...rest, legalAccepted: true, eligibilityBasis: record.eligibilityBasis, legalAcceptance: record } : { ...rest, legalAccepted: false };
 }
 /** True when the stored acceptance satisfies the host's requirement. */
-export function isLegalAccepted(state, requiredVersion, custom) {
+export function isLegalAccepted(state, requiredVersion, custom, requiredDocumentsHash) {
     if (custom)
         return custom(state);
+    // A host that supplies the documents' hash is asking for the text itself to be what was accepted:
+    // a changed text re-prompts even when the version string did not move.
+    if (requiredDocumentsHash !== undefined && state.legalAcceptance?.documentsHash !== requiredDocumentsHash)
+        return false;
     if (requiredVersion !== undefined)
         return state.legalAcceptance?.version === requiredVersion;
+    if (requiredDocumentsHash !== undefined)
+        return state.legalAcceptance !== undefined;
     return state.legalAccepted;
 }
 /** FNV-1a fallback when SubtleCrypto is unavailable. */
@@ -73,7 +79,17 @@ function TitleStrip({ titlebar, dragRegion }) {
         return null;
     return _jsx("div", { className: "rk-onboarding__titlebar", "data-testid": "onboarding-titlebar", ...(dragRegion ? { "data-tauri-drag-region": "" } : {}), children: titlebar });
 }
-export function Onboarding({ settings, legal, steps = [], permissions, models, license, onComplete, onSkip, className, requiredVersion, isAccepted, documentsHash, beforeLegalGate, requireModel, autoStartDownload, shouldAutoStart, onModelsStepEnter, modelsIntro, allowSkip = true, titlebar, dragRegion, legalDragRegion = false, legalReceipt }) {
+function NoticeList({ documents }) {
+    if (!documents.length)
+        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 }) {
+    if (legalMode === "gate" && !legal)
+        throw new Error("Onboarding: `legal` is required when legalMode is \"gate\"");
+    const gated = legalMode === "gate";
+    /** Leading steps the user cannot navigate to: the Agreement stand-in in gate mode. */
+    const lead = gated ? 1 : 0;
     const [state, setState] = useState(null);
     const [saving, setSaving] = useState(false);
     const [error, setError] = useState(null);
@@ -138,18 +154,19 @@ export function Onboarding({ settings, legal, steps = [], permissions, models, l
         return () => { live = false; };
     }, [settings, legalReceipt]);
     const builtins = useMemo(() => [
-        { id: "legal", label: "Agreement", title: "Review agreement", skippable: false, render: () => _jsx("p", { className: "rk-onboarding__muted", children: "Agreement accepted." }) },
+        ...(gated ? [{ id: "legal", label: "Agreement", title: "Review agreement", skippable: false, render: () => _jsx("p", { className: "rk-onboarding__muted", children: "Agreement accepted." }) }] : []),
+        ...(legalMode === "notice" ? [{ id: "notice", label: "Notice", title: "Notices", skippable: false, render: () => _jsx(NoticeList, { documents: legal?.documents ?? [] }) }] : []),
         ...(permissions ? [permissionsStep(permissions)] : []),
         ...(models ? [modelsStep(models, { required: requireModel, autoStartDownload, shouldAutoStart, onModelsStepEnter, intro: modelsIntro, startGuard: modelsStarted })] : []),
         ...(license ? [licenseStep(license)] : []),
         ...steps,
-    ], [license, models, permissions, steps, requireModel, autoStartDownload, shouldAutoStart, onModelsStepEnter, modelsIntro]);
+    ], [gated, legalMode, legal?.documents, license, models, permissions, steps, requireModel, autoStartDownload, shouldAutoStart, onModelsStepEnter, modelsIntro]);
     const activeState = state ?? INITIAL;
-    const accepted = isLegalAccepted(activeState, requiredVersion, isAccepted);
+    const accepted = !gated || isLegalAccepted(activeState, requiredVersion, isAccepted, requiredDocumentsHash);
     const needsGate = state !== null && !accepted;
     // The agreement gate does not depend on the saved step: until it is accepted, the active step is the first.
     // Once accepted, the Agreement step (index 0) is never shown again when other steps exist.
-    const index = !accepted ? 0 : builtins.length > 1 ? Math.max(1, Math.min(activeState.currentStep, builtins.length - 1)) : 0;
+    const index = !accepted ? 0 : builtins.length > lead ? Math.max(lead, Math.min(activeState.currentStep, builtins.length - 1)) : 0;
     const active = builtins[index];
     const activeId = active?.id ?? "";
     const setReady = useCallback((ready) => setReadyMap((m) => m[activeId] === ready ? m : { ...m, [activeId]: ready }), [activeId]);
@@ -192,14 +209,18 @@ export function Onboarding({ settings, legal, steps = [], permissions, models, l
     };
     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" })] });
+    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), children: "Finish setup" })] });
     if (!state || !active)
         return _jsx("div", { className: cx("rk-onboarding", className), "aria-busy": "true", children: _jsx("p", { className: "rk-onboarding__muted", children: "Loading setup\u2026" }) });
     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: "Loading setup\u2026" })] });
+        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 ?? await hashDocuments(legal.documents), acceptedAt: new Date().toISOString(), 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);
@@ -216,6 +237,6 @@ export function Onboarding({ settings, legal, steps = [], permissions, models, l
                     } })] });
     }
     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: 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: i === 0 && builtins.length > 1, onClick: () => { if (i > 0 && (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] }), _jsx("h1", { children: active.title }), 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, onClick: () => { void save({ currentStep: index, skipped: true }).then((ok) => ok ? runCallback(onSkip) : undefined); }, children: "Set up later" }) : null, _jsx("span", { className: "rk-onboarding__hint", children: !canContinue && active.blockedHint ? active.blockedHint : null }), _jsx(Button, { variant: "secondary", disabled: index <= 1 || saving, onClick: () => void save({ currentStep: index - 1 }), children: "Back" }), _jsx(Button, { variant: "primary", disabled: saving || !canContinue, onClick: () => void markAndMove(index + 1, active.id), children: index === builtins.length - 1 ? "Finish setup" : "Continue" })] })] })] });
+    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, onClick: () => { if (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] }), _jsx("h1", { children: active.title }), 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, onClick: () => { void save({ currentStep: index, skipped: true }).then((ok) => ok ? runCallback(onSkip) : undefined); }, children: "Set up later" }) : null, _jsx("span", { className: "rk-onboarding__hint", children: !canContinue && active.blockedHint ? active.blockedHint : null }), _jsx(Button, { variant: "secondary", disabled: index <= lead || saving, onClick: () => void save({ currentStep: index - 1 }), children: "Back" }), _jsx(Button, { variant: "primary", disabled: saving || !canContinue, onClick: () => void markAndMove(index + 1, active.id), children: index === builtins.length - 1 ? "Finish setup" : "Continue" })] })] })] });
 }

package/dist/index.d.ts

@@ -1,4 +1,4 @@
 export { Onboarding, isLegalAccepted, onboardingStateKey } from "./Onboarding.js";
-export { licenseStep, modelsStep, permissionsStep } from "./steps.js";
+export { licenseStep, modelsStep, permissionsStep, signInStep } from "./steps.js";
 export type { ModelsStepOptions } from "./steps.js";
 export type * from "./types.js";

package/dist/index.js

@@ -1,2 +1,2 @@
 export { Onboarding, isLegalAccepted, onboardingStateKey } from "./Onboarding.js";
-export { licenseStep, modelsStep, permissionsStep } from "./steps.js";
+export { licenseStep, modelsStep, permissionsStep, signInStep } from "./steps.js";

package/dist/steps.d.ts

@@ -1,5 +1,5 @@
 import { type ReactNode } from "react";
-import type { LicenseBackend, ModelsAutoStart, ModelsBackend, OnboardingStep, PermissionsBackend } from "./types.js";
+import type { SignInBackend, LicenseBackend, ModelsAutoStart, ModelsBackend, OnboardingStep, PermissionsBackend } from "./types.js";
 export declare function permissionsStep(backend: PermissionsBackend, options?: {
     label?: string;
     title?: string;
@@ -26,3 +26,9 @@ export declare function licenseStep(backend: LicenseBackend, options?: {
     title?: string;
     description?: string;
 }): OnboardingStep;
+/** Sign-in step. Every button hands off to the shared owner and opens the user's default browser; no in-app webview. */
+export declare function signInStep(backend: SignInBackend, options?: {
+    label?: string;
+    title?: string;
+    description?: string;
+}): OnboardingStep;

package/dist/steps.js

@@ -1,6 +1,6 @@
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useCallback, useEffect, useRef, useState } from "react";
-import { Button, Input, Badge } from "@rightkit/app-shell/react";
+import { Button, Input, Badge } from "@rightkit/react-shell/react";
 function ProgressBar({ value, label }) {
     const pct = Math.max(0, Math.min(1, value));
     return _jsx("div", { className: "rk-onboarding__progress", role: "progressbar", "aria-label": label, "aria-valuemin": 0, "aria-valuemax": 100, "aria-valuenow": Math.round(pct * 100), children: _jsx("i", { style: { width: `${pct * 100}%` } }) });
@@ -113,3 +113,28 @@ function LicenseBody({ backend }) {
 export function licenseStep(backend, options = {}) {
     return { id: "license", label: options.label ?? "Licence", title: options.title ?? "Choose how you’ll use this app", description: options.description ?? "Activate a licence, start a trial, or continue with the free plan.", skippable: true, render: () => _jsx(LicenseBody, { backend: backend }) };
 }
+function SignInBody({ backend }) {
+    const [account, setAccount] = useState({ signedIn: false });
+    const [busy, setBusy] = useState(null);
+    const [error, setError] = useState(null);
+    useEffect(() => { let live = true; backend.load().then((a) => { if (live)
+        setAccount(a); }, () => undefined); return () => { live = false; }; }, [backend]);
+    const start = async (provider) => {
+        setBusy(provider);
+        setError(null);
+        try {
+            setAccount(await backend.start(provider));
+        }
+        catch (e) {
+            setError(e instanceof Error ? e.message : "Sign-in did not finish.");
+        }
+        finally {
+            setBusy(null);
+        }
+    };
+    return _jsxs("div", { className: "rk-onboarding__signin", children: [account.signedIn ? _jsxs("p", { children: ["Signed in", account.account ? _jsxs(_Fragment, { children: [" as ", _jsx("strong", { children: account.account })] }) : null, "."] }) : null, _jsx("div", { className: "rk-onboarding__row-actions", children: backend.providers.map((p) => _jsx(Button, { size: "sm", variant: "secondary", disabled: busy !== null, onClick: () => void start(p.id), children: busy === p.id ? "Waiting for your browser…" : p.label ?? `Sign in with ${p.id === "google" ? "Google" : p.id === "apple" ? "Apple" : "your account"}` }, p.id)) }), _jsx("p", { className: "rk-onboarding__hint", children: _jsx("small", { children: "Opens your browser. You stay signed in to the accounts you already use there." }) }), error ? _jsx("p", { role: "alert", children: error }) : null] });
+}
+/** Sign-in step. Every button hands off to the shared owner and opens the user's default browser; no in-app webview. */
+export function signInStep(backend, options = {}) {
+    return { id: "sign-in", label: options.label ?? "Sign in", title: options.title ?? "Sign in", description: options.description ?? "Sign-in opens your default browser, so you stay signed in to the accounts you already use there.", skippable: true, render: () => _jsx(SignInBody, { backend: backend }) };
+}

package/dist/types.d.ts

@@ -5,7 +5,7 @@ export interface SettingsSnapshot {
     values: SettingsValues;
     revision: number;
 }
-/** Structural port shared with @rightkit/settings-ui and rightkit-settings. */
+/** Structural port shared with @rightkit/settings-ui and rightkit-app-settings. */
 export interface SettingsBackend {
     load(): Promise<SettingsSnapshot>;
     patch(patch: SettingsValues, expectedRevision?: number): Promise<SettingsSnapshot>;
@@ -57,6 +57,28 @@ export interface LicenseBackend {
     purchaseUrl?: string;
     openExternal?: (url: string) => void | Promise<void>;
 }
+export type SignInProvider = "google" | "apple" | "oauth";
+/**
+ * Sign-in owned by `rightkit-oauth`. Every provider opens the user's DEFAULT browser (never an in-app webview, so existing
+ * browser sessions are kept); `start` must call the shared owner (`OAuthClient::sign_in_with_browser` through the app's
+ * command), not open a window of its own. Orthic-Labs/rightkit#279.
+ */
+export interface SignInBackend {
+    providers: readonly {
+        id: SignInProvider;
+        label?: string;
+    }[];
+    /** Account already signed in, if any. */
+    load(): Promise<{
+        signedIn: boolean;
+        account?: string;
+    }>;
+    /** Open the default browser for `provider` and resolve when the sign-in finishes (or reject / throw on failure or cancel). */
+    start(provider: SignInProvider): Promise<{
+        signedIn: boolean;
+        account?: string;
+    }>;
+}
 export type EligibilityBasis = "individual" | "enterprise";
 /** Full record of one legal acceptance, persisted so version changes can re-prompt. */
 export interface LegalAcceptanceRecord {
@@ -94,6 +116,7 @@ export interface OnboardingStepContext {
     permissions?: PermissionsBackend;
     models?: ModelsBackend;
     license?: LicenseBackend;
+    signIn?: SignInBackend;
     /** Readiness reported by steps via `setReady`, keyed by step id. */
     ready: Readonly<Record<string, boolean>>;
     /** Reports whether the active step is ready (used by `canContinue`). Stable per step. */
@@ -114,9 +137,21 @@ export interface OnboardingStep {
 export interface LegalStepConfig extends Omit<LegalGateProps, "variant" | "onAgree" | "onQuit"> {
     onQuit?: () => void;
 }
+/**
+ * How legal documents take part in onboarding.
+ * - `gate` (default): the blocking agreement gate comes first and is recorded (needs `legal`).
+ * - `notice`: no gate and no acceptance. A first "Notice" step lists the `legal` documents as links; Continue moves on (free or open-source apps that still hold their notice).
+ * - `none`: no legal step at all; `legal` is not needed.
+ */
+export type LegalMode = "gate" | "notice" | "none";
 export interface OnboardingProps {
     settings: SettingsBackend;
-    legal: LegalStepConfig;
+    /** Required when `legalMode` is `gate` (default). Optional for `notice` (the documents shown) and `none`. */
+    legal?: LegalStepConfig;
+    /** Default `gate`. See `LegalMode`. */
+    legalMode?: LegalMode;
+    /** Name shown in the step rail. Default: `legal.appName`. */
+    appName?: string;
     /** App-specific steps are appended after built-in steps, in supplied order. */
     steps?: readonly OnboardingStep[];
     permissions?: PermissionsBackend;
@@ -129,7 +164,13 @@ export interface OnboardingProps {
     requiredVersion?: string;
     /** Custom acceptance check; takes precedence over `requiredVersion`. */
     isAccepted?: (state: PersistedOnboardingState) => boolean;
-    /** Hash of the legal documents recorded with the acceptance. Default: hash of document titles and URLs. */
+    /**
+     * Hash the stored acceptance must carry. A stored acceptance with a different (or no) hash re-prompts even when
+     * the version is unchanged, so a text change without a version bump is caught. Pass the hash of the MATERIAL
+     * documents only (see `@rightkit/legal`), not of appendices that regenerate on dependency bumps.
+     */
+    requiredDocumentsHash?: string;
+    /** Hash of the legal documents recorded with the acceptance. Default: `requiredDocumentsHash`, else a hash of document titles and URLs. Recorded only; never compared. */
     documentsHash?: string;
     /** Runs (and is awaited) before the legal gate is shown, e.g. to resize or reveal the window. */
     beforeLegalGate?: () => void | Promise<void>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rightkit/onboarding",
-  "version": "0.3.2",
+  "version": "0.5.0",
   "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",
@@ -24,25 +24,26 @@
     "*.css"
   ],
   "peerDependencies": {
-    "@rightkit/app-shell": ">=0.2.0 <1",
+    "@rightkit/react-shell": ">=0.2.0 <1",
     "@rightkit/legal-ui": ">=0.1.2 <1",
     "react": ">=18 <21"
   },
   "devDependencies": {
-    "@rightkit/app-shell": "0.4.1",
-    "@rightkit/legal-ui": "0.2.0",
-    "@rightkit/qa-chrome": "0.1.3",
-    "@testing-library/jest-dom": "^6.6.3",
-    "@testing-library/react": "^16.1.0",
-    "@testing-library/user-event": "^14.5.2",
-    "@types/react": "^19.0.0",
-    "@types/react-dom": "^19.0.0",
-    "jsdom": "^25.0.1",
-    "react": "^19.0.0",
-    "react-dom": "^19.0.0",
-    "typescript": "^5.7.0",
-    "vite": "^6.0.0",
-    "vitest": "^2.1.8"
+    "@rightkit/react-shell": "0.6.8",
+    "@rightkit/legal-ui": "0.3.0",
+    "@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",
+    "@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"
   },
   "publishConfig": {
     "registry": "https://registry.npmjs.org",
@@ -50,7 +51,7 @@
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/bogusyogi/rightkit.git",
+    "url": "git+https://github.com/Orthic-Labs/rightkit.git",
     "directory": "packages/onboarding"
   },
   "scripts": {