@rightkit/system-ui 0.0.0-stage → 0.1.0

package/dist/api.d.ts

@@ -0,0 +1,1011 @@
+/** True in the Windows webview: the hub runs one page on both systems and a few strings differ. */
+export declare const isWindows: boolean;
+export interface Metric<T> {
+    value: T | null;
+    capability: string;
+    label: string;
+}
+export interface Disk {
+    mount_point: string;
+    total_bytes: number | null;
+    /** Physically free: what the file system would let a write use now. */
+    available_bytes: number | null;
+    /** macOS only: more space the system could reclaim (snapshots, caches); never added to the free figure. */
+    reclaimable_bytes?: number | null;
+    removable: boolean;
+}
+export interface Status {
+    cpu_usage_percent: Metric<number>;
+    memory_used_bytes: Metric<number>;
+    memory_total_bytes: Metric<number>;
+    memory_pressure: Metric<string>;
+    swap_used_bytes: Metric<number>;
+    swap_total_bytes: Metric<number>;
+    disks: Disk[];
+}
+export interface Process {
+    identity: {
+        pid: number;
+        start_time: number;
+    };
+    name: string;
+    cpu_usage_percent: number;
+    memory: Metric<number>;
+}
+/** State of one volume's whole-disk index. `partial`: some folders were skipped or unreadable (Full Disk Access). */
+export interface DiskIndexVolume {
+    mount_point: string;
+    state: "building" | "ready" | "failed";
+    entries: number;
+    crawl_ms: number;
+    resumed_from_snapshot: boolean;
+    full_disk_access: boolean;
+    partial: boolean;
+    unreadable_dirs: number;
+    error: string | null;
+    health?: DiskIndexHealth | null;
+}
+/** `since` is Unix seconds. Absent until the monitor's first tick and on platforms without the index. */
+export interface DiskIndexHealth {
+    state: "healthy" | "unhealthy";
+    reasons: string[];
+    since: number;
+}
+export interface DiskIndexStatus {
+    supported: boolean;
+    volumes: DiskIndexVolume[];
+    health?: DiskIndexHealth | null;
+}
+/** Image and video compression (the host app #202): the switch, whether a verified FFmpeg is there, and why not. */
+export interface MediaCompressStatus {
+    enabled: boolean;
+    available: boolean;
+    formats: string[];
+    note: string | null;
+}
+/** Measured from the written copy, never estimated. */
+export interface MediaCompressOutcome {
+    source: string;
+    output: string;
+    source_bytes: number;
+    output_bytes: number;
+    saved_bytes: number;
+}
+/** `known: false` means the index does not hold the path yet; the numbers are then meaningless. */
+export interface IndexedSize {
+    path: string;
+    known: boolean;
+    allocated: number;
+    allocated_unique: number;
+    logical: number;
+    files: number;
+}
+export interface Row {
+    path: string;
+    name: string;
+    is_dir: boolean;
+    bytes: number;
+    /** A "smaller files" total, not a real path. */
+    summary?: boolean;
+    /** Modified time in Unix seconds (a folder's: the newest below it); 0 or absent when unknown. */
+    modified?: number;
+}
+/** A range of modified times in Unix seconds: `since` inclusive, `before` exclusive. */
+export interface ChangedRange {
+    since?: number;
+    before?: number;
+}
+/** What a search found, with the matches a date range left out for having no date. */
+export interface SearchResult {
+    rows: Row[];
+    /** Which source answered: Windows Search, the Mac file index, or the saved scan. */
+    source?: "windows_search" | "file_index" | "saved_scan";
+    undated: number;
+    /** The saved scan carries modified times; false until it is scanned again. */
+    has_dates: boolean;
+}
+/** An item's identity when the person asked for an action on it (device and inode). */
+export interface FileIdentity {
+    dev: number;
+    ino: number;
+    is_dir: boolean;
+}
+/** What the Storage inspector reads for one item; null means it could not be read. */
+export interface Inspect {
+    is_dir: boolean;
+    is_link: boolean;
+    logical_bytes: number | null;
+    created_at: number | null;
+    modified_at: number | null;
+    files: number | null;
+    folders: number | null;
+}
+export interface MovePlan {
+    target: string;
+    same_volume: boolean;
+}
+export interface MoveResult {
+    target: string;
+    copied: boolean;
+}
+export interface Folder {
+    path: string;
+    root: string;
+    rows: Row[];
+    total_children: number;
+    incomplete: boolean;
+    needs_access: boolean;
+    /** Items the scan could not read (long paths, access denied, entry limit). */
+    unread?: number;
+    limited: boolean;
+    root_label: string;
+    /** Unix seconds when this data was scanned. */
+    scanned_at: number;
+    /** Shown from the last saved scan rather than a scan made this session. */
+    from_snapshot: boolean;
+    /** Rows carry modified times; false for a scan saved before they were kept. */
+    has_dates?: boolean;
+}
+export interface ScanStatus {
+    running: boolean;
+    running_root: string | null;
+    has_index: boolean;
+    root: string | null;
+    scanned_at: number | null;
+    from_snapshot: boolean;
+    /** The index is kept current while the hub runs; without it a saved scan only gets older. */
+    live_refresh: boolean;
+}
+export interface Volume {
+    name: string;
+    mount_point: string;
+    /** Null for a network volume that did not answer in time (never zero). */
+    total_bytes: number | null;
+    /** Physically free: what the file system would let a write use now. */
+    available_bytes: number | null;
+    /** macOS only: more space the system could reclaim (snapshots, caches); never added to the free figure. */
+    reclaimable_bytes?: number | null;
+    removable: boolean;
+    internal: boolean;
+    disk_image: boolean;
+    /** "network" for a mounted SMB, AFP, NFS or WebDAV share or a mapped network drive. */
+    kind: "local" | "network";
+    /** The server and share of a network volume, when known. */
+    detail: string | null;
+    /** "not responding" for a network volume that did not answer in time. */
+    state: "ok" | "not responding";
+}
+export interface CleanupFinding {
+    id: string;
+    rule_id: string;
+    rule_name?: string;
+    category: string;
+    name: string;
+    path: string;
+    bytes: number;
+    apparent_bytes?: number;
+    partial: boolean;
+    risk: "safe" | "review" | "info";
+    eligible: boolean;
+    preselected: boolean;
+    reason: string;
+    action: string;
+    dev: string;
+    ino: string;
+    /** What the item is ("cache", "virtual machine", ...); absent in findings saved before this field. */
+    kind?: string;
+    /** Plain-words safety note ("old release build"); empty when not described. */
+    safety?: string;
+    /** Who made the item: the owning app, tool or project; empty when unknown. */
+    owner?: string;
+    /** Unix seconds the item was last written; 0 when unknown. */
+    last_used?: number;
+}
+export interface ChromeSnapshots {
+    count: number;
+    apparent_bytes: number;
+    reclaimable_bytes: number;
+    reclaimable_known: boolean;
+    running: boolean;
+    since_at: number | null;
+    since_count: number | null;
+}
+export interface CleanupReport {
+    chrome_snapshots?: ChromeSnapshots | null;
+    findings: CleanupFinding[];
+    safe_bytes: number;
+    review_bytes: number;
+    scanned_at: number;
+}
+export interface CleanupApplyResult {
+    moved_items: number;
+    moved_bytes: number;
+    skipped: {
+        path: string;
+        reason: string;
+    }[];
+    activity_id: string | null;
+}
+export interface AppEntry {
+    name: string;
+    path: string;
+    bundle_id: string | null;
+    version: string | null;
+    size_bytes: number;
+    last_used: number | null;
+    running: boolean;
+    protected: string | null;
+}
+export interface RelatedItem {
+    path: string;
+    /** Library folder, or "Application". */
+    label: string;
+    /** "Application", "User Library", "System Library" or "Installer receipt". */
+    location: string;
+    exact: boolean;
+    /** exact, helper, group, prefix, team, name or receipt. */
+    confidence: string;
+    reason: string;
+    /** Root-owned: Finder asks for an administrator password. */
+    admin: boolean;
+    size_bytes: number;
+    preselected: boolean;
+}
+export interface BackgroundEntry {
+    kind: string;
+    label: string;
+    path: string | null;
+}
+export interface AppDetail {
+    app: AppEntry;
+    items: RelatedItem[];
+    background: BackgroundEntry[];
+    receipts: string[];
+}
+export interface UninstallResult {
+    moved: {
+        path: string;
+        bytes: number;
+    }[];
+    failed: {
+        path: string;
+        error: string;
+    }[];
+    /** Same value as moved_bytes. Moved to the Trash or Recycle Bin frees nothing until it is emptied. */
+    bytes_moved: number;
+    moved_bytes: number;
+}
+/** One listening or bound socket of a process, from `process_inspect`. */
+export interface ListeningPort {
+    protocol: string;
+    family: string;
+    address: string;
+    port: number;
+}
+/** On-demand inspection of one process. A null list could not be read; its note says why. */
+export interface ProcessConnection {
+    protocol: string;
+    family: string;
+    /** An address, never a looked-up name: nothing is resolved. */
+    remote_address: string;
+    remote_port: number;
+}
+export interface ProcessInspection {
+    listening: ListeningPort[] | null;
+    /** Established connections: the remote ends the process talks to. Null when unreadable; absent from older engines. */
+    connections?: ProcessConnection[] | null;
+    open_files: string[] | null;
+    notes: string[];
+}
+export interface ProcessMember {
+    identity: {
+        pid: number;
+        start_time: number;
+    };
+    name: string;
+    cpu_usage_percent: number;
+    /** Memory the process is responsible for: on macOS the physical footprint, including compressed and swapped pages. */
+    memory_bytes: number;
+    /** Resident size (in RAM now) when it differs from `memory_bytes`; absent when unknown. */
+    resident_bytes?: number;
+    /** Null when the platform did not report it. */
+    threads: number | null;
+    /** Windows: share of the busiest GPU engine, 0..100; null when unreadable or switched off. */
+    gpu_percent?: number | null;
+    /** Unix seconds; null when unreadable. */
+    started_at: number | null;
+}
+export interface ProcessRow {
+    key: string;
+    name: string;
+    bundle_id: string | null;
+    app_path: string | null;
+    lead: {
+        pid: number;
+        start_time: number;
+    };
+    cpu_usage_percent: number;
+    memory_bytes: number;
+    /** Resident size (in RAM now) when it differs from `memory_bytes`; absent when unknown. */
+    resident_bytes?: number;
+    /** Null when any member's count is unreadable. */
+    threads: number | null;
+    /** Windows: the members' GPU use added up (of the busiest engine); null when unreadable or switched off. */
+    gpu_percent?: number | null;
+    /** Bytes read and written since the previous refresh, plus lifetime totals, summed over the group (#324 item 10). Absent from older engines. Windows counts include pipe and network I/O. */
+    disk_io?: {
+        read_bytes: number;
+        written_bytes: number;
+        total_read_bytes: number;
+        total_written_bytes: number;
+    } | null;
+    /** Unix seconds the lead started; null when unreadable. */
+    started_at: number | null;
+    /** The app bundle or the executable; null when unknown. */
+    executable: string | null;
+    members: ProcessMember[];
+    can_act: boolean;
+    refusal: string | null;
+}
+export interface Change {
+    path: string;
+    /** Signed change in bytes. */
+    bytes: number;
+}
+export interface Growth {
+    available: boolean;
+    /** Unix seconds of the scan compared against. */
+    since: number | null;
+    grown: Change[];
+    shrunk: Change[];
+    reason: string | null;
+}
+export type QuitOutcome = "quit" | "still_running";
+/** One Activity timeline row. `at` is Unix seconds; `open` names the section that owns it. */
+export interface ActivityRow {
+    at: number;
+    kind: "Cleanup" | "Undo" | "Uninstall" | "App update" | "Drive health" | "Scan" | "Send" | "Chat" | "Remote" | "File index" | "Hub";
+    summary: string;
+    open: "cleanup" | "apps" | "storage" | "chat" | null;
+}
+export interface ActivityTimeline {
+    rows: ActivityRow[];
+    /** Sources that exist but could not be read. */
+    unreadable: string[];
+}
+export declare const api: {
+    status: () => Promise<Status>;
+    processes: () => Promise<Process[]>;
+    scan: (path?: string) => Promise<Folder>;
+    scanStatus: () => Promise<ScanStatus>;
+    lastScan: () => Promise<Folder | null>;
+    growth: () => Promise<Growth>;
+    children: (path: string) => Promise<Folder>;
+    /** `minBytes` keeps only items larger than that many bytes. */
+    search: (query: string, limit?: number, extensions?: string[], minBytes?: number) => Promise<Row[]>;
+    /** `search` with a modified-time range; says how many matches had no date. */
+    searchChanged: (query: string, minBytes?: number, changed?: ChangedRange, limit?: number) => Promise<SearchResult>;
+    diskIndexStatus: () => Promise<DiskIndexStatus>;
+    diskIndexSizes: (paths: string[]) => Promise<IndexedSize[]>;
+    apps: () => Promise<AppEntry[]>;
+    appDetail: (path: string) => Promise<AppDetail>;
+    uninstall: (path: string, bundleId: string | null, items: string[]) => Promise<UninstallResult>;
+    processRows: () => Promise<ProcessRow[]>;
+    quit: (r: ProcessRow) => Promise<QuitOutcome>;
+    forceQuit: (r: ProcessRow) => Promise<QuitOutcome>;
+    /** Listening ports and open files of one process, read now. Nothing is sampled in the background. */
+    inspectProcess: (r: ProcessRow) => Promise<ProcessInspection>;
+    volumes: () => Promise<Volume[]>;
+    eject: (mount: string) => Promise<void>;
+    /** Opens the Full Disk Access pane in System Settings. */
+    openFullDiskAccess: () => Promise<void>;
+    fullDiskAccessStatus: () => Promise<string>;
+    cleanupScan: () => Promise<CleanupReport>;
+    /** The last saved findings, or null when none were saved. Never scans. */
+    cleanupCached: () => Promise<CleanupReport | null>;
+    cleanupApply: (items: CleanupFinding[]) => Promise<CleanupApplyResult>;
+    cleanupRestore: (id: string) => Promise<unknown>;
+    reveal: (path: string) => Promise<void>;
+    /** Device and inode of an item now; the file actions check them again before acting. */
+    fileIdentity: (path: string) => Promise<FileIdentity>;
+    /** Opens a folder, or selects a file, in Finder. Read-only. */
+    finderOpen: (path: string) => Promise<void>;
+    /** The native folder picker; null when cancelled. */
+    fileChooseFolder: () => Promise<string | null>;
+    fileMovePlan: (path: string, id: FileIdentity, destination: string) => Promise<MovePlan>;
+    /** Renames within one drive; across drives, copies then trashes the original when copyAcrossVolumes is set. */
+    fileMove: (path: string, id: FileIdentity, destination: string, copyAcrossVolumes: boolean) => Promise<MoveResult>;
+    fileTrash: (path: string, id: FileIdentity) => Promise<void>;
+    mediaCompressStatus: () => Promise<MediaCompressStatus>;
+    mediaCompress: (path: string, options?: {
+        quality?: number;
+        max_dimension?: number;
+    }) => Promise<MediaCompressOutcome>;
+    /** Facts the scan does not hold for one item: read-only, one path, never recursive. */
+    storageInspect: (path: string) => Promise<Inspect>;
+    /** The raw bytes of one image for the inspector's preview; rejects with the reason when there is no preview. */
+    storagePreview: (path: string) => Promise<ArrayBuffer>;
+    /** Drive health for these mounts; samples smartctl only when ten minutes have passed. */
+    driveHealth: (mounts: string[]) => Promise<HealthReport>;
+    /** Read-only merge of the records each feature keeps; newest first, at most `limit` rows older than `before`. */
+    activityTimeline: (limit: number, before: number | null) => Promise<ActivityTimeline>;
+    homePath: () => Promise<string>;
+    duplicatesScan: (path: string) => Promise<DuplicateReport>;
+    /** Moves each extra copy to the Trash after re-checking it; the kept copy is never touched. */
+    duplicatesTrash: (items: {
+        kept: string;
+        path: string;
+    }[]) => Promise<DuplicatesTrashResult>;
+};
+export interface SelfTest {
+    kind: string;
+    result: string;
+    passed: boolean | null;
+    power_on_hours: number | null;
+}
+/** One successful SMART reading. `at` is Unix seconds. */
+export interface HealthReading {
+    at: number;
+    passed: boolean | null;
+    temperature_c: number | null;
+    wear_percent: number | null;
+    written_bytes: number | null;
+    power_on_hours: number | null;
+    critical_warning: number | null;
+    media_errors: number | null;
+    self_tests: SelfTest[];
+}
+export interface HealthAlert {
+    id: string;
+    at: number;
+    disk: string;
+    kind: "warning" | "wear" | "media_errors";
+    message: string;
+}
+export interface DriveCard {
+    mount: string;
+    disk: string | null;
+    model: string | null;
+    status: "ok" | "warning" | "unavailable" | "unknown";
+    reachable: boolean;
+    /** The latest good reading; when the connection hides SMART, the last one kept, with its date. */
+    latest: HealthReading | null;
+    history: HealthReading[];
+}
+export interface HealthReport {
+    tool_available: boolean;
+    sampled_at: number | null;
+    drives: DriveCard[];
+    /** Newest first. */
+    alerts: HealthAlert[];
+}
+export interface DuplicateGroup {
+    kept_path: string;
+    extras: string[];
+    size_bytes: number;
+}
+export interface DuplicateReport {
+    groups: DuplicateGroup[];
+    skipped: {
+        path: string;
+        reason: string;
+    }[];
+    diagnostics: string[];
+    truncated: boolean;
+    files_considered: number;
+    bytes_read: number;
+}
+export interface DuplicatesTrashResult {
+    moved: {
+        path: string;
+        bytes: number;
+    }[];
+    skipped: {
+        path: string;
+        reason: string;
+    }[];
+    moved_bytes: number;
+}
+/** Decimal byte count ("1.5 GB"), or "—" when the value is unknown. */
+export declare function bytes(n: number | null | undefined): string;
+/** "136.3 GB more reclaimable by macOS" when it is at least 1 GB and 2% of the drive, else null. */
+export declare function reclaimableNote(v: {
+    total_bytes: number | null;
+    reclaimable_bytes?: number | null;
+}): string | null;
+/** True when a saved result (Unix seconds) is old enough to refresh. */
+export declare function isStale(secs: number): boolean;
+/** "just now", "5 min ago", "2 h ago", or the date for anything older. */
+export declare function ago(secs: number): string;
+/** Colour for a 0–1 share, matching the notch rings. */
+export declare function tone(fraction: number): string;
+export declare function signedBytes(n: number): string;
+export interface CachedApps {
+    /** Unix seconds when the saved list was written; null when there is none. */
+    saved_at: number | null;
+    apps: AppEntry[];
+}
+/** One source's share of an app's leftovers (`apps-leftovers` events). */
+export interface LeftoverPart {
+    source: "bundle" | "vendor" | "background" | "library" | "receipts";
+    items: RelatedItem[];
+    background: BackgroundEntry[];
+    receipts: string[];
+}
+export type LeftoversEvent = {
+    kind: "part";
+    path: string;
+    part: LeftoverPart;
+} | {
+    kind: "done";
+    path: string;
+    error: string | null;
+};
+/** Update state of one app. Only Sparkle, Homebrew and App Store apps can have one. */
+export interface AppUpdate {
+    path: string;
+    name: string;
+    bundle_id: string | null;
+    installed_version: string | null;
+    source: "app_store" | "homebrew" | "sparkle" | "winget" | "none";
+    state: "available" | "current" | "app_store" | "unknown" | "unavailable";
+    latest_version: string | null;
+    cask: string | null;
+    store_url: string | null;
+    reason: string | null;
+    /** Unix seconds when this row was checked. */
+    checked_at: number;
+}
+export interface UpdateReport {
+    /** Unix seconds of the newest check; null before any check. */
+    checked_at: number | null;
+    apps: AppUpdate[];
+}
+export interface UpdateJob {
+    path: string;
+    state: "running" | "done" | "failed";
+    message: string;
+}
+/** One login or background item that starts by itself (src-tauri/src/startup_items.rs). Read only. */
+export interface StartupItem {
+    name: string;
+    kind: string;
+    scope: "user" | "all users" | "system";
+    /** The plist, shortcut or executable; null when there is no file. */
+    path: string | null;
+    /** What it runs; null when unknown. */
+    program: string | null;
+    /** null when it cannot be told. */
+    enabled: boolean | null;
+    vendor: string | null;
+}
+export interface StartupReport {
+    rows: StartupItem[];
+    /** Plain notes on sources that could not be read or are not listed. */
+    notes: string[];
+}
+export declare const appsApi: {
+    cached: () => Promise<CachedApps>;
+    refresh: () => Promise<void>;
+    summary: (path: string) => Promise<AppEntry>;
+    leftovers: (path: string) => Promise<void>;
+    /** Cached icons by path; the rest arrive as `apps-icon` events. */
+    icons: (paths: string[]) => Promise<Record<string, string>>;
+    updatesCached: () => Promise<UpdateReport>;
+    updatesRefresh: (force: boolean) => Promise<void>;
+    /** Returns "running", "opened" or "store". */
+    update: (path: string) => Promise<string>;
+    /** Startup and login items, read only. Called when the Starts by itself section opens. */
+    startupItems: () => Promise<StartupReport>;
+};
+export interface ShareDevice {
+    fingerprint: string;
+    alias: string;
+    deviceModel?: string | null;
+    deviceType?: string | null;
+    ip: string;
+    port: number;
+    protocol: string;
+}
+export interface ShareIncoming {
+    id: string;
+    from: string;
+    fingerprint: string;
+    fileCount: number;
+    totalBytes: number;
+    isMessage: boolean;
+    preview?: string | null;
+    files: {
+        name: string;
+        size: number;
+    }[];
+    known: boolean;
+}
+export interface ShareTransfer {
+    id: string;
+    direction: "send" | "receive";
+    peer: string;
+    state: "waiting" | "active" | "done" | "failed" | "cancelled" | "declined";
+    totalBytes: number;
+    doneBytes: number;
+    filesTotal: number;
+    filesDone: number;
+    current?: string | null;
+    savedTo?: string | null;
+    savedFiles: string[];
+    error?: string | null;
+}
+export interface ShareSnapshot {
+    running: boolean;
+    error: string | null;
+    alias?: string;
+    saveDir?: string;
+    devices: ShareDevice[];
+    incoming: ShareIncoming[];
+    transfers: ShareTransfer[];
+    warnings: string[];
+    localNetwork: "unknown" | "granted" | "blocked";
+}
+export declare const shareApi: {
+    state: () => Promise<ShareSnapshot>;
+    devices: () => Promise<ShareDevice[]>;
+    /** Send files and/or text to a device (by fingerprint). Resolves with the transfer id. */
+    send: (to: string, paths: string[], text?: string) => Promise<string>;
+    accept: (id: string) => Promise<boolean>;
+    decline: (id: string) => Promise<boolean>;
+    cancel: (id: string) => Promise<boolean>;
+    dismiss: (id: string) => Promise<void>;
+};
+/** Effect classes a paired device may request (`agent/effect.rs`, kebab-case). */
+export declare const DEVICE_GRANT_CLASSES: readonly ["reversible", "irreversible-destruction", "spend", "publication"];
+export type DeviceGrantClass = (typeof DEVICE_GRANT_CLASSES)[number];
+/** One device from `device.list` (the answer is `{ devices: DeviceRecord[] }`). */
+export interface DeviceRecord {
+    deviceId: string;
+    name: string;
+    platform: string;
+    /** Hex key fingerprint; null until the engine reports it. */
+    keyFingerprint: string | null;
+    state: string;
+    grants: string[];
+    grantsExpireAtMs: number | null;
+    revision: number;
+    /** Null when the engine does not say whether the link is up. */
+    linkUp: boolean | null;
+    /** The computer may add devices for the circle. */
+    admit?: boolean;
+}
+/** The answer to `device.list`. */
+export interface DeviceListResult {
+    devices: DeviceRecord[];
+}
+/**
+ * `code`: only the code is known; the owner types it on the other computer. Name, platform, id and
+ * fingerprint are empty and Approve is not offered. `confirm`: the other computer has confirmed and
+ * the full card with Approve and Reject is shown.
+ */
+export type PendingPairingStage = "code" | "confirm";
+/** The live pairing awaiting the owner (`device.pair.pending` → `pending`). */
+export interface PendingPairing {
+    pairingId: string;
+    /** Eight digits, shown as 4+4. */
+    code: string;
+    stage: PendingPairingStage;
+    deviceName: string;
+    platform: string;
+    deviceId: string;
+    keyFingerprint: string;
+    expiresAtMs: number;
+}
+/** The answer to `device.pair.pending`: `pending` is set only while `open` is true. */
+export interface PendingPairingResult {
+    open: boolean;
+    pending: PendingPairing | null;
+}
+/** What `device.pair.start` returns (the code is never in it). */
+export interface PairingStarted {
+    pairingId: string;
+    expiresAtMs: number;
+    /** The single-use join secret (64 hex) the QR carries as `s=`; a phone that proves it joins with one scan. */
+    secret?: string | null;
+    /** This computer's iroh endpoint id (64 hex); a phone's QR carries it. */
+    endpointId?: string;
+    /** Our relay, when one is set; null otherwise. */
+    relayUrl?: string | null;
+    /** This computer's private-network addresses (ip:port); the QR carries them for a phone. */
+    addrs?: string[];
+}
+/** What `device.join` returns once this computer joined a host. */
+export interface JoinedHost {
+    state: string;
+    deviceId: string;
+    hostName: string;
+}
+/** What `device.join.create` returns. `token` and `command` are a bearer secret until used or expired: show them to the owner only. */
+export interface JoinCreated {
+    /** `pulse-join:1:...` */
+    token: string;
+    /** `pulse device join <token>`, the one line to run on the computer being added. */
+    command: string;
+    pairingId: string;
+    expiresAtMs: number;
+    /** Guest links only (#493): per `uname -m` arch, the pinned artifact and the copyable install command (a bearer secret, it carries the pass). Absent on older engines. */
+    linux?: Record<string, {
+        url: string;
+        sha256: string;
+        size: number;
+        glibc: string;
+        command: string;
+    }>;
+    /** Why no Linux command was made (no published Linux build, unreadable manifest). */
+    linuxUnavailable?: string;
+}
+/** The engine's refusal text is `code: message`; these codes mean the owner check wants a (new) PIN. */
+export declare const OWNER_CHECK_CODES: RegExp;
+/** A Touch ID proof of the owner: the engine's single-use challenge and the signature the Mac notch made over it. The engine verifies it. */
+export interface OwnerProof {
+    challenge: string;
+    sig: unknown;
+}
+export type PhoneReadMode = "allow" | "deny";
+export type PhoneSendMode = "allow" | "ask" | "deny";
+/** One paired phone from `device.phone.access`; `error` is set when its policy file is unreadable. */
+export interface PhoneAccess {
+    deviceId: string;
+    name: string;
+    read?: PhoneReadMode;
+    send?: PhoneSendMode;
+    admin?: boolean;
+    error?: string;
+}
+export interface PhoneAccessResult {
+    enabled: boolean;
+    defaults: {
+        read: PhoneReadMode;
+        send: PhoneSendMode;
+    };
+    phones: PhoneAccess[];
+}
+/** A phone send held for the owner (`device.phone.asks`); it times out after 60 s. */
+export interface PhoneAsk {
+    askId: string;
+    deviceId: string;
+    deviceName: string;
+    chat: string;
+    chatName: string;
+    preview: string;
+    createdAtMs: number;
+}
+/** One guest from `device.guest.list` (#492): a cloud box that redeemed a guest link. */
+export interface GuestRecord {
+    deviceId: string;
+    name: string;
+    platform: string;
+    status: "pending" | "approved" | "lapsed";
+    /** The three digits the box printed when it joined; compare before approving. */
+    checkCode: string;
+    /** What the box said about itself; nothing verifies it. */
+    reportedSession: string | null;
+    mintedBy: string;
+    approvedAtMs: number | null;
+    leaseExpiresAtMs: number;
+    lastSeenMs: number | null;
+    /** What it may not do on any computer: add or manage devices, the phone admin path. */
+    refused: string[];
+}
+export declare const devicesApi: {
+    list: () => Promise<DeviceListResult>;
+    pending: () => Promise<PendingPairingResult>;
+    /** Opens a phone pairing. The engine checks the owner (`pin`, the the host app PIN) first. */
+    pairStart: (pin?: string, proof?: OwnerProof) => Promise<PairingStarted>;
+    /** Joins the computer whose owner made `token` (`pulse-join:1:...`); nothing else is asked. */
+    joinWith: (token: string) => Promise<JoinedHost>;
+    /** The engine checks the owner itself: `pin` is the the host app PIN. Without it the engine refuses `unlock_needs_auth`. */
+    pairApprove: (pairingId: string, pin?: string, proof?: OwnerProof) => Promise<unknown>;
+    /** Grants or takes away a computer's `admit` (it may add devices for the circle); owner-checked like Add a device. */
+    admitSet: (deviceId: string, allowed: boolean, pin?: string, proof?: OwnerProof) => Promise<unknown>;
+    /** The enrolled owner-check keys (`remote.owner.key.status`; the Mac notch's and Windows Hello's). */
+    ownerKeys: () => Promise<{
+        keys: {
+            keyId: string;
+            device: string;
+            dev: boolean;
+            bound?: boolean;
+        }[];
+        /** Where the owner-check keys are kept; `weaker` is Windows without the elevated the host app service (a file any process of this account can rewrite). */
+        ownerCheck?: {
+            protection?: "service" | "file" | "keychain";
+            weaker?: boolean;
+        };
+        /** True once a day while the owner key needs confirming (the engine remembers the offer), so a recreated web view does not ask again. */
+        bindDue?: boolean;
+    }>;
+    /** Confirms this computer's owner-check key (binds it to this device) with one owner check. Windows signs in the hub; the Mac's notch signs (`notch_command`, `signOwnerChallenge`, op `bind`). */
+    ownerKeyBind: () => Promise<unknown>;
+    /** Removes one owner-check key; the engine checks `pin`. */
+    ownerKeyRevoke: (keyId: string, pin: string) => Promise<unknown>;
+    /** "Add a device": the engine checks `pin` (the the host app PIN) first, then makes one join command valid for ten minutes. */
+    joinCreate: (pin?: string, proof?: OwnerProof) => Promise<JoinCreated>;
+    /** "Make a guest link" (#492): the same owner check as Add a device, then one single-use link for a cloud box. */
+    guestCreate: (leaseMs: number, pin?: string, proof?: OwnerProof) => Promise<JoinCreated>;
+    guests: () => Promise<{
+        guests: GuestRecord[];
+    }>;
+    /** Owner UI only: makes a pending cloud agent one of your machines until its lease ends. */
+    guestApprove: (deviceId: string) => Promise<unknown>;
+    /** Voids the open join command. */
+    joinCancel: () => Promise<unknown>;
+    pairReject: (pairingId: string) => Promise<unknown>;
+    revoke: (deviceId: string) => Promise<unknown>;
+    phoneAccess: () => Promise<PhoneAccessResult>;
+    /** `read` allow|deny|default; `send` allow|ask|deny|default; omit one to leave it. */
+    phoneAccessSet: (deviceId: string, change: {
+        read?: PhoneReadMode | "default";
+        send?: PhoneSendMode | "default";
+    }) => Promise<unknown>;
+    /** Off revokes the phone's approval key first (system prompt); rejects if cancelled, leaving admin on. */
+    phoneAdminSet: (deviceId: string, allow: boolean) => Promise<unknown>;
+    phoneAsks: () => Promise<{
+        asks: PhoneAsk[];
+    }>;
+    phoneAnswer: (askId: string, allow: boolean) => Promise<unknown>;
+    computerName: () => Promise<string | null>;
+    /** `revision` is the one the device was read at; `expiresAtMs` null means no expiry. */
+    grantsSet: (deviceId: string, revision: number, classes: DeviceGrantClass[], expiresAtMs: number | null) => Promise<unknown>;
+};
+/** One remote request waiting for the owner's answer (core/src/remote/approvals.rs `Item`, state `pending`). */
+export interface RemoteApproval {
+    id: string;
+    /** `act` (one change) or `session` (a family's grant). */
+    kind: string;
+    /** The tool for an act (e.g. `files.patch`), the family (`terminal`) for a session. */
+    scope: string;
+    /** The door the call came in by: `local` or `gateway`. */
+    origin: string;
+    /** What the request is bound to; shown to nobody, sent back with the answer so the engine can check it. */
+    bind: string;
+    /** What it will do and the folder or file name it touches; never file contents or secrets. */
+    summary: string;
+    /** The external chat's client name (unlock requests). */
+    client?: string;
+    state: string;
+    created: number;
+    decided: number;
+    lastUsed: number;
+}
+/** The engine answers `remote.approvals.pending` with `{ items: [...] }` (engine/src/contract.rs); a bare list or `{ approvals }` is read too. */
+export declare function pendingApprovals(answer: unknown): RemoteApproval[];
+export declare const remoteApprovalsApi: {
+    pending: () => Promise<unknown>;
+    /** Approves or denies one pending request, bound to the item as displayed (the engine compares a digest of its fields). Owner UI only: the engine checks that the caller is the the host app hub. */
+    decide: (a: RemoteApproval, approve: boolean, pin?: string) => Promise<unknown>;
+};
+/** The per-chat unlock: the the host app PIN and the owner's answer to an unlock request (`scope === "unlock"`). Never log or keep a PIN. */
+export declare const remoteUnlockApi: {
+    pinStatus: () => Promise<unknown>;
+    /** `current` is needed only when a PIN is already set. */
+    pinSet: (pin: string, current?: string) => Promise<unknown>;
+    /** Denies, or approves with the the host app PIN (the hub cannot show the system prompt). */
+    decide: (a: RemoteApproval, approve: boolean, pin?: string) => Promise<unknown>;
+};
+/** A sign-in request an agent made on a paired computer and that waits for the owner. */
+export interface BrowserRequest {
+    id: string;
+    sites: string[];
+    reason: string;
+    chat: string;
+    expires_ms?: number;
+}
+/** A sign-in session on a paired computer. `needs-owner` is the state the live view is for. */
+export interface BrowserSession {
+    session: string;
+    sites: string[];
+    chat: string;
+    state: string;
+    url?: string;
+    title?: string;
+}
+/** One frame of a session: JPEG, at most 1280 wide; `seq` rises with each new frame. */
+export interface BrowserFrame {
+    seq: number;
+    jpeg_b64: string;
+    width: number;
+    height: number;
+    url: string;
+    title: string;
+}
+/** An input for the session, with x and y in frame pixels. `text` is never logged or kept. */
+export type BrowserInput = {
+    type: "click";
+    x: number;
+    y: number;
+} | {
+    type: "text";
+    text: string;
+} | {
+    type: "key";
+    key: string;
+} | {
+    type: "scroll";
+    dy: number;
+};
+/** The rows a list call answers: a bare list, or the list under `items` or the given key. */
+export declare function browserRows<T>(answer: unknown, key?: string): T[];
+export declare const browserRemoteApi: {
+    pending: (device: string) => Promise<unknown>;
+    /** A single-use nonce for one approval (valid for 60 seconds). */
+    challenge: (device: string, id: string) => Promise<{
+        nonce: string;
+    }>;
+    approve: (device: string, id: string, nonce: string) => Promise<unknown>;
+    deny: (device: string, id: string) => Promise<unknown>;
+    sessions: (device: string) => Promise<unknown>;
+    frame: (device: string, session: string, afterSeq: number) => Promise<BrowserFrame>;
+    input: (device: string, session: string, events: BrowserInput[]) => Promise<unknown>;
+    /** Hands the session back to the agent. */
+    done: (device: string, session: string) => Promise<unknown>;
+};
+/** One saved item of the agent secure box, as `remote.secure.list` answers: labels, hosts, last four and limits, never a value. */
+export interface SecureItem {
+    id: string;
+    kind: "login" | "card";
+    label: string;
+    /** A login's one site. */
+    host?: string;
+    /** A login has a one-time code saved (never the secret). */
+    totp?: boolean;
+    /** A card's shops. */
+    hosts?: string[];
+    last4?: string;
+    maxCents?: number;
+    autoCents?: number;
+    monthCents?: number;
+}
+export interface SecureList {
+    items: SecureItem[];
+    month?: string;
+    spentCents?: Record<string, number>;
+}
+/** `cancelled` when the system dialog was closed; otherwise the saved item's metadata. */
+export type SecureSaved = SecureItem | {
+    cancelled: true;
+};
+/**
+ * The agent secure box (#345 logins, #346 virtual cards). The renderer sends only non-secret fields and the PIN;
+ * the username, password, card number, name, expiry and CVC are typed into a system dialog opened by the command
+ * and go straight to the engine, so no secret ever exists in this page.
+ */
+export declare const secureBoxApi: {
+    list: () => Promise<SecureList>;
+    remove: (id: string) => Promise<unknown>;
+    saveLogin: (label: string, host: string, pin: string, withTotp?: boolean) => Promise<SecureSaved>;
+    /** Adds or replaces a saved login's one-time code; the secret is typed into the system dialog. */
+    setTotp: (id: string, host: string, pin: string) => Promise<SecureSaved>;
+    saveCard: (c: {
+        label: string;
+        hosts: string[];
+        zip: string;
+        maxCents: number;
+        autoCents: number;
+        monthCents: number;
+    }, pin: string) => Promise<SecureSaved>;
+};
+/** The sentence the Devices page shows when the engine refuses pairing with `listen_off`. */
+export declare const LISTEN_OFF_SENTENCE = "Turn on Settings > Devices > Accept device links (LAN only) on this computer first.";
+/** The engine's `listen_off` refusal (engine/src/devicelink_host.rs, pair_start). The hub's engine link
+ *  passes only the refusal's message, not its code, so the message text identifies it. */
+export declare function isListenOff(e: unknown): boolean;
+export declare const isProtectedKey: (key: string) => boolean;
+/** A protected change waiting for the the host app PIN (the engine asks for it when a change makes a gate less safe). */
+export interface PinAsk {
+    key: string;
+    value: unknown;
+    problem: string | null;
+}
+export declare function onProtectedPin(fn: ((ask: PinAsk | null) => void) | null): void;
+/** Sends one protected change to the engine. Without a PIN a change that loosens a gate is refused with
+ *  `unlock_needs_auth`; that opens the PIN prompt (`ProtectedPinPrompt`). Never logs or keeps the PIN. */
+export declare function setProtectedSetting(key: string, value: unknown, pin?: string): Promise<void>;
+/** Sets one notch setting the way the Settings page does: `notch_command` with a `set` command
+ *  (a protected key goes through the engine instead). */
+export declare function setNotchSetting(key: string, value: unknown): Promise<unknown>;