@rightkit/video-ui 0.0.0-stage → 0.1.1

package/dist/hooks/useEngine.js

@@ -0,0 +1,68 @@
+import { useEffect, useRef, useState } from "react";
+import { engineDoctor, engineStatus, errorMessage, } from "../lib/engine.js";
+const POLL_MS = 1000;
+/** Latest doctor report, read by views that need one readiness check without polling. */
+let latestDoctor = null;
+const doctorListeners = new Set();
+export function subscribeDoctor(listener) {
+    doctorListeners.add(listener);
+    return () => {
+        doctorListeners.delete(listener);
+    };
+}
+export const getDoctor = () => latestDoctor;
+function publishDoctor(report) {
+    latestDoctor = report;
+    doctorListeners.forEach((listener) => listener());
+}
+/** Polls `engine_status` and loads the doctor report once the engine is ready. */
+export function useEngine() {
+    const [status, setStatus] = useState(null);
+    const [doctor, setDoctor] = useState(null);
+    const [doctorError, setDoctorError] = useState(null);
+    const [statusError, setStatusError] = useState(null);
+    const doctorRequested = useRef(false);
+    useEffect(() => {
+        let cancelled = false;
+        const tick = async () => {
+            try {
+                const next = await engineStatus();
+                if (cancelled)
+                    return;
+                setStatus(next);
+                setStatusError(null);
+                if (next.state !== "ready") {
+                    doctorRequested.current = false;
+                }
+                else if (!doctorRequested.current) {
+                    doctorRequested.current = true;
+                    engineDoctor()
+                        .then((report) => {
+                        if (cancelled)
+                            return;
+                        setDoctor(report);
+                        publishDoctor(report);
+                        setDoctorError(null);
+                    })
+                        .catch((error) => {
+                        if (cancelled)
+                            return;
+                        doctorRequested.current = false;
+                        setDoctorError(errorMessage(error));
+                    });
+                }
+            }
+            catch (error) {
+                if (!cancelled)
+                    setStatusError(errorMessage(error));
+            }
+        };
+        void tick();
+        const timer = window.setInterval(() => void tick(), POLL_MS);
+        return () => {
+            cancelled = true;
+            window.clearInterval(timer);
+        };
+    }, []);
+    return { status, doctor, doctorError, statusError };
+}

package/dist/hooks/useHdrToSdr.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Whether this computer can finish HDR (PQ or HLG) footage to SDR, from the engine's
+ * optional `hdr_to_sdr` readiness check. `undefined` until the report loads or when the
+ * engine does not report the check; callers must treat `undefined` as "unknown" and
+ * disable nothing.
+ */
+export declare function useHdrToSdr(): boolean | undefined;
+/** Presets that need HDR to SDR conversion. */
+export declare const HDR_COLOR_PRESETS: readonly ["hdr-natural", "hdr-soft"];
+/** The one-line notice shown when HDR to SDR conversion is unavailable. */
+export declare const HDR_UNAVAILABLE_NOTICE = "HDR to SDR conversion is not available on this computer. HDR (PQ or HLG) footage cannot be finished here.";

package/dist/hooks/useHdrToSdr.js

@@ -0,0 +1,19 @@
+import { useSyncExternalStore } from "react";
+import { getDoctor, subscribeDoctor } from "./useEngine.js";
+/**
+ * Whether this computer can finish HDR (PQ or HLG) footage to SDR, from the engine's
+ * optional `hdr_to_sdr` readiness check. `undefined` until the report loads or when the
+ * engine does not report the check; callers must treat `undefined` as "unknown" and
+ * disable nothing.
+ */
+export function useHdrToSdr() {
+    const doctor = useSyncExternalStore(subscribeDoctor, getDoctor);
+    const check = doctor?.readiness?.checks?.find((c) => c.id === "hdr_to_sdr");
+    if (!check)
+        return undefined;
+    return (check.status ?? "").toLowerCase() === "ok";
+}
+/** Presets that need HDR to SDR conversion. */
+export const HDR_COLOR_PRESETS = ["hdr-natural", "hdr-soft"];
+/** The one-line notice shown when HDR to SDR conversion is unavailable. */
+export const HDR_UNAVAILABLE_NOTICE = "HDR to SDR conversion is not available on this computer. HDR (PQ or HLG) footage cannot be finished here.";

package/dist/hooks/useProgress.d.ts

@@ -0,0 +1,10 @@
+import { type ProgressState, seedFromStatus } from "../lib/progress.js";
+export type { ProgressState } from "../lib/progress.js";
+/** Progress of the one engine call the UI is currently following (by tag, then frame id). */
+export declare function useProgress(): {
+    progress: ProgressState;
+    begin: (kind: string, assembleId?: string | null) => string;
+    patch: (p: Partial<ProgressState>) => void;
+    seed: (status: Parameters<typeof seedFromStatus>[1]) => void;
+    reset: () => void;
+};

package/dist/hooks/useProgress.js

@@ -0,0 +1,32 @@
+import { useCallback, useEffect, useRef, useState } from "react";
+import { onEngineEvent } from "../lib/engine.js";
+import { beginProgress, initialProgress, reduceFrame, seedFromStatus } from "../lib/progress.js";
+/** Progress of the one engine call the UI is currently following (by tag, then frame id). */
+export function useProgress() {
+    const [progress, setProgress] = useState(initialProgress);
+    useEffect(() => {
+        let off;
+        let cancelled = false;
+        void onEngineEvent((frame) => setProgress((s) => reduceFrame(s, frame))).then((fn) => {
+            if (cancelled)
+                fn();
+            else
+                off = fn;
+        });
+        return () => {
+            cancelled = true;
+            off?.();
+        };
+    }, []);
+    const seq = useRef(0);
+    const begin = useCallback((kind, assembleId = null) => {
+        seq.current += 1;
+        const tag = `${kind}-${Date.now().toString(36)}-${seq.current}`;
+        setProgress(beginProgress(tag, assembleId));
+        return tag;
+    }, []);
+    const patch = useCallback((p) => setProgress((s) => ({ ...s, ...p })), []);
+    const seed = useCallback((status) => setProgress(seedFromStatus(initialProgress, status)), []);
+    const reset = useCallback(() => setProgress(initialProgress), []);
+    return { progress, begin, patch, seed, reset };
+}

package/dist/index.d.ts

@@ -0,0 +1,55 @@
+export * from "./appName.js";
+export * from "./components/DesktopWorkspace.js";
+export * from "./components/Player.js";
+export * from "./components/RangePreview.js";
+export * from "./demo/DemoSettings.js";
+export * from "./demo/bindings.js";
+export * from "./demo/useDemo.js";
+export * from "./editor/CaptionInspector.js";
+export * from "./editor/ChangesPanel.js";
+export * from "./editor/ColourInspector.js";
+export * from "./editor/Inspector.js";
+export * from "./editor/Timeline.js";
+export * from "./editor/TranscriptPanel.js";
+export * from "./editor/actions.js";
+export * from "./editor/adapter.js";
+export * from "./editor/capabilities.js";
+export * from "./editor/gesture.js";
+export * from "./editor/keys.js";
+export * from "./editor/model.js";
+export * from "./editor/vendor/hyperframes/PlayheadIndicator.js";
+export * from "./editor/vendor/hyperframes/audioWaveformPeaks.js";
+export * from "./editor/vendor/hyperframes/rulerGeometry.js";
+export * from "./editor/vendor/hyperframes/useInspectorGestureTransaction.js";
+export * from "./hooks/useEngine.js";
+export * from "./hooks/useHdrToSdr.js";
+export * from "./hooks/useProgress.js";
+export * from "./legal/legalConfig.js";
+export * from "./lib/assemble.js";
+export * from "./lib/asset.js";
+export * from "./lib/dialog.js";
+export * from "./lib/genright.js";
+export * from "./lib/mediaAdapters.js";
+export * from "./lib/mic.js";
+export * from "./lib/models.js";
+export * from "./lib/modelsBackend.js";
+export * from "./lib/services.js";
+export * from "./lib/settingsBackend.js";
+export * from "./lib/shell.js";
+export * from "./ui/icons.js";
+export * from "./views/AssetsView.js";
+export * from "./views/AutoEditView.js";
+export * from "./views/BatchDelivery.js";
+export * from "./views/BundleExport.js";
+export * from "./views/ExportsView.js";
+export * from "./views/Home.js";
+export * from "./views/OnboardingGate.js";
+export * from "./views/PhrasesView.js";
+export * from "./views/ProgressView.js";
+export * from "./views/PromptPanel.js";
+export * from "./views/RecipeLibrary.js";
+export * from "./views/RetentionView.js";
+export * from "./views/SettingsView.js";
+export * from "./views/ShortsView.js";
+export * from "./views/SourcesView.js";
+export * from "./views/TimelineView.js";

package/dist/index.js

@@ -0,0 +1,57 @@
+// Generated entry: every module whose exports do not collide with an earlier one.
+// Every module is also importable directly by subpath, e.g. `<package>/lib/foo`.
+export * from "./appName.js";
+export * from "./components/DesktopWorkspace.js";
+export * from "./components/Player.js";
+export * from "./components/RangePreview.js";
+export * from "./demo/DemoSettings.js";
+export * from "./demo/bindings.js";
+export * from "./demo/useDemo.js";
+export * from "./editor/CaptionInspector.js";
+export * from "./editor/ChangesPanel.js";
+export * from "./editor/ColourInspector.js";
+export * from "./editor/Inspector.js";
+export * from "./editor/Timeline.js";
+export * from "./editor/TranscriptPanel.js";
+export * from "./editor/actions.js";
+export * from "./editor/adapter.js";
+export * from "./editor/capabilities.js";
+export * from "./editor/gesture.js";
+export * from "./editor/keys.js";
+export * from "./editor/model.js";
+export * from "./editor/vendor/hyperframes/PlayheadIndicator.js";
+export * from "./editor/vendor/hyperframes/audioWaveformPeaks.js";
+export * from "./editor/vendor/hyperframes/rulerGeometry.js";
+export * from "./editor/vendor/hyperframes/useInspectorGestureTransaction.js";
+export * from "./hooks/useEngine.js";
+export * from "./hooks/useHdrToSdr.js";
+export * from "./hooks/useProgress.js";
+export * from "./legal/legalConfig.js";
+export * from "./lib/assemble.js";
+export * from "./lib/asset.js";
+export * from "./lib/dialog.js";
+export * from "./lib/genright.js";
+export * from "./lib/mediaAdapters.js";
+export * from "./lib/mic.js";
+export * from "./lib/models.js";
+export * from "./lib/modelsBackend.js";
+export * from "./lib/services.js";
+export * from "./lib/settingsBackend.js";
+export * from "./lib/shell.js";
+export * from "./ui/icons.js";
+export * from "./views/AssetsView.js";
+export * from "./views/AutoEditView.js";
+export * from "./views/BatchDelivery.js";
+export * from "./views/BundleExport.js";
+export * from "./views/ExportsView.js";
+export * from "./views/Home.js";
+export * from "./views/OnboardingGate.js";
+export * from "./views/PhrasesView.js";
+export * from "./views/ProgressView.js";
+export * from "./views/PromptPanel.js";
+export * from "./views/RecipeLibrary.js";
+export * from "./views/RetentionView.js";
+export * from "./views/SettingsView.js";
+export * from "./views/ShortsView.js";
+export * from "./views/SourcesView.js";
+export * from "./views/TimelineView.js";

package/dist/legal/legalConfig.d.ts

@@ -0,0 +1,38 @@
+import type { LegalStepConfig } from "@rightkit/onboarding";
+/**
+ * the host app facts for the suite legal gate, sourced from its legal/legal-manifest.json and generated
+ * src/generated/legal-contract.json, never hardcoded, so a title, URL or document change cannot drift from the gate.
+ * A published package cannot import files of the app that installs it: the host calls configureLegal() once at
+ * startup. ES module exports are live bindings, so every importer sees the configured values.
+ */
+export interface LegalContract {
+    acceptanceVersion: string;
+    materialSha256: string;
+    [key: string]: unknown;
+}
+/** Version the stored acceptance must match; a document change re-prompts. */
+export declare let REQUIRED_LEGAL_ACCEPTANCE_VERSION: string;
+/** Hash of the agreed (material) documents, recorded with the acceptance. */
+export declare let LEGAL_MATERIAL_SHA256: string;
+export interface LegalDocumentText {
+    title: string;
+    text: string;
+}
+/** The bundled copy of a shipped legal document (offline, exactly what was hashed). */
+export declare function legalDocumentText(file: string): string;
+/** Every document the user agrees to or acknowledges (not the build-provenance notices). */
+export declare let LEGAL_GATE_DOCUMENTS: {
+    title: string;
+    url: string;
+    path: string;
+}[];
+/**
+ * Called once by the host at startup with its manifest, contract and the bundled legal texts keyed by file name
+ * (a Vite host: `import.meta.glob("/legal/*.md", { query: "?raw", import: "default", eager: true })`).
+ */
+export declare function configureLegal({ manifest, contract, texts }: {
+    manifest: unknown;
+    contract: LegalContract;
+    texts?: Record<string, string>;
+}): void;
+export declare function legalStepConfig(): LegalStepConfig;

package/dist/legal/legalConfig.js

@@ -0,0 +1,77 @@
+import { assertLegalManifest } from "@rightkit/legal/browser";
+import { exit } from "@tauri-apps/plugin-process";
+import { logs } from "../lib/services.js";
+import { quitNow } from "../lib/shell.js";
+import { hostAppName } from "../appName.js";
+/** Version the stored acceptance must match; a document change re-prompts. */
+export let REQUIRED_LEGAL_ACCEPTANCE_VERSION;
+/** Hash of the agreed (material) documents, recorded with the acceptance. */
+export let LEGAL_MATERIAL_SHA256;
+// Suite-wide master titles are long; the gate list shows short ones.
+const SHORT_TITLES = {
+    license: "License",
+    eula: "End User License Agreement",
+    acceptable_use: "Acceptable Use Policy",
+};
+let TEXTS = {};
+/** The bundled copy of a shipped legal document (offline, exactly what was hashed). */
+export function legalDocumentText(file) {
+    return TEXTS[file.split("/").pop() ?? file] ?? "";
+}
+/** Every document the user agrees to or acknowledges (not the build-provenance notices). */
+export let LEGAL_GATE_DOCUMENTS = [];
+/**
+ * Called once by the host at startup with its manifest, contract and the bundled legal texts keyed by file name
+ * (a Vite host: `import.meta.glob("/legal/*.md", { query: "?raw", import: "default", eager: true })`).
+ */
+export function configureLegal({ manifest, contract, texts = {} }) {
+    const m = assertLegalManifest(manifest);
+    if (typeof contract?.acceptanceVersion !== "string" || typeof contract?.materialSha256 !== "string") {
+        throw new TypeError("configureLegal: the contract needs acceptanceVersion and materialSha256 strings");
+    }
+    REQUIRED_LEGAL_ACCEPTANCE_VERSION = contract.acceptanceVersion;
+    LEGAL_MATERIAL_SHA256 = contract.materialSha256;
+    TEXTS = Object.fromEntries(Object.entries(texts).map(([k, v]) => [k.split("/").pop() ?? k, v]));
+    LEGAL_GATE_DOCUMENTS = m.documents
+        .filter((d) => d.role !== "third_party_notices")
+        .map((d) => ({ title: SHORT_TITLES[d.role] ?? d.title, url: d.publicUrl, path: String(d.path ?? "") }));
+}
+export function legalStepConfig() {
+    return {
+        appName: hostAppName(),
+        trustLine: `${hostAppName()} edits your footage on this computer. Your media is never uploaded by ${hostAppName()}.`,
+        // Each link expands the bundled copy inline in the gate: it works offline and is the exact text agreed to.
+        documents: LEGAL_GATE_DOCUMENTS.map((d) => ({
+            title: d.title,
+            url: d.url,
+            content: legalDocumentText(d.path),
+            contentFormat: "markdown",
+        })),
+        agreementStatement: `I have read and agree to the ${hostAppName()} Desktop License, End User License Agreement, Acceptable Use Policy, and Product Schedule, and I acknowledge the Privacy Notice.`,
+        // The suite gate is light-only: suite ivory base with the host app AA light accent.
+        theme: {
+            bg: "#FBF7EF",
+            surface: "#FFFCF5",
+            border: "#E6DECF",
+            text: "#231F1A",
+            muted: "#6B655C",
+            accent: "#0C9A43",
+            accentContrast: "#1A1208",
+            fontDisplay: "Tanker, 'Arial Narrow', sans-serif",
+            fontBody: "Author, -apple-system, BlinkMacSystemFont, sans-serif",
+        },
+        wordmarkFontUrl: "/fonts/Tanker-400.woff2",
+        // Declining quits the app. The gate stays in front until the process is gone, so no
+        // unaccepted UI is reachable. Both paths end in the host's RunEvent::Exit cleanup.
+        onQuit: async () => {
+            try {
+                await quitNow();
+            }
+            catch {
+                logs.error("legal_decline_quit_failed", { surface: "legal" });
+                await logs.flush().catch(() => undefined);
+                await exit(0);
+            }
+        },
+    };
+}

package/dist/lib/assemble.d.ts

@@ -0,0 +1,100 @@
+export type ShotInput = {
+    prompt?: string;
+    kind: "video" | "image";
+    duration_s: number;
+    provider: string;
+    model: string;
+    params?: Record<string, unknown>;
+};
+export type NarrationInput = {
+    text: string;
+    provider: string;
+    model: string;
+    voice?: string;
+};
+/** TitleSpec: the template fields (`template` tag + its text fields) flattened beside timing. */
+export type TitleInput = ({
+    template: "lower_third";
+    title: string;
+    subtitle?: string;
+} | {
+    template: "centered";
+    text: string;
+} | {
+    template: "caption";
+    text: string;
+}) & {
+    start_s: number;
+    duration_s: number;
+    fade_in_s?: number;
+    fade_out_s?: number;
+};
+export type AssembleInput = {
+    prompt: string;
+    assemble_id: string;
+    shots: ShotInput[];
+    narration?: NarrationInput;
+    titles?: TitleInput[];
+    preset: "youtube" | "reels";
+    encoder?: string;
+    render: boolean;
+    out?: string;
+};
+/** What the form holds; titles keep one editable text field plus an optional subtitle. */
+export type TitleDraft = {
+    template: "lower_third" | "centered" | "caption";
+    text: string;
+    subtitle: string;
+    start_s: number;
+    duration_s: number;
+};
+export type AssembleForm = {
+    prompt: string;
+    shots: ShotInput[];
+    narration: {
+        text: string;
+        provider: string;
+        model: string;
+        voice: string;
+    } | null;
+    titles: TitleDraft[];
+    preset: "youtube" | "reels";
+    render: boolean;
+};
+/** assemble_id: letters, digits, '-' or '_' (max 64). */
+export declare function newAssembleId(): string;
+export declare function titleInput(t: TitleDraft): TitleInput;
+export declare function buildAssembleInput(form: AssembleForm, assembleId: string): AssembleInput;
+/** The `assemble.status` result for one assemble id. */
+export type AssembleStatus = {
+    assemble_id: string;
+    /** running | done | failed | cancelled */
+    status: string;
+    stage: string;
+    error: {
+        code?: string;
+        message?: string;
+    } | null;
+    timeline_built: boolean;
+    render: {
+        output?: string;
+    } | null;
+    /** false when the stored render's output file is missing or no render was stored; absent on an older engine. */
+    render_exists?: boolean;
+    requests: {
+        item: string;
+        request_id: string;
+        state: string | null;
+        job_id: string | null;
+        imported: boolean;
+    }[];
+    updated: number;
+};
+export type PendingAssemble = {
+    assembleId: string;
+    input: AssembleInput;
+    startedAt: number;
+};
+export declare function loadPending(dir: string): PendingAssemble | null;
+export declare function savePending(dir: string, pending: PendingAssemble): void;
+export declare function clearPending(dir: string): void;

package/dist/lib/assemble.js

@@ -0,0 +1,72 @@
+// Request/response shapes of `assemble`, exactly as `AssembleInput` deserializes
+// (crates/cutright-engine/src/genright_cmd.rs; every struct there is deny_unknown_fields
+// except TitleSpec, whose flattened TitleTemplate is).
+/** assemble_id: letters, digits, '-' or '_' (max 64). */
+export function newAssembleId() {
+    const rand = Math.random().toString(36).slice(2, 8);
+    return `a-${Date.now().toString(36)}-${rand}`;
+}
+export function titleInput(t) {
+    const timing = { start_s: t.start_s, duration_s: t.duration_s };
+    const text = t.text.trim();
+    if (t.template === "lower_third") {
+        const subtitle = t.subtitle.trim();
+        return { template: "lower_third", title: text, ...(subtitle ? { subtitle } : {}), ...timing };
+    }
+    return { template: t.template, text, ...timing };
+}
+export function buildAssembleInput(form, assembleId) {
+    const input = {
+        prompt: form.prompt.trim(),
+        assemble_id: assembleId,
+        shots: form.shots.map((s) => ({
+            ...(s.prompt?.trim() ? { prompt: s.prompt.trim() } : {}),
+            kind: s.kind,
+            duration_s: s.duration_s,
+            provider: s.provider,
+            model: s.model,
+        })),
+        preset: form.preset,
+        render: form.render,
+    };
+    const n = form.narration;
+    if (n && n.text.trim()) {
+        input.narration = {
+            text: n.text.trim(),
+            provider: n.provider,
+            model: n.model,
+            ...(n.voice.trim() ? { voice: n.voice.trim() } : {}),
+        };
+    }
+    if (form.titles.length > 0)
+        input.titles = form.titles.map(titleInput);
+    return input;
+}
+const key = (dir) => `cutright.assemble.${dir}`;
+export function loadPending(dir) {
+    try {
+        const v = JSON.parse(localStorage.getItem(key(dir)) ?? "null");
+        if (v && typeof v.assembleId === "string" && v.input && typeof v.input === "object")
+            return v;
+    }
+    catch {
+        /* unavailable or corrupt */
+    }
+    return null;
+}
+export function savePending(dir, pending) {
+    try {
+        localStorage.setItem(key(dir), JSON.stringify(pending));
+    }
+    catch {
+        /* ignore */
+    }
+}
+export function clearPending(dir) {
+    try {
+        localStorage.removeItem(key(dir));
+    }
+    catch {
+        /* ignore */
+    }
+}

package/dist/lib/asset.d.ts

@@ -0,0 +1,2 @@
+/** URL for a local file (thumbnail, source, render) inside the Tauri webview. */
+export declare const assetUrl: (path: string) => string;

package/dist/lib/asset.js

@@ -0,0 +1,3 @@
+import { convertFileSrc } from "@tauri-apps/api/core";
+/** URL for a local file (thumbnail, source, render) inside the Tauri webview. */
+export const assetUrl = (path) => convertFileSrc(path);

package/dist/lib/dialog.d.ts

@@ -0,0 +1,4 @@
+export declare function pickFolder(title: string): Promise<string | null>;
+export declare function pickMedia(): Promise<string[]>;
+/** Pick one file (e.g. a retention CSV export). `extensions: null` = no filter. */
+export declare function pickFile(title: string, extensions: string[] | null): Promise<string | null>;

package/dist/lib/dialog.js

@@ -0,0 +1,44 @@
+import { pickFile as rkPickFile, pickFiles as rkPickFiles, pickFolder as rkPickFolder } from "@rightkit/tauri/dialog";
+/**
+ * The rightkit-qa suite answers native dialogs through the in-app control
+ * server (served only when the QA launcher enables it): it sets this value and
+ * the next dialog returns it instead of opening an OS sheet. Release builds compile it out.
+ * The pickers are @rightkit/tauri/dialog; it has no QA answer source (its README: an app's QA answers
+ * pickers in its own seam), so this seam stays until RightKit ships one (see the exception ledger).
+ */
+function qaAnswer() {
+    if (!(typeof __RIGHTKIT_QA__ === "boolean" && __RIGHTKIT_QA__))
+        return undefined;
+    return window.__RIGHTKIT_QA_DIALOG__;
+}
+export async function pickFolder(title) {
+    const qa = qaAnswer();
+    if (qa !== undefined)
+        return typeof qa === "string" ? qa : null;
+    return rkPickFolder({ title });
+}
+export async function pickMedia() {
+    const qa = qaAnswer();
+    if (qa !== undefined)
+        return qa === null ? [] : Array.isArray(qa) ? qa : [qa];
+    const picked = await rkPickFiles({
+        title: "Add media",
+        filters: [
+            {
+                name: "Media",
+                extensions: ["mp4", "mov", "mkv", "webm", "m4v", "png", "jpg", "jpeg", "webp", "wav", "mp3", "m4a", "flac"],
+            },
+        ],
+    });
+    return picked ?? [];
+}
+/** Pick one file (e.g. a retention CSV export). `extensions: null` = no filter. */
+export async function pickFile(title, extensions) {
+    const qa = qaAnswer();
+    if (qa !== undefined)
+        return typeof qa === "string" ? qa : null;
+    return rkPickFile({
+        title,
+        filters: extensions && extensions.length > 0 ? [{ name: "Files", extensions }] : undefined,
+    });
+}

package/dist/lib/engine.d.ts

@@ -0,0 +1,44 @@
+import type { EngineEvent as ShellEngineEvent } from "@rightkit/tauri-shell";
+import type { EngineFrame } from "./progress.js";
+export type EngineState = "starting" | "ready" | "restarting" | "failed" | "stopped";
+export type EngineHello = {
+    engine: string;
+    version: string;
+    contract_version: number;
+};
+export type EngineStatus = {
+    state: EngineState;
+    hello: EngineHello | null;
+    restarts: number;
+    last_error: string | null;
+};
+export type DoctorCheck = {
+    id?: string;
+    name?: string;
+    status?: string;
+    detail?: string;
+    message?: string;
+};
+export type DoctorReport = {
+    readiness?: {
+        status?: string;
+        checks?: DoctorCheck[];
+    };
+};
+export declare const engineStatus: () => Promise<EngineStatus>;
+export declare const engineDoctor: () => Promise<DoctorReport>;
+export type EngineCallError = {
+    code: string;
+    message: string;
+    origin: "supervisor" | "engine";
+};
+export declare const engineBusy: () => boolean;
+export declare function engineCall<T = unknown>(method: string, params?: Record<string, unknown>, tag?: string): Promise<T>;
+export declare const revealPath: (path: string) => Promise<void>;
+export type { EngineEvent, EngineFrame } from "./progress.js";
+/** Every engine event payload (`{call, id, tag, event}`), lifecycle frames included. */
+export declare const onEngineRaw: (handler: (payload: ShellEngineEvent) => void) => Promise<() => void>;
+/** Frames are `{id: engine request id, tag: the caller's tag for that call, event}`. */
+export declare function onEngineEvent(handler: (frame: EngineFrame) => void): Promise<() => void>;
+export declare function errorCode(error: unknown): string | undefined;
+export declare function errorMessage(error: unknown): string;