@rightkit/onboarding 0.3.3 → 0.6.0

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`; 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); types from `types.ts`, `ModelsStepOptions` |
 | `@rightkit/onboarding/onboarding.css` | Stylesheet |
 
 ## Peer dependencies
@@ -43,7 +43,9 @@ import "@rightkit/onboarding/onboarding.css";
 />
 ```
 
-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)`.
+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.
 
 ## When the legal gate re-prompts
 

package/dist/Onboarding.d.ts

@@ -2,4 +2,4 @@ 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, requiredDocumentsHash?: string): boolean;
 export declare function onboardingStateKey(): string;
-export declare function Onboarding({ settings, legal, 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;
+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;

package/dist/Onboarding.js

@@ -6,6 +6,7 @@ import { cx } from "./ui.js";
 import { licenseStep, modelsStep, permissionsStep } 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…" };
 function readAcceptance(value) {
     if (!value || typeof value !== "object")
         return undefined;
@@ -29,6 +30,7 @@ function readState(value) {
         legalAccepted: candidate.legalAccepted === true || legalAcceptance !== undefined,
         eligibilityBasis: legalAcceptance?.eligibilityBasis ?? (candidate.eligibilityBasis === "individual" || candidate.eligibilityBasis === "enterprise" ? candidate.eligibilityBasis : undefined),
         ...(legalAcceptance ? { legalAcceptance } : {}),
+        ...(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). */
@@ -79,7 +81,18 @@ 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, requiredDocumentsHash, 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, labels: labelOverrides }) {
+    if (legalMode === "gate" && !legal)
+        throw new Error("Onboarding: `legal` is required when legalMode is \"gate\"");
+    const L = { ...DEFAULT_LABELS, ...labelOverrides };
+    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);
@@ -87,6 +100,9 @@ export function Onboarding({ settings, legal, steps = [], permissions, models, l
     const [gateCleared, setGateCleared] = useState(false);
     /** One auto-start per mount, even when the models step unmounts (Back/Next) or the step list is rebuilt. */
     const modelsStarted = useRef(false);
+    /** Values passed to `ctx.setResult`, keyed by step id; handed to `onComplete`. */
+    const stepResults = useRef({});
+    const [continuing, setContinuing] = useState(false);
     /** Persists a patch; throws when the settings backend rejects it. */
     const persist = useCallback(async (patch) => {
         setSaving(true);
@@ -144,20 +160,24 @@ 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, requiredDocumentsHash);
+    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 ?? "";
+    /** The step on screen now; an `onContinue` that resolves after the step changed is stale. */
+    const activeIdRef = useRef(activeId);
+    activeIdRef.current = activeId;
     const setReady = useCallback((ready) => setReadyMap((m) => m[activeId] === ready ? m : { ...m, [activeId]: ready }), [activeId]);
     useEffect(() => {
         if (!needsGate) {
@@ -177,7 +197,8 @@ export function Onboarding({ settings, legal, steps = [], permissions, models, l
             setGateCleared(true); })();
         return () => { live = false; };
     }, [needsGate, gateCleared, beforeLegalGate]);
-    const context = { state: activeState, settings, setState: saveStep, permissions, models, license, ready: readyMap, setReady };
+    const setResult = useCallback((value) => { stepResults.current[activeId] = value; }, [activeId]);
+    const context = { state: activeState, settings, setState: saveStep, permissions, models, license, ready: readyMap, setReady, setResult };
     const canContinue = active?.canContinue ? active.canContinue(context) : true;
     const runCallback = async (callback) => {
         try {
@@ -187,22 +208,57 @@ export function Onboarding({ settings, legal, steps = [], permissions, models, l
             setError(e instanceof Error ? e.message : String(e));
         }
     };
-    const markAndMove = async (nextIndex, completedId) => {
-        const completed = completedId && !activeState.completed.includes(completedId) ? [...activeState.completed, completedId] : activeState.completed;
+    const resultOf = (completed, skipped) => ({ completed, skipped, steps: { ...stepResults.current } });
+    /** Marks `mark.completed` done or `mark.skipped` skipped (never both), then moves to `nextIndex`; completing the last step calls `onComplete`. */
+    const markAndMove = async (nextIndex, mark = {}) => {
+        const previousSkipped = activeState.skippedSteps ?? [];
+        // A step is completed or skipped, never both: a skip removes an earlier completion of the same step.
+        const completedBase = activeState.completed.filter((id) => id !== mark.skipped);
+        const completed = mark.completed && !completedBase.includes(mark.completed) ? [...completedBase, mark.completed] : completedBase;
+        const skippedBase = previousSkipped.filter((id) => id !== mark.completed);
+        const skippedSteps = mark.skipped && !skippedBase.includes(mark.skipped) ? [...skippedBase, mark.skipped] : skippedBase;
         if (nextIndex >= builtins.length) {
-            if (await save({ completed, currentStep: Math.max(0, builtins.length - 1), skipped: false }))
-                await runCallback(onComplete);
+            if (await save({ completed, skippedSteps, currentStep: Math.max(0, builtins.length - 1), skipped: false }))
+                await runCallback(() => onComplete(resultOf(completed, skippedSteps)));
             return;
         }
-        await save({ completed, currentStep: nextIndex, skipped: false });
+        await save({ completed, skippedSteps, currentStep: nextIndex, skipped: false });
+    };
+    /** Primary button: runs the step's `onContinue` veto first; `false` or a throw keeps the step. */
+    const advance = async () => {
+        if (active.onContinue) {
+            const stepId = active.id;
+            setContinuing(true);
+            setError(null);
+            let proceed = true;
+            try {
+                proceed = (await active.onContinue(context)) !== false;
+            }
+            catch (e) {
+                if (activeIdRef.current === stepId)
+                    setError(e instanceof Error ? e.message : String(e));
+                return;
+            }
+            finally {
+                setContinuing(false);
+            }
+            // The step changed while onContinue was awaited: discard this completion rather than move or save from stale state.
+            if (!proceed || activeIdRef.current !== stepId)
+                return;
+        }
+        await markAndMove(index + 1, { completed: active.id });
     };
     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(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: "Loading setup\u2026" }) });
+        return _jsx("div", { className: cx("rk-onboarding", className), "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: "Loading setup\u2026" })] });
+            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 })] });
+        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 };
@@ -218,10 +274,10 @@ export function Onboarding({ settings, legal, steps = [], permissions, models, l
                         const progress = reacceptance ? {} : { completed: ["legal"], currentStep: builtins.length > 1 ? 1 : 0 };
                         await persist({ legalAccepted: true, eligibilityBasis, legalAcceptance, ...progress });
                         if (!reacceptance && builtins.length === 1)
-                            await onComplete();
+                            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: 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) || 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/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;
@@ -21,7 +21,28 @@ export interface ModelsStepOptions extends ModelsAutoStart {
     };
 }
 export declare function modelsStep(backend: ModelsBackend, options?: ModelsStepOptions): OnboardingStep;
-export declare function licenseStep(backend: LicenseBackend, options?: {
+/** Copy overrides for the licence step. Each key defaults to the English text. */
+export interface LicenseStepCopy {
+    /** Key field label and placeholder. Default "Licence key". */
+    keyLabel?: string;
+    /** Submit button. Default "Activate". */
+    activateLabel?: string;
+    /** Trial button. Default "Start trial". */
+    trialLabel?: string;
+    /** Plans link. Default "View plans". */
+    plansLabel?: string;
+    /** Status text when no licence is active. Default "You can continue without a licence.". */
+    noLicenceDetail?: string;
+}
+export interface LicenseStepOptions {
+    label?: string;
+    title?: string;
+    description?: string;
+    copy?: LicenseStepCopy;
+}
+export declare function licenseStep(backend: LicenseBackend, options?: LicenseStepOptions): 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;

package/dist/steps.js

@@ -1,4 +1,4 @@
-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/react-shell/react";
 function ProgressBar({ value, label }) {
@@ -100,16 +100,45 @@ export function modelsStep(backend, options = {}) {
         render: (ctx) => _jsx(ModelsBody, { backend: backend, onReady: ctx.setReady, autoStartDownload: options.autoStartDownload, shouldAutoStart: options.shouldAutoStart, onModelsStepEnter: options.onModelsStepEnter, intro: options.intro, startGuard: options.startGuard }),
     };
 }
-function LicenseBody({ backend }) {
+function LicenseBody({ backend, copy }) {
     const [state, setState] = useState({ status: "none" });
     const [key, setKey] = useState("");
     const [busy, setBusy] = useState(false);
     const [error, setError] = useState(null);
     useEffect(() => void backend.load().then(setState, (e) => setError(e instanceof Error ? e.message : String(e))), [backend]);
     const run = (fn) => { setBusy(true); setError(null); void fn().then(setState, (e) => setError(e instanceof Error ? e.message : String(e))).finally(() => setBusy(false)); };
-    return _jsxs("div", { className: "rk-onboarding__card", "data-testid": "onboarding-license", children: [_jsxs("div", { className: "rk-onboarding__license-state", children: [_jsx(Badge, { tone: state.status === "active" || state.status === "trial" ? "ok" : state.status === "expired" || state.status === "invalid" ? "bad" : "neutral", children: state.label ?? state.status }), _jsx("span", { children: state.detail ?? "You can continue without a licence." })] }), error ? _jsx("p", { className: "rk-onboarding__error", role: "alert", children: error }) : null, backend.activate ? _jsxs("form", { className: "rk-onboarding__form", onSubmit: (e) => { e.preventDefault(); if (key.trim())
-                    run(() => backend.activate(key.trim())); }, children: [_jsx(Input, { "aria-label": "Licence key", placeholder: "Licence key", value: key, onChange: (e) => setKey(e.target.value), disabled: busy }), _jsx(Button, { size: "sm", variant: "primary", type: "submit", disabled: busy || !key.trim(), children: "Activate" })] }) : null, _jsxs("div", { className: "rk-onboarding__row-actions", children: [backend.startTrial ? _jsx(Button, { size: "sm", variant: "secondary", disabled: busy, onClick: () => run(() => backend.startTrial()), children: "Start trial" }) : null, backend.purchaseUrl ? _jsx(Button, { size: "sm", variant: "ghost", onClick: () => void backend.openExternal?.(backend.purchaseUrl), children: "View plans" }) : null] })] });
+    return _jsxs("div", { className: "rk-onboarding__card", "data-testid": "onboarding-license", children: [_jsxs("div", { className: "rk-onboarding__license-state", children: [_jsx(Badge, { tone: state.status === "active" || state.status === "trial" ? "ok" : state.status === "expired" || state.status === "invalid" ? "bad" : "neutral", children: state.label ?? state.status }), _jsx("span", { children: state.detail ?? copy.noLicenceDetail })] }), error ? _jsx("p", { className: "rk-onboarding__error", role: "alert", children: error }) : null, backend.activate ? _jsxs("form", { className: "rk-onboarding__form", onSubmit: (e) => { e.preventDefault(); if (key.trim())
+                    run(() => backend.activate(key.trim())); }, children: [_jsx(Input, { "aria-label": copy.keyLabel, placeholder: copy.keyLabel, value: key, onChange: (e) => setKey(e.target.value), disabled: busy }), _jsx(Button, { size: "sm", variant: "primary", type: "submit", disabled: busy || !key.trim(), children: copy.activateLabel })] }) : null, _jsxs("div", { className: "rk-onboarding__row-actions", children: [backend.startTrial ? _jsx(Button, { size: "sm", variant: "secondary", disabled: busy, onClick: () => run(() => backend.startTrial()), children: copy.trialLabel }) : null, backend.purchaseUrl ? _jsx(Button, { size: "sm", variant: "ghost", onClick: () => void backend.openExternal?.(backend.purchaseUrl), children: copy.plansLabel }) : null] })] });
 }
 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 }) };
+    const copy = {
+        keyLabel: "Licence key", activateLabel: "Activate", trialLabel: "Start trial", plansLabel: "View plans",
+        noLicenceDetail: "You can continue without a licence.", ...options.copy,
+    };
+    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, copy: copy }) };
+}
+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

@@ -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 {
@@ -86,6 +108,29 @@ export interface PersistedOnboardingState {
     /** Legacy mirror of `legalAcceptance.eligibilityBasis`. */
     eligibilityBasis?: EligibilityBasis;
     legalAcceptance?: LegalAcceptanceRecord;
+    /** Step ids the user skipped with the per-step Skip button (not marked complete). */
+    skippedSteps?: string[];
+}
+/** What `onComplete` receives. `steps` holds values passed to `ctx.setResult` during this mount. */
+export interface OnboardingResult {
+    completed: string[];
+    skipped: string[];
+    steps: Record<string, unknown>;
+}
+/** Button and status copy. Each key defaults to the English text shown in the table. */
+export interface OnboardingLabels {
+    /** "Set up later". */
+    skip: string;
+    /** Per-step Skip button. */
+    skipStep: string;
+    /** "Back". */
+    back: string;
+    /** "Continue". */
+    continue: string;
+    /** "Finish setup" on the last step. */
+    finish: string;
+    /** "Loading setup…". */
+    loading: string;
 }
 export interface OnboardingStepContext {
     state: PersistedOnboardingState;
@@ -94,10 +139,13 @@ 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. */
     setReady: (ready: boolean) => void;
+    /** Stores a value for this step; it is passed to `onComplete` as `result.steps[step.id]`. */
+    setResult: (value: unknown) => void;
 }
 export interface OnboardingStep {
     id: string;
@@ -109,21 +157,44 @@ export interface OnboardingStep {
     canContinue?: (context: OnboardingStepContext) => boolean;
     /** Shown beside the disabled Continue/Finish button. */
     blockedHint?: string;
+    /** Primary button text for this step (e.g. "Open CodeRight"). Overrides Continue and Finish setup. */
+    continueLabel?: string;
+    /**
+     * Runs before Continue/Finish advances. Return `false` (or throw) to keep the step; a throw shows its message.
+     * `void` or `true` advances. Not run for Back, the rail, or Skip.
+     */
+    onContinue?: (context: OnboardingStepContext) => void | boolean | Promise<void | boolean>;
+    /** Empty title hides the heading (e.g. a Welcome step). */
     render: (context: OnboardingStepContext) => ReactNode;
 }
 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;
     models?: ModelsBackend;
     license?: LicenseBackend;
-    onComplete: () => void | Promise<void>;
+    /** 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>;
+    /** Override any button or status text. Keys not given keep the English defaults. */
+    labels?: Partial<OnboardingLabels>;
     className?: string;
     /** Version the user must have accepted. A different (or missing) stored version re-prompts with `variant: "re-acceptance"`. */
     requiredVersion?: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rightkit/onboarding",
-  "version": "0.3.3",
+  "version": "0.6.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",
@@ -29,20 +29,21 @@
     "react": ">=18 <21"
   },
   "devDependencies": {
-    "@rightkit/react-shell": "0.6.4",
-    "@rightkit/legal-ui": "0.2.2",
-    "@rightkit/qa-chrome": "0.1.6",
-    "@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.7.0",
+    "@rightkit/legal-ui": "0.4.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/Orthic-Labs/rightkit.git",
+    "url": "git+https://github.com/bogusyogi/rightkit.git",
     "directory": "packages/onboarding"
   },
   "scripts": {