@clickless/react 0.0.0-stage → 0.1.0

package/dist/presets/mergePresets.d.ts

@@ -0,0 +1,20 @@
+import type { Capabilities, LayoutItem } from "../core/index.js";
+import type { PropPreset } from "./propPresets.js";
+type OwnDeclaration = {
+    description: string | undefined;
+    capabilities: Partial<Omit<Capabilities, "props">> | undefined;
+    defaults: Partial<Pick<LayoutItem, "w" | "h" | "hidden">>;
+};
+type Declaration = {
+    description: string | undefined;
+    capabilities: Partial<Capabilities> | undefined;
+    defaults: Partial<Pick<LayoutItem, "w" | "h" | "hidden" | "props">>;
+};
+/**
+ * A component's declaration with its presets folded in: their props make up
+ * `capabilities.props`, their starting values `defaults.props`, and their
+ * sentences follow `description` in order. A prop declared by two presets is
+ * refused, since its two meanings would contradict.
+ */
+export declare function mergePresets(componentId: string, declaration: OwnDeclaration, presets: readonly PropPreset[]): Declaration;
+export {};

package/dist/presets/propPresets.d.ts

@@ -0,0 +1,305 @@
+import type { CSSProperties } from "react";
+import { type PropCapabilities, type PropValue } from "../core/index.js";
+/**
+ * A setting users may change, or a few that belong together, with its values
+ * and the sentence that tells the model what it means. Pass it in `<Adaptive presets>`:
+ * its props and starting values become part of the component's declaration, and
+ * its sentence follows `description`, which is where the model learns what each
+ * prop means.
+ */
+export interface PropPreset<Reading = unknown> {
+    /** Which preset this is, such as "stripes". */
+    readonly preset: string;
+    readonly capabilities: Readonly<Record<string, PropCapabilities>>;
+    readonly defaults: Readonly<Record<string, PropValue>>;
+    /** One or two sentences naming each of its props, added to the component's description. */
+    readonly description: string;
+    /**
+     * The preset's current value, from the props a render-function child receives.
+     * A missing or unexpected value reads as the preset's default.
+     */
+    read(adaptiveProps: Readonly<Record<string, PropValue>>): Reading;
+}
+/**
+ * A custom setting: one whose values the application gives, such as a choice of
+ * the application's own views. Its prop takes the name it is given in
+ * `<Adaptive presets>`, so `{ order: propPresets.choice(...) }` declares a prop
+ * called `order`.
+ */
+export interface CustomPreset<Reading = unknown> {
+    /** Which preset this is, such as "choice". */
+    readonly preset: string;
+    /** The preset with its prop given this name. */
+    named(propName: string): PropPreset<Reading>;
+}
+/** The presets of one component, each under a name of the integrator's choosing. */
+export type PresetSet = Readonly<Record<string, PropPreset | CustomPreset>>;
+/** The current value of each preset in a set, under the same name. */
+export type PresetValues<Presets extends PresetSet> = {
+    [PresetName in keyof Presets]: Presets[PresetName] extends PropPreset<infer Reading> ? Reading : Presets[PresetName] extends CustomPreset<infer Reading> ? Reading : never;
+};
+/** Each preset of a set as a `PropPreset`, a custom one taking its key as its prop's name. */
+export declare function presetsByName(presets: PresetSet): Record<string, PropPreset>;
+/**
+ * A chosen colour and the text colour to draw on it: black or white, whichever
+ * reads better on that colour.
+ */
+export type ColourReading = {
+    colour: string;
+    /** Black or white, whichever is readable on `colour`. */
+    textColour: string;
+};
+/** The options `accent`, `colour` and `stripes` share on what is drawn on the colour and behind it. */
+type ReadabilityOptions = {
+    /**
+     * Text is drawn on the colour in its reading's `textColour`, as on a button
+     * or a selected entry. The planner is then told, and its reply says when a
+     * chosen colour turns that text from white to black or back.
+     */
+    textOn?: boolean;
+    /**
+     * The colour behind it, written as #rrggbb, such as the page's `#ffffff`. The
+     * planner's reply then says when a chosen colour would be hard to see on it:
+     * under 3:1 for a colour with no text on it, such as a link or a line, and
+     * all but the same as what is behind it, such as white on white, with `textOn`.
+     */
+    against?: string;
+};
+type Density = "comfortable" | "compact";
+/** `density`: how much room each row or entry takes. Reads as "comfortable" or "compact". */
+declare function density({ initial }?: {
+    initial?: Density;
+}): PropPreset<Density>;
+/**
+ * `stripes`: colouring every other row. Reads as the stripe colour and the text
+ * colour readable on it, or null when off.
+ *
+ * With `palette`, users choose among the named colours given, such as
+ * `{ grey: "#f3f2ee", red: "#b91c1c" }`. Without it, they may choose any colour,
+ * held in a second prop, `stripeColour`.
+ */
+declare function stripes(options?: ({
+    initial?: "off" | "on";
+    colour?: string;
+    suggested?: readonly string[];
+} & ReadabilityOptions) | {
+    palette: Readonly<Record<string, string>>;
+    initial?: string;
+}): PropPreset<ColourReading | null>;
+/**
+ * `background` and `textColour`. Reads as both colours, with `textColour` turned
+ * black or white where the chosen one would be hard to read on the background,
+ * as the description promises the model; `chosenTextColour` is the user's choice as is.
+ */
+declare function colours({ background, textColour, suggested, }?: {
+    background?: string;
+    textColour?: string;
+    suggested?: readonly string[];
+}): PropPreset<{
+    background: string;
+    textColour: string;
+    chosenTextColour: string;
+    /** Both colours as a style, ready to spread onto the component's outer element. */
+    style: CSSProperties;
+}>;
+/** `textSize`: the size of the text in pixels, a whole number from `min` to `max`. */
+declare function textSize({ initial, min, max, }?: {
+    initial?: number;
+    min?: number;
+    max?: number;
+}): PropPreset<number>;
+/**
+ * Showing or hiding one part of the component, such as
+ * `{ trend: propPresets.toggle({ shows: "the line comparing it with last month" }) }`.
+ * The prop takes its name from the key and holds "on" or "off"; it reads as true while shown.
+ */
+declare function toggle({ shows, initial }: {
+    shows: string;
+    initial?: boolean;
+}): CustomPreset<boolean>;
+/**
+ * One of a list of the application's own values, such as the view of a calendar:
+ * `{ view: propPresets.choice({ values: ["day", "week", "month"], initial: "week", means: "how much of the calendar shows at once" }) }`.
+ * `means` says what the prop is, in plain words, for the model: "view is …".
+ */
+declare function choice<const Value extends string>({ values, initial, means, }: {
+    values: readonly Value[];
+    initial: NoInfer<Value>;
+    means: string;
+}): CustomPreset<Value>;
+/**
+ * A number from `min` to `max`, whole unless `whole` is false, such as the corner
+ * radius of a button. `means` says what it is, with its unit: "the corner radius in pixels".
+ */
+declare function number({ min, max, initial, whole, means, }: {
+    min: number;
+    max: number;
+    initial: number;
+    whole?: boolean;
+    means: string;
+}): CustomPreset<number>;
+/**
+ * Any colour, such as the colour of a chart's bars. `means` says what it colours:
+ * "the colour of the bars". `suggested` lists colours to prefer, such as the brand's.
+ * Reads as the colour and the text colour readable on it; give `textOn` where
+ * text is drawn on it in that text colour, and `against` for the colour behind it.
+ */
+declare function colour({ initial, suggested, means, ...readabilityOptions }: {
+    initial: string;
+    suggested?: readonly string[];
+    means: string;
+} & ReadabilityOptions): CustomPreset<ColourReading>;
+/**
+ * Which of the application's own entries show, and in what order, such as the
+ * columns of a table. `means` says what the list holds: "the columns that show,
+ * left to right". All of `values` show to begin with unless `initial` is given;
+ * `min` is the fewest the list may hold, and `required` lists entries it must
+ * always hold, such as the tab of the page that is open. They can still be moved.
+ */
+declare function visibleList<const Value extends string>({ values, initial, min, required, means, }: {
+    values: readonly Value[];
+    initial?: readonly NoInfer<Value>[];
+    min?: number;
+    required?: readonly NoInfer<Value>[];
+    means: string;
+}): CustomPreset<Value[]>;
+/**
+ * `count`: how many entries show, such as rows of a table or bars of a chart.
+ * `of` names the entries, in the plural, where the component's title does not
+ * make them plain: "months" on a chart titled "Revenue".
+ */
+declare function count({ of, min, max, initial, }: {
+    of?: string;
+    min?: number;
+    max: number;
+    initial: number;
+}): PropPreset<number>;
+type HighlightReading = {
+    /** The highlight colour. */
+    colour: string;
+    /** Black or white, whichever is readable on the highlight colour. */
+    textColour: string;
+    /**
+     * Whether an entry is highlighted. `position` counts from 0 at the top. `entry`
+     * is the entry's value of the measure given to `above` or `below`, or, where
+     * `kinds` is given too, `{ measure, kind }`, with `kind` the entry's value of it.
+     */
+    isHighlighted(position: number, entry?: HighlightedEntry): boolean;
+    /**
+     * The style for an entry: the highlight colour and readable text where it is
+     * highlighted, and nothing where it is not. Pass it to the entry's own `style`,
+     * such as `<tr style={highlight.styleFor(rowIndex, row.amount)}>` or
+     * `<tr style={highlight.styleFor(rowIndex, { kind: row.status })}>`.
+     */
+    styleFor(position: number, entry?: HighlightedEntry): CSSProperties | undefined;
+};
+/** An entry's value of the measure, or that and its kind. */
+type HighlightedEntry = number | {
+    measure?: number;
+    kind?: string;
+};
+/**
+ * Colouring the entries that stand out in a list or table: the top few, such as
+ * the top 3 (`top`), those whose value of a measure is more than an amount
+ * (`above`) or less than one (`below`), or any of these. `entries` names them, in
+ * the plural, where the component's title does not make them plain. `measure`
+ * says what is compared, with its unit and without "the": "amount invoiced in
+ * pounds", or "start time in hours from midnight, such as 13.5 for 1:30 pm".
+ * `above` and `below` compare the same value, so given together they name the
+ * same measure.
+ * `kinds` colours the entries of chosen kinds, from a fixed set the application
+ * names in `values`, such as `{ of: "statuses", values: ["booked", "arrived",
+ * "cancelled"] }`. The values are kinds an entry falls into, never the entries
+ * themselves, so a person's or customer's name is never one.
+ * Adds `highlightTop`, `highlightAbove`, `highlightBelow`, `highlightKinds`
+ * (whichever are given) and `highlightColour`. 0, or no kinds, turns any of them
+ * off, and all start off.
+ *
+ * None has a largest value unless you give `max`: the amount is compared
+ * with the entries shown at the time, so it suits a list whose contents change.
+ */
+declare function highlight({ entries, top, above, below, kinds, colour, suggested, }: {
+    entries?: string;
+    top?: true | {
+        max: number;
+    };
+    above?: {
+        measure: string;
+        max?: number;
+    };
+    below?: {
+        measure: string;
+        max?: number;
+    };
+    kinds?: {
+        of: string;
+        values: readonly string[];
+    };
+    colour?: string;
+    suggested?: readonly string[];
+}): PropPreset<HighlightReading>;
+type TextStyle = "regular" | "italic" | "bold" | "bold italic";
+/**
+ * `textStyle`: whether the text is bold, italic, both or neither. It leaves
+ * letter case alone, so a prop of your own for capitals combines with it.
+ * Reads as `{ bold, italic }`; what bold looks like is up to you.
+ */
+declare function textStyle({ initial }?: {
+    initial?: TextStyle;
+}): PropPreset<{
+    bold: boolean;
+    italic: boolean;
+}>;
+/**
+ * `accent`: the one colour that marks what stands out, such as the selected
+ * entry of a menu or today in a calendar. Name what it marks in `marks`.
+ * Reads as the colour and the text colour readable on it; give `textOn` where
+ * text is drawn on it in that text colour, such as a button's label, and
+ * `against` for the colour behind it.
+ */
+declare function accent({ marks, colour, suggested, ...readabilityOptions }: {
+    marks: string;
+    colour?: string;
+    suggested?: readonly string[];
+} & ReadabilityOptions): PropPreset<ColourReading>;
+/**
+ * The settings users may change, for `<Adaptive presets>`, each under a name of
+ * your choosing. Built-in settings (`count`, `highlight`, `density`, `stripes`,
+ * `colours`, `textSize`, `textStyle`, `accent`) come with their names, values and
+ * wording, shared across applications; use one when it fits. Custom settings
+ * (`toggle`, `choice`, `number`, `colour`, `visibleList`) take the application's
+ * own values and a few words saying what they mean, and their prop takes the name
+ * it is given.
+ *
+ * @example
+ * <Adaptive id="invoices" kind="table" title="Invoices" defaults={{ w: 12, h: 5 }}
+ *   presets={{
+ *     columns: propPresets.visibleList({ values: COLUMN_IDS, min: 1, means: "the columns that show, left to right" }),
+ *     stripes: propPresets.stripes({ suggested: BRAND_COLOURS }),
+ *     rows: propPresets.density(),
+ *   }}>
+ *   {(props, adaptiveControls, presetValues) => (
+ *     <InvoiceTable
+ *       columns={presetValues.columns}
+ *       stripeColour={presetValues.stripes}
+ *       compact={presetValues.rows === "compact"}
+ *     />
+ *   )}
+ * </Adaptive>
+ */
+export declare const propPresets: {
+    count: typeof count;
+    highlight: typeof highlight;
+    density: typeof density;
+    stripes: typeof stripes;
+    colours: typeof colours;
+    textSize: typeof textSize;
+    textStyle: typeof textStyle;
+    accent: typeof accent;
+    toggle: typeof toggle;
+    choice: typeof choice;
+    number: typeof number;
+    colour: typeof colour;
+    visibleList: typeof visibleList;
+};
+export {};

package/dist/region/changedComponentIds.d.ts

@@ -0,0 +1,13 @@
+import type { Layout } from "../core/index.js";
+/**
+ * Components whose own settings differ, plus the smallest set that had to move
+ * to turn one order into the other. Components that merely shifted because
+ * something else moved past them are left out.
+ */
+export declare function findChangedComponentIds(previousLayout: Layout, nextLayout: Layout): ReadonlySet<string>;
+/**
+ * The entries of `nextOrder` that are new, or had to move to turn
+ * `previousOrder` into it. Entries that merely shifted because something else
+ * moved past them are left out.
+ */
+export declare function entriesOutOfOrder(previousOrder: readonly string[], nextOrder: readonly string[]): Set<string>;

package/dist/region/firstPaintOrder.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Where each item is drawn before the region has mounted: on the server and
+ * on the first paint. There is no manifest yet, only the saved layout and the
+ * items as they render, one after another in the order they are written.
+ *
+ * A saved item keeps its saved place. One added since the layout was saved
+ * goes straight after the item written before it, or first if it is written
+ * first, which is where reconciling puts it once the region mounts.
+ *
+ * "Written before" is taken to be "rendered before". That holds unless part
+ * of the region is inside a Suspense boundary that is still waiting while the
+ * server sends the rest: items after it then render first, and an added item
+ * may be drawn out of place until the region mounts.
+ */
+export declare class FirstPaintOrder {
+    private placedItems;
+    /** `savedIndex` is the item's position in the saved order, or -1 if it is not in it. */
+    placeItem(itemId: string, savedIndex: number): number;
+}

package/dist/region/previewRequests.d.ts

@@ -0,0 +1,21 @@
+/**
+ * A request whose answer is part of the preview on the screen. A follow-up
+ * typed during a preview adds its change to the preview, so one preview can
+ * hold several, and is kept or discarded as one change.
+ */
+export interface PreviewRequest {
+    prompt: string;
+    /** What the planner answered: what this request changed from the screen it was typed on. */
+    message: string;
+    viaVoice: boolean;
+}
+/**
+ * How the change the requests made together is told, as it is saved or
+ * reported: their prompts one to a line, and their answers one after another.
+ * The oldest requests are left out where all of them would be too long to store.
+ */
+export declare function describePreviewRequests(previewRequests: readonly PreviewRequest[]): {
+    prompt: string;
+    message: string;
+    viaVoice: boolean;
+};

package/dist/region/regionContext.d.ts

@@ -0,0 +1,96 @@
+import { useLayoutEffect } from "react";
+import type { Layout } from "../core/index.js";
+import { ActionRegistry } from "../actions/actionRegistry.js";
+import { EngineClient, type EngineOptions } from "../engine/engineClient.js";
+import type { FirstPaintOrder } from "./firstPaintOrder.js";
+import { RegionGroup } from "./regionGroup.js";
+import { RegionStore } from "./regionStore.js";
+export declare class RegionStoreRegistry {
+    private storesByRegionId;
+    private groupsByRegionIds;
+    /** Null when the provider was given no engine. */
+    readonly engine: EngineClient | null;
+    /** The actions offered on the page right now. */
+    readonly actions: ActionRegistry;
+    private dictationOffered;
+    private promptDrafts;
+    private draftListeners;
+    constructor(engineOptions: EngineOptions | undefined, userId?: string);
+    /**
+     * Whether the engine can turn speech into text. Asked once for all the
+     * regions on a page. A failed request is not remembered, so it is asked again.
+     */
+    isDictationOffered(): Promise<boolean>;
+    /**
+     * The prompt typed for a set of regions and not sent yet, so it is still
+     * there when the user comes back to them, as on returning to a page.
+     */
+    draftFor: (regionIdsKey: string) => string;
+    keepDraft: (regionIdsKey: string, draftText: string) => void;
+    /** Two bars for the same regions show the same draft, so each hears when it changes. */
+    subscribeToDrafts: (draftListener: () => void) => (() => void);
+    private latestChangeSequence;
+    /** Numbers the changes made in any of these regions, so the newest among several can be told. */
+    private nextChangeSequence;
+    /**
+     * Where the latest action run falls among the changes, in the same
+     * numbering, or 0 when none has run since the page was loaded.
+     */
+    private actionRunSequence;
+    private actionRunListeners;
+    latestActionRunSequence: () => number;
+    /** Notes that an action has just run, after every change made so far. */
+    noteActionRun: () => void;
+    subscribeToActionRuns: (actionRunListener: () => void) => (() => void);
+    /**
+     * Stops every store trying the engine again in the background, to save
+     * changes or read saved layouts, for when the provider unmounts.
+     */
+    dispose: () => void;
+    /** Lets the stores try the engine again in the background, as when React mounts the provider once more. */
+    resume: () => void;
+    storeFor(regionId: string): RegionStore;
+    /** The regions one prompt bar speaks for. The same ids in the same order give the same group. */
+    groupFor(regionIds: readonly string[]): RegionGroup;
+}
+export declare const RegionStoreRegistryContext: import("react").Context<RegionStoreRegistry | null>;
+/**
+ * The id an item's element carries in the page, so the region can name its
+ * items to assistive technology in the order they are shown. `regionTag` is
+ * the region's own `useId`, which keeps the id from matching one the host
+ * application uses, or one in another region. Ids in a list of references are
+ * separated by spaces, so anything but letters, digits and `-` is written as
+ * its character code between two `_`.
+ */
+export declare function itemElementId(regionTag: string, itemId: string): string;
+export interface RegionContextValue {
+    /** Unique to this region on the page, and the same on the server and in the browser. */
+    regionTag: string;
+    regionStore: RegionStore;
+    /** False when the region draws nothing of its own and the page's containers place its items. */
+    regionDrawsGrid: boolean;
+    /** The columns the layout is kept in. */
+    layoutColumns: number;
+    /** The columns drawn on this screen, which may be fewer. */
+    drawnColumns: number;
+    /** Each item's span on this screen when it has fewer columns than the layout, else null. */
+    drawnSpans: ReadonlyMap<string, number> | null;
+    /** Lets items render the saved layout on the server and on first paint. */
+    initialLayout: Layout | undefined;
+    /** The order the saved layout gives every component it knows, on screen or off. */
+    initialOrder: readonly string[];
+    firstPaintOrder: FirstPaintOrder;
+}
+export declare const RegionContext: import("react").Context<RegionContextValue | null>;
+export declare function useRegionStore(regionId: string): RegionStore;
+/** For ClickLess's own prompt UI, which has nothing to show without the provider. */
+export declare function useRegionStoreRegistry(): RegionStoreRegistry;
+/**
+ * For what wraps or runs in the application's own components. Outside a
+ * provider, as in the application's tests or stories, each caller gets a
+ * registry of its own with no engine: a region shows its defaults and keeps
+ * changes in memory, `useAdaptiveRegion` reads the region it sits in (or an
+ * empty one of its own outside any region), and an action is offered to no one.
+ */
+export declare function useRegionStoreRegistryOrStandIn(): RegionStoreRegistry;
+export declare const useIsomorphicLayoutEffect: typeof useLayoutEffect;

package/dist/region/regionGroup.d.ts

@@ -0,0 +1,189 @@
+import type { Action, ActionCall } from "../core/index.js";
+import { type ConversationTurn, type EngineClient } from "../engine/engineClient.js";
+import type { HistoryPage } from "../engine/engineResponses.js";
+import type { RegionSnapshot } from "./regionSnapshot.js";
+import { type PlannedPreviewOutcome, type RegionStore, type UndoResult } from "./regionStore.js";
+/** What a prompt bar shows of the regions it speaks for. */
+export interface RegionGroupSnapshot {
+    /**
+     * Each region, in the order they were named. One that is not on the screen
+     * has a null manifest, and takes no part in anything until it is.
+     */
+    regions: readonly {
+        regionId: string;
+        snapshot: RegionSnapshot;
+    }[];
+    /** True while a proposed change is on the screen, waiting to be kept or discarded. */
+    previewing: boolean;
+    canUndo: boolean;
+    /**
+     * The order of the newest change on the screen an undo would take back,
+     * among the changes and action runs since the page was loaded, or 0 when it
+     * was made before then. See `RegionStoreRegistry.latestActionRunSequence`.
+     */
+    newestChangeSequence: number;
+    /** True while the regions show how they first looked, in place of their layouts. */
+    showingOriginal: boolean;
+    /** True when any region on the screen differs from how it first looked. */
+    differsFromOriginal: boolean;
+    /** True while any region's saved layout is being fetched. */
+    loading: boolean;
+    /** True when any region's saved layout could not be fetched. */
+    loadFailed: boolean;
+    /**
+     * Which point in the history the screen is at, in the same numbering as
+     * `HistoryEntry.revision`: for one region, that region's revision; for
+     * several, the latest change's own number (its `changeId`), which the
+     * engine counts across regions.
+     */
+    revision: number;
+    hasHistory: boolean;
+    /** True while any region shows a change of the application's own that is not saved yet. */
+    hasUnsavedChanges: boolean;
+}
+/** What a prompt is planned with besides the regions: what the screen can do, and what was said before. */
+export interface PlanContext {
+    actions: readonly Action[];
+    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;
+}
+/** What a prompt bar's request came to: the answer for the user, the actions to run, and what became of the preview. */
+export interface PlannedRequest {
+    message: string;
+    actionCalls: ActionCall[];
+    previewOutcome: PlannedPreviewOutcome;
+}
+/**
+ * The regions one prompt bar speaks for, such as a page and the sidebar beside
+ * it. A prompt is planned for all of them in one request, and what it changes
+ * is previewed, kept, discarded and undone in all of them together, while each
+ * region's layout is still stored on its own.
+ *
+ * A group of one is that region and nothing more: everything is passed
+ * straight to its store.
+ */
+export declare class RegionGroup {
+    private readonly regionStores;
+    private readonly engine;
+    private readonly singleRegionStore;
+    private pendingPreview;
+    /** The last preview saved, so an answer planned from it is shown on the layouts it became. */
+    private lastSavedPreview;
+    private commitInProgress;
+    private snapshotListeners;
+    private stopListeningToStores;
+    private cachedSnapshot;
+    private cachedSnapshotInputs;
+    private serverSnapshot;
+    constructor(regionStores: readonly RegionStore[], engine: EngineClient | null);
+    subscribe: (snapshotListener: () => void) => (() => void);
+    /**
+     * Stops listening to the regions once nothing listens here. While a preview
+     * waits it goes on listening, though the prompt bar may be gone, as one in a
+     * closed sheet is: if a region then drops its part, as on leaving the page,
+     * the preview is still reported as abandoned.
+     */
+    private stopListeningIfUnwatched;
+    getSnapshot: () => RegionGroupSnapshot;
+    getServerSnapshot: () => RegionGroupSnapshot;
+    /**
+     * Asks the engine to turn a request into operations and previews them, in
+     * every region they are for. As for one region, a request made while a
+     * preview is showing is planned from it, region by region, and its answer
+     * is added to it; one made with none showing replaces any that appears
+     * meanwhile, as if discarded.
+     */
+    planFromPrompt: (prompt: string, viaVoice?: boolean, planContext?: PlanContext) => Promise<PlannedRequest>;
+    /** Previews the operations, in every region they are for, or none of them if any no longer fits. */
+    private showNewPreview;
+    /**
+     * Adds a follow-up's operations to the preview it was planned from: each
+     * region's after its part of the preview, in a region the preview had not
+     * changed as its first part. Nothing changes if any region no longer fits.
+     * A follow-up that takes the whole preview back leaves nothing to keep, so
+     * the preview counts as discarded.
+     */
+    private addToPreview;
+    /**
+     * Sends a plan request made from `preview`. When the engine says the preview
+     * no longer applies to the saved layouts it was made on, it can never be
+     * saved, so it is taken off, as one that left the screen.
+     */
+    private answeringForPreview;
+    /**
+     * Saves the preview: every region's part, or none. Resolves to null when
+     * there is no preview. One that no longer fits is taken off the screen.
+     */
+    commitPreview: () => Promise<{
+        applied: boolean;
+    } | null>;
+    /** Takes the preview off the screen, in every region, without saving it. */
+    cancelPreview: () => void;
+    /** `cancelPreview`, for when the user chose not to keep it. The engine is told, once. */
+    discardPreview: () => void;
+    /**
+     * `cancelPreview`, for when the preview leaves the screen before the user
+     * chose, because a region it changed dropped its part. The engine is told, once.
+     */
+    private abandonPreview;
+    /** Record-keeping only: the user is never made to wait on it or told it failed. One being saved is not reported. */
+    private reportPreviewNotKept;
+    /**
+     * Takes back the latest change among the regions on the screen, in each of
+     * them it reached, on the screen or not: a prompt that changed two is undone
+     * in both. The result says when part of it stays in place elsewhere.
+     */
+    undoLastChange: () => Promise<UndoResult>;
+    /**
+     * Shows every region as it first looked, before any change, without saving
+     * anything, or goes back to their layouts. A preview, or any change, ends it.
+     */
+    showOriginal: (shown: boolean) => void;
+    /**
+     * Returns the screen to how it was after the given saved change; 0 is as it
+     * was before any. Resolves to the number of the latest saved change afterwards.
+     */
+    restoreRevision: (revision: number) => Promise<number>;
+    /** Saved changes, newest first. For several regions each entry is one change, whichever regions it reached. */
+    readHistory: (options: {
+        limit: number;
+        before?: number;
+        promptedOnly?: boolean;
+    }) => Promise<HistoryPage>;
+    private savePreview;
+    /**
+     * Shows what the engine answered, in each of `regionStores` whose layout it
+     * changed, with the operations that changed it. Every other region, one off
+     * the screen as well, gives way to it, unless it is an undo, which is no new
+     * change. A preview no longer describes the screen.
+     */
+    private acceptAnswer;
+    /** `regionStores` and every other region of the group holding changes not saved yet, which go first. */
+    private withUnsavedChanges;
+    /**
+     * When the engine says a region changed elsewhere, nothing was saved in any
+     * of them. The ones it names are fetched again before failing, which takes
+     * the preview off the screen.
+     */
+    private reloadingOnConflict;
+    /**
+     * Waits its turn in every one of the regions, so a change to several does
+     * not cross one made to any of them alone. Turns are always taken in the
+     * same order, so two groups that share regions cannot wait on each other.
+     * `writeChange` is given the change's `sequence`, taken once the first turn has
+     * begun: a change made in any of the regions while it waits for the others
+     * is newer than it.
+     */
+    private oneWriteAtATime;
+    private storesOnScreen;
+    private onStoreChange;
+    private isStillShowing;
+    private notifyListeners;
+    private computeSnapshot;
+}