@rightkit/onboarding 0.2.0 → 0.2.2

package/README.md

@@ -24,10 +24,44 @@ import "@rightkit/onboarding/onboarding.css";
 | `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. |
+| `shouldAutoStart(entry, models)` | Choose which missing model auto-starts when the models step first opens (first `missing` entry returning true). Replaces `autoStartDownload`'s rule, including its "a model is already installed" guard. Once per mount, across re-renders and Back/Next. |
+| `onModelsStepEnter(ctx)` | Full control, called once when the step opens and the list has loaded: `ctx.models`, `ctx.start(id)`, `ctx.refresh()`. Replaces `shouldAutoStart` and `autoStartDownload`; a throw is shown in the step. |
 | `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). |
+| `dragRegion` | Add `data-tauri-drag-region` to that strip on the setup steps (default `false`; height `--rk-onboarding-titlebar-h`, default 32px). Never rendered on the legal stage. |
+| `legalDragRegion` | Also render the drag region on the legal stage (default `false`; the legal gate has no strip, and `titlebar` content alone never adds the attribute). |
+| `legalReceipt` | `{ read(), write(record) }`: the app's own acceptance receipt. See below. |
+
+## App-owned legal receipt
+
+An app that already persists its own acceptance receipt passes `legalReceipt` and keeps that store as the source of truth. `read()` runs on load (sync or async) and returns a `LegalAcceptanceRecord` (`version`, `documentsHash`, `acceptedAt`, `eligibilityBasis`) or `null`. Its result replaces any acceptance in the settings backend: `null`, a throw, or an incomplete record all mean "not accepted", so the gate shows. `requiredVersion` / `isAccepted` then evaluate against the app's receipt, and a receipt for another version re-prompts with `variant: "re-acceptance"`. On agree, `write(record)` is awaited first; if it throws, the gate shows its save-failure alert and nothing else is persisted.
+
+Mapping example for ScrapeRight's four-field `scraperight.legal-acceptance.v1` receipt (`legalAcceptanceVersion`, `legalAcceptedAt`, `legalEligibilityBasis`, `legalMaterialSha256`; pass `documentsHash={LEGAL_MATERIAL_SHA256}` so the hash round-trips):
+
+```ts
+const legalReceipt: LegalReceiptPort = {
+  read() {
+    const r = loadLegalAcceptance(); // reads localStorage "scraperight.legal-acceptance.v1"
+    if (!r?.legalAcceptanceVersion || !r.legalAcceptedAt || !r.legalEligibilityBasis) return null;
+    return {
+      version: r.legalAcceptanceVersion,
+      acceptedAt: r.legalAcceptedAt,
+      eligibilityBasis: r.legalEligibilityBasis, // "individual" | "enterprise"
+      documentsHash: r.legalMaterialSha256 ?? "",
+    };
+  },
+  write(rec) {
+    saveLegalAcceptance({
+      legalAcceptanceVersion: rec.version,
+      legalAcceptedAt: rec.acceptedAt, // UTC ISO, ends in Z
+      legalEligibilityBasis: rec.eligibilityBasis,
+      legalMaterialSha256: rec.documentsHash,
+    });
+  },
+};
+<Onboarding legalReceipt={legalReceipt} requiredVersion={REQUIRED_LEGAL_ACCEPTANCE_VERSION} documentsHash={LEGAL_MATERIAL_SHA256} ... />
+```
 
 ## Custom steps and readiness
 

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): 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, modelsIntro, allowSkip, titlebar, dragRegion }: OnboardingProps): import("react").JSX.Element;
+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

@@ -1,5 +1,5 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useCallback, useEffect, useMemo, useState } from "react";
+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";
@@ -31,6 +31,13 @@ function readState(value) {
         ...(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)
@@ -66,12 +73,14 @@ function TitleStrip({ titlebar, dragRegion }) {
         return null;
     return _jsx("div", { className: "rk-onboarding__titlebar", "data-testid": "onboarding-titlebar", ...(dragRegion ? { "data-tauri-drag-region": "" } : {}), children: titlebar });
 }
-export function Onboarding({ settings, legal, steps = [], permissions, models, license, onComplete, onSkip, className, requiredVersion, isAccepted, documentsHash, beforeLegalGate, requireModel, autoStartDownload, modelsIntro, allowSkip = true, titlebar, dragRegion }) {
+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);
@@ -100,16 +109,41 @@ export function Onboarding({ settings, legal, steps = [], permissions, models, l
         }
     }, [persist]);
     const saveStep = useCallback(async (patch) => { await save(patch); }, [save]);
-    useEffect(() => { let live = true; void settings.load().then((snapshot) => { if (live)
-        setState(readState(snapshot.values[KEY])); }, (e) => { if (live)
-        setError(e instanceof Error ? e.message : String(e)); }); return () => { live = false; }; }, [settings]);
+    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, intro: modelsIntro })] : []),
+        ...(models ? [modelsStep(models, { required: requireModel, autoStartDownload, shouldAutoStart, onModelsStepEnter, intro: modelsIntro, startGuard: modelsStarted })] : []),
         ...(license ? [licenseStep(license)] : []),
         ...steps,
-    ], [license, models, permissions, steps, requireModel, autoStartDownload, modelsIntro]);
+    ], [license, models, permissions, steps, requireModel, autoStartDownload, shouldAutoStart, onModelsStepEnter, modelsIntro]);
     const activeState = state ?? INITIAL;
     const accepted = isLegalAccepted(activeState, requiredVersion, isAccepted);
     const needsGate = state !== null && !accepted;
@@ -162,10 +196,19 @@ export function Onboarding({ settings, legal, steps = [], permissions, models, l
         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: dragRegion }), _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: "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 }) => {
+        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)

package/dist/steps.d.ts

@@ -1,11 +1,11 @@
 import { type ReactNode } from "react";
-import type { LicenseBackend, ModelsBackend, OnboardingStep, PermissionsBackend } from "./types.js";
+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 {
+export interface ModelsStepOptions extends ModelsAutoStart {
     label?: string;
     title?: string;
     description?: string;
@@ -15,6 +15,10 @@ export interface ModelsStepOptions {
     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?: {

package/dist/steps.js

@@ -29,12 +29,13 @@ 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, onReady, autoStartDownload, intro }) {
+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 autoStarted = useRef(false);
+    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();
@@ -56,9 +57,23 @@ function ModelsBody({ backend, onReady, autoStartDownload, intro }) {
         void request.then(reload, (e) => setError(e instanceof Error ? e.message : String(e))).finally(() => setBusy(null));
     };
     useEffect(() => {
-        if (!autoStartDownload || !loaded || autoStarted.current)
+        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");
@@ -66,7 +81,7 @@ function ModelsBody({ backend, onReady, autoStartDownload, intro }) {
             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]);
+    }, [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";
@@ -82,7 +97,7 @@ export function modelsStep(backend, options = {}) {
         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 }),
+        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 }) {

package/dist/types.d.ts

@@ -66,6 +66,16 @@ export interface LegalAcceptanceRecord {
     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;
@@ -125,15 +135,38 @@ export interface OnboardingProps {
     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. */
+    /** 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. Default false. */
+    /** 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rightkit/onboarding",
-  "version": "0.2.0",
+  "version": "0.2.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",
@@ -30,7 +30,7 @@
   },
   "devDependencies": {
     "@rightkit/app-shell": "0.2.0",
-    "@rightkit/legal-ui": "0.1.2",
+    "@rightkit/legal-ui": "0.1.3",
     "@testing-library/jest-dom": "^6.6.3",
     "@testing-library/react": "^16.1.0",
     "@testing-library/user-event": "^14.5.2",