@hearthscale/app 0.2.4 → 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,6 +29,24 @@ 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,
@@ -79,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. */
@@ -99,6 +137,8 @@ interface CompanionOption {
         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 {
@@ -171,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: {
@@ -620,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.
@@ -722,6 +764,7 @@ type TriggerDeclaration = {
     name: string;
     keys?: string;
     hold?: boolean;
+    armed?: boolean;
     kind: 'hotkey';
 } | {
     name: string;
@@ -800,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
@@ -952,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.
      */
@@ -991,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';
 };
 /**
@@ -1057,7 +1152,7 @@ type CompletionOption = 'logprobs' | 'topLogprobs' | 'topK' | 'minP' | 'grammar'
  * 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' | 'adapter' | '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
@@ -1177,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;
@@ -1205,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';
 /**
@@ -1441,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.
      */
@@ -1493,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.
      */
@@ -1731,7 +1840,7 @@ interface Manifest {
      * Semver, shown and never interpreted.
      */
     version: string;
-    api: 6;
+    api: 7;
     description: string;
     icon?: Schemed;
     license?: string;
@@ -1880,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.
      *
@@ -2070,6 +2190,14 @@ interface InstalledCompanionSource {
     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
  * app's tools with these arguments, `{}` when absent. A result that names
@@ -2102,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;
     /**
@@ -2109,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;
 }
@@ -2216,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;
     /**
@@ -2273,6 +2436,11 @@ interface ModelCard {
      * 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
@@ -2299,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,
@@ -2995,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;
     /**
@@ -3514,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. */
  | {
@@ -4313,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. */
@@ -4712,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
@@ -4959,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. */
@@ -4997,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
@@ -5016,6 +5216,7 @@ interface AppContext {
             };
             echo?: boolean;
             keep?: boolean;
+            part?: number;
         }): Promise<{
             capture: string;
             startedAt: number;
@@ -5034,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>;
@@ -5046,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
@@ -5225,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[]>;
@@ -5269,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.4",
+  "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.2.3"
+    "@hearthscale/contract": "0.3.0"
   },
   "scripts": {
     "build": "node scripts/build.mjs",