@clickless/react 0.0.0-stage → 0.1.0

package/dist/engine/engineClient.d.ts

@@ -0,0 +1,231 @@
+import type { Action, Manifest, Operation, OperationError } from "../core/index.js";
+/**
+ * How a previewed change from a prompt ended without being kept: the user
+ * chose not to keep it, or it left the screen before they chose.
+ */
+export type PreviewNotKeptOutcome = "discarded" | "abandoned";
+/** Which way a page's text, and so its rows, run. */
+export type TextDirection = "ltr" | "rtl";
+/** An earlier request on the screen and the reply it got, with what came of it. */
+export interface ConversationTurn {
+    request: string;
+    reply: string;
+}
+import { type ActionRunRecorded, type ActionRunsPage, type LayoutResponse, type PlanAcrossRegionsResponse, type PlanResponse, type RegionLayoutsResponse, type UndoAcrossRegionsResponse, type UndoLayoutResponse, type DiscardResponse, type FeaturesResponse, type TranscriptionResponse, type HistoryPage } from "./engineResponses.js";
+export interface EngineOptions {
+    /**
+     * Base URL of the ClickLess engine, without a trailing slash. It must start
+     * with `https://`, or `http://` for this machine only (`localhost`,
+     * `127.0.0.1`, `[::1]` or a `.localhost` name): at any other address nothing
+     * is sent.
+     */
+    url: string;
+    /**
+     * Returns the token your backend signed for the current user. Called before
+     * every request, so it can refresh an expired token.
+     */
+    getToken: () => string | Promise<string>;
+    fetch?: typeof fetch;
+}
+/**
+ * A change the user is looking at and has not kept, sent with a prompt typed
+ * meanwhile, which is then planned from it.
+ */
+export interface PreviewToPlanFrom {
+    /** Applied, in order, to the saved layout the preview was made on. */
+    operations: readonly Operation[];
+    /** The revision the preview was made on. If the saved layout has changed since, nothing is planned. */
+    baseRevision: number;
+}
+/** A region as the screen last saw it, so the engine can tell when it has changed since. */
+export interface RegionAsLastSeen {
+    regionId: string;
+    baseRevision: number;
+}
+export declare class EngineError extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly errors?: OperationError[] | undefined;
+    /** For a change across several regions: the ones that had changed elsewhere. */
+    readonly regionIds?: readonly string[];
+    constructor(message: string, status: number, code: string, errors?: OperationError[] | undefined, errorOptions?: ErrorOptions & {
+        regionIds?: readonly string[];
+    });
+}
+/**
+ * True when the error says the engine could not be reached or could not answer
+ * properly: no connection, an address it may not be called at, no answer in
+ * time, no token from the host, a reply that is not the engine's, or a fault on
+ * the engine's side.
+ */
+export declare function isEngineUnavailable(error: unknown): boolean;
+/**
+ * True when the same request may well succeed later: the engine was
+ * unavailable or busy, the user's sign-in was refused (a fresh token may be
+ * accepted), or it asked for a pause. A 403 is not among them: the sign-in was
+ * accepted but the user has no permission, which asking again will not change.
+ * Anything that is not an `EngineError` is counted too,
+ * so nothing unexpected throws away a change for good.
+ */
+export declare function isWorthRetrying(error: unknown): boolean;
+/** The error for an engine that could not be reached at all. */
+export declare function engineUnreachableError(cause?: unknown): EngineError;
+/** The engine, for something that cannot be done without one. */
+export declare function requireEngine(engine: EngineClient | null, actionDescription: string): EngineClient;
+export declare class EngineClient {
+    private readonly engineOptions;
+    private readonly userId?;
+    private engineReachable;
+    private reachabilityListeners;
+    private tokenForAnotherUserReported;
+    private insecureUrlReported;
+    private tenantId;
+    /**
+     * `userId` is the user every request is made for. A token the host gives for
+     * anyone else, or for them in a tenant other than the first token's, is
+     * never sent: `getToken` gives the token of whoever is signed in when it
+     * answers, which, for a request made just before another user signed in,
+     * is not the user it was made for.
+     */
+    constructor(engineOptions: EngineOptions, userId?: string | undefined);
+    /**
+     * False from the moment a request finds the engine unavailable until one
+     * gets an answer from it again. True until anything has been asked.
+     */
+    get isReachable(): boolean;
+    subscribeToReachability: (reachabilityListener: () => void) => (() => void);
+    private setReachable;
+    readLayout(regionId: string): Promise<LayoutResponse>;
+    applyOperations(regionId: string, revisionRequest: {
+        manifest: Manifest;
+        operations: readonly Operation[];
+        prompt?: string;
+        message?: string;
+        baseRevision: number;
+        viaVoice?: boolean;
+    }): Promise<LayoutResponse>;
+    restoreRevision(regionId: string, revision: number, baseRevision: number): Promise<LayoutResponse>;
+    readHistory(regionId: string, pageOptions: {
+        limit: number;
+        before?: number;
+        promptedOnly?: boolean;
+    }): Promise<HistoryPage>;
+    undoLastChange(regionId: string, baseRevision: number): Promise<UndoLayoutResponse>;
+    /** Tells the engine a change it planned for a prompt was previewed and not kept. */
+    reportDiscardedPreview(regionId: string, discardReport: {
+        manifestVersion: string;
+        prompt: string;
+        message: string;
+        operations: readonly Operation[];
+        viaVoice?: boolean;
+        /** "abandoned" when the preview left the screen before the user chose. Defaults to "discarded". */
+        outcome?: PreviewNotKeptOutcome;
+    }): Promise<DiscardResponse>;
+    planFromPrompt(regionId: string, planRequest: {
+        manifest: Manifest;
+        prompt: string;
+        viaVoice?: boolean;
+        /** Which way the page reads, so "left" and "right" mean what the user sees. Defaults to "ltr". */
+        textDirection?: TextDirection;
+        /** The columns this screen draws the layout in, when fewer than the manifest's. */
+        drawnColumns?: number;
+        /** The preview on the screen, if any: the answer is what the prompt changes from it. */
+        preview?: PreviewToPlanFrom;
+    }): Promise<PlanResponse>;
+    /** `planFromPrompt` for several regions of one screen, planned together in one request. */
+    planAcrossRegions(planRequest: {
+        regions: {
+            manifest: Manifest;
+            /** The columns this screen draws the region in, when fewer than its manifest's. */
+            drawnColumns?: number;
+            /** This region's part of the preview on the screen, if any. */
+            preview?: PreviewToPlanFrom;
+        }[];
+        prompt: string;
+        viaVoice?: boolean;
+        /** What the screen offers to do for the user. There may then be no regions. */
+        actions?: readonly Action[];
+        /** Earlier requests on the screen and their replies, oldest first. */
+        conversation?: readonly ConversationTurn[];
+        /** Files the user attached: their names and types only. */
+        attachedFiles?: readonly {
+            name: string;
+            type: string;
+        }[];
+        /** What a missed request is recorded under when no region is on the screen. */
+        screenId?: string;
+        /** Which way the page reads, so "left" and "right" mean what the user sees. Defaults to "ltr". */
+        textDirection?: TextDirection;
+    }): Promise<PlanAcrossRegionsResponse>;
+    /** Saves one change to several regions: every region's part is stored, or none is. */
+    saveChangeAcrossRegions(changeRequest: {
+        regions: {
+            manifest: Manifest;
+            operations: readonly Operation[];
+            baseRevision: number;
+        }[];
+        prompt?: string;
+        message?: string;
+        viaVoice?: boolean;
+    }): Promise<RegionLayoutsResponse>;
+    /** Undoes the latest change among these regions, in each of them it reached. */
+    undoAcrossRegions(regions: RegionAsLastSeen[]): Promise<UndoAcrossRegionsResponse>;
+    /** Returns these regions to how they were after the change `changeId`; 0 is before any. */
+    restoreAcrossRegions(changeId: number, regions: RegionAsLastSeen[]): Promise<RegionLayoutsResponse>;
+    /** The history of several regions as one list. Each entry's `revision` is its change's number. */
+    readChanges(regionIds: readonly string[], pageOptions: {
+        limit: number;
+        before?: number;
+        promptedOnly?: boolean;
+    }): Promise<HistoryPage>;
+    /** `reportDiscardedPreview` for a preview that changed several regions. */
+    reportDiscardedAcrossRegions(discardReport: {
+        prompt: string;
+        message: string;
+        regions: {
+            regionId: string;
+            manifestVersion: string;
+            operations: readonly Operation[];
+        }[];
+        viaVoice?: boolean;
+        outcome?: PreviewNotKeptOutcome;
+    }): Promise<DiscardResponse>;
+    /**
+     * Notes that the user ran an action, or turned it down, and how it ended.
+     * Only the names of the fields it was given are sent, never their values.
+     */
+    recordActionRun(actionRunReport: {
+        screenId: string;
+        actionName: string;
+        actionTitle: string;
+        /** Whether it changed something, or only what was shown. */
+        mode: "read" | "write";
+        parameterNames: readonly string[];
+        outcome: "done" | "failed" | "cancelled";
+        viaVoice?: boolean;
+    }): Promise<ActionRunRecorded>;
+    /** The signed-in user's own action runs on one screen, newest first. */
+    readActionRuns(screenId: string, pageOptions: {
+        limit: number;
+    }): Promise<ActionRunsPage>;
+    /** What the engine is set up to do, so only what will work is offered. */
+    readFeatures(): Promise<FeaturesResponse>;
+    /**
+     * Turns a recording of a spoken prompt into text. `vocabularyHints` are names
+     * likely to be spoken, such as the titles on the screen.
+     */
+    transcribeRecording(recording: Blob, vocabularyHints?: readonly string[]): Promise<TranscriptionResponse>;
+    private sendRegionRequest;
+    private sendJsonRequest;
+    private sendRequest;
+    /**
+     * One request, given up on once `timeoutMs` has passed since it began,
+     * whatever it is waiting on then: the host's token, the answer, or the
+     * reading of its body. Nothing waits on the engine for longer.
+     */
+    private sendRequestOnce;
+    /** The request itself, from asking for the token to reading the answer, stopped by `timeoutSignal`. */
+    private sendRequestWithin;
+    private refuseTokenForAnotherAccount;
+    private throwEngineError;
+}

package/dist/engine/engineErrorMessages.d.ts

@@ -0,0 +1,13 @@
+/** Said to the user when a change they previewed can no longer be made. */
+export declare const PREVIEW_NO_LONGER_FITS_MESSAGE = "That change no longer fits this screen. Please try again.";
+/** Said when a change would leave a part of the screen with nothing on it. */
+export declare const WOULD_EMPTY_PAGE_MESSAGE = "That would leave this page empty, so nothing was changed.";
+/** Said when the engine cannot be reached, or cannot answer, so nothing can be personalised for now. */
+export declare const ENGINE_UNAVAILABLE_MESSAGE = "Personalising isn't available right now. Please try again in a little while.";
+/** Said when a recording held no speech that could be made out. */
+export declare const NOTHING_HEARD_MESSAGE = "We couldn't hear anything. Please try again.";
+/**
+ * A sentence for the person using the application. The engine's own error text
+ * is written for developers, so none of it is passed through.
+ */
+export declare function describeError(error: unknown): string;

package/dist/engine/engineResponses.d.ts

@@ -0,0 +1,201 @@
+import { ActionCall, Operation, type Layout, type OperationError } from "../core/index.js";
+export interface LayoutResponse {
+    revision: number;
+    /** null means the default layout. */
+    layout: Layout | null;
+    /** Whether the latest saved change can be undone. Absent from engines that do not say. */
+    canUndo?: boolean;
+    /**
+     * The number of the change that made this revision, counted across all of the
+     * user's regions. 0 when the region was never changed. Absent from engines
+     * that cannot change several regions at once.
+     */
+    changeId?: number;
+}
+/** A region's layout in an answer that carries several. */
+export interface RegionLayoutResponse extends LayoutResponse {
+    regionId: string;
+}
+export interface RegionLayoutsResponse {
+    regions: RegionLayoutResponse[];
+}
+/** The change an undo took back. */
+export interface UndoneChange {
+    /** `restore` went back to an earlier version of the screen. */
+    kind: "apply" | "restore";
+    /** What the user asked for. Null for a change made with the application's own controls. */
+    prompt: string | null;
+    /** From several regions, every region's, one region after another. */
+    operations: Operation[];
+}
+/**
+ * What an undo answers. `notUndoneIn` names the regions the undone change also
+ * reached that keep their part of it, because they changed again since.
+ * `undone` is the change taken back, null when the engine cannot tell which.
+ * Both are absent from engines that do not say. The undo has happened whatever
+ * `undone` holds, so it is read with care rather than checked with the rest.
+ */
+export interface UndoLayoutResponse extends LayoutResponse {
+    notUndoneIn?: string[];
+    undone?: UndoneChange | null;
+}
+/** `UndoLayoutResponse` for an undo across several regions. */
+export interface UndoAcrossRegionsResponse extends RegionLayoutsResponse {
+    notUndoneIn?: string[];
+    undone?: UndoneChange | null;
+}
+/** What the planner proposes for a prompt sent for several regions. */
+export interface PlanAcrossRegionsResponse {
+    /** Only the regions that change. */
+    changes: {
+        regionId: string;
+        operations: Operation[];
+    }[];
+    /** The actions to run, in order. Absent from engines that offer none. */
+    actionCalls?: ActionCall[];
+    message: string;
+}
+export interface PlanResponse {
+    operations: Operation[];
+    message: string;
+}
+export interface DiscardResponse {
+    /** False when the engine is set to keep no such records. */
+    recorded: boolean;
+}
+export interface FeaturesResponse {
+    /** Whether the engine can turn a spoken prompt into text. */
+    dictation: boolean;
+}
+export interface TranscriptionResponse {
+    /** What was said. Empty when nothing could be made out, or when it seemed to hold a secret. */
+    text: string;
+    /**
+     * Given only when what was said is not given back, such as when it seems to
+     * hold a password or card number: what to tell the user instead.
+     */
+    message?: string;
+}
+export interface HistoryEntry {
+    /**
+     * Which point in the history this is: pass it to `restoreRevision`. From one
+     * region's history it is that region's revision. From a history of several
+     * regions it is the change's own number, the same as `changeId`.
+     */
+    revision: number;
+    /**
+     * Only in a history of several regions: the number of the change, counted
+     * across all of the user's regions. Its presence says that `revision` holds
+     * this number and not a region's revision.
+     */
+    changeId?: number;
+    /** `apply` is a change; `undo` and `restore` returned to an earlier layout. */
+    kind: "apply" | "undo" | "restore";
+    /** What the user asked for. Null for changes made with the application's own controls. */
+    prompt: string | null;
+    /** What the planner replied. */
+    message: string | null;
+    operations: Operation[];
+    createdAt: string;
+    /**
+     * From a history of several regions: what the change did in each region it
+     * reached. `revision` is then the number of the change as a whole, and
+     * `operations` holds every region's, one region after another.
+     */
+    regions?: {
+        regionId: string;
+        revision: number;
+        operations: Operation[];
+    }[];
+}
+export interface HistoryPage {
+    /** Newest first. */
+    revisions: HistoryEntry[];
+    hasMore: boolean;
+}
+export declare function isLayoutResponse(responseBody: unknown): responseBody is LayoutResponse;
+export declare function isPlanResponse(responseBody: unknown): responseBody is PlanResponse;
+export declare function isPlanAcrossRegionsResponse(responseBody: unknown): responseBody is PlanAcrossRegionsResponse;
+export declare function isRegionLayoutsResponse(responseBody: unknown): responseBody is RegionLayoutsResponse;
+export declare function isUndoLayoutResponse(responseBody: unknown): responseBody is UndoLayoutResponse;
+export declare function isUndoAcrossRegionsResponse(responseBody: unknown): responseBody is UndoAcrossRegionsResponse;
+export declare function isDiscardResponse(responseBody: unknown): responseBody is DiscardResponse;
+export declare function isFeaturesResponse(responseBody: unknown): responseBody is FeaturesResponse;
+export declare function isTranscriptionResponse(responseBody: unknown): responseBody is TranscriptionResponse;
+/** A history entry as the engine sends it, before what it says is made safe to show. */
+interface EngineHistoryEntry {
+    revision: number;
+    createdAt: string;
+    kind?: unknown;
+    prompt?: unknown;
+    message?: unknown;
+    operations: unknown[];
+}
+/** One region's history as the engine sends it. */
+export interface EngineHistoryPage {
+    /** Newest first. */
+    revisions: EngineHistoryEntry[];
+    hasMore: boolean;
+}
+export declare function isEngineHistoryPage(responseBody: unknown): responseBody is EngineHistoryPage;
+/** One region's history with what is shown made safe to show. */
+export declare function historyPageFromEngine(enginePage: EngineHistoryPage): HistoryPage;
+/** The engine's history of several regions, as it sends it. */
+export interface ChangesPage {
+    /** Newest first. */
+    changes: {
+        changeId: number;
+        kind?: unknown;
+        prompt?: unknown;
+        message?: unknown;
+        createdAt: string;
+        regions: {
+            regionId: string;
+            revision: number;
+            operations: unknown[];
+        }[];
+    }[];
+    hasMore: boolean;
+}
+export declare function isChangesPage(responseBody: unknown): responseBody is ChangesPage;
+/** A history of several regions in the same shape as one region's, one entry per change, made safe to show. */
+export declare function historyPageFromChanges(changesPage: ChangesPage): HistoryPage;
+/** What the engine said went wrong: the `detail` of an error reply. */
+export interface ErrorDetail {
+    code?: string;
+    message?: string;
+    errors?: OperationError[];
+    /** For a request that named several regions: the ones that had changed elsewhere. */
+    regionIds?: string[];
+}
+/**
+ * The `detail` of an error reply, keeping only the fields of the kind the engine
+ * sends: a reply that is not the engine's can hold anything. Empty when `detail`
+ * is not an object, as for the plain sentence the engine sends for a missing or
+ * rejected token.
+ */
+export declare function readErrorDetail(responseBody: unknown): ErrorDetail;
+/** An action the user ran or turned down, as the engine keeps it: never the values it was given. */
+export interface ActionRunEntry {
+    id: number;
+    actionName: string;
+    actionTitle: string;
+    /** `read` only changed what was shown, such as opening a page. */
+    actionMode: "read" | "write";
+    /** The names of the fields it was given. */
+    parameterNames: string[];
+    outcome: "done" | "failed" | "cancelled";
+    createdAt: string;
+}
+export interface ActionRunsPage {
+    /** Newest first. */
+    runs: ActionRunEntry[];
+    hasMore: boolean;
+}
+export interface ActionRunRecorded {
+    recorded: boolean;
+    id?: number;
+}
+export declare function isActionRunsPage(responseBody: unknown): responseBody is ActionRunsPage;
+export declare function isActionRunRecorded(responseBody: unknown): responseBody is ActionRunRecorded;
+export {};

package/dist/engine/plainReplies.d.ts

@@ -0,0 +1,2 @@
+/** Said when a prompt came back with nothing to change, nothing to do and nothing said. As the engine says it. */
+export declare const NOTHING_UNDERSTOOD_MESSAGE = "I couldn't work out what to change. Could you say it another way?";

package/dist/hooks/useActionRunHistory.d.ts

@@ -0,0 +1,12 @@
+import type { ActionRunEntry } from "../engine/engineResponses.js";
+/**
+ * For the prompt panel: the signed-in user's latest action runs on a screen, newest first, read from
+ * the engine: what they did, never with what values. Read again whenever
+ * `refreshKey` changes, such as after a run is recorded. Empty without an
+ * engine, or when it cannot be read: a past list is never worth an error.
+ */
+export declare function useActionRunHistory(screenId: string, { enabled, limit, refreshKey }?: {
+    enabled?: boolean;
+    limit?: number;
+    refreshKey?: number;
+}): readonly ActionRunEntry[];

package/dist/hooks/useAdaptiveAction.d.ts

@@ -0,0 +1,11 @@
+import { type ActionDefinition } from "../actions/actionRegistry.js";
+/**
+ * Offers an action while the calling component is mounted: something the
+ * application can do for its user when they ask, such as changing their name
+ * or opening a customer's record. The prompt panel then asks the planner for it
+ * when a request calls for it, asks the user to confirm a `write`, and calls
+ * `run`, which makes the request with the user's own sign-in.
+ *
+ * `run` and `confirm` may be new functions on every render: the latest are used.
+ */
+export declare function useAdaptiveAction(definition: ActionDefinition): void;

package/dist/hooks/useAdaptiveRegion.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Reads a region's manifest and layout and returns the functions that change it.
+ * Works anywhere inside `AdaptiveProvider`, including outside the region itself.
+ * Outside the provider it reads the region it sits in, or, outside that
+ * region too, an empty one of its own whose changes reach nothing on screen.
+ */
+export declare function useAdaptiveRegion(regionId: string): {
+    manifest: import("../core/index.js").Manifest | null;
+    layout: import("../core/index.js").Layout | null;
+    preview: import("../core/index.js").Layout | null;
+    original: import("../core/index.js").Layout | null;
+    differsFromOriginal: boolean;
+    changedComponentIds: ReadonlySet<string>;
+    savedLayoutAdjustments: readonly import("../core/index.js").LayoutChange[];
+    loading: boolean;
+    loadFailed: boolean;
+    canUndo: boolean;
+    revision: number;
+    hasHistory: boolean;
+    hasUnsavedChanges: boolean;
+    applyOperations: (operations: readonly import("../core/index.js").Operation[], prompt?: string, message?: string, viaVoice?: boolean) => Promise<import("../core/index.js").ApplyOperationsOutcome>;
+    previewOperations: (operations: readonly import("../core/index.js").Operation[], prompt?: string, message?: string, viaVoice?: boolean) => import("../core/index.js").ApplyOperationsOutcome;
+    commitPreview: () => Promise<import("../core/index.js").ApplyOperationsOutcome | null>;
+    cancelPreview: () => void;
+    discardPreview: () => void;
+    undoLastChange: () => Promise<import("../index.js").UndoResult>;
+    planFromPrompt: (prompt: string, viaVoice?: boolean) => Promise<import("../engine/engineResponses.js").PlanResponse>;
+    restoreRevision: (revision: number) => Promise<number>;
+    readHistory: (options: {
+        limit: number;
+        before?: number;
+        promptedOnly?: boolean;
+    }) => Promise<import("../engine/engineResponses.js").HistoryPage>;
+};

package/dist/hooks/useChangeHistory.d.ts

@@ -0,0 +1,32 @@
+import type { Manifest } from "../core/index.js";
+import type { HistoryEntry } from "../engine/engineResponses.js";
+export interface ChangeHistoryOptions {
+    /** How many entries to hold at first, and to load each time. Default 5. */
+    pageSize?: number;
+    /**
+     * `prompts` (the default) lists only changes the user asked for in words,
+     * which reads as a conversation. `all` also lists changes made with the
+     * application's own controls, undos and restores.
+     */
+    include?: "prompts" | "all";
+}
+/**
+ * A user's saved changes to a region, oldest first so they read like a
+ * conversation. Holds the latest page and loads earlier ones on request.
+ *
+ * Given several region ids, it is the history of them all as one list. A
+ * change that reached more than one region is one entry, whose `revision` is
+ * the number of the change as a whole and whose `regions` says what it did in each.
+ */
+export declare function useChangeHistory(regionId: string | readonly string[], historyOptions?: ChangeHistoryOptions): {
+    entries: HistoryEntry[];
+    loading: boolean;
+    error: string | null;
+    hasEarlier: boolean;
+    loadEarlier: () => void;
+};
+/**
+ * A short description of a change made without a prompt, for a history that
+ * includes them. An entry in a form it does not know is described in general terms.
+ */
+export declare function describeHistoryEntry(entry: Pick<HistoryEntry, "kind" | "operations">, manifest: Manifest | null): string;

package/dist/hooks/useDictation.d.ts

@@ -0,0 +1,50 @@
+/**
+ * `starting` is the wait for the browser to hand over the microphone, which
+ * the first time includes asking the user for permission.
+ */
+export type DictationStatus = "idle" | "starting" | "recording" | "transcribing";
+export interface DictationOptions {
+    /**
+     * Called with everything made out of the current recording so far. `isFinal`
+     * is true on the last call for a recording. Today there is one call per
+     * recording; a caller that replaces what the previous call gave it will keep
+     * working when text arrives while the user is still speaking.
+     */
+    onTranscript: (transcript: string, isFinal: boolean) => void;
+    /** Names likely to be spoken, such as the titles on the screen. */
+    vocabularyHints?: readonly string[];
+    /** A recording is ended for the user after this long. Default 60. */
+    maxSeconds?: number;
+    /** False puts off asking the engine whether it offers dictation. Default true. */
+    enabled?: boolean;
+}
+/** The name of the custom property that carries how loud the user is, from 0 to 1. */
+export declare const SOUND_LEVEL_PROPERTY = "--clickless-dictation-level";
+/**
+ * Records a spoken prompt and has the engine turn it into text, which it does
+ * by passing the recording to OpenAI's speech-to-text service. Use it to build
+ * your own microphone button, or render `PromptPanel` with `dictation`.
+ *
+ * Nothing is recorded until `start` is called, and the microphone is let go as
+ * soon as the recording ends. Must be rendered inside `AdaptiveProvider`.
+ */
+export declare function useDictation(dictationOptions: DictationOptions): {
+    /** True when the engine offers dictation and this browser can record. False until both are known. */
+    available: boolean;
+    status: DictationStatus;
+    /** Whole seconds recorded so far. */
+    elapsedSeconds: number;
+    /** A sentence for the user about why the last recording gave no text, or null. */
+    error: string | null;
+    /** Puts the error away, as when the user starts typing instead. */
+    clearError: () => void;
+    start: () => Promise<void>;
+    stop: () => void;
+    cancel: () => void;
+    /**
+     * Give this to the element that shows the sound level, or one around it. While recording, its
+     * `--clickless-dictation-level` custom property is set to a number from 0
+     * (silence) to 1 (loud) several times a second.
+     */
+    soundLevelRef: (element: HTMLElement | null) => void;
+};

package/dist/hooks/useEngineReachable.d.ts

@@ -0,0 +1,5 @@
+/**
+ * False while the engine cannot be reached, from the first request that finds
+ * it so until one gets an answer again. True with no engine, and on the server.
+ */
+export declare function useEngineReachable(): boolean;