@rightkit/onboarding 0.3.1 → 0.3.2

package/dist/Onboarding.d.ts

@@ -0,0 +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 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;

package/dist/Onboarding.js

@@ -0,0 +1,221 @@
+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 { 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 || legalAcceptance !== undefined,
+        eligibilityBasis: legalAcceptance?.eligibilityBasis ?? (candidate.eligibilityBasis === "individual" || candidate.eligibilityBasis === "enterprise" ? candidate.eligibilityBasis : undefined),
+        ...(legalAcceptance ? { legalAcceptance } : {}),
+    };
+}
+/** Replace the acceptance in `state` with the one from the app's receipt (`undefined`: not accepted). */
+function withReceipt(state, record) {
+    const { legalAcceptance: _drop, eligibilityBasis: _basis, ...rest } = state;
+    void _drop;
+    void _basis;
+    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) {
+    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; }
+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, shouldAutoStart, onModelsStepEnter, modelsIntro, allowSkip = true, titlebar, dragRegion, legalDragRegion = false, legalReceipt }) {
+    const [state, setState] = useState(null);
+    const [saving, setSaving] = useState(false);
+    const [error, setError] = useState(null);
+    const [readyMap, setReadyMap] = useState({});
+    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);
+    /** Persists a patch; throws when the settings backend rejects it. */
+    const persist = useCallback(async (patch) => {
+        setSaving(true);
+        setError(null);
+        const next = { ...(state ?? INITIAL), ...patch };
+        try {
+            const snap = await settings.patch({ [KEY]: next });
+            setState(readState(snap.values[KEY]));
+        }
+        catch (e) {
+            setError(e instanceof Error ? e.message : String(e));
+            throw e;
+        }
+        finally {
+            setSaving(false);
+        }
+    }, [settings, state]);
+    /** Like `persist` but reports success as a boolean; the failure is already visible via `error`. */
+    const save = useCallback(async (patch) => {
+        try {
+            await persist(patch);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }, [persist]);
+    const saveStep = useCallback(async (patch) => { await save(patch); }, [save]);
+    useEffect(() => {
+        let live = true;
+        void (async () => {
+            try {
+                const loaded = readState((await settings.load()).values[KEY]);
+                if (!legalReceipt) {
+                    if (live)
+                        setState(loaded);
+                    return;
+                }
+                // The app's receipt is the source of truth for acceptance; an unreadable receipt counts as none.
+                let record;
+                try {
+                    record = readAcceptance(await legalReceipt.read());
+                }
+                catch {
+                    record = undefined;
+                }
+                if (live)
+                    setState(withReceipt(loaded, record));
+            }
+            catch (e) {
+                if (live)
+                    setError(e instanceof Error ? e.message : String(e));
+            }
+        })();
+        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." }) },
+        ...(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]);
+    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.
+    // 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 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?.();
+        }
+        catch (e) {
+            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;
+        if (nextIndex >= builtins.length) {
+            if (await save({ completed, currentStep: Math.max(0, builtins.length - 1), skipped: false }))
+                await runCallback(onComplete);
+            return;
+        }
+        await save({ completed, currentStep: nextIndex, skipped: false });
+    };
+    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 _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" })] });
+        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 };
+                        if (legalReceipt) {
+                            try {
+                                await legalReceipt.write(legalAcceptance);
+                            }
+                            catch (e) {
+                                setError(e instanceof Error ? e.message : String(e));
+                                throw e;
+                            }
+                        }
+                        const progress = reacceptance ? {} : { completed: ["legal"], currentStep: builtins.length > 1 ? 1 : 0 };
+                        await persist({ legalAccepted: true, eligibilityBasis, legalAcceptance, ...progress });
+                        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: [_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

@@ -0,0 +1,4 @@
+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

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

package/dist/steps.d.ts

@@ -0,0 +1,28 @@
+import { type ReactNode } from "react";
+import type { LicenseBackend, ModelsAutoStart, ModelsBackend, OnboardingStep, PermissionsBackend } from "./types.js";
+export declare function permissionsStep(backend: PermissionsBackend, options?: {
+    label?: string;
+    title?: string;
+    description?: string;
+}): OnboardingStep;
+export interface ModelsStepOptions extends ModelsAutoStart {
+    label?: string;
+    title?: string;
+    description?: string;
+    /** 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;
+    /** Shared "already auto-started" flag. `Onboarding` supplies one that survives Back/Next and re-renders; omit it and the guard lives for the step's mount only. */
+    startGuard?: {
+        current: boolean;
+    };
+}
+export declare function modelsStep(backend: ModelsBackend, options?: ModelsStepOptions): OnboardingStep;
+export declare function licenseStep(backend: LicenseBackend, options?: {
+    label?: string;
+    title?: string;
+    description?: string;
+}): OnboardingStep;

package/dist/steps.js

@@ -0,0 +1,115 @@
+import { 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";
+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}%` } }) });
+}
+const formatBytes = (n) => {
+    if (n === undefined)
+        return "";
+    const units = ["B", "KB", "MB", "GB", "TB"];
+    let value = n;
+    let unit = 0;
+    while (value >= 1000 && unit < units.length - 1) {
+        value /= 1000;
+        unit += 1;
+    }
+    return `${value >= 100 || unit === 0 ? Math.round(value) : value.toFixed(1)} ${units[unit]}`;
+};
+const permissionTone = (state) => state === "ready" ? "ok" : state === "denied" || state === "restricted" ? "bad" : state === "needed" ? "warn" : "neutral";
+function PermissionsBody({ backend }) {
+    const [items, setItems] = useState([]);
+    const [busy, setBusy] = useState(null);
+    const [error, setError] = useState(null);
+    const reload = useCallback(() => backend.list().then(setItems, (e) => setError(e instanceof Error ? e.message : String(e))), [backend]);
+    useEffect(() => void reload(), [reload]);
+    return (_jsxs("div", { className: "rk-onboarding__card", "data-testid": "onboarding-permissions", children: [error ? _jsx("p", { className: "rk-onboarding__error", role: "alert", children: error }) : null, items.length === 0 && !error ? _jsx("p", { className: "rk-onboarding__muted", children: "Checking permissions\u2026" }) : null, items.map((item) => (_jsxs("div", { className: "rk-onboarding__row", "data-permission-id": item.id, children: [_jsxs("div", { children: [_jsx("strong", { children: item.label }), _jsx("p", { children: item.description ?? item.detail })] }), _jsxs("div", { className: "rk-onboarding__row-actions", children: [_jsx(Badge, { tone: permissionTone(item.state), children: item.state }), item.state === "needed" || item.state === "denied" ? (_jsx(Button, { size: "sm", variant: "secondary", disabled: busy === item.id, onClick: () => { setBusy(item.id); setError(null); void backend.request(item.id).then((next) => setItems((current) => current.map((x) => x.id === next.id ? next : x)), (e) => setError(e instanceof Error ? e.message : String(e))).finally(() => setBusy(null)); }, children: item.state === "denied" ? "Try again" : "Allow" })) : null] })] }, item.id)))] }));
+}
+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, onReady, autoStartDownload, shouldAutoStart, onModelsStepEnter, intro, startGuard }) {
+    const [models, setModels] = useState([]);
+    const [loaded, setLoaded] = useState(false);
+    const [busy, setBusy] = useState(null);
+    const [error, setError] = useState(null);
+    const ownGuard = useRef(false);
+    const autoStarted = startGuard ?? ownGuard;
+    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;
+        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 hasInstalled = models.some((m) => m.state === "installed");
+    useEffect(() => { onReady?.(hasInstalled); }, [hasInstalled, onReady]);
+    const run = (id, request) => {
+        setBusy(id);
+        setError(null);
+        void request.then(reload, (e) => setError(e instanceof Error ? e.message : String(e))).finally(() => setBusy(null));
+    };
+    useEffect(() => {
+        if (!loaded || autoStarted.current)
+            return;
+        if (!onModelsStepEnter && !shouldAutoStart && !autoStartDownload)
+            return;
+        autoStarted.current = true;
+        if (onModelsStepEnter) {
+            // The app owns which model starts and when; the hook runs once per Onboarding mount.
+            const ctx = { models, start: (id) => backend.install(id).then(reload), refresh: () => backend.list().then((list) => { setModels(list); return list; }) };
+            void Promise.resolve().then(() => onModelsStepEnter(ctx)).catch((e) => setError(e instanceof Error ? e.message : String(e)));
+            return;
+        }
+        if (shouldAutoStart) {
+            const pick = models.find((m) => m.state === "missing" && shouldAutoStart(m, models));
+            if (pick)
+                run(pick.id, backend.install(pick.id));
+            return;
+        }
+        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, shouldAutoStart, onModelsStepEnter, loaded, models, backend]);
+    return (_jsxs("div", { className: "rk-onboarding__card", "data-testid": "onboarding-models", children: [intro ? _jsx("div", { className: "rk-onboarding__intro", "data-testid": "onboarding-models-intro", children: intro }) : null, error ? _jsx("p", { className: "rk-onboarding__error", role: "alert", children: error }) : null, models.map((model) => {
+                const progress = model.progress ?? (model.state === "installed" ? 1 : 0);
+                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,
+        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, shouldAutoStart: options.shouldAutoStart, onModelsStepEnter: options.onModelsStepEnter, intro: options.intro, startGuard: options.startGuard }),
+    };
+}
+function LicenseBody({ backend }) {
+    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] })] });
+}
+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 }) };
+}

package/dist/types.d.ts

@@ -0,0 +1,172 @@
+import type { ReactNode } from "react";
+import type { LegalGateDocument, LegalGateProps, LegalGateTheme } from "@rightkit/legal-ui";
+export type SettingsValues = Record<string, unknown>;
+export interface SettingsSnapshot {
+    values: SettingsValues;
+    revision: number;
+}
+/** Structural port shared with @rightkit/settings-ui and rightkit-settings. */
+export interface SettingsBackend {
+    load(): Promise<SettingsSnapshot>;
+    patch(patch: SettingsValues, expectedRevision?: number): Promise<SettingsSnapshot>;
+    subscribe?(handler: (keys: string[]) => void): Promise<() => void>;
+}
+export type PermissionState = "ready" | "needed" | "waiting" | "denied" | "restricted";
+export interface PermissionStatus {
+    id: string;
+    label: string;
+    description?: string;
+    state: PermissionState;
+    detail?: string;
+}
+export interface PermissionsBackend {
+    list(): Promise<PermissionStatus[]>;
+    request(id: string): Promise<PermissionStatus>;
+}
+export type ModelState = "missing" | "installed" | "downloading" | "verifying" | "error";
+export interface ModelEntry {
+    id: string;
+    label: string;
+    description?: string;
+    sizeBytes?: number;
+    state: ModelState;
+    progress?: number;
+    error?: {
+        code: string;
+        message: string;
+    };
+}
+export interface ModelsBackend {
+    list(): Promise<ModelEntry[]>;
+    install(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 {
+    status: "none" | "trial" | "active" | "expired" | "invalid";
+    label?: string;
+    detail?: string;
+    tier?: string;
+    validUntil?: string | null;
+}
+export interface LicenseBackend {
+    load(): Promise<LicenseState>;
+    activate?(key: string): Promise<LicenseState>;
+    startTrial?(): Promise<LicenseState>;
+    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;
+}
+/**
+ * App-owned persistence for the legal acceptance. Lets an app keep its existing receipt (any shape, any store) and map it
+ * to and from the package's record. When supplied it is the source of truth: `read()` is consulted on load and overrides
+ * whatever acceptance the settings backend holds (`null` means "not accepted", so the gate shows), and `write()` is
+ * awaited when the user agrees, before the settings backend is patched.
+ */
+export interface LegalReceiptPort {
+    read(): LegalAcceptanceRecord | null | Promise<LegalAcceptanceRecord | null>;
+    write(record: LegalAcceptanceRecord): void | Promise<void>;
+}
+export interface PersistedOnboardingState {
+    version: 1;
+    currentStep: number;
+    completed: string[];
+    skipped: boolean;
+    /** Legacy boolean, still written for older readers. Prefer `legalAcceptance`. */
+    legalAccepted: boolean;
+    /** Legacy mirror of `legalAcceptance.eligibilityBasis`. */
+    eligibilityBasis?: EligibilityBasis;
+    legalAcceptance?: LegalAcceptanceRecord;
+}
+export interface OnboardingStepContext {
+    state: PersistedOnboardingState;
+    settings: SettingsBackend;
+    setState: (next: Partial<PersistedOnboardingState>) => Promise<void>;
+    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;
+    label: string;
+    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"> {
+    onQuit?: () => void;
+}
+export interface OnboardingProps {
+    settings: SettingsBackend;
+    legal: LegalStepConfig;
+    /** 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>;
+    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 (skipped when any model is installed or downloading). Default false. */
+    autoStartDownload?: boolean;
+    /** Choose which missing model starts when the models step first opens: the first `state === "missing"` entry for which this returns true. Replaces the `autoStartDownload` rule (no "something is installed" guard; the app decides). Fires at most once per `Onboarding` mount, across re-renders and Back/Next. */
+    shouldAutoStart?: (entry: ModelEntry, models: readonly ModelEntry[]) => boolean;
+    /** Full control: called once, when the models step first opens and the list has loaded. Replaces `shouldAutoStart` and `autoStartDownload`. Start models through `ctx.start`. Fires at most once per `Onboarding` mount; a throw is shown in the step. */
+    onModelsStepEnter?: (ctx: ModelsStepEnterContext) => void | Promise<void>;
+    /** 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 of the setup steps. Default false. Never applied to the legal stage; see `legalDragRegion`. */
+    dragRegion?: boolean;
+    /** Also render the drag region on the legal stage (loading and gate). Default false: the legal gate has no strip. */
+    legalDragRegion?: boolean;
+    /** Read and write the legal acceptance in the app's own receipt instead of (overriding) the settings backend's copy. */
+    legalReceipt?: LegalReceiptPort;
+}
+export type { LegalGateDocument, LegalGateTheme };
+/** Context handed to `onModelsStepEnter`. */
+export interface ModelsStepEnterContext {
+    /** The model list as loaded when the step opened. */
+    models: readonly ModelEntry[];
+    /** Start installing one model, then refresh the list. */
+    start(id: string): Promise<void>;
+    /** Re-read the list from the backend (and update the step). */
+    refresh(): Promise<ModelEntry[]>;
+}
+/** The auto-start options shared by `Onboarding` and `modelsStep`. */
+export interface ModelsAutoStart {
+    autoStartDownload?: boolean;
+    shouldAutoStart?: (entry: ModelEntry, models: readonly ModelEntry[]) => boolean;
+    onModelsStepEnter?: (ctx: ModelsStepEnterContext) => void | Promise<void>;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/ui.d.ts

@@ -0,0 +1 @@
+export declare const cx: (...parts: Array<string | false | null | undefined>) => string;

package/dist/ui.js

@@ -0,0 +1 @@
+export const cx = (...parts) => parts.filter(Boolean).join(" ");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rightkit/onboarding",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "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,7 +29,7 @@
     "react": ">=18 <21"
   },
   "devDependencies": {
-    "@rightkit/app-shell": "0.4.0",
+    "@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",