@arraypress/extension-kit 1.6.0 → 1.8.0

package/src/testing/index.d.ts

@@ -1,5 +1,5 @@
 /**
- * The kit's test helpers: a fake `chrome.storage`, Playwright helpers for
+ * The kit's test helpers: a fake `chrome.storage`, a fake on-device model, Playwright helpers for
  * end-to-end tests (time limits, a pool, a browser that passes for a
  * person's) and a server for their pages, Chrome's install warnings and
  * saved tab groups, and checks for a packaging test. Node only.
@@ -8,19 +8,26 @@
  */
 export { TEST_BUILDS_ENV, testBuildDir } from '../build/test-build.js';
 export { chromeUserAgent, closeOnSignal, realisticBrowser } from './browser.js';
-export { CHECK_MS, checkRunner, checkToolbarTheme, extensionProfile, launchExtension, offscreenEmulator, recordIconCalls, until, } from './e2e.js';
+export { CHECK_MS, checkRunner, checkToolbarTheme, extensionProfile, launchExtension, offscreenEmulator, recordIconCalls, runChecks, until, } from './e2e.js';
 export { exitPoint, parseLiveOptions, parseProxy } from './live.js';
 export { eachLimited } from '../time/pool.js';
 export { filesIn, launchDownloading } from './downloads.js';
+export { fakeLanguageModel } from './fake-model.js';
+export { messageLookup, readMessages } from './messages.js';
+export { heartbeat } from './heartbeat.js';
+export { playPermissionPrompt } from './prompt.js';
 export { serve, testCertificate } from './server.js';
-export { SYNC_WRITES_PER_MINUTE, fakeChromeStorage } from './fake-storage.js';
+export { SYNC_QUOTA_BYTES, SYNC_WRITES_PER_MINUTE, fakeChromeStorage } from './fake-storage.js';
 export { filesUnder, manifestReferences, missingReferences, referencedPath, zipEntries } from './package.js';
 export { savedTabGroups } from './saved-groups.js';
 export { installWarnings, warningsAddedBy, withoutPermissions } from './warnings.js';
 export type CheckRunner = import('./e2e.js').CheckRunner;
+export type FakeLanguageModel = import('./fake-model.js').FakeLanguageModel;
+export type FakeModelState = import('./fake-model.js').FakeModelState;
 export type ExtensionProfile = import('./e2e.js').ExtensionProfile;
 export type LaunchedExtension = import('./e2e.js').LaunchedExtension;
 export type LaunchOptions = import('./e2e.js').LaunchOptions;
+export type Messages = import('./messages.js').Messages;
 export type Exit = import('./live.js').Exit;
 export type LiveOptions = import('./live.js').LiveOptions;
 export type SavedTabGroup = import('./saved-groups.js').SavedTabGroup;
@@ -32,9 +39,12 @@ export type TestServer = import('./server.js').TestServer;
  * The helpers' types, for a test's JSDoc.
  *
  * @typedef {import('./e2e.js').CheckRunner} CheckRunner
+ * @typedef {import('./fake-model.js').FakeLanguageModel} FakeLanguageModel
+ * @typedef {import('./fake-model.js').FakeModelState} FakeModelState
  * @typedef {import('./e2e.js').ExtensionProfile} ExtensionProfile
  * @typedef {import('./e2e.js').LaunchedExtension} LaunchedExtension
  * @typedef {import('./e2e.js').LaunchOptions} LaunchOptions
+ * @typedef {import('./messages.js').Messages} Messages
  * @typedef {import('./live.js').Exit} Exit
  * @typedef {import('./live.js').LiveOptions} LiveOptions
  * @typedef {import('./saved-groups.js').SavedTabGroup} SavedTabGroup

package/src/testing/index.js

@@ -1,5 +1,5 @@
 /**
- * The kit's test helpers: a fake `chrome.storage`, Playwright helpers for
+ * The kit's test helpers: a fake `chrome.storage`, a fake on-device model, Playwright helpers for
  * end-to-end tests (time limits, a pool, a browser that passes for a
  * person's) and a server for their pages, Chrome's install warnings and
  * saved tab groups, and checks for a packaging test. Node only.
@@ -10,13 +10,17 @@
 export { TEST_BUILDS_ENV, testBuildDir } from '../build/test-build.js';
 export { chromeUserAgent, closeOnSignal, realisticBrowser } from './browser.js';
 export {
-  CHECK_MS, checkRunner, checkToolbarTheme, extensionProfile, launchExtension, offscreenEmulator, recordIconCalls, until,
+  CHECK_MS, checkRunner, checkToolbarTheme, extensionProfile, launchExtension, offscreenEmulator, recordIconCalls, runChecks, until,
 } from './e2e.js';
 export { exitPoint, parseLiveOptions, parseProxy } from './live.js';
 export { eachLimited } from '../time/pool.js';
 export { filesIn, launchDownloading } from './downloads.js';
+export { fakeLanguageModel } from './fake-model.js';
+export { messageLookup, readMessages } from './messages.js';
+export { heartbeat } from './heartbeat.js';
+export { playPermissionPrompt } from './prompt.js';
 export { serve, testCertificate } from './server.js';
-export { SYNC_WRITES_PER_MINUTE, fakeChromeStorage } from './fake-storage.js';
+export { SYNC_QUOTA_BYTES, SYNC_WRITES_PER_MINUTE, fakeChromeStorage } from './fake-storage.js';
 export { filesUnder, manifestReferences, missingReferences, referencedPath, zipEntries } from './package.js';
 export { savedTabGroups } from './saved-groups.js';
 export { installWarnings, warningsAddedBy, withoutPermissions } from './warnings.js';
@@ -25,9 +29,12 @@ export { installWarnings, warningsAddedBy, withoutPermissions } from './warnings
  * The helpers' types, for a test's JSDoc.
  *
  * @typedef {import('./e2e.js').CheckRunner} CheckRunner
+ * @typedef {import('./fake-model.js').FakeLanguageModel} FakeLanguageModel
+ * @typedef {import('./fake-model.js').FakeModelState} FakeModelState
  * @typedef {import('./e2e.js').ExtensionProfile} ExtensionProfile
  * @typedef {import('./e2e.js').LaunchedExtension} LaunchedExtension
  * @typedef {import('./e2e.js').LaunchOptions} LaunchOptions
+ * @typedef {import('./messages.js').Messages} Messages
  * @typedef {import('./live.js').Exit} Exit
  * @typedef {import('./live.js').LiveOptions} LiveOptions
  * @typedef {import('./saved-groups.js').SavedTabGroup} SavedTabGroup

package/src/testing/messages.d.ts

@@ -0,0 +1,33 @@
+export type Messages = Record<string, {
+    message: string;
+    description?: string;
+    placeholders?: Record<string, {
+        content: string;
+    }>;
+}>;
+/**
+ * One locale's messages.json.
+ *
+ * @typedef {Record<string, {message: string, description?: string, placeholders?: Record<string, {content: string}>}>} Messages
+ */
+/**
+ * Read a locale's messages.
+ *
+ * @param {string} extensionDir - The extension's folder (with `_locales/`).
+ * @param {string} locale - "en" or "en_GB".
+ * @returns {Messages} Its messages.
+ * @example
+ * readMessages('extension', 'en_GB').optionsColour.message;
+ */
+export declare function readMessages(extensionDir: string, locale: string): Messages;
+/**
+ * `chrome.i18n.getMessage` over a locale's real messages ('' for a missing key, as Chrome gives).
+ *
+ * @param {string} extensionDir - The extension's folder.
+ * @param {string} [locale] - Default "en"; another locale is read over en.
+ * @returns {(key: string, substitutions?: string | string[]) => string} The lookup.
+ * @example
+ * const t = messageLookup('extension');
+ * t('optionsMoreActions', ['example.com']); // 'More actions for example.com'
+ */
+export declare function messageLookup(extensionDir: string, locale?: string): (key: string, substitutions?: string | string[]) => string;

package/src/testing/messages.js

@@ -0,0 +1,51 @@
+/**
+ * Chrome's message lookup for an extension's unit tests: its real `_locales`
+ * files, a locale's messages over `en`'s, named placeholders ("$SITE$" →
+ * `{site: {content: '$1'}}`) filled from substitutions as
+ * `chrome.i18n.getMessage` fills them. Node only. From the copies in Better
+ * Prices, Better Downloads, Better Saves and Clean Links (`test/helpers/i18n.js`).
+ *
+ * @module testing/messages
+ */
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+
+/**
+ * One locale's messages.json.
+ *
+ * @typedef {Record<string, {message: string, description?: string, placeholders?: Record<string, {content: string}>}>} Messages
+ */
+
+/**
+ * Read a locale's messages.
+ *
+ * @param {string} extensionDir - The extension's folder (with `_locales/`).
+ * @param {string} locale - "en" or "en_GB".
+ * @returns {Messages} Its messages.
+ * @example
+ * readMessages('extension', 'en_GB').optionsColour.message;
+ */
+export function readMessages(extensionDir, locale) {
+  return JSON.parse(readFileSync(path.join(extensionDir, '_locales', locale, 'messages.json'), 'utf8'));
+}
+
+/**
+ * `chrome.i18n.getMessage` over a locale's real messages ('' for a missing key, as Chrome gives).
+ *
+ * @param {string} extensionDir - The extension's folder.
+ * @param {string} [locale] - Default "en"; another locale is read over en.
+ * @returns {(key: string, substitutions?: string | string[]) => string} The lookup.
+ * @example
+ * const t = messageLookup('extension');
+ * t('optionsMoreActions', ['example.com']); // 'More actions for example.com'
+ */
+export function messageLookup(extensionDir, locale = 'en') {
+  const messages = { ...readMessages(extensionDir, 'en'), ...(locale === 'en' ? {} : readMessages(extensionDir, locale)) };
+  return (key, substitutions = []) => {
+    const entry = messages[key];
+    if (!entry) return '';
+    const subs = [substitutions].flat();
+    return entry.message.replace(/\$([A-Za-z_]+)\$/g, (_, name) => (entry.placeholders?.[name.toLowerCase()]?.content ?? '')
+      .replace(/\$(\d)/g, (/** @type {string} */ __, /** @type {string} */ n) => subs[Number(n) - 1] ?? ''));
+  };
+}

package/src/testing/prompt.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Chrome's permission prompt, played in an extension page for an e2e test: Playwright can't
+ * click Chrome's own prompt. From Topicless' and Better Screenshots' e2e helpers.
+ *
+ * @module testing/prompt
+ */
+/**
+ * Stand in for Chrome's permission prompt in a page: each `chrome.permissions.request` is
+ * recorded on `window.asked` (what was asked, and whether a click was behind it,
+ * `navigator.userActivation.isActive`) and answered from `answers` (the next one; the last is
+ * kept), as a person clicking “Allow” or “Deny” would. Runs in the page: give it to
+ * `page.evaluate` or `page.addInitScript`, so it takes no closures.
+ *
+ * @param {boolean[]} answers - The answers, in order.
+ * @example
+ * await page.evaluate(playPermissionPrompt, [true]);
+ * await page.click('#download');
+ * const asked = await page.evaluate(() => window.asked); // [{ permissions: ['downloads'], origins: undefined, gesture: true }]
+ */
+export declare function playPermissionPrompt(answers: boolean[]): void;

package/src/testing/prompt.js

@@ -0,0 +1,29 @@
+/**
+ * Chrome's permission prompt, played in an extension page for an e2e test: Playwright can't
+ * click Chrome's own prompt. From Topicless' and Better Screenshots' e2e helpers.
+ *
+ * @module testing/prompt
+ */
+
+/**
+ * Stand in for Chrome's permission prompt in a page: each `chrome.permissions.request` is
+ * recorded on `window.asked` (what was asked, and whether a click was behind it,
+ * `navigator.userActivation.isActive`) and answered from `answers` (the next one; the last is
+ * kept), as a person clicking “Allow” or “Deny” would. Runs in the page: give it to
+ * `page.evaluate` or `page.addInitScript`, so it takes no closures.
+ *
+ * @param {boolean[]} answers - The answers, in order.
+ * @example
+ * await page.evaluate(playPermissionPrompt, [true]);
+ * await page.click('#download');
+ * const asked = await page.evaluate(() => window.asked); // [{ permissions: ['downloads'], origins: undefined, gesture: true }]
+ */
+export function playPermissionPrompt(answers) {
+  /** @type {{permissions?: string[], origins?: string[], gesture: boolean}[]} */
+  const asked = [];
+  Object.assign(window, { asked });
+  chrome.permissions.request = /** @type {typeof chrome.permissions.request} */ (/** @type {unknown} */ (async (/** @type {chrome.permissions.Permissions} */ permissions) => {
+    asked.push({ permissions: permissions.permissions, origins: permissions.origins, gesture: navigator.userActivation.isActive });
+    return answers.length > 1 ? answers.shift() : answers[0];
+  }));
+}

package/src/ui/model-row.d.ts

@@ -0,0 +1,111 @@
+/**
+ * The settings row “Chrome’s built-in AI”: how the on-device model stands,
+ * what that means, and Download when it can be had, with Chrome's progress.
+ * The download starts from the click (Chrome only downloads from a user
+ * gesture): nothing is awaited in the click before `create()`. The words are
+ * the page's messages under {@link MODEL_MESSAGES}' keys.
+ *
+ * Markup it fills (the page's, so it sits in any card):
+ *
+ * ```html
+ * <div class="row two-line">
+ *   <span class="label">
+ *     <span data-i18n="optionsModel">Chrome’s built-in AI</span>
+ *     <span class="secondary"><span id="model-status"></span> <span id="model-help" hidden></span></span>
+ *     <progress id="model-progress" max="1" value="0" hidden></progress>
+ *   </span>
+ *   <button id="model-download" type="button" data-i18n="optionsModelDownload" hidden>Download</button>
+ * </div>
+ * ```
+ *
+ * @module ui/model-row
+ */
+import type { Availability, LanguageModelOptions, LanguageModelStatic, ModelStatus } from '../ai/model.js';
+export type ModelRowParts = {
+    /**
+     * The state's words.
+     */
+    status: HTMLElement;
+    /**
+     * What it means, or why a download failed.
+     */
+    help: HTMLElement;
+    /**
+     * Download.
+     */
+    download: HTMLButtonElement;
+    /**
+     * The download's progress, 0–1.
+     */
+    progress: HTMLProgressElement;
+};
+export type ModelRowOptions = {
+    /**
+     * What sessions are made with (a download is for these).
+     */
+    options: LanguageModelOptions;
+    /**
+     * The model's state as the code that uses it sees it (the
+     * worker's, asked by message, when the worker uses it).
+     */
+    state: () => Promise<Availability>;
+    /**
+     * The page's messages.
+     */
+    t: (key: string, substitutions?: string | string[]) => string;
+    /**
+     * The Prompt API in this page. Default Chrome's.
+     */
+    model?: () => LanguageModelStatic | undefined;
+    /**
+     * Hears each state shown
+     * (to turn the switches that need the model on or off).
+     */
+    onShown?: (status: ModelStatus, availability: Availability) => void;
+};
+export type ModelRow = {
+    /**
+     * Ask the state again and show it.
+     */
+    refresh: () => Promise<Availability>;
+    /**
+     * The state last shown (null before the first).
+     */
+    current: () => Availability | null;
+};
+/** @import { Availability, LanguageModelOptions, LanguageModelStatic, ModelStatus } from '../ai/model.js' */
+/**
+ * @typedef {object} ModelRowParts
+ * @property {HTMLElement} status The state's words.
+ * @property {HTMLElement} help What it means, or why a download failed.
+ * @property {HTMLButtonElement} download Download.
+ * @property {HTMLProgressElement} progress The download's progress, 0–1.
+ */
+/**
+ * @typedef {object} ModelRowOptions
+ * @property {LanguageModelOptions} options What sessions are made with (a download is for these).
+ * @property {() => Promise<Availability>} state The model's state as the code that uses it sees it (the
+ *   worker's, asked by message, when the worker uses it).
+ * @property {(key: string, substitutions?: string | string[]) => string} t The page's messages.
+ * @property {() => LanguageModelStatic | undefined} [model] The Prompt API in this page. Default Chrome's.
+ * @property {(status: ModelStatus, availability: Availability) => void} [onShown] Hears each state shown
+ *   (to turn the switches that need the model on or off).
+ */
+/**
+ * @typedef {object} ModelRow
+ * @property {() => Promise<Availability>} refresh Ask the state again and show it.
+ * @property {() => Availability | null} current The state last shown (null before the first).
+ */
+/**
+ * Wire the row up and show the model's state.
+ *
+ * @param {ModelRowParts} parts - The row's elements.
+ * @param {ModelRowOptions} setup - What to ask, and the words.
+ * @returns {ModelRow} The row.
+ * @example
+ * const row = createModelRow({ status: byId('model-status'), help: byId('model-help'),
+ *   download: byId('model-download', HTMLButtonElement), progress: byId('model-progress', HTMLProgressElement) },
+ *   { options: SESSION_OPTIONS, state: () => ask(MESSAGES.modelState), t, onShown: ({ state }) => { useAi.disabled = state === 'off'; } });
+ * await row.refresh();
+ */
+export declare function createModelRow({ status, help, download, progress }: ModelRowParts, { options, state, t, model, onShown }: ModelRowOptions): ModelRow;

package/src/ui/model-row.js

@@ -0,0 +1,108 @@
+/**
+ * The settings row “Chrome’s built-in AI”: how the on-device model stands,
+ * what that means, and Download when it can be had, with Chrome's progress.
+ * The download starts from the click (Chrome only downloads from a user
+ * gesture): nothing is awaited in the click before `create()`. The words are
+ * the page's messages under {@link MODEL_MESSAGES}' keys.
+ *
+ * Markup it fills (the page's, so it sits in any card):
+ *
+ * ```html
+ * <div class="row two-line">
+ *   <span class="label">
+ *     <span data-i18n="optionsModel">Chrome’s built-in AI</span>
+ *     <span class="secondary"><span id="model-status"></span> <span id="model-help" hidden></span></span>
+ *     <progress id="model-progress" max="1" value="0" hidden></progress>
+ *   </span>
+ *   <button id="model-download" type="button" data-i18n="optionsModelDownload" hidden>Download</button>
+ * </div>
+ * ```
+ *
+ * @module ui/model-row
+ */
+
+import { MODEL_MESSAGES, chromeLanguageModel, describeModel, downloadModel } from '../ai/model.js';
+
+/** @import { Availability, LanguageModelOptions, LanguageModelStatic, ModelStatus } from '../ai/model.js' */
+
+/**
+ * @typedef {object} ModelRowParts
+ * @property {HTMLElement} status The state's words.
+ * @property {HTMLElement} help What it means, or why a download failed.
+ * @property {HTMLButtonElement} download Download.
+ * @property {HTMLProgressElement} progress The download's progress, 0–1.
+ */
+
+/**
+ * @typedef {object} ModelRowOptions
+ * @property {LanguageModelOptions} options What sessions are made with (a download is for these).
+ * @property {() => Promise<Availability>} state The model's state as the code that uses it sees it (the
+ *   worker's, asked by message, when the worker uses it).
+ * @property {(key: string, substitutions?: string | string[]) => string} t The page's messages.
+ * @property {() => LanguageModelStatic | undefined} [model] The Prompt API in this page. Default Chrome's.
+ * @property {(status: ModelStatus, availability: Availability) => void} [onShown] Hears each state shown
+ *   (to turn the switches that need the model on or off).
+ */
+
+/**
+ * @typedef {object} ModelRow
+ * @property {() => Promise<Availability>} refresh Ask the state again and show it.
+ * @property {() => Availability | null} current The state last shown (null before the first).
+ */
+
+/**
+ * Wire the row up and show the model's state.
+ *
+ * @param {ModelRowParts} parts - The row's elements.
+ * @param {ModelRowOptions} setup - What to ask, and the words.
+ * @returns {ModelRow} The row.
+ * @example
+ * const row = createModelRow({ status: byId('model-status'), help: byId('model-help'),
+ *   download: byId('model-download', HTMLButtonElement), progress: byId('model-progress', HTMLProgressElement) },
+ *   { options: SESSION_OPTIONS, state: () => ask(MESSAGES.modelState), t, onShown: ({ state }) => { useAi.disabled = state === 'off'; } });
+ * await row.refresh();
+ */
+export function createModelRow({ status, help, download, progress }, { options, state, t, model = chromeLanguageModel, onShown }) {
+  /** @type {Availability | null} */
+  let shown = null;
+
+  /**
+   * Show a state, or why the last download failed.
+   *
+   * @param {Availability} availability - The model's.
+   * @param {string} [problem] - What went wrong.
+   */
+  function show(availability, problem = '') {
+    const described = describeModel(availability);
+    shown = availability;
+    status.dataset.state = described.state;
+    status.textContent = t(described.status);
+    help.textContent = problem || (described.help ? t(described.help) : '');
+    help.hidden = !help.textContent;
+    download.hidden = !described.canDownload;
+    download.disabled = false;
+    progress.hidden = true;
+    onShown?.(described, availability);
+  }
+
+  download.addEventListener('click', () => {
+    download.disabled = true;
+    progress.hidden = false;
+    progress.value = 0;
+    downloadModel(model(), options, {
+      onProgress: (loaded) => {
+        progress.value = loaded;
+        status.textContent = t(MODEL_MESSAGES.downloading, [String(Math.round(loaded * 100))]);
+      },
+    }).then(async () => show(await state()), () => show('downloadable', t(MODEL_MESSAGES.downloadFailed)));
+  });
+
+  return {
+    async refresh() {
+      const availability = await state();
+      show(availability);
+      return availability;
+    },
+    current: () => shown,
+  };
+}

package/src/ui/text-dialog.d.ts

@@ -20,13 +20,33 @@ export type FieldRequest = {
      */
     label: string;
     /**
-     * The text to start with. Default ''.
+     * The text to start with. Default ''. A promise is text
+     * still being worked out (an on-device model's suggestion): the field waits, disabled, with
+     * `waiting` under it, and takes the text when it comes ('' if it fails).
      */
-    value?: string;
+    value?: string | Promise<string>;
+    /**
+     * What the field says while its `value` is worked out ("Finding words…").
+     */
+    waiting?: string;
     /**
      * Shown while it's empty. Default none.
      */
     placeholder?: string;
+    /**
+     * A `<textarea>` (cr-textarea) rather than one line: Enter starts a new
+     * line, and only the action button saves. Default false.
+     */
+    multiline?: boolean;
+    /**
+     * A multi-line field's height in lines. Default 6.
+     */
+    rows?: number;
+    /**
+     * Help under the field (cr-input's
+     * description), or a function of its text, kept up as it's typed ("12 words"). Default none.
+     */
+    hint?: string | ((text: string) => string);
     /**
      * Why the (non-blank) text can't be used,
      * shown under the field; null when it can. Default: anything but blank.
@@ -71,8 +91,16 @@ export type FieldsRequest = DialogRequest & {
  * @typedef {object} FieldRequest
  * @property {string} name Its key in the answer ("folder"), and part of its id.
  * @property {string} label Its label ("Folder").
- * @property {string} [value] The text to start with. Default ''.
+ * @property {string | Promise<string>} [value] The text to start with. Default ''. A promise is text
+ *   still being worked out (an on-device model's suggestion): the field waits, disabled, with
+ *   `waiting` under it, and takes the text when it comes ('' if it fails).
+ * @property {string} [waiting] What the field says while its `value` is worked out ("Finding words…").
  * @property {string} [placeholder] Shown while it's empty. Default none.
+ * @property {boolean} [multiline] A `<textarea>` (cr-textarea) rather than one line: Enter starts a new
+ *   line, and only the action button saves. Default false.
+ * @property {number} [rows] A multi-line field's height in lines. Default 6.
+ * @property {string | ((text: string) => string)} [hint] Help under the field (cr-input's
+ *   description), or a function of its text, kept up as it's typed ("12 words"). Default none.
  * @property {(text: string) => string | null} [validate] Why the (non-blank) text can't be used,
  *   shown under the field; null when it can. Default: anything but blank.
  * @property {number} [maxLength] Its `maxlength`. Default none.
@@ -120,13 +148,14 @@ export declare function checkText(text: string, validate?: (text: string) => str
  *
  * @param {string} name - The field's name.
  * @param {boolean} only - Whether it's the dialog's only field.
- * @returns {{input: string, error: string}} The ids.
+ * @returns {{input: string, error: string, hint: string}} The ids.
  * @example
- * fieldIds('folder', false); // → {input: 'text-dialog-folder', error: 'text-dialog-folder-error'}
+ * fieldIds('folder', false); // → {input: 'text-dialog-folder', error: 'text-dialog-folder-error', hint: 'text-dialog-folder-hint'}
  */
 export declare function fieldIds(name: string, only: boolean): {
     input: string;
     error: string;
+    hint: string;
 };
 export type Parts = {
     /**
@@ -162,11 +191,19 @@ export type Field = {
     /**
      * Its input.
      */
-    input: HTMLInputElement;
+    input: HTMLInputElement | HTMLTextAreaElement;
     /**
      * The reason under it.
      */
     error: HTMLElement;
+    /**
+     * The help under it.
+     */
+    hint: HTMLElement;
+    /**
+     * Whether its value is still being worked out.
+     */
+    waiting: boolean;
 };
 /**
  * Ask for several pieces of text in the page's dialog, one field each.
@@ -199,4 +236,4 @@ export declare function askFields({ title, fields: requests, action, cancel, ret
  *   validate: (text) => (siteFromInput(text) ? null : 'Enter a site, like example.com'),
  * });
  */
-export declare function askText({ label, value, placeholder, validate, maxLength, ...dialog }: TextRequest): Promise<string | null>;
+export declare function askText({ label, value, placeholder, validate, maxLength, multiline, rows, hint, waiting, ...dialog }: TextRequest): Promise<string | null>;