@rightkit/onboarding 0.0.0-stage → 0.1.0

package/LICENSE-APACHE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/LICENSE-MIT

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Adrian D'souza
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,15 @@
-# Temporary Holding Version
+# @rightkit/onboarding
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+First-run onboarding framework for Right Suite apps: a legal agreement gate first, then ordered steps (permissions, model download, licence/trial, plus app-defined steps) with progress, skip and resume.
+
+```tsx
+import { Onboarding } from "@rightkit/onboarding";
+import "@rightkit/onboarding/onboarding.css";
+
+<Onboarding settings={settings} legal={legal} permissions={permissions} models={models} license={license}
+  onComplete={finish} onSkip={later} />
+```
+
+- `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.
+- `onComplete` and `onSkip` run only after the state was saved. A rejected save is shown in an alert and neither callback runs.

package/dist/Onboarding.d.ts

@@ -0,0 +1,3 @@
+import type { OnboardingProps } from "./types.js";
+export declare function onboardingStateKey(): string;
+export declare function Onboarding({ settings, legal, steps, permissions, models, license, onComplete, onSkip, className }: OnboardingProps): import("react").JSX.Element;

package/dist/Onboarding.js

@@ -0,0 +1,98 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useCallback, useEffect, useMemo, 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 readState(value) {
+    if (!value || typeof value !== "object")
+        return INITIAL;
+    const candidate = value;
+    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,
+    };
+}
+export function onboardingStateKey() { return KEY; }
+export function Onboarding({ settings, legal, steps = [], permissions, models, license, onComplete, onSkip, className }) {
+    const [state, setState] = useState(null);
+    const [saving, setSaving] = useState(false);
+    const [error, setError] = useState(null);
+    /** 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 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]);
+    const builtins = useMemo(() => [
+        { id: "legal", label: "Agreement", title: "Review agreement", skippable: false, render: () => null },
+        ...(permissions ? [permissionsStep(permissions)] : []),
+        ...(models ? [modelsStep(models)] : []),
+        ...(license ? [licenseStep(license)] : []),
+        ...steps,
+    ], [license, models, permissions, steps]);
+    const activeState = state ?? INITIAL;
+    // 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;
+    const active = builtins[index];
+    const context = { state: activeState, settings, setState: saveStep, permissions, models, license };
+    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 (!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(); } }) });
+    }
+    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" })] })] })] });
+}

package/dist/index.d.ts

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

package/dist/index.js

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

package/dist/steps.d.ts

@@ -0,0 +1,16 @@
+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?: {
+    label?: string;
+    title?: string;
+    description?: string;
+}): OnboardingStep;
+export declare function licenseStep(backend: LicenseBackend, options?: {
+    label?: string;
+    title?: string;
+    description?: string;
+}): OnboardingStep;

package/dist/steps.js

@@ -0,0 +1,71 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useCallback, useEffect, 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 }) {
+    const [models, setModels] = useState([]);
+    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]);
+    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?.();
+    }, [backend, reload]);
+    const action = (model) => {
+        setBusy(model.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) => {
+                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);
+            }), 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 }) };
+}
+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,98 @@
+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>;
+    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 interface PersistedOnboardingState {
+    version: 1;
+    currentStep: number;
+    completed: string[];
+    skipped: boolean;
+    legalAccepted: boolean;
+    eligibilityBasis?: "individual" | "enterprise";
+}
+export interface OnboardingStepContext {
+    state: PersistedOnboardingState;
+    settings: SettingsBackend;
+    setState: (next: Partial<PersistedOnboardingState>) => Promise<void>;
+    permissions?: PermissionsBackend;
+    models?: ModelsBackend;
+    license?: LicenseBackend;
+}
+export interface OnboardingStep {
+    id: string;
+    label: string;
+    title: string;
+    description?: string;
+    skippable?: boolean;
+    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;
+}
+export type { LegalGateDocument, LegalGateTheme };

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/onboarding.css

@@ -0,0 +1,37 @@
+/* @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 *, .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__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__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__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__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__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-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__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__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 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; } }

package/package.json

@@ -1,6 +1,57 @@
 {
   "name": "@rightkit/onboarding",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.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",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./onboarding.css": "./onboarding.css"
+  },
+  "files": [
+    "dist",
+    "onboarding.css",
+    "README.md",
+    "LICENSE-MIT",
+    "LICENSE-APACHE"
+  ],
+  "sideEffects": [
+    "*.css"
+  ],
+  "peerDependencies": {
+    "@rightkit/app-shell": ">=0.1.0 <1",
+    "@rightkit/legal-ui": ">=0.1.0",
+    "react": ">=18 <20"
+  },
+  "devDependencies": {
+    "@rightkit/app-shell": "0.1.0",
+    "@rightkit/legal-ui": "0.1.1",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "typescript": "^5.7.0",
+    "vite": "^6.0.0",
+    "vitest": "^2.1.8"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bogusyogi/claude.git",
+    "directory": "tools/rightkit/packages/onboarding"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "pretest": "pnpm --filter \"@rightkit/onboarding^...\" run build",
+    "test": "vitest run"
+  }
 }