@hearthscale/app 0.2.3 → 0.3.0

package/README.md

@@ -86,7 +86,7 @@ the view as `hearthscale/web/key` while the page has the keyboard. The page
 keeps its address through a restart, and the app's tools drive it through
 `surface.command`.
 
-An app that names `peers` in `uses` talks to itself on other computers in
+An app that names `peers` in `uses` talks to itself on other devices in
 rooms. A view opens a room with `hearthscale/peers/create` and shows the
 person its ticket to pass on; `hearthscale/peers/join` asks the person for
 a ticket in a sheet the shell draws, so the view never names one. Both
@@ -94,7 +94,7 @@ need a click. The view and the backend (`ctx.peers`) then send messages,
 JSON of at most 64 KiB, to the room's other members, hear
 theirs (`hearthscale/peers/message`, `ctx.peers.on('message')`) and leave.
 A room carries only these messages: no file, process or credential of
-either platform. It ends for everyone when the computer that opened it
+either platform. It ends for everyone when the device that opened it
 leaves. A member keeps its place and joins again on its own after a drop
 or a restart; no message is kept.
 

package/dist/index.d.ts

@@ -1,3 +1,21 @@
+/**
+ * What a Server asks Hearthscale's api about models and what it answers:
+ * the models that suit one computer, best first for each kind, with the
+ * exact files of each. The Server keeps the last answer on disk.
+ */
+
+/** A model's licence: its name, and whether it is open for commercial use. */
+interface OfferedLicense {
+    name: string;
+    commercial: boolean;
+}
+
+/**
+ * Control: the first-party half of the inference contract — everything the
+ * OpenAI shape cannot express. Served by the Server (`hearthd`) beside the
+ * generation routes.
+ */
+
 /** Resolved publisher identity, independent of the model architecture.
  *  `GET /v1/publishers/{owner}/picture` answers the picture of the Hub
  *  user or organisation `repository` names first: its bytes as
@@ -11,14 +29,33 @@ interface ModelIdentity {
     /** The Hub repository whose publisher supplies the artwork; null for other sources. */
     repository: string | null;
 }
+/** What a transcription model's card and file state about it. A list is empty,
+ *  and a field null, where neither says. */
+interface SpeechFacts {
+    /** The languages it hears, by their short codes. */
+    languages: string[];
+    /** The percent of words, or of characters in a language written without
+     *  spaces, its publisher measured wrong on a public test set, by language. */
+    errors: Record<string, number>;
+    /** How long 30 s of speech took on a graphics device, as its publisher measured
+     *  it on the reference computer most like its Server. */
+    seconds: number | null;
+    /** The same on the processor. */
+    processorSeconds: number | null;
+    /** It writes English from another language. */
+    translates: boolean | null;
+    /** It tells the language by itself. */
+    detects: boolean | null;
+}
 /** A job kind a model runs: the JSON Schema (draft-07) of its input, every
  *  object of it closed. A property of `"format": "asset"`, alone or as the
  *  items of an array, names a file by its asset id on the app's side,
  *  `contentMediaType` saying what it takes, and its `description` the
  *  limits the model sets on it; it reaches the Server as a `RenderUpload`
- *  in the same place. A property's `default` is what the model's saved
- *  settings give a job that leaves it out, as an image model's picture
- *  size, steps and guidance. */
+ *  in the same place. A property of `"format": "model"` names another
+ *  model of the same Server by its card id; it reaches the Server as that
+ *  model's id. A property's `default` is what the model's saved settings
+ *  give a job that leaves it out. */
 interface JobSpec {
     input: Record<string, unknown>;
 }
@@ -78,6 +115,8 @@ interface HubRepository {
     vision: boolean;
     tools: boolean;
     reasoning: boolean;
+    /** What a speech model's card states about it. */
+    speech: SpeechFacts | null;
 }
 /** A file that can fill a companion role: where it is, how big it is, and
  *  whether its checksum is published. */
@@ -86,6 +125,28 @@ interface CompanionOption {
     path: string;
     sizeBytes: number;
     verifiable: boolean;
+    installed?: {
+        modelId: string;
+        path: string;
+        source: {
+            type: string;
+            repo: string;
+            revision: string;
+        };
+        sha256: string;
+        sizeBytes: number;
+    };
+    containsVision?: boolean;
+    /** The licence the recommendations state for a usual part of a family. */
+    license?: OfferedLicense;
+}
+/** A companion role of a candidate and the files that fill it. */
+interface CompanionRole {
+    role: string;
+    label: string;
+    options: CompanionOption[];
+    /** A gated base or encoder repository whose files this caller cannot read. */
+    gated?: string;
 }
 /** One file of a repository a pull can name: the whole shard set where it
  *  is a numbered shard, with the weights' projector beside it where the
@@ -110,23 +171,14 @@ interface HubCandidate {
         label: string;
         path: string;
     }[];
-    /** The companion roles the repository does not supply; a pull names a
-     *  file for each, found in the model's family, the first unless the
-     *  person chooses another. */
-    requires: {
-        role: string;
-        label: string;
-        options: CompanionOption[];
-    }[];
+    /** Companion roles whose files the pull selects from compatible installed
+     *  components, the model's family or the encoder's own releases. */
+    requires: CompanionRole[];
     /** The companion roles the model loads where a pull names a file for
-     *  them, which the repository does not supply: `llm_vision`, the vision
+     *  them: `llm_vision`, the vision
      *  part of a language model encoder, for a family that reads reference
      *  pictures through it. */
-    offers: {
-        role: string;
-        label: string;
-        options: CompanionOption[];
-    }[];
+    offers: CompanionRole[];
     /** Whether the repository holds vision projectors beside the file. */
     projector: boolean;
     /** The projectors to choose from where there is more than one, each
@@ -140,6 +192,8 @@ interface HubCandidate {
     /** The task the model serves, as `CatalogRole` names it. */
     role: string;
     format: string;
+    /** For an adapter: model ids from a Server, card ids from the platform. */
+    fits?: string[];
     /** Why the file cannot be pulled, in the Server's words. */
     reason?: string;
 }
@@ -157,6 +211,8 @@ interface HubListing {
     repo: string;
     model: HubRepository;
     files: number;
+    /** The path of the file a press takes, where one can be taken. */
+    fileToTake: string | null;
     candidates: HubCandidate[];
     companions: CompanionOption[];
     capabilities: {
@@ -544,9 +600,11 @@ type SourceKind = 'app' | 'connector';
 type ToolOutcome = 'completed' | 'failed' | 'cancelled' | 'skipped' | 'unknown';
 type Decision = 'run' | 'refused';
 /**
- * Who or what let a call run, or refused it.
+ * Who or what let a call run, or refused it. A call whose arguments name
+ * no path the tool takes is refused by its path, in words that say how to
+ * name one.
  */
-type DecisionBy = 'level' | 'silent' | 'grant' | 'fence' | 'judge' | 'review' | 'person' | 'floor';
+type DecisionBy = 'level' | 'silent' | 'grant' | 'fence' | 'judge' | 'review' | 'person' | 'floor' | 'path';
 type Risk = 'low' | 'high' | 'too_destructive';
 type Authorisation = 'explicitly_no' | 'neutral' | 'explicitly_yes';
 /**
@@ -604,7 +662,7 @@ type SurfaceOp = 'navigate' | 'evaluate' | 'screenshot' | 'show' | 'close';
 /**
  * One setting's value.
  */
-type SettingValue = string | number | boolean;
+type SettingValue = string | number | boolean | string[];
 /**
  * What a model card answers on, and what a job runs: a role word of
  *         the runtimes, such as chat, embedding, image or transcription.
@@ -706,6 +764,7 @@ type TriggerDeclaration = {
     name: string;
     keys?: string;
     hold?: boolean;
+    armed?: boolean;
     kind: 'hotkey';
 } | {
     name: string;
@@ -784,13 +843,12 @@ type SystemEvent = 'idle' | 'active' | 'lock' | 'unlock' | 'sleep' | 'wake' | 'p
  * `events`, `models`, `jobs` and `peers` alike, each only when its app
  * names it here. An agent's core tools need no namespace here.
  */
-type Uses = ('sessions' | 'sessions.create' | 'secrets' | 'notifications' | 'readers' | 'roots' | 'exec' | 'catalogue' | 'surface' | 'store' | 'db' | 'events' | 'models' | 'jobs' | 'terminals' | 'files.open' | 'surfaces.open' | 'peers' | 'index' | 'capture.microphone' | 'capture.system-sound' | 'capture.program-sound' | 'capture.screen' | 'capture.window' | 'capture.camera' | 'desktop.context' | 'desktop.actions') | 'net.ask' | 'desktop.overlay' | 'input.controller' | 'system.state';
+type Uses = ('sessions' | 'sessions.create' | 'secrets' | 'notifications' | 'readers' | 'roots' | 'exec' | 'catalogue' | 'surface' | 'store' | 'db' | 'events' | 'models' | 'jobs' | 'terminals' | 'files.open' | 'surfaces.open' | 'peers' | 'index' | 'capture.microphone' | 'capture.system-sound' | 'capture.program-sound' | 'capture.screen' | 'capture.window' | 'capture.camera' | 'desktop.context' | 'desktop.actions') | 'net.ask' | 'desktop.around' | 'desktop.overlay' | 'input.controller' | 'system.state';
 /**
- * The model an introduction card downloads on this computer's Server: one
- * its catalogue lists, by the id its device row gives it, or a file of a
- * Hugging Face repository.
+ * The model an introduction card downloads on this computer's Server: a
+ * file of a Hugging Face repository, or the best model of a kind.
  */
-type OnboardingDownload = string | HubFile;
+type OnboardingDownload = HubFile | BestModel;
 /**
  * What a surface is: `view`, an MCP Apps document in a sandboxed frame,
  * which may reserve slots for the chat the shell draws for the app's own
@@ -936,6 +994,22 @@ type SettingDeclaration = {
     minLength?: number;
     maxLength?: number;
     pattern?: string;
+    /**
+     * The tool that lists the values to pick from, for a list only the
+     * computer knows, such as its microphones. It is called with `{}` and
+     * answers `{ options: [{ value, label }] }`. The page calls it with no
+     * press, so it is one the app declares, its views may call, and that
+     * neither changes anything nor reaches out.
+     */
+    optionsFrom?: string;
+    /**
+     * The field takes several lines.
+     */
+    multiline?: boolean;
+    /**
+     * What the empty field shows.
+     */
+    placeholder?: string;
     /**
      * The value the platform holds until the person changes it.
      */
@@ -975,19 +1049,56 @@ type SettingDeclaration = {
      */
     default: number;
     type: 'integer';
+} | {
+    /**
+     * The setting's label.
+     */
+    title: string;
+    /**
+     * The tooltip of the setting's row.
+     */
+    description?: string;
+    items: ListSettingItems;
+    maxItems?: number;
+    /**
+     * What the empty field shows.
+     */
+    placeholder?: string;
+    /**
+     * The value the platform holds until the person changes it.
+     */
+    default: string[];
+    type: 'array';
 };
 /**
- * One row of a settings group: a setting by its name, or a button that
- * calls one of the app's tools with `{}`. A tool whose result names a view
- * opens that view in a modal over the settings; any other shows its text
- * in a tooltip of the button.
+ * The one type a list setting's entries have.
+ */
+type StringType = 'string';
+/**
+ * One row of a settings group: a setting by its name, with a button at the
+ * end of its row where it names one, or a button alone. A button calls one of
+ * the app's tools with `{}`. A tool whose result names a view opens that view
+ * in a modal over the settings; any other shows its text in a tooltip of the
+ * button.
  */
 type SettingsItem = {
     property: string;
+    /**
+     * The row shows only while another setting holds a value.
+     */
+    when?: SettingsWhen;
+    /**
+     * The buttons beside the setting's control, in their order. A list or a
+     * field of several lines fills its row and takes none.
+     *
+     * @minItems 1
+     */
+    actions?: SettingsAction[];
     kind: 'property';
 } | {
     tool: string;
     title: string;
+    confirm?: SettingsConfirm;
     kind: 'tool';
 };
 /**
@@ -1038,15 +1149,10 @@ type ProviderStatus = ('ready' | 'unreachable' | 'unauthenticated' | 'error') |
  */
 type CompletionOption = 'logprobs' | 'topLogprobs' | 'topK' | 'minP' | 'grammar' | 'stop' | 'seed';
 /**
- * The kinds of model an app's Discover search lists, each a task word of
- * the inference contract's `HubTask` whose models answer an app's
- * requests: chat models in GGUF, one word for each kind of media and
- * vector model a runtime of the Server installs from Hugging Face, and
- * every format a runtime of the Server reads. Draft weights, which load
- * only beside another model, are none of them, and an upscaler, which the
- * Server takes from its catalogue alone, has no word.
+ * The kinds of model an app's Discover search lists, each a `HubTask` word
+ * of the inference contract. Draft weights and upscalers have none.
  */
-type DiscoverTask = 'text' | 'image' | 'transcription' | 'diarization' | 'separation' | 'speech' | 'music' | 'embedding' | 'rerank' | 'all';
+type DiscoverTask = 'text' | 'image' | 'video' | 'transcription' | 'diarization' | 'separation' | 'speech' | 'music' | 'embedding' | 'rerank' | 'adapter' | 'all';
 /**
  * What an app asks to install on a Hearthscale Server: a card a Server
  * lists and does not hold, by its id, or a file of a Hugging Face
@@ -1166,6 +1272,10 @@ type ListenEvent = {
     stream: string;
     index: number;
     text: string;
+    /**
+     * The words after `text` that may still change.
+     */
+    tentative?: string;
     type: 'partial';
 } | {
     stream: string;
@@ -1194,7 +1304,7 @@ type NoticeAction = {
     title: string;
     id: string;
 };
-type HotkeyPhase = 'pressed' | 'released';
+type HotkeyPhase = ('pressed' | 'released') | 'cancelled';
 type DeviceEvent = 'connected' | 'removed';
 type PowerSource = 'ac' | 'battery';
 /**
@@ -1430,6 +1540,15 @@ interface AskFacts {
      */
     label?: string;
     arguments?: string;
+    /**
+     * On a card of an app's or a connector's tool: what the call would do,
+     * in one sentence the utility model wrote once the card was open.
+     */
+    plain?: string;
+    /**
+     * The utility model is still writing `plain`.
+     */
+    writing?: true;
     /**
      * The absolute path a file call would touch.
      */
@@ -1482,9 +1601,10 @@ interface AskFacts {
         [k: string]: unknown;
     };
     /**
-     * A connector card: the connector, and the tools waiting on a bulk
-     * card, or the sign-in's issuer, or the device code the person types
-     * at the verification address. An app's sign-in card carries the
+     * A connector card: the connector by its id, with the name the person
+     * knows it or its app by in `sourceName`, and the tools waiting on a
+     * bulk card, or the sign-in's issuer, or the device code the person
+     * types at the verification address. An app's sign-in card carries the
      * issuer, the scopes, and the code or the sign-in a window starts
      * with the authorization endpoint its browser opens.
      */
@@ -1720,7 +1840,7 @@ interface Manifest {
      * Semver, shown and never interpreted.
      */
     version: string;
-    api: 6;
+    api: 7;
     description: string;
     icon?: Schemed;
     license?: string;
@@ -1869,6 +1989,17 @@ interface Budget {
  */
 interface ModelNeed {
     required: boolean;
+    /**
+     * The setting that holds the device this kind of model hears, which its
+     * test on the app's page opens.
+     */
+    input?: string;
+    /**
+     * The tool that says which of a search's models the app recommends: it takes
+     * `{ languages, models }` and answers `{ recommended: [{ repo, word }] }`, the
+     * one it recommends most first. It runs with no press.
+     */
+    recommend?: string;
     /**
      * The Hugging Face tasks the kind's card states, every one of them.
      *
@@ -2045,6 +2176,27 @@ interface HubCompanion {
     role: string;
     repo: string;
     file: string;
+    installed?: InstalledCompanion;
+}
+interface InstalledCompanion {
+    modelId: string;
+    path: string;
+    source: InstalledCompanionSource;
+    sha256: string;
+    sizeBytes: number;
+}
+interface InstalledCompanionSource {
+    type: string;
+    repo: string;
+    revision: string;
+}
+/**
+ * The model of a kind that the app's own tool recommends, where its manifest
+ * names one, else the first recommended for the user's device, else
+ * the first of a search, found when the card opens.
+ */
+interface BestModel {
+    best: ModelKind;
 }
 /**
  * A right-click entry of the app's rail button: a call of one of the
@@ -2078,6 +2230,13 @@ interface SettingsSchema {
         [k: string]: SettingDeclaration;
     };
 }
+/**
+ * The entries of a list setting: strings, each at most `maxLength` long.
+ */
+interface ListSettingItems {
+    type: StringType;
+    maxLength?: number;
+}
 interface SettingsGroup {
     title: string;
     /**
@@ -2085,6 +2244,29 @@ interface SettingsGroup {
      */
     items: SettingsItem[];
 }
+/**
+ * A setting and the value that shows a row.
+ */
+interface SettingsWhen {
+    property: string;
+    is: unknown;
+}
+/**
+ * A button beside a setting's control.
+ */
+interface SettingsAction {
+    tool: string;
+    title: string;
+    confirm?: SettingsConfirm;
+}
+/**
+ * What a button asks before it runs its tool, for a press that cannot be undone.
+ * The answer that goes ahead carries the button's own title.
+ */
+interface SettingsConfirm {
+    title: string;
+    body: string;
+}
 interface Mentions {
     tool: string;
 }
@@ -2192,6 +2374,11 @@ interface ModelCard {
      * states them.
      */
     tasks?: string[];
+    /**
+     * What a transcription model's card and file state about it, where its
+     * provider states it.
+     */
+    speech?: SpeechFacts;
     vision?: boolean;
     tools?: boolean;
     /**
@@ -2241,6 +2428,19 @@ interface ModelCard {
      * Server reports it.
      */
     progress?: DownloadProgressBytes;
+    /**
+     * For an adapter whose Server states them, the cards of the models it fits.
+     */
+    fits?: string[];
+    /**
+     * For an adapter whose Server states them, its prompt trigger words.
+     */
+    triggers?: string[];
+    /**
+     * The name of a licence that limits commercial use, where a Server's
+     * recommendation states one.
+     */
+    limitingLicense?: string;
 }
 /**
  * A Hearthscale Server this computer names, as `ctx.models.servers` and
@@ -2267,6 +2467,11 @@ interface HubSearch {
      * The order of a Discover search: the inference contract's `HubSort`.
      */
     sort?: HubSort;
+    /**
+     * The short codes of the languages a speech model must hear, with commas
+     * between them.
+     */
+    language?: string;
 }
 /**
  * A file of a Hugging Face repository to install on a Hearthscale Server,
@@ -2963,9 +3168,10 @@ interface AppSkill {
 interface HotkeyState {
     name: string;
     /**
-     * The keys that fire the hotkey now, the person's or else the
-     * declared ones; none where neither names any, or where another
-     * app's hotkey holds them.
+     * The keys the hotkey names, the person's or else the declared ones;
+     * none where neither names any, or where another app's hotkey holds
+     * them. A hotkey declared with `armed: false` fires them only while
+     * its backend arms it.
      */
     keys?: string;
     /**
@@ -3482,6 +3688,15 @@ type HostSlotNotification =
         session: string | null;
     };
 }
+/** The person asked to go back or forward in the tab, whose web page has
+ *  loaded none. Every view that fills a tab hears it, with or without a
+ *  slot, and moves through its own places. */
+ | {
+    method: 'hearthscale/ui/history';
+    params: {
+        direction: 'back' | 'forward';
+    };
+}
 /** The tab's web page changed: its address, title, icon, load, history
  *  or zoom. Sent once when the view starts and at each change. */
  | {
@@ -3620,6 +3835,14 @@ interface ViewHostMethods {
         params: Empty;
         result: Empty;
     };
+    /** Opens the Server's window at Explore, at the models of `kind`, on a
+     *  click inside the view. A kind that no Explore task lists is refused. */
+    'hearthscale/ui/open-explore': {
+        params: {
+            kind: ModelKind;
+        };
+        result: Empty;
+    };
     /** Keeps a JSON value for this view's tab, which the host gives back in
      *  `hearthscale/widgetState`; it never reaches a model. The value takes
      *  at most 65,536 UTF-16 code units as JSON text. */
@@ -4273,6 +4496,17 @@ interface ViewExtensionMethods {
             servers: ModelServer[];
         };
     };
+    /** The cards Hearthscale recommends of a kind, best first and in every
+     *  state, this computer's own Server first. */
+    'hearthscale/models/recommended': {
+        uses: 'models';
+        params: {
+            kind: ModelKind;
+        };
+        result: {
+            cards: ModelCard[];
+        };
+    };
     /** A search of a Server's Discover: the public Hugging Face
      *  repositories of `task` that `search` matches, as that Server answers
      *  it. Needs a click, as it reads Hugging Face. */
@@ -4672,8 +4906,8 @@ type CapturedPart = {
     width: number;
     height: number;
 };
-/** A transcription stream. The Server cuts the sound at pauses, and
- *  each part becomes a segment. */
+/** A transcription stream. The sound is cut at pauses unless `pauses` is
+ *  false, and each part becomes a segment. */
 interface Listening {
     readonly id: string;
     /** 16 kHz mono 16-bit little-endian PCM, at most 10 s at a time, such
@@ -4919,11 +5153,15 @@ interface AppContext {
             root: string;
             path?: string;
         }): Promise<boolean>;
-        /** With a hotkey trigger: the keys that fire each of the app's
-         *  hotkeys now, the person's or else the declared ones, so the app
-         *  can show them; `keys` is absent where none are set or another
-         *  app's hotkey holds them, which `takenBy` names. */
+        /** With a hotkey trigger: the keys of each of the app's hotkeys, the
+         *  person's or else the declared ones, so the app can show them;
+         *  `keys` is absent where none are set or another app's hotkey holds
+         *  them, which `takenBy` names. A hotkey declared with `armed: false`
+         *  fires its keys only while `arm` holds them. */
         hotkeys: {
+            /** Makes a hotkey declared with `armed: false` hold its keys, or lets
+             *  them go: at every other moment they reach the program in front. */
+            arm(name: string, on: boolean): Promise<void>;
             list(): Promise<HotkeyState[]>;
             /** Hears a move of the keys of any of them, with every one as
              *  `list` answers it. */
@@ -4957,7 +5195,9 @@ interface AppContext {
          *  taken in milliseconds since the Unix epoch on the computer that
          *  captures, the clock every capture there shares: a part's moment is
          *  `startedAt + at`. Sound comes as 16 kHz mono 16-bit PCM in parts of
-         *  half a second, one after another, silence included; the screen, a window and the camera as a JPEG
+         *  half a second, or `part` ms from 50 to 500 for the microphone and
+         *  the computer's sound, one after another, silence included; the last
+         *  part may be shorter; the screen, a window and the camera as a JPEG
          *  picture every `interval` ms (1000 unless named, at least 250), the
          *  screen cut to `region` when named. `device` names a device of
          *  `devices`; a window and a program need one. `echo` takes the
@@ -4976,6 +5216,7 @@ interface AppContext {
             };
             echo?: boolean;
             keep?: boolean;
+            part?: number;
         }): Promise<{
             capture: string;
             startedAt: number;
@@ -4994,10 +5235,21 @@ interface AppContext {
         }) => void): () => void;
     };
     /** Other programs on the person's computer: what they show, with
-     *  `desktop.context`, and typing into the one in front, with
-     *  `desktop.actions`. */
+     *  `desktop.context`, the text around the cursor, with `desktop.around`,
+     *  and typing into the one in front, with `desktop.actions`. */
     desktop: {
         context(): Promise<DesktopContext>;
+        /** With `desktop.around`: the text around the cursor of the focused field
+         *  in the program in front, up to 1024 characters each way. A password
+         *  field gives no text and answers `password: true`. Null where the
+         *  program does not tell it, or a Hearthscale window has the focus
+         *  anywhere but in a view of this app. */
+        around(): Promise<{
+            before: string;
+            selected: string;
+            after: string;
+            password?: true;
+        } | null>;
         /** Calls `on('change')` with each change from now on, and keeps the
          *  backend up. */
         watch(): Promise<void>;
@@ -5006,12 +5258,21 @@ interface AppContext {
         on(event: 'ended', fn: (ended: {
             reason: string;
         }) => void): () => void;
+        /** The window in front now, to name to `type` or `paste`, which then
+         *  refuse once another window is in front. Null where the system names no
+         *  window, as Wayland does: the text then goes to whichever window has the
+         *  focus. */
+        front(): Promise<string | null>;
         /** Types the text into the focused field of the program in front. */
-        type(text: string): Promise<void>;
+        type(text: string, options?: {
+            front?: string | null;
+        }): Promise<void>;
         /** Pastes the text there through the clipboard, which it restores. */
-        paste(text: string): Promise<void>;
-        /** Presses each combination in turn, such as `ctrl+a` or `enter`: a
-         *  key with `ctrl`, `shift`, `alt` or `meta` before it. */
+        paste(text: string, options?: {
+            front?: string | null;
+        }): Promise<void>;
+        /** Presses each combination in turn, at most 200, such as `ctrl+a` or
+         *  `enter`: a key with `ctrl`, `shift`, `alt` or `meta` before it. */
         keys(keys: string[]): Promise<void>;
     };
     /** With `input.controller`: the person's game controllers, read also
@@ -5185,6 +5446,11 @@ interface AppContext {
             task?: string;
             state?: CardState;
         }): Promise<ModelList>;
+        /** The cards Hearthscale recommends of a kind for each Server's computer,
+         *  best first and in every state, this computer's own Server first. A card
+         *  a Server does not hold yet goes to `install` by its id. Empty where a
+         *  Server has no answer. */
+        recommended(kind: ModelKind): Promise<ModelCard[]>;
         /** The Hearthscale Servers this app may install on: this computer's
          *  first, then each paired one, with whether each serves now. */
         servers(): Promise<ModelServer[]>;
@@ -5229,15 +5495,28 @@ interface AppContext {
          *  the reason none can: this app's, or another app's under the
          *  `sessions.create` grant. */
         effective(kind: ModelKind, app?: string): Promise<EffectiveModel>;
+        /** The languages the person speaks to this app, as short codes, as they
+         *  chose them on its page; empty where they chose none. */
+        languages(): Promise<string[]>;
         /** Opens a stream on the transcription card `model` names, or else on
          *  the app's transcription model, which runs on a Hearthscale Server:
          *  the sound written in goes out as text while it is spoken. Rejects
-         *  when the model is not on a Server. `words` are hint words, such as
-         *  names, for a model whose engine takes them. */
+         *  when the model is not on a Server. `words` are names and terms the
+         *  sound holds, which an engine that takes hints favours and the text of
+         *  any other is corrected to. `aliases` names, for a term, what the model
+         *  may write for it. With `pauses: false`, a pause ends no segment, and
+         *  one segment runs until `end`. `translate` writes English on a model
+         *  that translates, or not, over the setting the person saved on the
+         *  model; any other model writes what it hears. `filterSilence` leaves
+         *  out the sound that holds no voice. */
         listen(options?: {
             language?: string;
             model?: string;
             words?: string[];
+            aliases?: Record<string, string[]>;
+            pauses?: boolean;
+            translate?: boolean;
+            filterSilence?: boolean;
         }): Promise<Listening>;
     };
     /** With `sessions.create`: the projects of an app this one may start

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hearthscale/app",
-  "version": "0.2.3",
+  "version": "0.3.0",
   "description": "The types a Hearthscale app's backend and views import: the backend's exports and context, the view's host methods, extensions and slots; and the typed call of a view's requests.",
   "license": "MIT",
   "type": "module",
@@ -39,7 +39,7 @@
     "rollup": "^4.62.2",
     "rollup-plugin-dts": "^6.5.1",
     "typescript": "^5.6.3",
-    "@hearthscale/contract": "0.1.0"
+    "@hearthscale/contract": "0.3.0"
   },
   "scripts": {
     "build": "node scripts/build.mjs",