@rightkit/onboarding 0.1.0 → 0.2.0

package/README.md

@@ -11,5 +11,32 @@ import "@rightkit/onboarding/onboarding.css";
 ```
 
 - `settings` is a `SettingsBackend`; progress is stored under the `onboarding.state` key.
-- The agreement is enforced whenever `legalAccepted` is not persisted as `true`, regardless of the saved step index.
+- The agreement is enforced until accepted, regardless of the saved step index. Acceptance is stored as `legalAcceptance: { version, documentsHash, acceptedAt (UTC ISO), eligibilityBasis }`; legacy `legalAccepted: true` is still read.
 - `onComplete` and `onSkip` run only after the state was saved. A rejected save is shown in an alert and neither callback runs.
+
+## Props
+
+| Prop | Purpose |
+| --- | --- |
+| `requiredVersion` | Version the user must have accepted. A different or missing stored version re-prompts with the legal gate's `re-acceptance` variant. Legacy boolean acceptance is only re-prompted when this is set. |
+| `isAccepted(state)` | Custom acceptance check; overrides `requiredVersion`. |
+| `documentsHash` | Hash recorded with the acceptance (default: SHA-256 of document titles and URLs). |
+| `beforeLegalGate()` | Awaited before the gate shows (e.g. size or reveal the window). The package does no window sizing itself. |
+| `requireModel` | Continue/Finish on the models step wait for an installed model. |
+| `autoStartDownload` | Start the first missing model download when the models step opens. |
+| `modelsIntro` | App copy shown at the top of the models step. |
+| `allowSkip` | Show "Set up later" (default `true`). |
+| `titlebar` | Node rendered in a strip along the top. |
+| `dragRegion` | Add `data-tauri-drag-region` to that strip (default `false`; height `--rk-onboarding-titlebar-h`, default 32px). |
+
+## Custom steps and readiness
+
+A step may set `canContinue(context)`; Continue/Finish stay disabled while it returns `false` (optional `blockedHint` is shown). Steps with async readiness call `context.setReady(boolean)` from `render` and read `context.ready[stepId]`. Back is disabled on the first step after the agreement.
+
+## Models backend
+
+`ModelsBackend.cancel` is optional; the Pause control appears only when it is supplied.
+
+## Tests
+
+`pnpm exec vitest run` runs the jsdom unit tests (`src/*.test.tsx`) and the headless-Chrome e2e.

package/dist/Onboarding.d.ts

@@ -1,3 +1,5 @@
-import type { OnboardingProps } from "./types.js";
+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 onboardingStateKey(): string;
-export declare function Onboarding({ settings, legal, steps, permissions, models, license, onComplete, onSkip, className }: OnboardingProps): import("react").JSX.Element;
+export declare function Onboarding({ settings, legal, steps, permissions, models, license, onComplete, onSkip, className, requiredVersion, isAccepted, documentsHash, beforeLegalGate, requireModel, autoStartDownload, modelsIntro, allowSkip, titlebar, dragRegion }: OnboardingProps): import("react").JSX.Element;

package/dist/Onboarding.js

@@ -6,24 +6,72 @@ 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 };
+function readAcceptance(value) {
+    if (!value || typeof value !== "object")
+        return undefined;
+    const r = value;
+    if (typeof r.version !== "string" || typeof r.documentsHash !== "string" || typeof r.acceptedAt !== "string")
+        return undefined;
+    if (r.eligibilityBasis !== "individual" && r.eligibilityBasis !== "enterprise")
+        return undefined;
+    return { version: r.version, documentsHash: r.documentsHash, acceptedAt: r.acceptedAt, eligibilityBasis: r.eligibilityBasis };
+}
 function readState(value) {
     if (!value || typeof value !== "object")
         return INITIAL;
     const candidate = value;
+    const legalAcceptance = readAcceptance(candidate.legalAcceptance);
     return {
         version: 1,
         currentStep: typeof candidate.currentStep === "number" && candidate.currentStep >= 0 ? Math.floor(candidate.currentStep) : 0,
         completed: Array.isArray(candidate.completed) ? candidate.completed.filter((x) => typeof x === "string") : [],
         skipped: candidate.skipped === true,
-        legalAccepted: candidate.legalAccepted === true,
-        eligibilityBasis: candidate.eligibilityBasis === "individual" || candidate.eligibilityBasis === "enterprise" ? candidate.eligibilityBasis : undefined,
+        legalAccepted: candidate.legalAccepted === true || legalAcceptance !== undefined,
+        eligibilityBasis: legalAcceptance?.eligibilityBasis ?? (candidate.eligibilityBasis === "individual" || candidate.eligibilityBasis === "enterprise" ? candidate.eligibilityBasis : undefined),
+        ...(legalAcceptance ? { legalAcceptance } : {}),
     };
 }
+/** True when the stored acceptance satisfies the host's requirement. */
+export function isLegalAccepted(state, requiredVersion, custom) {
+    if (custom)
+        return custom(state);
+    if (requiredVersion !== undefined)
+        return state.legalAcceptance?.version === requiredVersion;
+    return state.legalAccepted;
+}
+/** FNV-1a fallback when SubtleCrypto is unavailable. */
+function fnv(text) {
+    let h = 0x811c9dc5;
+    for (let i = 0; i < text.length; i += 1) {
+        h ^= text.charCodeAt(i);
+        h = Math.imul(h, 0x01000193) >>> 0;
+    }
+    return `fnv1a:${h.toString(16).padStart(8, "0")}`;
+}
+async function hashDocuments(documents) {
+    const text = JSON.stringify(documents.map((d) => [d.title, d.url ?? ""]));
+    try {
+        const subtle = globalThis.crypto?.subtle;
+        if (subtle) {
+            const digest = await subtle.digest("SHA-256", new TextEncoder().encode(text));
+            return `sha256:${[...new Uint8Array(digest)].map((b) => b.toString(16).padStart(2, "0")).join("")}`;
+        }
+    }
+    catch { /* fall through */ }
+    return fnv(text);
+}
 export function onboardingStateKey() { return KEY; }
-export function Onboarding({ settings, legal, steps = [], permissions, models, license, onComplete, onSkip, className }) {
+function TitleStrip({ titlebar, dragRegion }) {
+    if (!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, modelsIntro, allowSkip = true, titlebar, dragRegion }) {
     const [state, setState] = useState(null);
     const [saving, setSaving] = useState(false);
     const [error, setError] = useState(null);
+    const [readyMap, setReadyMap] = useState({});
+    const [gateCleared, setGateCleared] = useState(false);
     /** Persists a patch; throws when the settings backend rejects it. */
     const persist = useCallback(async (patch) => {
         setSaving(true);
@@ -56,17 +104,41 @@ export function Onboarding({ settings, legal, steps = [], permissions, models, l
         setState(readState(snapshot.values[KEY])); }, (e) => { if (live)
         setError(e instanceof Error ? e.message : String(e)); }); return () => { live = false; }; }, [settings]);
     const builtins = useMemo(() => [
-        { id: "legal", label: "Agreement", title: "Review agreement", skippable: false, render: () => null },
+        { id: "legal", label: "Agreement", title: "Review agreement", skippable: false, render: () => _jsx("p", { className: "rk-onboarding__muted", children: "Agreement accepted." }) },
         ...(permissions ? [permissionsStep(permissions)] : []),
-        ...(models ? [modelsStep(models)] : []),
+        ...(models ? [modelsStep(models, { required: requireModel, autoStartDownload, intro: modelsIntro })] : []),
         ...(license ? [licenseStep(license)] : []),
         ...steps,
-    ], [license, models, permissions, steps]);
+    ], [license, models, permissions, steps, requireModel, autoStartDownload, modelsIntro]);
     const activeState = state ?? INITIAL;
+    const accepted = isLegalAccepted(activeState, requiredVersion, isAccepted);
+    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.
-    const index = activeState.legalAccepted ? Math.min(activeState.currentStep, builtins.length - 1) : 0;
+    // 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 active = builtins[index];
-    const context = { state: activeState, settings, setState: saveStep, permissions, models, license };
+    const activeId = active?.id ?? "";
+    const setReady = useCallback((ready) => setReadyMap((m) => m[activeId] === ready ? m : { ...m, [activeId]: ready }), [activeId]);
+    useEffect(() => {
+        if (!needsGate) {
+            setGateCleared(false);
+            return;
+        }
+        if (gateCleared)
+            return;
+        let live = true;
+        void (async () => { try {
+            await beforeLegalGate?.();
+        }
+        catch (e) {
+            if (live)
+                setError(e instanceof Error ? e.message : String(e));
+        } if (live)
+            setGateCleared(true); })();
+        return () => { live = false; };
+    }, [needsGate, gateCleared, beforeLegalGate]);
+    const context = { state: activeState, settings, setState: saveStep, permissions, models, license, ready: readyMap, setReady };
+    const canContinue = active?.canContinue ? active.canContinue(context) : true;
     const runCallback = async (callback) => {
         try {
             await callback?.();
@@ -88,11 +160,19 @@ export function Onboarding({ settings, legal, steps = [], permissions, models, l
         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 _jsx("div", { className: cx("rk-onboarding", className), "aria-busy": "true", children: _jsx("p", { className: "rk-onboarding__muted", children: "Loading setup\u2026" }) });
-    if (!activeState.legalAccepted) {
-        return _jsx("div", { className: cx("rk-onboarding rk-onboarding--legal", className), "data-testid": "onboarding-legal", children: _jsx(LegalGate, { ...legal, variant: "first-run", onQuit: () => void legal.onQuit?.(), onAgree: async ({ eligibilityBasis }) => { await persist({ legalAccepted: true, eligibilityBasis, completed: ["legal"], currentStep: builtins.length > 1 ? 1 : 0 }); if (builtins.length === 1)
-                    await onComplete(); } }) });
+    if (needsGate) {
+        if (!gateCleared)
+            return _jsxs("div", { className: cx("rk-onboarding", className), "aria-busy": "true", children: [_jsx(TitleStrip, { titlebar: titlebar, dragRegion: dragRegion }), _jsx("p", { className: "rk-onboarding__muted", children: "Loading setup\u2026" })] });
+        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: dragRegion }), _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 progress = reacceptance ? {} : { completed: ["legal"], currentStep: builtins.length > 1 ? 1 : 0 };
+                        await persist({ legalAccepted: true, eligibilityBasis, legalAcceptance, ...progress });
+                        if (!reacceptance && builtins.length === 1)
+                            await onComplete();
+                    } })] });
     }
     const body = active.render(context);
-    return _jsxs("main", { className: cx("rk-onboarding", className), "data-testid": "onboarding", "data-step-id": active.id, children: [_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, onClick: () => { if (i > 0 || activeState.legalAccepted)
-                                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: [_jsx(Button, { variant: "ghost", disabled: saving, onClick: () => { void save({ currentStep: index, skipped: true }).then((ok) => ok ? runCallback(onSkip) : undefined); }, children: "Set up later" }), _jsx("span", {}), _jsx(Button, { variant: "secondary", disabled: index === 0 || saving, onClick: () => void save({ currentStep: index - 1 }), children: "Back" }), _jsx(Button, { variant: "primary", disabled: saving, 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: 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" })] })] })] });
 }

package/dist/index.d.ts

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

package/dist/index.js

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

package/dist/steps.d.ts

@@ -1,14 +1,22 @@
+import { type ReactNode } from "react";
 import type { LicenseBackend, ModelsBackend, OnboardingStep, PermissionsBackend } from "./types.js";
 export declare function permissionsStep(backend: PermissionsBackend, options?: {
     label?: string;
     title?: string;
     description?: string;
 }): OnboardingStep;
-export declare function modelsStep(backend: ModelsBackend, options?: {
+export interface ModelsStepOptions {
     label?: string;
     title?: string;
     description?: string;
-}): OnboardingStep;
+    /** Continue/Finish wait until at least one model is installed. Default false. */
+    required?: boolean;
+    /** Start downloading the first missing model when the step opens. Default false. */
+    autoStartDownload?: boolean;
+    /** App copy rendered at the top of the step. */
+    intro?: ReactNode;
+}
+export declare function modelsStep(backend: ModelsBackend, options?: ModelsStepOptions): OnboardingStep;
 export declare function licenseStep(backend: LicenseBackend, options?: {
     label?: string;
     title?: string;

package/dist/steps.js

@@ -1,5 +1,5 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useCallback, useEffect, useState } from "react";
+import { useCallback, useEffect, useRef, useState } from "react";
 import { Button, Input, Badge } from "@rightkit/app-shell/react";
 function ProgressBar({ value, label }) {
     const pct = Math.max(0, Math.min(1, value));
@@ -29,32 +29,61 @@ function PermissionsBody({ backend }) {
 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 }) };
 }
-function ModelsBody({ backend }) {
+function ModelsBody({ backend, onReady, autoStartDownload, intro }) {
     const [models, setModels] = useState([]);
+    const [loaded, setLoaded] = useState(false);
     const [busy, setBusy] = useState(null);
     const [error, setError] = useState(null);
-    const reload = useCallback(() => backend.list().then(setModels, (e) => setError(e instanceof Error ? e.message : String(e))), [backend]);
+    const autoStarted = useRef(false);
+    const reload = useCallback(() => backend.list().then((list) => { setModels(list); setLoaded(true); }, (e) => setError(e instanceof Error ? e.message : String(e))), [backend]);
     useEffect(() => {
         void reload();
         if (!backend.subscribe)
             return;
         let off;
-        void backend.subscribe((entry) => setModels((current) => current.some((m) => m.id === entry.id) ? current.map((m) => m.id === entry.id ? entry : m) : [...current, entry])).then((unsubscribe) => { off = unsubscribe; });
-        return () => off?.();
+        let live = true;
+        void backend.subscribe((entry) => setModels((current) => current.some((m) => m.id === entry.id) ? current.map((m) => m.id === entry.id ? entry : m) : [...current, entry])).then((unsubscribe) => { if (live)
+            off = unsubscribe;
+        else
+            unsubscribe(); });
+        return () => { live = false; off?.(); };
     }, [backend, reload]);
-    const action = (model) => {
-        setBusy(model.id);
+    const hasInstalled = models.some((m) => m.state === "installed");
+    useEffect(() => { onReady?.(hasInstalled); }, [hasInstalled, onReady]);
+    const run = (id, request) => {
+        setBusy(id);
         setError(null);
-        const request = model.state === "downloading" || model.state === "verifying" ? backend.cancel(model.id) : backend.install(model.id);
         void request.then(reload, (e) => setError(e instanceof Error ? e.message : String(e))).finally(() => setBusy(null));
     };
-    return (_jsxs("div", { className: "rk-onboarding__card", "data-testid": "onboarding-models", children: [error ? _jsx("p", { className: "rk-onboarding__error", role: "alert", children: error }) : null, models.map((model) => {
+    useEffect(() => {
+        if (!autoStartDownload || !loaded || autoStarted.current)
+            return;
+        autoStarted.current = true;
+        if (models.some((m) => m.state === "installed" || m.state === "downloading" || m.state === "verifying"))
+            return;
+        const first = models.find((m) => m.state === "missing");
+        if (first)
+            run(first.id, backend.install(first.id));
+        // run is intentionally omitted: it only closes over setters.
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [autoStartDownload, 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) => {
                 const progress = model.progress ?? (model.state === "installed" ? 1 : 0);
-                return _jsxs("div", { className: "rk-onboarding__row", "data-model-id": model.id, children: [_jsxs("div", { className: "rk-onboarding__grow", children: [_jsx("strong", { children: model.label }), _jsxs("p", { children: [model.description ?? "", model.sizeBytes ? ` · ${formatBytes(model.sizeBytes)}` : ""] }), model.state === "downloading" || model.state === "verifying" ? _jsx(ProgressBar, { value: progress, label: `${model.label} download` }) : null] }), _jsxs("div", { className: "rk-onboarding__row-actions", children: [_jsx(Badge, { tone: model.state === "installed" ? "ok" : model.state === "error" ? "bad" : "neutral", children: model.state }), model.state !== "installed" && model.state !== "error" ? _jsx(Button, { size: "sm", variant: "secondary", disabled: busy === model.id, onClick: () => action(model), children: model.state === "downloading" || model.state === "verifying" ? "Pause" : "Download" }) : model.state === "error" ? _jsx(Button, { size: "sm", variant: "secondary", disabled: busy === model.id, onClick: () => action(model), children: "Retry" }) : null] })] }, model.id);
+                const active = model.state === "downloading" || model.state === "verifying";
+                const cancel = backend.cancel;
+                return _jsxs("div", { className: "rk-onboarding__row", "data-model-id": model.id, children: [_jsxs("div", { className: "rk-onboarding__grow", children: [_jsx("strong", { children: model.label }), _jsxs("p", { children: [model.description ?? "", model.sizeBytes ? ` · ${formatBytes(model.sizeBytes)}` : ""] }), active ? _jsx(ProgressBar, { value: progress, label: `${model.label} download` }) : null] }), _jsxs("div", { className: "rk-onboarding__row-actions", children: [_jsx(Badge, { tone: model.state === "installed" ? "ok" : model.state === "error" ? "bad" : "neutral", children: model.state }), model.state === "installed" ? null
+                                    : model.state === "error" ? _jsx(Button, { size: "sm", variant: "secondary", disabled: busy === model.id, onClick: () => run(model.id, backend.install(model.id)), children: "Retry" })
+                                        : active ? (cancel ? _jsx(Button, { size: "sm", variant: "secondary", disabled: busy === model.id, onClick: () => run(model.id, cancel.call(backend, model.id)), children: "Pause" }) : null)
+                                            : _jsx(Button, { size: "sm", variant: "secondary", disabled: busy === model.id, onClick: () => run(model.id, backend.install(model.id)), children: "Download" })] })] }, model.id);
             }), models.length === 0 && !error ? _jsx("p", { className: "rk-onboarding__muted", children: "No models available." }) : null] }));
 }
 export function modelsStep(backend, options = {}) {
-    return { id: "models", label: options.label ?? "Models", title: options.title ?? "Choose local models", description: options.description ?? "Downloads are verified before a model is activated.", skippable: true, render: () => _jsx(ModelsBody, { backend: backend }) };
+    return {
+        id: "models", label: options.label ?? "Models", title: options.title ?? "Choose local models", description: options.description ?? "Downloads are verified before a model is activated.", skippable: true,
+        canContinue: options.required ? (ctx) => ctx.ready.models === true : undefined,
+        blockedHint: options.required ? "Download a model to continue." : undefined,
+        render: (ctx) => _jsx(ModelsBody, { backend: backend, onReady: ctx.setReady, autoStartDownload: options.autoStartDownload, intro: options.intro }),
+    };
 }
 function LicenseBody({ backend }) {
     const [state, setState] = useState({ status: "none" });

package/dist/types.d.ts

@@ -39,7 +39,8 @@ export interface ModelEntry {
 export interface ModelsBackend {
     list(): Promise<ModelEntry[]>;
     install(id: string): Promise<void>;
-    cancel(id: string): Promise<void>;
+    /** Optional. The cancel/pause control is shown only when the backend supplies this. */
+    cancel?(id: string): Promise<void>;
     subscribe?(handler: (entry: ModelEntry) => void): Promise<() => void>;
 }
 export interface LicenseState {
@@ -56,13 +57,25 @@ export interface LicenseBackend {
     purchaseUrl?: string;
     openExternal?: (url: string) => void | Promise<void>;
 }
+export type EligibilityBasis = "individual" | "enterprise";
+/** Full record of one legal acceptance, persisted so version changes can re-prompt. */
+export interface LegalAcceptanceRecord {
+    version: string;
+    documentsHash: string;
+    /** UTC ISO-8601 timestamp (`Date#toISOString`). */
+    acceptedAt: string;
+    eligibilityBasis: EligibilityBasis;
+}
 export interface PersistedOnboardingState {
     version: 1;
     currentStep: number;
     completed: string[];
     skipped: boolean;
+    /** Legacy boolean, still written for older readers. Prefer `legalAcceptance`. */
     legalAccepted: boolean;
-    eligibilityBasis?: "individual" | "enterprise";
+    /** Legacy mirror of `legalAcceptance.eligibilityBasis`. */
+    eligibilityBasis?: EligibilityBasis;
+    legalAcceptance?: LegalAcceptanceRecord;
 }
 export interface OnboardingStepContext {
     state: PersistedOnboardingState;
@@ -71,6 +84,10 @@ export interface OnboardingStepContext {
     permissions?: PermissionsBackend;
     models?: ModelsBackend;
     license?: LicenseBackend;
+    /** 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;
 }
 export interface OnboardingStep {
     id: string;
@@ -78,6 +95,10 @@ export interface OnboardingStep {
     title: string;
     description?: string;
     skippable?: boolean;
+    /** Continue/Finish stay disabled until this returns true. Default: always allowed. */
+    canContinue?: (context: OnboardingStepContext) => boolean;
+    /** Shown beside the disabled Continue/Finish button. */
+    blockedHint?: string;
     render: (context: OnboardingStepContext) => ReactNode;
 }
 export interface LegalStepConfig extends Omit<LegalGateProps, "variant" | "onAgree" | "onQuit"> {
@@ -94,5 +115,25 @@ export interface OnboardingProps {
     onComplete: () => void | Promise<void>;
     onSkip?: () => void | Promise<void>;
     className?: string;
+    /** Version the user must have accepted. A different (or missing) stored version re-prompts with `variant: "re-acceptance"`. */
+    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. */
+    documentsHash?: string;
+    /** Runs (and is awaited) before the legal gate is shown, e.g. to resize or reveal the window. */
+    beforeLegalGate?: () => void | Promise<void>;
+    /** Require at least one downloaded model before Continue/Finish on the models step. Default false. */
+    requireModel?: boolean;
+    /** Start downloading the first missing model when the models step opens. Default false. */
+    autoStartDownload?: boolean;
+    /** App copy shown at the top of the models step. */
+    modelsIntro?: ReactNode;
+    /** Show "Set up later". Default true. */
+    allowSkip?: boolean;
+    /** Optional titlebar content rendered in a strip along the top. */
+    titlebar?: ReactNode;
+    /** Render a `data-tauri-drag-region` strip at the top. Default false. */
+    dragRegion?: boolean;
 }
 export type { LegalGateDocument, LegalGateTheme };

package/onboarding.css

@@ -1,37 +1,41 @@
 /* @rightkit/onboarding — uses app-shell tokens and legal-ui's locked light gate. */
-.rk-onboarding { min-height: 100vh; display: grid; grid-template-columns: 220px minmax(0, 1fr); background: var(--plane, #fffcf5); color: var(--ink, #231f1a); font: 13px/1.45 -apple-system, BlinkMacSystemFont, "Segoe UI", system-ui, sans-serif; }
+.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 *, .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(--chrome, #eee9df); border-right: .5px solid var(--hairline, rgba(35,31,26,.11)); }
+.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; }
 .rk-onboarding__rail nav { display: grid; gap: 3px; }
-.rk-onboarding__step { display: flex; align-items: center; gap: 10px; width: 100%; padding: 9px 10px; border: 0; border-radius: 8px; background: transparent; color: var(--ink-2, #6b655c); font: inherit; text-align: left; cursor: pointer; }
-.rk-onboarding__step span { display: grid; place-items: center; width: 20px; height: 20px; border: 1px solid var(--line-strong, rgba(35,31,26,.18)); border-radius: 50%; font-size: 11px; }
-.rk-onboarding__step:hover { background: var(--fill, rgba(35,31,26,.05)); color: var(--ink); }
-.rk-onboarding__step.is-active { background: var(--sel, rgba(35,31,26,.06)); color: var(--ink); font-weight: 600; }
-.rk-onboarding__step.is-done span { border-color: var(--ok, #1e7f3c); color: var(--ok, #1e7f3c); }
+.rk-onboarding__step { display: flex; align-items: center; gap: 10px; width: 100%; padding: 9px 10px; border: 0; border-radius: 8px; background: transparent; color: var(--rk-ink-2, #6b655c); font: inherit; text-align: left; cursor: pointer; }
+.rk-onboarding__step span { display: grid; place-items: center; width: 20px; height: 20px; border: 1px solid var(--rk-line-strong, rgba(35,31,26,.18)); border-radius: 50%; font-size: 11px; }
+.rk-onboarding__step:hover { background: var(--rk-fill, rgba(35,31,26,.05)); color: var(--rk-ink); }
+.rk-onboarding__step.is-active { background: var(--rk-sel, rgba(35,31,26,.06)); color: var(--rk-ink); font-weight: 600; }
+.rk-onboarding__step.is-done span { border-color: var(--rk-ok, #1e7f3c); color: var(--rk-ok, #1e7f3c); }
 .rk-onboarding__main { display: flex; flex-direction: column; min-width: 0; max-width: 840px; width: 100%; padding: 64px clamp(24px, 7vw, 88px) 32px; }
 .rk-onboarding__main header { max-width: 620px; }
-.rk-onboarding__eyebrow { margin: 0 0 8px; color: var(--accent, #7040c4); font-size: 12px; font-weight: 650; letter-spacing: .08em; text-transform: uppercase; }
+.rk-onboarding__eyebrow { margin: 0 0 8px; color: var(--rk-accent, #7040c4); font-size: 12px; font-weight: 650; letter-spacing: .08em; text-transform: uppercase; }
 .rk-onboarding__main h1 { margin: 0; font-size: clamp(24px, 4vw, 34px); line-height: 1.1; letter-spacing: -.025em; }
-.rk-onboarding__description { margin: 10px 0 0; color: var(--ink-2, #6b655c); font-size: 15px; max-width: 58ch; }
+.rk-onboarding__description { margin: 10px 0 0; color: var(--rk-ink-2, #6b655c); font-size: 15px; max-width: 58ch; }
 .rk-onboarding__content { flex: 1; padding: 30px 0; }
 .rk-onboarding__card { display: grid; gap: 2px; max-width: 680px; padding: 6px 0; }
-.rk-onboarding__card > p { color: var(--ink-2, #6b655c); }
-.rk-onboarding__row { display: flex; align-items: center; justify-content: space-between; gap: 20px; padding: 16px 0; border-bottom: .5px solid var(--hairline, rgba(35,31,26,.11)); }
+.rk-onboarding__card > p { color: var(--rk-ink-2, #6b655c); }
+.rk-onboarding__row { display: flex; align-items: center; justify-content: space-between; gap: 20px; padding: 16px 0; border-bottom: .5px solid var(--rk-hairline, rgba(35,31,26,.11)); }
 .rk-onboarding__row:last-child { border-bottom: 0; }
-.rk-onboarding__row p { margin: 3px 0 0; color: var(--ink-2, #6b655c); font-size: 12.5px; }
+.rk-onboarding__row p { margin: 3px 0 0; color: var(--rk-ink-2, #6b655c); font-size: 12.5px; }
 .rk-onboarding__row-actions { display: flex; align-items: center; justify-content: flex-end; gap: 8px; flex-wrap: wrap; flex: none; }
 .rk-onboarding__grow { min-width: 0; flex: 1; }
-.rk-onboarding__muted { color: var(--ink-2, #6b655c); }
-.rk-onboarding__error { color: var(--bad, #c4001a); }
-.rk-onboarding__state { color: var(--ink-2, #6b655c); text-transform: capitalize; }
-.rk-onboarding__progress { height: 6px; margin-top: 8px; border-radius: 99px; background: var(--fill-3, rgba(35,31,26,.13)); overflow: hidden; }
-.rk-onboarding__progress i { display: block; height: 100%; background: var(--accent, #7040c4); }
+.rk-onboarding__muted { color: var(--rk-ink-2, #6b655c); }
+.rk-onboarding__error { color: var(--rk-bad, #c4001a); }
+.rk-onboarding__state { color: var(--rk-ink-2, #6b655c); text-transform: capitalize; }
+.rk-onboarding__progress { height: 6px; margin-top: 8px; border-radius: 99px; background: var(--rk-fill-3, rgba(35,31,26,.13)); overflow: hidden; }
+.rk-onboarding__progress i { display: block; height: 100%; background: var(--rk-accent, #7040c4); }
 .rk-onboarding__license-state { display: flex; align-items: center; gap: 10px; margin: 8px 0 18px; }
-.rk-onboarding__license-state small { color: var(--ink-2, #6b655c); }
+.rk-onboarding__license-state small { color: var(--rk-ink-2, #6b655c); }
 .rk-onboarding__form { display: flex; gap: 8px; margin-bottom: 14px; }
 .rk-onboarding__form .rk-input { flex: 1; }
-.rk-onboarding footer { display: flex; align-items: center; gap: 8px; padding-top: 16px; border-top: .5px solid var(--hairline, rgba(35,31,26,.11)); }
+.rk-onboarding footer { display: flex; align-items: center; gap: 8px; padding-top: 16px; border-top: .5px solid var(--rk-hairline, rgba(35,31,26,.11)); }
 .rk-onboarding footer span { flex: 1; }
 .rk-onboarding--legal { display: block; }
-@media (max-width: 640px) { .rk-onboarding { grid-template-columns: 1fr; } .rk-onboarding__rail { padding: 18px 12px; border-right: 0; border-bottom: .5px solid var(--hairline, rgba(35,31,26,.11)); } .rk-onboarding__rail nav { grid-template-columns: repeat(2, minmax(0, 1fr)); } .rk-onboarding__main { padding: 34px 20px 24px; } .rk-onboarding__row { align-items: flex-start; flex-direction: column; gap: 10px; } .rk-onboarding__row-actions { justify-content: flex-start; } }
+@media (max-width: 640px) { .rk-onboarding { grid-template-columns: 1fr; } .rk-onboarding__rail { padding: 18px 12px; border-right: 0; border-bottom: .5px solid var(--rk-hairline, rgba(35,31,26,.11)); } .rk-onboarding__rail nav { grid-template-columns: repeat(2, minmax(0, 1fr)); } .rk-onboarding__main { padding: 34px 20px 24px; } .rk-onboarding__row { align-items: flex-start; flex-direction: column; gap: 10px; } .rk-onboarding__row-actions { justify-content: flex-start; } }
+/* Optional window chrome strip (titlebar slot / data-tauri-drag-region). Height is app-tunable. */
+.rk-onboarding__titlebar { position: absolute; inset: 0 0 auto 0; z-index: 2; display: flex; align-items: center; height: var(--rk-onboarding-titlebar-h, 32px); padding: 0 12px; }
+.rk-onboarding__hint { color: var(--rk-ink-2, #6b655c); font-size: 12px; text-align: right; }
+.rk-onboarding__intro { margin-bottom: 12px; color: var(--rk-ink-2, #6b655c); }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rightkit/onboarding",
-  "version": "0.1.0",
+  "version": "0.2.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,15 +24,19 @@
     "*.css"
   ],
   "peerDependencies": {
-    "@rightkit/app-shell": ">=0.1.0 <1",
-    "@rightkit/legal-ui": ">=0.1.0",
+    "@rightkit/app-shell": ">=0.2.0 <1",
+    "@rightkit/legal-ui": ">=0.1.2 <1",
     "react": ">=18 <20"
   },
   "devDependencies": {
-    "@rightkit/app-shell": "0.1.0",
-    "@rightkit/legal-ui": "0.1.1",
+    "@rightkit/app-shell": "0.2.0",
+    "@rightkit/legal-ui": "0.1.2",
+    "@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",