@rightkit/onboarding 0.2.1 → 0.2.3

package/README.md

@@ -24,6 +24,8 @@ 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. |

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, legalDragRegion, legalReceipt }: 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";
@@ -73,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, legalDragRegion = false, legalReceipt }) {
+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);
@@ -138,10 +140,10 @@ export function Onboarding({ settings, legal, steps = [], permissions, models, l
     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;

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

@@ -135,8 +135,12 @@ 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. */
@@ -151,3 +155,18 @@ export interface OnboardingProps {
     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.1",
+  "version": "0.2.3",
   "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,8 +29,9 @@
     "react": ">=18 <20"
   },
   "devDependencies": {
-    "@rightkit/app-shell": "0.2.0",
+    "@rightkit/app-shell": "0.2.1",
     "@rightkit/legal-ui": "0.1.3",
+    "@rightkit/qa": "0.2.2",
     "@testing-library/jest-dom": "^6.6.3",
     "@testing-library/react": "^16.1.0",
     "@testing-library/user-event": "^14.5.2",