@rightkit/document-workspace 0.0.0-stage → 0.1.1

package/dist/settings/sections/UpdateLicenseBlock.js

@@ -0,0 +1,158 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { SettingRow, SettingsGroup, licenseSection, } from "@rightkit/settings-ui";
+import { LicenseClientError, isLicensed, isPro, licenseMessage } from "@rightkit/license";
+import { openExternal } from "@rightkit/document-core/state/tauriBridge";
+import { UPDATE_LICENSE_URL, getLicenseClient } from "../../state/updateLicense.js";
+import { PublishedLicense } from "../publishedSections.js";
+/** Fields the published section displays; a native change that alters none of them needs no re-read. */
+const signature = (v) => [v.mode, v.status, v.lifecycle, v.revisionState, v.kind, v.tier, v.validUntil, v.confirmationDueAt, v.staleSince, v.message]
+    .map(String)
+    .join("|");
+/**
+ * LicenseClientLike over the native client. Retained app code: the published section needs a
+ * synchronous client and `getLicenseClient()` is async; the key is trimmed here because the package
+ * passes the pasted text through untrimmed; the first read is memoised behind a loading gate. The key is only ever a
+ * transient command argument.
+ */
+function createLicenseClientLike() {
+    const firstRead = async () => {
+        const client = await getLicenseClient();
+        return client.status();
+    };
+    let first = null;
+    let firstDone = false;
+    return {
+        status: async () => {
+            if (!firstDone) {
+                first ??= firstRead().finally(() => {
+                    firstDone = true;
+                });
+                return first;
+            }
+            return (await getLicenseClient()).status();
+        },
+        activate: async (key) => (await getLicenseClient()).activate(key.trim()),
+        deactivate: async () => (await getLicenseClient()).deactivate(),
+        refresh: async () => (await getLicenseClient()).refresh(),
+    };
+}
+/** Kind badges stay neutral; the "updates" claims below depend on the view's entitlement. */
+const KIND = { trial: "Trial", term: "Term", lifetime: "Lifetime" };
+function licenseLabels(pro) {
+    return {
+        sectionLabel: "Update license",
+        statusLabel: "Update license",
+        activeStatusLabel: "Update license",
+        searchStatus: "Update license status",
+        searchActivate: "Activate update license key",
+        free: "Free public build",
+        freeDetail: "Activate a key for signed in-app updates.",
+        attention: "Update license — needs attention",
+        expired: "Expired",
+        trial: KIND.trial,
+        subscription: KIND.term,
+        lifetime: KIND.lifetime,
+        activeDetail: (kind, until) => {
+            if (!pro)
+                return `${kind} license active on this device.`;
+            if (kind === KIND.lifetime)
+                return "Lifetime updates active on this device.";
+            if (kind === KIND.trial)
+                return `Trial updates active${until ? ` through ${until}` : ""}.`;
+            return `Updates active${until ? ` through ${until}` : ""}.`;
+        },
+        expiredDetail: (kind, until) => kind === KIND.trial
+            ? "Update trial expired."
+            : `Update license expired${until ? ` on ${until}` : ""}.`,
+        deactivateTitle: "Remove this license",
+        deactivateHint: "Frees this device so you can enter a different key.",
+        deactivate: "Remove license",
+        keyTitle: "License key",
+        keyHint: "Paste the key from your purchase email.",
+        keyAria: "Update license key",
+        keyPlaceholder: "VR-XXXX-XXXX-XXXX",
+        activate: "Activate",
+        activating: "Activating...",
+        purchaseTitle: "Need an update license?",
+        purchase: "Buy update license",
+        verifyTitle: "Update license check",
+        verifyHint: "Connect once to verify this purchase.",
+        verify: "Verify purchase",
+    };
+}
+/**
+ * the host app update-license block: the published `licenseSection()` (`@rightkit/settings-ui` 0.7.0)
+ * over the native licence client. App-owned remainder, each piece with its reason:
+ * the lazy client above, the Disabled-build notice, the loading gate (the package shows "Free"
+ * until its first read settles), the non-Pro notice (the package marks any active licence as
+ * licensed), the cross-window re-read on native change events (the package only reads on mount),
+ * and the label map. The webview holds no key or token: the key is a transient command input and
+ * the view is the only state. Record: docs/rightkit-exceptions/M12.md#m12-update-license-block.
+ */
+export function UpdateLicenseBlock() {
+    const client = useMemo(createLicenseClientLike, []);
+    const [view, setView] = useState(null);
+    const [failure, setFailure] = useState(null);
+    const [revision, setRevision] = useState(0);
+    const shown = useRef("");
+    const adopt = useCallback((next) => {
+        if (!next)
+            return;
+        shown.current = signature(next);
+        setView(next);
+    }, []);
+    useEffect(() => {
+        let cancelled = false;
+        let stop;
+        void (async () => {
+            try {
+                const first = await client.status();
+                if (cancelled)
+                    return;
+                adopt(first);
+                const release = await (await getLicenseClient()).onChange((changed) => {
+                    if (cancelled || signature(changed) === shown.current)
+                        return;
+                    adopt(changed);
+                    setRevision((n) => n + 1); // remount the section so its own read picks the change up
+                }, () => undefined);
+                if (cancelled)
+                    release();
+                else
+                    stop = release;
+            }
+            catch (error) {
+                if (!cancelled)
+                    setFailure(error instanceof LicenseClientError && error.message ? error.message : licenseMessage("unknown"));
+            }
+        })();
+        return () => {
+            cancelled = true;
+            stop?.();
+        };
+    }, [client, adopt]);
+    const licensed = isLicensed(view);
+    const pro = isPro(view);
+    const section = useMemo(() => licenseSection({
+        client,
+        confirmDeactivate: false,
+        purchaseUrl: UPDATE_LICENSE_URL,
+        openExternal,
+        tierLabels: { pro: "Pro" },
+        onChange: adopt,
+        labels: licenseLabels(pro),
+        planSlot: licensed && !pro ? (_jsx(SettingsGroup, { children: _jsx(SettingRow, { label: "License active, updates not included", description: "This license does not include signed paid updates. Public patches stay available." }) })) : undefined,
+    }), [client, adopt, licensed, pro]);
+    let body = null;
+    if (failure) {
+        body = (_jsx(SettingsGroup, { title: "Update license", children: _jsx(SettingRow, { label: "Update license", description: _jsx("span", { role: "alert", children: failure }) }) }));
+    }
+    else if (view?.mode === "disabled") {
+        body = (_jsx(SettingsGroup, { title: "Update license", children: _jsx(SettingRow, { label: "Update license", description: licenseMessage("unconfigured") }) }));
+    }
+    else if (view) {
+        body = _jsx(PublishedLicense, { section: section }, revision);
+    }
+    return (_jsx("div", { "data-update-license": true, "aria-busy": !view && !failure ? true : undefined, children: body }));
+}

package/dist/state/explorer.d.ts

@@ -0,0 +1,32 @@
+export type ExplorerLocationKind = "home" | "desktop" | "documents" | "downloads" | "icloud" | "onedrive" | "volume" | "root";
+export interface ExplorerLocation {
+    id: string;
+    label: string;
+    kind: ExplorerLocationKind | string;
+    dir: string;
+}
+export interface ExplorerEntry {
+    name: string;
+    /** "dir" | a supported format id (e.g. "md", "pdf") | "other". */
+    kind: string;
+    /** Unix epoch milliseconds; null when unknown. */
+    modified: number | null;
+    /** Bytes; null for directories. */
+    size: number | null;
+    /** Dirs: canonical dir path. Supported files: broker-granted path (openable via `open`). */
+    path: string;
+}
+export interface ExplorerListing {
+    entries: ExplorerEntry[];
+    truncated: boolean;
+}
+export declare function explorerLocations(): Promise<ExplorerLocation[]>;
+/** `keep` is the NAME of one child the backend must list even when its cap would cut it. */
+export declare function explorerListDir(dir: string, keep?: string): Promise<ExplorerListing>;
+export declare function explorerWatchDir(dir: string): Promise<void>;
+export declare function explorerUnwatchDir(dir: string): Promise<void>;
+/** OS-level reveal (Finder select / Explorer /select) for dirs and unsupported files — unlike
+ *  `revealInFileExplorer` this does not need a broker grant; it only shows the file manager. */
+export declare function explorerReveal(path: string): Promise<void>;
+/** `explorer:changed` events fire {dir} when a watched directory changes; relist that node. */
+export declare function onExplorerChanged(cb: (dir: string) => void): Promise<() => void>;

package/dist/state/explorer.js

@@ -0,0 +1,111 @@
+// Bridge for the Tauri explorer backend (src-tauri/src/commands/explorer.rs). Follows the same
+// conventions as library.ts: lazy invoke import so vitest never touches the Tauri API, browser-QA
+// stubs, and no-op returns outside Tauri.
+import { inTauri, isBrowserQaMode } from "@rightkit/document-core/state/tauriBridge";
+import { hostAppName } from "../appName.js";
+async function invoke(cmd, args) {
+    const { invoke } = await import("@tauri-apps/api/core");
+    return invoke(cmd, args);
+}
+const QA_ROOT = `D:\\${hostAppName()} QA`;
+const QA_LOCATIONS = [
+    { id: "home", label: "Home", kind: "home", dir: QA_ROOT },
+    { id: "desktop", label: "Desktop", kind: "desktop", dir: `${QA_ROOT}\\Desktop` },
+    { id: "documents", label: "Documents", kind: "documents", dir: QA_ROOT },
+    { id: "downloads", label: "Downloads", kind: "downloads", dir: `${QA_ROOT}\\Downloads` },
+    { id: "c", label: "Windows (C:)", kind: "volume", dir: "C:\\" },
+];
+const QA_DIRS = {
+    [QA_ROOT]: [
+        { name: "Notes", kind: "dir", modified: null, size: null, path: `${QA_ROOT}\\Notes` },
+        { name: "Specs", kind: "dir", modified: null, size: null, path: `${QA_ROOT}\\Specs` },
+        {
+            name: "source-notes.md",
+            kind: "md",
+            modified: 1_725_000_000_000,
+            size: 4210,
+            path: `${QA_ROOT}\\source-notes.md`,
+        },
+        {
+            name: "local-preview.html",
+            kind: "html",
+            modified: 1_724_000_000_000,
+            size: 9182,
+            path: `${QA_ROOT}\\local-preview.html`,
+        },
+        {
+            name: "scratch.txt",
+            kind: "txt",
+            modified: 1_723_000_000_000,
+            size: 812,
+            path: `${QA_ROOT}\\scratch.txt`,
+        },
+        {
+            name: "installer.msi",
+            kind: "other",
+            modified: 1_722_000_000_000,
+            size: 5_242_880,
+            path: `${QA_ROOT}\\installer.msi`,
+        },
+    ],
+    [`${QA_ROOT}\\Notes`]: [
+        {
+            name: "roadmap.md",
+            kind: "md",
+            modified: 1_725_100_000_000,
+            size: 1204,
+            path: `${QA_ROOT}\\Notes\\roadmap.md`,
+        },
+    ],
+    [`${QA_ROOT}\\Specs`]: [],
+    [`${QA_ROOT}\\Desktop`]: [],
+    [`${QA_ROOT}\\Downloads`]: [],
+    "C:\\": [],
+};
+export async function explorerLocations() {
+    if (isBrowserQaMode())
+        return QA_LOCATIONS;
+    if (!inTauri())
+        return [];
+    return invoke("explorer_locations");
+}
+/** `keep` is the NAME of one child the backend must list even when its cap would cut it. */
+export async function explorerListDir(dir, keep) {
+    if (isBrowserQaMode())
+        return { entries: QA_DIRS[dir] ?? [], truncated: false };
+    if (!inTauri())
+        return { entries: [], truncated: false };
+    return invoke("explorer_list_dir", keep === undefined ? { dir } : { dir, keep });
+}
+export async function explorerWatchDir(dir) {
+    if (isBrowserQaMode() || !inTauri())
+        return;
+    await invoke("explorer_watch_dir", { dir });
+}
+export async function explorerUnwatchDir(dir) {
+    if (isBrowserQaMode() || !inTauri())
+        return;
+    await invoke("explorer_unwatch_dir", { dir });
+}
+/** OS-level reveal (Finder select / Explorer /select) for dirs and unsupported files — unlike
+ *  `revealInFileExplorer` this does not need a broker grant; it only shows the file manager. */
+export async function explorerReveal(path) {
+    if (isBrowserQaMode() || !inTauri())
+        return;
+    await invoke("explorer_reveal", { path });
+}
+/** `explorer:changed` events fire {dir} when a watched directory changes; relist that node. */
+export async function onExplorerChanged(cb) {
+    if (isBrowserQaMode() || !inTauri())
+        return () => { };
+    const { listen } = await import("@tauri-apps/api/event");
+    const un = await listen("explorer:changed", (e) => cb(e.payload.dir));
+    return () => {
+        try {
+            un();
+        }
+        catch {
+            /* bridge teardown race */
+        }
+    };
+}

package/dist/state/legal.d.ts

@@ -0,0 +1,51 @@
+import type { LegalAcceptanceRecord, SettingsBackend } from "@rightkit/onboarding";
+import type { Settings } from "@rightkit/document-core/settings/settings";
+/** The host app's generated acceptance contract (src/generated/legal-contract.json). */
+export interface LegalContract {
+    acceptanceVersion: string;
+    materialSha256: string;
+    [key: string]: unknown;
+}
+export declare let REQUIRED_LEGAL_ACCEPTANCE_VERSION: string;
+export declare let LEGAL_MATERIAL_SHA256: string;
+export type LegalEligibilityBasis = NonNullable<Settings["legalEligibilityBasis"]>;
+/** The four flat settings fields that together form the host app acceptance receipt. */
+export type LegalReceiptFields = Pick<Settings, "legalAcceptanceVersion" | "legalAcceptedAt" | "legalEligibilityBasis" | "legalMaterialSha256">;
+/**
+ * The checkout-role documents shown on the first-run/re-acceptance gate: every
+ * manifest document EXCEPT third_party_notices (a build-provenance appendix —
+ * not something a user agrees to at first run). Titles/URLs are sourced from
+ * legal-manifest.json, never hardcoded, so a publicUrl change (e.g. VR's
+ * privacy_notice lives at /privacy/, not /legal/privacy/) or a title change
+ * propagates automatically instead of drifting out of sync with the gate.
+ */
+export interface LegalGateDocumentLink {
+    title: string;
+    url: string;
+}
+export declare let LEGAL_GATE_DOCUMENTS: LegalGateDocumentLink[];
+/** Permanent legal links in Settings → About: every manifest document, with About's short names. */
+export declare let LEGAL_ABOUT_LINKS: LegalGateDocumentLink[];
+/** The host hands over its legal/legal-manifest.json and src/generated/legal-contract.json once at startup. */
+export declare function configureLegal({ manifest, contract }: {
+    manifest: unknown;
+    contract: LegalContract;
+}): void;
+/** True only when every field of the acceptance receipt is current: the
+ *  acceptance version and material-document hash match the generated
+ *  contract (src/generated/legal-contract.json, synced from legal-manifest.json
+ *  by scripts/sync-legal-acceptance-contract.mjs), the timestamp is a
+ *  canonical UTC instant, and an eligibility basis was recorded. */
+export declare function legalAcceptanceCurrent(settings: LegalReceiptFields): boolean;
+/** Map the flat settings receipt to the onboarding package's record (`null` when no receipt is stored). */
+export declare function legalReceiptRecord(settings: LegalReceiptFields): LegalAcceptanceRecord | null;
+/** Inverse of legalReceiptRecord(): the settings patch that stores one acceptance. */
+export declare function legalReceiptFields(record: LegalAcceptanceRecord): LegalReceiptFields;
+/** Onboarding's `isAccepted`: the stored record must pass every legalAcceptanceCurrent() rule. */
+export declare function legalRecordCurrent(record: LegalAcceptanceRecord | undefined): boolean;
+/**
+ * Backing store for onboarding's own progress record (`onboarding.state`). The legal receipt is NOT
+ * kept here: it stays in the settings store and reaches onboarding through `legalReceipt`. A storage
+ * failure throws so the gate surfaces it instead of silently dropping progress.
+ */
+export declare function createOnboardingSettingsBackend(): SettingsBackend;

package/dist/state/legal.js

@@ -0,0 +1,130 @@
+import { createAcceptanceReceipt, isCanonicalUtcTimestamp, needsLegalAcceptance, } from "@rightkit/legal";
+// Set once by the host at startup (configureLegal): a published package cannot import files of the app that installs it.
+// ES module exports are live bindings, so every importer sees the configured values.
+let legalManifest;
+export let REQUIRED_LEGAL_ACCEPTANCE_VERSION;
+export let LEGAL_MATERIAL_SHA256;
+// The manifest's suite-wide document titles ("Right Suite Desktop License v1.0
+// Ownership Notice") are too long for the gate's compact document list — these
+// three roles get a short display title instead. product_schedule and
+// privacy_notice already carry the host app-specific titles in the manifest
+// ("the host app Product Schedule" / "the host app Privacy Notice"), so those pass
+// through unchanged.
+const GATE_DOCUMENT_SHORT_TITLES = {
+    license: "License",
+    eula: "End User License Agreement",
+    acceptable_use: "Acceptable Use Policy",
+};
+function manifestLinks(shortTitles, excludeRoles = []) {
+    return legalManifest.documents
+        .filter((document) => !excludeRoles.includes(document.role))
+        .map((document) => ({
+        title: shortTitles[document.role] ?? document.title,
+        url: document.publicUrl,
+    }));
+}
+export let LEGAL_GATE_DOCUMENTS = [];
+/** Permanent legal links in Settings → About: every manifest document, with About's short names. */
+export let LEGAL_ABOUT_LINKS = [];
+/** The host hands over its legal/legal-manifest.json and src/generated/legal-contract.json once at startup. */
+export function configureLegal({ manifest, contract }) {
+    const m = manifest;
+    if (!m || !Array.isArray(m.documents))
+        throw new TypeError("configureLegal: a legal manifest with documents is required");
+    if (typeof contract?.acceptanceVersion !== "string" || typeof contract?.materialSha256 !== "string") {
+        throw new TypeError("configureLegal: the contract needs acceptanceVersion and materialSha256 strings");
+    }
+    legalManifest = m;
+    REQUIRED_LEGAL_ACCEPTANCE_VERSION = contract.acceptanceVersion;
+    LEGAL_MATERIAL_SHA256 = contract.materialSha256;
+    LEGAL_GATE_DOCUMENTS = manifestLinks(GATE_DOCUMENT_SHORT_TITLES, ["third_party_notices"]);
+    LEGAL_ABOUT_LINKS = manifestLinks({
+        license: "Ownership Notice",
+        eula: "EULA",
+        acceptable_use: "Acceptable Use",
+        product_schedule: "Product Schedule",
+        privacy_notice: "Privacy",
+        third_party_notices: "Third-party Notices",
+    });
+}
+/** True only when every field of the acceptance receipt is current: the
+ *  acceptance version and material-document hash match the generated
+ *  contract (src/generated/legal-contract.json, synced from legal-manifest.json
+ *  by scripts/sync-legal-acceptance-contract.mjs), the timestamp is a
+ *  canonical UTC instant, and an eligibility basis was recorded. */
+export function legalAcceptanceCurrent(settings) {
+    const basis = settings.legalEligibilityBasis;
+    if (!isCanonicalUtcTimestamp(settings.legalAcceptedAt) ||
+        (basis !== "individual" && basis !== "enterprise") ||
+        settings.legalMaterialSha256 !== LEGAL_MATERIAL_SHA256) {
+        return false;
+    }
+    // The stored acceptance is the flat settings fields, not a document-level receipt. Material
+    // hash equality (above) proves the agreed documents are unchanged, so the receipt is rebuilt from
+    // the manifest carrying the STORED acceptance version, and the package gate checks schema,
+    // app key and version against the manifest.
+    const manifest = legalManifest;
+    const receipt = {
+        ...createAcceptanceReceipt(manifest, {
+            acceptedAt: settings.legalAcceptedAt,
+            surface: "first_run",
+            eligibilityBasis: basis,
+        }),
+        acceptanceVersion: settings.legalAcceptanceVersion,
+    };
+    return !needsLegalAcceptance(manifest, receipt);
+}
+/** Map the flat settings receipt to the onboarding package's record (`null` when no receipt is stored). */
+export function legalReceiptRecord(settings) {
+    const basis = settings.legalEligibilityBasis;
+    if (!settings.legalAcceptanceVersion ||
+        !settings.legalMaterialSha256 ||
+        !isCanonicalUtcTimestamp(settings.legalAcceptedAt) ||
+        (basis !== "individual" && basis !== "enterprise")) {
+        return null;
+    }
+    return {
+        version: settings.legalAcceptanceVersion,
+        documentsHash: settings.legalMaterialSha256,
+        acceptedAt: settings.legalAcceptedAt,
+        eligibilityBasis: basis,
+    };
+}
+/** Inverse of legalReceiptRecord(): the settings patch that stores one acceptance. */
+export function legalReceiptFields(record) {
+    return {
+        legalAcceptanceVersion: record.version,
+        legalAcceptedAt: record.acceptedAt,
+        legalEligibilityBasis: record.eligibilityBasis,
+        legalMaterialSha256: record.documentsHash,
+    };
+}
+/** Onboarding's `isAccepted`: the stored record must pass every legalAcceptanceCurrent() rule. */
+export function legalRecordCurrent(record) {
+    return record !== undefined && legalAcceptanceCurrent(legalReceiptFields(record));
+}
+const ONBOARDING_STORE_KEY = "vr.onboarding.v1";
+/**
+ * Backing store for onboarding's own progress record (`onboarding.state`). The legal receipt is NOT
+ * kept here: it stays in the settings store and reaches onboarding through `legalReceipt`. A storage
+ * failure throws so the gate surfaces it instead of silently dropping progress.
+ */
+export function createOnboardingSettingsBackend() {
+    let revision = 0;
+    const read = () => {
+        const raw = localStorage.getItem(ONBOARDING_STORE_KEY);
+        return raw ? JSON.parse(raw) : {};
+    };
+    const snapshot = (values) => ({ values, revision });
+    return {
+        async load() {
+            return snapshot(read());
+        },
+        async patch(patch) {
+            const values = { ...read(), ...patch };
+            localStorage.setItem(ONBOARDING_STORE_KEY, JSON.stringify(values));
+            revision += 1;
+            return snapshot(values);
+        },
+    };
+}

package/dist/state/library.d.ts

@@ -0,0 +1,33 @@
+import { type DocFormat, type LoadedDocument, type ViewMode, type ViewMeta } from "@rightkit/document-core/documents/types";
+export interface FileEntry {
+    /** Opaque backend token for a known file. This is not a filesystem path. */
+    token: string;
+    displayName: string;
+    /** Location metadata for identity/display only. Opening still exchanges token for a grant. */
+    displayPath?: string;
+    format: DocFormat;
+    /** Last-opened time in epoch ms (recent_files.opened_at × 1000). Undefined when unavailable. */
+    openedAt?: number;
+}
+export interface OpenFileEntry {
+    /** Authorized real filesystem path for an already-open file. */
+    path: string;
+    displayName: string;
+    format: DocFormat;
+}
+export declare function listRecent(): Promise<FileEntry[]>;
+export declare function clearRecent(): Promise<void>;
+export declare function togglePin(entry: OpenFileEntry): Promise<boolean>;
+export declare function isPinnedPath(path: string): Promise<boolean>;
+export interface PinEntry {
+    path: string;
+    displayName: string;
+    format: string;
+    /** "file" | "dir" — directory pins power the explorer sidebar's pinned folders. */
+    kind: "file" | "dir";
+}
+/** All pins — files AND directories (dirs first, then files, in pin order). */
+export declare function listPins(): Promise<PinEntry[]>;
+export declare function togglePinDir(path: string, displayName: string): Promise<boolean>;
+export declare function recordRecent(doc: LoadedDocument): Promise<void>;
+export declare function saveViewState(path: string, lastView: ViewMode, viewMeta?: ViewMeta): Promise<void>;

package/dist/state/library.js

@@ -0,0 +1,110 @@
+import { baseName, formatFromPath, } from "@rightkit/document-core/documents/types";
+import { inTauri, isBrowserQaMode } from "@rightkit/document-core/state/tauriBridge";
+import { hostAppName } from "../appName.js";
+async function invoke(cmd, args) {
+    const { invoke } = await import("@tauri-apps/api/core");
+    return invoke(cmd, args);
+}
+function map(rows) {
+    return rows.map((r) => ({
+        token: r.path,
+        displayName: r.display_name,
+        displayPath: r.display_path,
+        format: r.format,
+        openedAt: r.opened_at ? r.opened_at * 1000 : undefined,
+    }));
+}
+export async function listRecent() {
+    if (isBrowserQaMode()) {
+        const now = Date.now();
+        return [
+            {
+                token: `D:\\${hostAppName()} QA\\source-notes.md`,
+                displayName: "source-notes.md",
+                format: "md",
+                openedAt: now - 12 * 60_000,
+            },
+            {
+                token: `D:\\${hostAppName()} QA\\local-preview.html`,
+                displayName: "local-preview.html",
+                format: "html",
+                openedAt: now - 3 * 3_600_000,
+            },
+            {
+                token: `D:\\${hostAppName()} QA\\scratch.txt`,
+                displayName: "scratch.txt",
+                format: "txt",
+                openedAt: now - 26 * 3_600_000,
+            },
+        ];
+    }
+    if (!inTauri())
+        return [];
+    return map(await invoke("list_recent", { limit: 20 }));
+}
+export async function clearRecent() {
+    if (isBrowserQaMode() || !inTauri())
+        return;
+    await invoke("clear_recent");
+}
+export async function togglePin(entry) {
+    if (isBrowserQaMode())
+        return true;
+    if (!inTauri())
+        return false;
+    return invoke("toggle_pin", {
+        path: entry.path,
+        displayName: entry.displayName,
+        format: entry.format,
+    });
+}
+export async function isPinnedPath(path) {
+    if (isBrowserQaMode())
+        return false;
+    if (!inTauri())
+        return false;
+    return invoke("is_pinned_path", { path });
+}
+/** All pins — files AND directories (dirs first, then files, in pin order). */
+export async function listPins() {
+    if (isBrowserQaMode())
+        return [];
+    if (!inTauri())
+        return [];
+    const rows = await invoke("list_pins");
+    return rows.map((r) => ({
+        path: r.path,
+        displayName: r.display_name,
+        format: r.format,
+        kind: r.kind,
+    }));
+}
+export async function togglePinDir(path, displayName) {
+    if (isBrowserQaMode())
+        return true;
+    if (!inTauri())
+        return false;
+    return invoke("toggle_pin_dir", { path, displayName });
+}
+export async function recordRecent(doc) {
+    if (isBrowserQaMode())
+        return;
+    if (!inTauri())
+        return;
+    await invoke("record_recent", {
+        path: doc.path,
+        displayName: baseName(doc.path),
+        format: formatFromPath(doc.path),
+    });
+}
+export async function saveViewState(path, lastView, viewMeta) {
+    if (isBrowserQaMode())
+        return;
+    if (!inTauri())
+        return;
+    await invoke("save_view_state", {
+        path,
+        lastView,
+        viewMeta: viewMeta ? JSON.stringify(viewMeta) : null,
+    });
+}

package/dist/state/updateLicense.d.ts

@@ -0,0 +1,31 @@
+import { type LicenseClient } from "@rightkit/license";
+import { type AutoUpdateStatus, type UpdateTier } from "@rightkit/app-update";
+export type UpdateState = "idle" | "checking" | "current" | "available" | "available-external" | "installing" | "install-failed" | "failed" | "license-required";
+export declare function resolvedAppVersion(): string;
+export declare const APP_VERSION: string;
+export declare const UPDATE_LICENSE_URL = "https://viewright.cc/pricing/";
+export type { UpdateTier };
+export declare function getLicenseClient(): Promise<LicenseClient>;
+export declare function openPendingExternalUpdate(): Promise<void>;
+export declare const UPDATE_CHECK_CACHE_KEY = "vr.updateCheck.v3";
+export declare function checkForUpdate(setLatestVersion: (version: string) => void, setUpdateState: (state: UpdateState) => void, setLatestTier?: (tier: UpdateTier | null) => void): Promise<UpdateState>;
+export declare function installPendingUpdate(setUpdateState: (state: UpdateState) => void, setInstallError?: (message: string) => void): Promise<UpdateState>;
+/** True while a manual-download installer URL is staged (public fallback or failed patch install). */
+export declare function hasPendingExternalUpdate(): boolean;
+/**
+ * the host app update flow as the function-style client `@rightkit/settings-ui` `updatesSection`
+ * expects (`UpdatesAdapter`): check()/install() resolve to an `AutoUpdateStatus`. The explicit
+ * check -> install split, the last-known-good cache and the public-release fallback stay in
+ * checkForUpdate()/installPendingUpdate(); this only maps their UpdateState into the shared status.
+ * `onChange` fires after each call so UI outside the section can re-read hasPendingExternalUpdate().
+ */
+export declare function createHostUpdatesAdapter(onChange?: () => void): {
+    check(): Promise<AutoUpdateStatus>;
+    install(): Promise<AutoUpdateStatus>;
+};
+/** Startup check through the native host. The host reads the licence record, so a paid update is
+ *  announced for a licensed user; a failure is advisory and returns null. */
+export declare function checkForBackgroundUpdate(): Promise<{
+    version: string;
+    tier: UpdateTier | null;
+} | null>;