@rightkit/onboarding 0.6.3 → 0.6.4

package/dist/Onboarding.d.ts

@@ -1,9 +1,23 @@
-import type { LegalAcceptanceRecord, OnboardingProps, PersistedOnboardingState } from "./types.js";
+import type { LegalAcceptanceRecord, OnboardingProps, PersistedOnboardingState, SettingsBackend } from "./types.js";
 /** @internal Validates one stored or returned acceptance record; `undefined` when it is not a well-formed record. */
 export declare function readAcceptance(value: unknown): LegalAcceptanceRecord | undefined;
 /** @internal Normalises the persisted `onboarding.state` value. */
 export declare function readState(value: unknown): PersistedOnboardingState;
 /** True when the stored acceptance satisfies the host's requirement. */
 export declare function isLegalAccepted(state: PersistedOnboardingState, requiredVersion?: string, custom?: (state: PersistedOnboardingState) => boolean, requiredDocumentsHash?: string): boolean;
+/**
+ * True when the setup step `stepId` is settled in a persisted onboarding state: the step is completed or skipped, or the
+ * whole setup was set aside ("Set up later", `skipped: true`). Reads the raw persisted value, so callers need no cast.
+ * Missing or malformed input is false; it never throws. Which steps gate an app stays with the app.
+ */
+export declare function isStepSettled(state: unknown, stepId: string): boolean;
+/**
+ * Restarts the setup at its first step ("Show onboarding again"). The setup progress (completed and skipped steps, the
+ * set-aside flag) is cleared, but the legal acceptance is kept: the agreement is not asked again, and `legal` stays
+ * completed. Reads the stored value first, so the rest of the settings are untouched.
+ */
+export declare function restartOnboardingSetup({ settings }: {
+    settings: SettingsBackend;
+}): Promise<void>;
 export declare function onboardingStateKey(): string;
-export declare function Onboarding({ settings, legal, legalMode, appName, steps, permissions, models, license, signIn, receiptDocuments, onComplete, onSkip, className, layout, requiredVersion, requiredDocumentsHash, isAccepted, documentsHash, beforeLegalGate, requireModel, autoStartDownload, shouldAutoStart, onModelsStepEnter, modelsIntro, allowSkip, titlebar, dragRegion, legalDragRegion, legalReceipt, labels: labelOverrides }: OnboardingProps): import("react").JSX.Element | null;
+export declare function Onboarding({ settings, legal, legalMode, appName, steps, permissions, models, license, signIn, receiptDocuments, onComplete, onSkip, className, layout, requiredVersion, requiredDocumentsHash, isAccepted, documentsHash, beforeLegalGate, requireModel, autoStartDownload, shouldAutoStart, onModelsStepEnter, modelsIntro, allowSkip, titlebar, dragRegion, legalDragRegion, legalReceipt, labels: labelOverrides, frame, density, trafficLightInset }: OnboardingProps): import("react").JSX.Element | null;

package/dist/Onboarding.js

@@ -50,12 +50,24 @@ export function readState(value) {
         ...(Array.isArray(candidate.skippedSteps) ? { skippedSteps: candidate.skippedSteps.filter((x) => typeof x === "string") } : {}),
     };
 }
-/** Replace the acceptance in `state` with the one from the app's receipt (`undefined`: not accepted). */
-function withReceipt(state, record) {
+/**
+ * Replace the acceptance in `state` with the one from the app's receipt (`undefined`: not accepted). A `historical` record
+ * (`HistoricalLegalReceipt`) is kept as the acceptance for the re-acceptance variant but never counts as accepted: it is
+ * flagged reopened, so the gate shows again and the setup progress is left alone.
+ */
+function withReceipt(state, record, historical = false) {
     const { legalAcceptance: _drop, eligibilityBasis: _basis, ...rest } = state;
     void _drop;
     void _basis;
-    return record ? { ...rest, legalAccepted: true, eligibilityBasis: record.eligibilityBasis, legalAcceptance: record } : { ...rest, legalAccepted: false };
+    if (!record)
+        return { ...rest, legalAccepted: false };
+    if (historical)
+        return { ...rest, legalAccepted: false, legalReopened: true, eligibilityBasis: record.eligibilityBasis, legalAcceptance: record };
+    return { ...rest, legalAccepted: true, eligibilityBasis: record.eligibilityBasis, legalAcceptance: record };
+}
+/** True when a `LegalReceiptPort.read()` value is a historical receipt (`{ record, current: false }`). */
+function isHistoricalReceipt(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value) && "record" in value && value.current === false;
 }
 /** True when the stored acceptance satisfies the host's requirement. */
 export function isLegalAccepted(state, requiredVersion, custom, requiredDocumentsHash) {
@@ -78,6 +90,39 @@ export function isLegalAccepted(state, requiredVersion, custom, requiredDocument
     // `legalAccepted` flag carries no version, time or basis, so it re-prompts once (as re-acceptance).
     return state.legalAcceptance !== undefined;
 }
+/**
+ * True when the setup step `stepId` is settled in a persisted onboarding state: the step is completed or skipped, or the
+ * whole setup was set aside ("Set up later", `skipped: true`). Reads the raw persisted value, so callers need no cast.
+ * Missing or malformed input is false; it never throws. Which steps gate an app stays with the app.
+ */
+export function isStepSettled(state, stepId) {
+    try {
+        if (typeof state !== "object" || state === null || typeof stepId !== "string")
+            return false;
+        const candidate = state;
+        if (candidate.skipped === true)
+            return true;
+        const completed = Array.isArray(candidate.completed) && candidate.completed.includes(stepId);
+        const skipped = Array.isArray(candidate.skippedSteps) && candidate.skippedSteps.includes(stepId);
+        return completed || skipped;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Restarts the setup at its first step ("Show onboarding again"). The setup progress (completed and skipped steps, the
+ * set-aside flag) is cleared, but the legal acceptance is kept: the agreement is not asked again, and `legal` stays
+ * completed. Reads the stored value first, so the rest of the settings are untouched.
+ */
+export async function restartOnboardingSetup({ settings }) {
+    const key = onboardingStateKey();
+    const snapshot = await settings.load();
+    const state = readState(snapshot.values[key]);
+    await settings.patch({
+        [key]: { ...state, currentStep: 0, skipped: false, skippedSteps: [], completed: state.completed.filter((id) => id === "legal") },
+    }, snapshot.revision);
+}
 /** FNV-1a fallback when SubtleCrypto is unavailable. */
 function fnv(text) {
     let h = 0x811c9dc5;
@@ -110,7 +155,7 @@ function NoticeList({ documents }) {
         return _jsx("p", { className: "rk-onboarding__muted", children: "No notices to show." });
     return _jsx("ul", { className: "rk-onboarding__notices", children: documents.map((d) => _jsx("li", { children: d.onOpen ? _jsx("button", { type: "button", onClick: d.onOpen, children: d.title }) : d.url ? _jsx("a", { href: d.url, target: "_blank", rel: "noreferrer", children: d.title }) : d.title }, d.title)) });
 }
-export function Onboarding({ settings, legal, legalMode = "gate", appName, steps = [], permissions, models, license, signIn, receiptDocuments, onComplete, onSkip, className, layout = "window", requiredVersion, requiredDocumentsHash, isAccepted, documentsHash, beforeLegalGate, requireModel, autoStartDownload, shouldAutoStart, onModelsStepEnter, modelsIntro, allowSkip = true, titlebar, dragRegion, legalDragRegion = false, legalReceipt, labels: labelOverrides }) {
+export function Onboarding({ settings, legal, legalMode = "gate", appName, steps = [], permissions, models, license, signIn, receiptDocuments, onComplete, onSkip, className, layout = "window", requiredVersion, requiredDocumentsHash, isAccepted, documentsHash, beforeLegalGate, requireModel, autoStartDownload, shouldAutoStart, onModelsStepEnter, modelsIntro, allowSkip = true, titlebar, dragRegion, legalDragRegion = false, legalReceipt, labels: labelOverrides, frame = "rail", density = "default", trafficLightInset = false }) {
     if (legalMode === "gate" && !legal)
         throw new Error("Onboarding: `legal` is required when legalMode is \"gate\"");
     const L = { ...DEFAULT_LABELS, ...labelOverrides };
@@ -169,14 +214,22 @@ export function Onboarding({ settings, legal, legalMode = "gate", appName, steps
                 }
                 // The app's receipt is the source of truth for acceptance; an unreadable receipt counts as none.
                 let record;
+                let historical = false;
                 try {
-                    record = readAcceptance(await legalReceipt.read());
+                    const value = await legalReceipt.read();
+                    if (isHistoricalReceipt(value)) {
+                        record = readAcceptance(value.record);
+                        historical = record !== undefined;
+                    }
+                    else
+                        record = readAcceptance(value);
                 }
                 catch {
                     record = undefined;
+                    historical = false;
                 }
                 if (live)
-                    setState(withReceipt(loaded, record));
+                    setState(withReceipt(loaded, record, historical));
             }
             catch (e) {
                 if (live)
@@ -275,7 +328,7 @@ export function Onboarding({ settings, legal, legalMode = "gate", appName, steps
         }
         await markAndMove(index + 1, { completed: active.id });
     };
-    const rootClass = cx("rk-onboarding", layout === "contained" && "rk-onboarding--contained", className);
+    const rootClass = cx("rk-onboarding", layout === "contained" && "rk-onboarding--contained", density === "compact" && "rk-onboarding--compact", trafficLightInset && "rk-onboarding--lights", frame === "card" && "rk-onboarding--card", className);
     if (error && !state)
         return _jsxs("div", { className: rootClass, children: [_jsx("p", { className: "rk-onboarding__error", role: "alert", children: error }), _jsx(Button, { onClick: () => window.location.reload(), children: "Retry" })] });
     if (state && !active)
@@ -334,6 +387,11 @@ export function Onboarding({ settings, legal, legalMode = "gate", appName, steps
                     } })] });
     }
     const body = active.render(context);
+    if (frame === "card") {
+        // The HeardRight v5 frame: one centred card, the app name on top, a dot pager and no step rail.
+        return _jsxs("main", { className: rootClass, "data-testid": "onboarding", "data-step-id": active.id, "data-frame": "card", children: [_jsx(TitleStrip, { titlebar: titlebar, dragRegion: dragRegion }), _jsxs("section", { className: "rk-onboarding__main rk-onboarding__main--card", children: [_jsx("div", { className: "rk-onboarding__brand rk-onboarding__brand--card", children: appName ?? legal?.appName }), _jsxs("div", { className: "rk-onboarding__frame", children: [active.title ? _jsx("h1", { children: active.title }) : null, 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: "secondary", disabled: index <= lead || saving || continuing, onClick: () => void save({ currentStep: index - 1 }), children: L.back }), _jsx("nav", { className: "rk-onboarding__dots", "aria-label": "Setup progress", children: builtins.map((step, i) => _jsx("button", { type: "button", className: cx("rk-onboarding__dot", i === index && "is-active", activeState.completed.includes(step.id) && "is-done"), "aria-label": `Step ${i + 1}: ${step.label}`, "aria-current": i === index ? "step" : undefined, disabled: (gated && i === 0 && builtins.length > 1) || continuing, onClick: () => { if (!continuing && i >= lead && (i <= index || canContinue))
+                                                    void save({ currentStep: i }); } }, step.id)) }), _jsx("span", { className: "rk-onboarding__hint", children: !canContinue && active.blockedHint ? active.blockedHint : null }), allowSkip ? _jsx(Button, { variant: "ghost", disabled: saving || continuing, onClick: () => { void save({ currentStep: index, skipped: true }).then((ok) => ok ? runCallback(onSkip) : undefined); }, children: L.skip }) : null, active.skippable ? _jsx(Button, { variant: "ghost", disabled: saving || continuing, onClick: () => void markAndMove(index + 1, { skipped: active.id }), children: L.skipStep }) : null, _jsx(Button, { variant: "primary", disabled: saving || continuing || !canContinue, onClick: () => void advance(), children: active.continueLabel ?? (index === builtins.length - 1 ? L.finish : L.continue) })] })] })] })] });
+    }
     return _jsxs("main", { className: rootClass, "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: appName ?? 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: (gated && i === 0 && builtins.length > 1) || continuing, onClick: () => { if (!continuing && i >= lead && (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] }), active.title ? _jsx("h1", { children: active.title }) : null, 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 || continuing, onClick: () => { void save({ currentStep: index, skipped: true }).then((ok) => ok ? runCallback(onSkip) : undefined); }, children: L.skip }) : null, active.skippable ? _jsx(Button, { variant: "ghost", disabled: saving || continuing, onClick: () => void markAndMove(index + 1, { skipped: active.id }), children: L.skipStep }) : null, _jsx("span", { className: "rk-onboarding__hint", children: !canContinue && active.blockedHint ? active.blockedHint : null }), _jsx(Button, { variant: "secondary", disabled: index <= lead || saving || continuing, onClick: () => void save({ currentStep: index - 1 }), children: L.back }), _jsx(Button, { variant: "primary", disabled: saving || continuing || !canContinue, onClick: () => void advance(), children: active.continueLabel ?? (index === builtins.length - 1 ? L.finish : L.continue) })] })] })] });
 }

package/dist/index.d.ts

@@ -1,8 +1,8 @@
-export { Onboarding, isLegalAccepted, onboardingStateKey } from "./Onboarding.js";
+export { Onboarding, isLegalAccepted, isStepSettled, onboardingStateKey, restartOnboardingSetup } from "./Onboarding.js";
 export { licenseStep, modelsStep, permissionsStep, signInStep } from "./steps.js";
 export type { LicenseStepCopy, LicenseStepOptions, ModelsStepOptions } from "./steps.js";
 export { licenseBackendFromView, licenseStateFromView, signInBackendFromOAuth } from "./adapters.js";
 export type { LicenseViewBackendOptions, LicenseViewClient, LicenseViewLike, OAuthSignInPort } from "./adapters.js";
-export { LEGAL_RECEIPT_COMMANDS, createNativeLegalReceiptPort, reopenLegalAcceptance, resetLegalAcceptance } from "./legal-receipt.js";
-export type { LegalReceiptInvoke, NativeLegalReceiptPortOptions } from "./legal-receipt.js";
+export { LEGAL_RECEIPT_COMMANDS, createNativeLegalReceiptPort, importLegacyAcceptance, reopenLegalAcceptance, resetLegalAcceptance } from "./legal-receipt.js";
+export type { LegacyAcceptanceImportOptions, LegalReceiptInvoke, NativeLegalReceiptPortOptions } from "./legal-receipt.js";
 export type * from "./types.js";

package/dist/index.js

@@ -1,4 +1,4 @@
-export { Onboarding, isLegalAccepted, onboardingStateKey } from "./Onboarding.js";
+export { Onboarding, isLegalAccepted, isStepSettled, onboardingStateKey, restartOnboardingSetup } from "./Onboarding.js";
 export { licenseStep, modelsStep, permissionsStep, signInStep } from "./steps.js";
 export { licenseBackendFromView, licenseStateFromView, signInBackendFromOAuth } from "./adapters.js";
-export { LEGAL_RECEIPT_COMMANDS, createNativeLegalReceiptPort, reopenLegalAcceptance, resetLegalAcceptance } from "./legal-receipt.js";
+export { LEGAL_RECEIPT_COMMANDS, createNativeLegalReceiptPort, importLegacyAcceptance, reopenLegalAcceptance, resetLegalAcceptance } from "./legal-receipt.js";

package/dist/legal-receipt.d.ts

@@ -1,4 +1,4 @@
-import type { LegalReceiptPort, SettingsBackend } from "./types.js";
+import type { LegalAcceptanceRecord, LegalReceiptCreateRequest, LegalReceiptPort, SettingsBackend } from "./types.js";
 /**
  * The commands of the native legal-receipt host service. The native side registers them once under the host caller policy
  * (`rightkit-tauri-shell` host services); the trusted window is the one that shows the legal gate. Names are provisional
@@ -8,6 +8,8 @@ export declare const LEGAL_RECEIPT_COMMANDS: Readonly<{
     read: "rightkit_legal_receipt_read";
     create: "rightkit_legal_receipt_create";
     reset: "rightkit_legal_receipt_reset";
+    /** Imports a renderer-held legacy acceptance once (see `importLegacyAcceptance`). */
+    import: "rightkit_legal_receipt_import";
 }>;
 /** Tauri's `invoke`, structurally (`@tauri-apps/api/core`). No import, so the package stays free of Tauri. */
 export type LegalReceiptInvoke = (command: string, args?: Record<string, unknown>) => Promise<unknown>;
@@ -18,7 +20,9 @@ export interface NativeLegalReceiptPortOptions {
 /**
  * `LegalReceiptPort` over the native legal-receipt service.
  *
- * - `read` returns the stored record, or `null` when there is none or the stored value is not a well-formed record.
+ * - `read` returns the stored record, or `null` when there is none or the stored value is not a well-formed record. A
+ *   historical receipt (a version or digest that no longer matches) comes back as `{ record, current: false }`, which keeps
+ *   the re-acceptance variant and the setup progress; the native service offers it that way.
  * - `create` sends the declaration (`version`, `documentsHash`, `documents`, `eligibilityBasis`, `surface`) and NO time. The
  *   service compares it with the manifest it embeds, stamps native UTC time, stores the receipt and returns the record; a
  *   refusal or a malformed answer throws, which keeps the gate closed.
@@ -26,6 +30,27 @@ export interface NativeLegalReceiptPortOptions {
  * There is no `write`: the renderer never supplies a stored record.
  */
 export declare function createNativeLegalReceiptPort({ invoke, commands }: NativeLegalReceiptPortOptions): LegalReceiptPort;
+export interface LegacyAcceptanceImportOptions {
+    invoke: LegalReceiptInvoke;
+    /** Key of the renderer-held legacy receipt, for example `scraperight.legal-acceptance.v1`. */
+    storageKey: string;
+    /**
+     * Maps the stored text to the declaration the native service verifies against its manifest (hashes, versions, documents).
+     * `null`: not an importable record; nothing is sent and the legacy key stays in place.
+     */
+    parse: (raw: string) => LegalReceiptCreateRequest | null;
+    /** Storage that holds the legacy key. Default `localStorage` when present. `null`: no legacy storage to read. */
+    storage?: Pick<Storage, "getItem" | "removeItem"> | null;
+    commands?: Partial<typeof LEGAL_RECEIPT_COMMANDS>;
+}
+/**
+ * One-time import of a renderer-held (legacy) acceptance into the native receipt. The legacy record is submitted once to the
+ * native `import` command, which verifies it against the manifest and stamps the import with its own clock. Only after the
+ * native service confirms the record is the legacy key removed. A refusal or a failed call throws and leaves the key in place,
+ * so the next launch retries; no acceptance is invented here. Returns the imported record, or `null` when there is nothing to
+ * import.
+ */
+export declare function importLegacyAcceptance({ invoke, storageKey, parse, storage, commands }: LegacyAcceptanceImportOptions): Promise<LegalAcceptanceRecord | null>;
 /**
  * Re-opens the agreement: the stored acceptance stops counting, so the gate shows as a re-acceptance on the next mount of
  * `Onboarding`. The old record (and the app's receipt) stays until the user agrees again; agreeing creates the new receipt and

package/dist/legal-receipt.js

@@ -8,6 +8,8 @@ export const LEGAL_RECEIPT_COMMANDS = Object.freeze({
     read: "rightkit_legal_receipt_read",
     create: "rightkit_legal_receipt_create",
     reset: "rightkit_legal_receipt_reset",
+    /** Imports a renderer-held legacy acceptance once (see `importLegacyAcceptance`). */
+    import: "rightkit_legal_receipt_import",
 });
 /** Host commands reject with `{ code, message }`; the gate and steps show `Error#message`. */
 function hostError(error) {
@@ -24,10 +26,26 @@ async function call(invoke, command, args) {
         throw hostError(error);
     }
 }
+/** The declaration the native service compares with its manifest: never a time. */
+function declaration(request) {
+    return {
+        version: request.version,
+        documentsHash: request.documentsHash,
+        documents: request.documents,
+        eligibilityBasis: request.eligibilityBasis,
+        surface: request.surface,
+    };
+}
+/** True for a historical receipt value (`{ record, current: false }`) as the native read may return it. */
+function isHistoricalValue(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value) && "record" in value && value.current === false;
+}
 /**
  * `LegalReceiptPort` over the native legal-receipt service.
  *
- * - `read` returns the stored record, or `null` when there is none or the stored value is not a well-formed record.
+ * - `read` returns the stored record, or `null` when there is none or the stored value is not a well-formed record. A
+ *   historical receipt (a version or digest that no longer matches) comes back as `{ record, current: false }`, which keeps
+ *   the re-acceptance variant and the setup progress; the native service offers it that way.
  * - `create` sends the declaration (`version`, `documentsHash`, `documents`, `eligibilityBasis`, `surface`) and NO time. The
  *   service compares it with the manifest it embeds, stamps native UTC time, stores the receipt and returns the record; a
  *   refusal or a malformed answer throws, which keeps the gate closed.
@@ -39,18 +57,16 @@ export function createNativeLegalReceiptPort({ invoke, commands }) {
     return {
         async read() {
             const value = await call(invoke, names.read);
-            return value === null || value === undefined ? null : readAcceptance(value) ?? null;
+            if (value === null || value === undefined)
+                return null;
+            if (isHistoricalValue(value)) {
+                const record = readAcceptance(value.record);
+                return record ? { record, current: false } : null;
+            }
+            return readAcceptance(value) ?? null;
         },
         async create(request) {
-            const created = readAcceptance(await call(invoke, names.create, {
-                request: {
-                    version: request.version,
-                    documentsHash: request.documentsHash,
-                    documents: request.documents,
-                    eligibilityBasis: request.eligibilityBasis,
-                    surface: request.surface,
-                },
-            }));
+            const created = readAcceptance(await call(invoke, names.create, { request: declaration(request) }));
             if (!created)
                 throw new Error("The legal receipt service returned an invalid record.");
             return created;
@@ -58,6 +74,47 @@ export function createNativeLegalReceiptPort({ invoke, commands }) {
         async reset() { await call(invoke, names.reset); },
     };
 }
+function browserStorage() {
+    try {
+        return typeof localStorage === "undefined" ? null : localStorage;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * One-time import of a renderer-held (legacy) acceptance into the native receipt. The legacy record is submitted once to the
+ * native `import` command, which verifies it against the manifest and stamps the import with its own clock. Only after the
+ * native service confirms the record is the legacy key removed. A refusal or a failed call throws and leaves the key in place,
+ * so the next launch retries; no acceptance is invented here. Returns the imported record, or `null` when there is nothing to
+ * import.
+ */
+export async function importLegacyAcceptance({ invoke, storageKey, parse, storage, commands }) {
+    const names = { ...LEGAL_RECEIPT_COMMANDS, ...commands };
+    const backing = storage === undefined ? browserStorage() : storage;
+    let raw;
+    try {
+        raw = backing?.getItem(storageKey) ?? null;
+    }
+    catch {
+        raw = null;
+    }
+    if (raw === null)
+        return null;
+    const request = parse(raw);
+    if (!request)
+        return null;
+    const imported = readAcceptance(await call(invoke, names.import, { request: declaration(request) }));
+    if (!imported)
+        throw new Error("The legal receipt service returned an invalid record.");
+    try {
+        backing?.removeItem(storageKey);
+    }
+    catch {
+        /* the native receipt is stored; the native import is idempotent, so a later run only repeats the confirmation */
+    }
+    return imported;
+}
 /**
  * Re-opens the agreement: the stored acceptance stops counting, so the gate shows as a re-acceptance on the next mount of
  * `Onboarding`. The old record (and the app's receipt) stays until the user agrees again; agreeing creates the new receipt and

package/dist/types.d.ts

@@ -130,8 +130,17 @@ export interface LegalReceiptCreateRequest {
  * `reset()` clears the stored receipt (used by `resetLegalAcceptance`). A port needs `create` or `write`; with neither,
  * agreeing fails and the gate stays closed.
  */
+/**
+ * A receipt that exists but no longer counts: its version or documents differ from the current agreement. `read()` may
+ * return it so the gate shows as a re-acceptance and the setup progress is kept (`current: false`). Any other return
+ * value is a current record or `null`.
+ */
+export interface HistoricalLegalReceipt {
+    record: LegalAcceptanceRecord;
+    current: false;
+}
 export interface LegalReceiptPort {
-    read(): LegalAcceptanceRecord | null | Promise<LegalAcceptanceRecord | null>;
+    read(): LegalAcceptanceRecord | HistoricalLegalReceipt | null | Promise<LegalAcceptanceRecord | HistoricalLegalReceipt | null>;
     /** Native receipt creation: returns the stored record, stamped with native time. Preferred over `write`. */
     create?(request: LegalReceiptCreateRequest): LegalAcceptanceRecord | Promise<LegalAcceptanceRecord>;
     /** @deprecated Renderer-built record with webview time. Implement `create` on a native receipt service instead. */
@@ -226,6 +235,19 @@ export type LegalMode = "gate" | "notice" | "none";
 export interface OnboardingProps {
     /** Window-sized by default; use `contained` when the host sizes the setup surface. */
     layout?: "window" | "contained";
+    /**
+     * Setup chrome. `rail` (default): a left step rail with a "Step n of N" eyebrow. `card`: one centred card with the app
+     * name on top and a dot pager, no rail (the HeardRight v5 onboarding mock). Applies to the setup steps only; the legal
+     * gate keeps its own layout.
+     */
+    frame?: "rail" | "card";
+    /** Vertical density of the setup steps. `compact` (rail frame): main padding 18px top, content 8px, rail 188px wide. Default `default`. */
+    density?: "default" | "compact";
+    /**
+     * Clears the macOS traffic lights: the rail (or card brand row) and the titlebar strip start past them. Use with a
+     * `titlebar` or `dragRegion` on macOS windows with overlay title bars. Default false.
+     */
+    trafficLightInset?: boolean;
     settings: SettingsBackend;
     /** Required when `legalMode` is `gate` (default). Optional for `notice` (the documents shown) and `none`. */
     legal?: LegalStepConfig;
@@ -277,7 +299,7 @@ export interface OnboardingProps {
     modelsIntro?: ReactNode;
     /** Show "Set up later". Default true. */
     allowSkip?: boolean;
-    /** Optional titlebar content rendered in a strip along the top. */
+    /** Optional titlebar content rendered in a strip along the top. On macOS with `trafficLightInset`, the strip starts past the lights. */
     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;

package/onboarding.css

@@ -40,3 +40,23 @@
 .rk-onboarding__titlebar { position: absolute; inset: 0 0 auto 0; z-index: 2; display: flex; align-items: center; height: var(--rk-onboarding-titlebar-h, 32px); padding: 0 12px; }
 .rk-onboarding__hint { color: var(--rk-ink-2, #6b655c); font-size: 12px; text-align: right; }
 .rk-onboarding__intro { margin-bottom: 12px; color: var(--rk-ink-2, #6b655c); }
+/* Density (HeardRight: onboarding too tall). compact: rail 188px, main 18px top, content 8px. */
+.rk-onboarding--compact { grid-template-columns: 188px minmax(0, 1fr); }
+.rk-onboarding--compact .rk-onboarding__main { padding-top: 18px; }
+.rk-onboarding--compact .rk-onboarding__content { padding: 8px 0; }
+/* macOS traffic lights: the rail and the titlebar strip start past them (lights-top: rail top; lights width from shell.css). */
+.rk-onboarding--lights .rk-onboarding__rail { padding-top: var(--rk-onboarding-lights-top, 40px); }
+.rk-onboarding--lights .rk-onboarding__titlebar { padding-left: calc(var(--rk-lights-width, 72px) + 6px); }
+.rk-onboarding--lights .rk-onboarding__brand--card { padding-left: calc(var(--rk-lights-width, 72px) + 6px); }
+/* card frame (HeardRight v5 mock): one centred card, the app name on top, a dot pager and no rail. */
+.rk-onboarding--card { display: flex; flex-direction: column; align-items: stretch; }
+.rk-onboarding--card .rk-onboarding__main--card { flex: 1; display: flex; flex-direction: column; align-items: center; max-width: none; width: 100%; padding: 0 clamp(24px, 5vw, 56px) 24px; }
+.rk-onboarding__brand--card { align-self: stretch; padding: 18px 20px; font-size: 18px; font-weight: 900; letter-spacing: -.03em; }
+.rk-onboarding__frame { display: flex; flex-direction: column; flex: 1; width: min(860px, 100%); min-height: 0; padding-top: 24px; }
+.rk-onboarding--card .rk-onboarding__content { flex: 1; }
+.rk-onboarding--card footer .rk-onboarding__hint { flex: none; }
+.rk-onboarding__dots { display: flex; align-items: center; justify-content: center; gap: 10px; flex: 1; }
+.rk-onboarding__dot { width: 10px; height: 10px; padding: 0; border: 0; border-radius: 999px; background: var(--rk-line-strong, rgba(35,31,26,.18)); cursor: pointer; transition: width .2s ease, background .2s ease; }
+.rk-onboarding__dot.is-done { background: var(--rk-ok, #1e7f3c); }
+.rk-onboarding__dot.is-active { width: 42px; background: var(--rk-accent, #7040c4); }
+.rk-onboarding__dot:disabled { cursor: not-allowed; }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rightkit/onboarding",
-  "version": "0.6.3",
+  "version": "0.6.4",
   "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,21 +29,11 @@
     "react": ">=18 <21"
   },
   "devDependencies": {
-    "@rightkit/react-shell": "0.7.2",
-    "@rightkit/legal-ui": "0.4.1",
-    "@rightkit/qa-chrome": "0.1.9",
-    "@testing-library/jest-dom": "^7.0.1",
-    "@testing-library/dom": "^10.4.2",
-    "@testing-library/react": "^16.3.3",
-    "@testing-library/user-event": "^14.6.8",
+    "@rightkit/react-shell": "0.7.3",
+    "@rightkit/legal-ui": "0.4.2",
     "@types/react": "^19.3.0",
-    "@types/react-dom": "^19.3.0",
-    "jsdom": "^30.1.3",
     "react": "^19.3.1",
-    "react-dom": "^19.3.1",
-    "typescript": "^7.0.2",
-    "vite": "^8.3.4",
-    "vitest": "^5.0.5"
+    "typescript": "^7.0.2"
   },
   "publishConfig": {
     "registry": "https://registry.npmjs.org",
@@ -56,8 +46,6 @@
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",
-    "typecheck": "tsc -p tsconfig.json --noEmit",
-    "pretest": "pnpm --filter \"@rightkit/onboarding^...\" run build",
-    "test": "vitest run"
+    "typecheck": "tsc -p tsconfig.json --noEmit"
   }
 }