@iyulab/lowline-form 0.11.0 → 0.12.1

package/dist/draft.d.ts

@@ -19,8 +19,18 @@ export interface Reported {
     promise?: number;
     score?: number;
 }
+/**
+ * Whether the promise of the answer shown was displayed beside it, and the probability it was drawn to be displayed with
+ * — fixed before the draw: 1 for a form that always displays it, 0 for one that never does.
+ */
+export interface PromiseShown {
+    shown: boolean;
+    probability: number;
+}
 interface Track extends Reported {
     shown?: Suggestion;
+    /** Whether the promise of the suggestion shown was displayed beside it. */
+    promise_shown?: PromiseShown;
     declined?: boolean;
     held?: number;
     /** The answer held back for a check, kept so the record can say what the person was not shown. */
@@ -36,9 +46,10 @@ interface Track extends Reported {
  *
  * Written as the engine reads it: `{ opened, fields: { field: { shown, declined, held } } }`, and — only what was
  * reported — `opened_at`, `saved_at` (milliseconds on one steady clock), `arrival` (the fields in the order their values
- * arrived), `by` and `batch`, and in a field `layer`, `promise`, `score`, `at` and `withheld`.
+ * arrived), `by` and `batch`, and in a field `layer`, `promise`, `score`, `promise_shown`, `at` and `withheld`.
  */
 export declare class Draft {
+    #private;
     readonly opened: Values;
     readonly fields: Record<string, Track>;
     private openedAt?;
@@ -48,7 +59,10 @@ export declare class Draft {
     private batch?;
     /** A record opened holding `values` — none for a new one. Empty values are left out. */
     constructor(values?: Values);
-    /** A suggestion came into view for the field. A suggestion turned down earlier stays turned down only if it is this. */
+    /**
+     * A suggestion came into view for the field. It is turned down if the person turned its value down before in this
+     * record — even with other suggestions shown since.
+     */
     show(field: string, suggestion: Suggestion, reported?: Reported): void;
     /**
      * The field's answer is held back for a check, drawn with `probability`: what the person settles is checked.
@@ -57,6 +71,12 @@ export declare class Draft {
     hold(field: string, probability: number, withheld?: {
         suggestion: Suggestion;
     } & Reported): void;
+    /**
+     * Whether the promise of the suggestion shown for the field was displayed beside it, drawn with `probability` (fixed
+     * before the draw: 1 for always, 0 for never). It stands until another suggestion is shown or the answer is held back
+     * for a check. False, changing nothing, when no suggestion is shown.
+     */
+    showPromise(field: string, shown: boolean, probability: number): boolean;
     /** The record was opened at `ms` on the session's clock (a steady clock in milliseconds: only differences are read). */
     openAt(ms: number): void;
     /** The record is being saved at `ms` on the same clock. */
@@ -72,7 +92,7 @@ export declare class Draft {
     private report;
     /** The person turned down the suggestion in view; false, changing nothing, when none was shown. */
     decline(field: string): boolean;
-    /** Whether `suggestion` is the one in view for the field and the person turned it down. */
+    /** Whether `suggestion` is the one in view for the field and the person turned it down — now or before, in this record. */
     declined(field: string, suggestion: Suggestion): boolean;
     shown(field: string): Suggestion | undefined;
     held(field: string): number | undefined;

package/dist/draft.js

@@ -6,20 +6,29 @@
  *
  * Written as the engine reads it: `{ opened, fields: { field: { shown, declined, held } } }`, and — only what was
  * reported — `opened_at`, `saved_at` (milliseconds on one steady clock), `arrival` (the fields in the order their values
- * arrived), `by` and `batch`, and in a field `layer`, `promise`, `score`, `at` and `withheld`.
+ * arrived), `by` and `batch`, and in a field `layer`, `promise`, `score`, `promise_shown`, `at` and `withheld`.
  */
 export class Draft {
+    /** The values the person turned down, by field: for this record, each stays turned down whatever is shown between. */
+    #turnedDown;
     /** A record opened holding `values` — none for a new one. Empty values are left out. */
     constructor(values = {}) {
         this.fields = {};
         this.arrival = [];
+        /** The values the person turned down, by field: for this record, each stays turned down whatever is shown between. */
+        this.#turnedDown = new Map();
         this.opened = Object.fromEntries(Object.entries(values).filter(([, v]) => !isEmpty(v)));
     }
-    /** A suggestion came into view for the field. A suggestion turned down earlier stays turned down only if it is this. */
+    /**
+     * A suggestion came into view for the field. It is turned down if the person turned its value down before in this
+     * record — even with other suggestions shown since.
+     */
     show(field, suggestion, reported = {}) {
         const track = (this.fields[field] ??= {});
-        if (!sameSuggestion(track.shown, suggestion))
-            track.declined = false;
+        if (!sameSuggestion(track.shown, suggestion)) {
+            track.declined = this.#turnedDown.get(field)?.has(suggestion.value) === true;
+            delete track.promise_shown;
+        }
         track.shown = { ...suggestion };
         delete track.held;
         delete track.withheld;
@@ -42,6 +51,21 @@ export class Draft {
         }
         this.fields[field] = track;
     }
+    /**
+     * Whether the promise of the suggestion shown for the field was displayed beside it, drawn with `probability` (fixed
+     * before the draw: 1 for always, 0 for never). It stands until another suggestion is shown or the answer is held back
+     * for a check. False, changing nothing, when no suggestion is shown.
+     */
+    showPromise(field, shown, probability) {
+        if (!(probability >= 0 && probability <= 1) || (shown ? probability === 0 : probability === 1)) {
+            throw new RangeError(`a promise ${shown ? 'shown' : 'not shown'} with probability ${probability} is not possible`);
+        }
+        const track = this.fields[field];
+        if (!track?.shown)
+            return false;
+        track.promise_shown = { shown, probability };
+        return true;
+    }
     /** The record was opened at `ms` on the session's clock (a steady clock in milliseconds: only differences are read). */
     openAt(ms) {
         this.openedAt = whole(ms);
@@ -88,9 +112,12 @@ export class Draft {
         if (!track?.shown)
             return false;
         track.declined = true;
+        const values = this.#turnedDown.get(field) ?? new Set();
+        values.add(track.shown.value);
+        this.#turnedDown.set(field, values);
         return true;
     }
-    /** Whether `suggestion` is the one in view for the field and the person turned it down. */
+    /** Whether `suggestion` is the one in view for the field and the person turned it down — now or before, in this record. */
     declined(field, suggestion) {
         const track = this.fields[field];
         return track?.declined === true && sameSuggestion(track.shown, suggestion);

package/dist/headless.d.ts

@@ -1,3 +1,3 @@
-export { Draft, valuesOf, type Suggestion, type Value, type Values } from './draft.js';
+export { Draft, valuesOf, type PromiseShown, type Suggestion, type Value, type Values } from './draft.js';
 export { Session, englishStrings, type Abstain, type Basis, type FieldState, type Proposal, type Round, type Strings } from './session.js';
 export { LowlineClient, LowlineError, type Attachment, type FieldReport, type ThresholdChoice } from './client.js';

package/dist/lowline-form.d.ts

@@ -28,8 +28,27 @@ export declare class LowlineForm extends LitElement {
     data: Record<string, unknown>;
     /** How often a field's answer is held back to check it, from 0 to 1. */
     rate: number;
+    /**
+     * The probability the host drew this record with to be settled again by a second person — an audit — from 0 (not
+     * audited, the default) to 1. Audited, the form shows none of what the first settler or the decider said: the decided
+     * fields' answers are held back with it as checks. Open the record with only the values it does not decide, and name
+     * the second person with `settled-by`.
+     */
+    audit: number;
     /** The words the form shows, in the host's language. */
     strings: Strings;
+    /**
+     * Whether a suggestion the engine allows to go in unasked is put in as the field's starting value. Off by default: a
+     * value in a field reads as the person's own, so a suggestion stays beside the field until the person takes it. A host
+     * that turns it on puts values in before anyone looks, and a value put in and saved unchanged is settled as taken.
+     */
+    prefill: boolean;
+    /**
+     * How often a suggestion's promise — how often a suggestion like it has been right, as a count out of ten — is shown
+     * beside it, from 0 to 1. Off (0) by default. Drawn once for each suggestion shown, and the draw is sent with the save,
+     * so a host can measure whether showing it helps people settle rightly before turning it on for everyone.
+     */
+    promiseRate: number;
     /** Who is writing, as an opaque id the host gives — one person, one id; not a name. Sent with the save when set. */
     settledBy: string;
     /** The batch the record is written in, when several come at once from one source. Sent with the save when set. */

package/dist/lowline-form.js

@@ -39,8 +39,27 @@ let LowlineForm = class LowlineForm extends LitElement {
         this.data = {};
         /** How often a field's answer is held back to check it, from 0 to 1. */
         this.rate = 0.05;
+        /**
+         * The probability the host drew this record with to be settled again by a second person — an audit — from 0 (not
+         * audited, the default) to 1. Audited, the form shows none of what the first settler or the decider said: the decided
+         * fields' answers are held back with it as checks. Open the record with only the values it does not decide, and name
+         * the second person with `settled-by`.
+         */
+        this.audit = 0;
         /** The words the form shows, in the host's language. */
         this.strings = englishStrings;
+        /**
+         * Whether a suggestion the engine allows to go in unasked is put in as the field's starting value. Off by default: a
+         * value in a field reads as the person's own, so a suggestion stays beside the field until the person takes it. A host
+         * that turns it on puts values in before anyone looks, and a value put in and saved unchanged is settled as taken.
+         */
+        this.prefill = false;
+        /**
+         * How often a suggestion's promise — how often a suggestion like it has been right, as a count out of ten — is shown
+         * beside it, from 0 to 1. Off (0) by default. Drawn once for each suggestion shown, and the draw is sent with the save,
+         * so a host can measure whether showing it helps people settle rightly before turning it on for everyone.
+         */
+        this.promiseRate = 0;
         /** Who is writing, as an opaque id the host gives — one person, one id; not a name. Sent with the save when set. */
         this.settledBy = '';
         /** The batch the record is written in, when several come at once from one source. Sent with the save when set. */
@@ -60,6 +79,8 @@ let LowlineForm = class LowlineForm extends LitElement {
             const formdown = this.formdown;
             if (formdown)
                 formdown.updateData({ ...formdown.data, [field]: value });
+            // A value taken is one the records can answer from: ask again, as after a value typed.
+            this.changed();
         };
         this.declined = (event) => {
             const { field } = event.detail;
@@ -80,11 +101,26 @@ let LowlineForm = class LowlineForm extends LitElement {
             this.client = new LowlineClient(this.src);
             this.canJudge = true;
         }
-        if (changed.has('record') || changed.has('form') || changed.has('data') || changed.has('content')) {
+        if (changed.has('record') ||
+            changed.has('form') ||
+            changed.has('data') ||
+            changed.has('content') ||
+            changed.has('audit')) {
             // The values it was opened with are taken before anything is suggested or put in.
             this.session = new Session(this.record, valuesOf(this.data), this.rate, Math.random, this.strings);
+            this.session.prefills = this.prefill;
+            this.session.promises = this.promiseRate;
+            this.session.audit = this.audit;
             this.fieldStates = {};
         }
+        else if (this.session) {
+            if (changed.has('prefill'))
+                this.session.prefills = this.prefill;
+            if (changed.has('promiseRate'))
+                this.session.promises = this.promiseRate;
+            if (changed.has('strings'))
+                this.session.strings = this.strings;
+        }
     }
     updated(changed) {
         if (changed.has('record') || changed.has('form') || changed.has('content'))
@@ -141,6 +177,8 @@ let LowlineForm = class LowlineForm extends LitElement {
         this.fieldStates = session.applyFill(proposals);
         if (this.formdown)
             this.formdown.fieldStates = this.fieldStates;
+        // The fields the writing did not fill keep what the records say of them.
+        void this.ask();
     }
     /** Asks again what to show for the decided fields still open. */
     async ask() {
@@ -170,7 +208,7 @@ let LowlineForm = class LowlineForm extends LitElement {
             session.took(this.values());
         }
         formdown.fieldStates = this.fieldStates;
-        if (this.canJudge)
+        if (this.canJudge && !session.auditing)
             void this.judge(session, values, shown);
     }
     /**
@@ -220,9 +258,18 @@ __decorate([
 __decorate([
     property({ type: Number })
 ], LowlineForm.prototype, "rate", void 0);
+__decorate([
+    property({ type: Number })
+], LowlineForm.prototype, "audit", void 0);
 __decorate([
     property({ attribute: false })
 ], LowlineForm.prototype, "strings", void 0);
+__decorate([
+    property({ type: Boolean })
+], LowlineForm.prototype, "prefill", void 0);
+__decorate([
+    property({ type: Number, attribute: 'promise-rate' })
+], LowlineForm.prototype, "promiseRate", void 0);
 __decorate([
     property({ attribute: 'settled-by' })
 ], LowlineForm.prototype, "settledBy", void 0);

package/dist/session.d.ts

@@ -55,6 +55,18 @@ export interface Strings {
     fromJudgement: string;
     /** The note of a value filled in from what the person wrote. */
     fromWriting: string;
+    /**
+     * The note of an empty decided field shown no suggestion, by why: a field is never left looking like one that is not
+     * decided. An empty text shows no note for that reason.
+     */
+    abstain: Record<Abstain, string>;
+    /** The note of an empty decided field a judgement was asked for and gave nothing the form can show. */
+    judgedNothing: string;
+    /**
+     * How often a suggestion like the one shown has been right, as a count out of ten — `{right}` is filled in. Said only
+     * when the host turns the display on (`promises`), after where the suggestion comes from.
+     */
+    promise: string;
 }
 export declare const englishStrings: Strings;
 /** What the form does with one round of proposals: what each field shows, and the values to put in unasked. */
@@ -71,7 +83,8 @@ export declare class Session {
     readonly id: string;
     readonly rate: number;
     private readonly random;
-    private readonly strings;
+    /** The words the form shows; a host may change them while a record is written, and the next round says them. */
+    strings: Strings;
     /** A steady clock in milliseconds (`performance.now()` by default): the record's times are read from it. */
     private readonly clock;
     draft: Draft;
@@ -80,11 +93,37 @@ export declare class Session {
     private filled;
     /** What filling from the person's writing offers, by field, until the person picks it or turns it down. */
     private written;
+    /** Why filling from the person's writing gave a field nothing to offer, by field, until it offers one. */
+    private unfilled;
     /** The judgement asked for each field, by what it reads; `null` while the host is still judging. */
     private judgements;
+    /**
+     * Whether a suggestion the engine allows to go in unasked (`prefill`) is put in as the field's starting value. Off, it
+     * stays beside the field until the person takes it.
+     */
+    prefills: boolean;
+    /**
+     * How often the promise of a suggestion is shown beside it, from 0 (never — the default) to 1 (always). Drawn once for
+     * each suggestion a field shows, and the draw goes into the draft — so the records can tell whether seeing it changed
+     * what people settled. A value outside 0 to 1 shows none.
+     */
+    promises: number;
+    /**
+     * The probability this record was drawn with to be settled again by a second person — an audit — or 0 (the default)
+     * for a record written as usual. Above 0 and at most 1, the person is shown nothing the first settler or the decider
+     * said: every decided field's answer is held back with this probability (a check), and no other suggestion, note or
+     * judgement is shown. The host draws the record and opens it with only the values it did not decide.
+     */
+    audit: number;
+    /** Whether the record is being audited: `audit` is a probability above 0 and at most 1. */
+    get auditing(): boolean;
+    /** The promise draw of the suggestion each field shows: whether its promise is shown. */
+    private promised;
     /** The values the form held when it was last looked at, to tell which fields' values arrived since. */
     private seen;
-    constructor(id: string, opened: Values, rate?: number, random?: () => number, strings?: Strings, 
+    constructor(id: string, opened: Values, rate?: number, random?: () => number, 
+    /** The words the form shows; a host may change them while a record is written, and the next round says them. */
+    strings?: Strings, 
     /** A steady clock in milliseconds (`performance.now()` by default): the record's times are read from it. */
     clock?: () => number);
     /**
@@ -133,6 +172,15 @@ export declare class Session {
     saved(values: Values): void;
     /** Whether the field's answer is held back now — drawn the first time a checkable value is proposed for it. */
     private draw;
+    /** How often promises are shown: `promises` when it is one, else never. */
+    private promiseRate;
+    /** Whether the promise of the field's suggestion `value` is shown — drawn the first time that suggestion is shown. */
+    private promiseShown;
+    /**
+     * A promise as a count out of ten, rounded down: a promise is never said higher than the records bear it out, and a
+     * count reads more plainly than a percentage.
+     */
+    private promiseNote;
     /** Where the suggestion comes from, in words. A field's value is shown as the record holds it now. */
     private note;
 }

package/dist/session.js

@@ -3,8 +3,20 @@ export const englishStrings = {
     decline: 'Not this',
     fromValue: 'As before with {field} {value}',
     fromSimilar: 'As in a similar record',
-    fromJudgement: 'Suggested from what was written',
+    fromJudgement: 'Judged from this record’s values — no settled record answers it',
     fromWriting: 'From what you wrote',
+    abstain: {
+        off: 'Yours to decide — this form suggests nothing here',
+        'no-evidence': 'No suggestion yet — nothing settled bears on it',
+        unsure: 'No suggestion — the records are not sure enough',
+        'not-allowed': 'No suggestion among the choices you may pick',
+        'needs-judgement': 'Needs your judgement — the records cannot tell',
+        'not-a-choice': 'No suggestion — the value given was not one of the choices',
+        malformed: 'No suggestion — the value given does not fit this field',
+        together: 'No suggestion until the fields decided with it are settled',
+    },
+    judgedNothing: 'Needs your judgement — neither the records nor a judgement gave a suggestion',
+    promise: 'right {right} times in 10 like this',
 };
 /**
  * One record being written: its draft, and what its fields show. A field's answer may be held back once, at random,
@@ -12,7 +24,13 @@ export const englishStrings = {
  * is looked at, and only for a value the decider suggests.
  */
 export class Session {
-    constructor(id, opened, rate = 0.05, random = Math.random, strings = englishStrings, 
+    /** Whether the record is being audited: `audit` is a probability above 0 and at most 1. */
+    get auditing() {
+        return this.audit > 0 && this.audit <= 1;
+    }
+    constructor(id, opened, rate = 0.05, random = Math.random, 
+    /** The words the form shows; a host may change them while a record is written, and the next round says them. */
+    strings = englishStrings, 
     /** A steady clock in milliseconds (`performance.now()` by default): the record's times are read from it. */
     clock = () => performance.now()) {
         this.id = id;
@@ -25,8 +43,30 @@ export class Session {
         this.filled = new Set();
         /** What filling from the person's writing offers, by field, until the person picks it or turns it down. */
         this.written = new Map();
+        /** Why filling from the person's writing gave a field nothing to offer, by field, until it offers one. */
+        this.unfilled = new Map();
         /** The judgement asked for each field, by what it reads; `null` while the host is still judging. */
         this.judgements = new Map();
+        /**
+         * Whether a suggestion the engine allows to go in unasked (`prefill`) is put in as the field's starting value. Off, it
+         * stays beside the field until the person takes it.
+         */
+        this.prefills = true;
+        /**
+         * How often the promise of a suggestion is shown beside it, from 0 (never — the default) to 1 (always). Drawn once for
+         * each suggestion a field shows, and the draw goes into the draft — so the records can tell whether seeing it changed
+         * what people settled. A value outside 0 to 1 shows none.
+         */
+        this.promises = 0;
+        /**
+         * The probability this record was drawn with to be settled again by a second person — an audit — or 0 (the default)
+         * for a record written as usual. Above 0 and at most 1, the person is shown nothing the first settler or the decider
+         * said: every decided field's answer is held back with this probability (a check), and no other suggestion, note or
+         * judgement is shown. The host draws the record and opens it with only the values it did not decide.
+         */
+        this.audit = 0;
+        /** The promise draw of the suggestion each field shows: whether its promise is shown. */
+        this.promised = new Map();
         this.draft = new Draft(opened);
         this.draft.openAt(this.clock());
         this.seen = { ...this.draft.opened };
@@ -63,29 +103,53 @@ export class Session {
             if (proposal.suggestion && !this.written.has(proposal.field))
                 this.draw(proposal);
         }
+        // Audited, the record shows nothing anyone said of it: answers that can be checked are held, the rest go unshown.
+        if (this.auditing)
+            return { fieldStates: {}, prefill: {} };
         // A field held back for a check holds back the open fields of its group: the person settling it with nothing in view
         // is not shown what is suggested alongside it. Only the held field is the check.
         const held = proposals.filter((p) => this.draft.held(p.field) !== undefined);
         const hidden = (p) => held.some((h) => h.field === p.field || (h.together != null && h.together === p.together));
         for (const proposal of proposals) {
             const { field, suggestion } = proposal;
-            if (!suggestion || this.written.has(field))
+            if (this.written.has(field))
                 continue;
             if (hidden(proposal))
                 continue;
-            // Turned down, it stays down for this record: neither shown again nor put back in.
-            if (this.draft.declined(field, suggestion))
+            if (!suggestion) {
+                // Why the field is empty, said beside it: silent, it would read as a field nothing is suggested for, and a
+                // person passes over it. A field that already holds a value needs no word.
+                const judged = this.judgements.get(field)?.proposal === proposal;
+                // A field that asks for a judgement on nothing yet has not been looked at: there is nothing to say of it.
+                const early = proposal.abstain === 'needs-judgement' && (proposal.asks?.length ?? 0) === 0;
+                const why = this.unfilled.get(field) ??
+                    (judged ? this.strings.judgedNothing : proposal.abstain && !early ? this.strings.abstain[proposal.abstain] : '');
+                if (why && isEmpty(values[field]))
+                    round.fieldStates[field] = { note: why };
                 continue;
+            }
+            // Turned down, it stays down for this record — whatever was suggested between: neither shown again nor put back in.
+            // The draft takes it as the suggestion in view, turned down, so the record says what was last offered.
             this.draft.show(field, suggestion, proposal);
+            if (this.draft.declined(field, suggestion))
+                continue;
+            // The answers that carry a promise say in the record whether it was shown beside them, and with what chance.
+            const promised = proposal.promise !== undefined && (suggestion.origin ?? 'decider') === 'decider';
+            const shown = promised && this.promiseShown(field, suggestion.value);
+            if (promised)
+                this.draft.showPromise(field, shown, this.promiseRate());
             this.draft.reach(field, this.clock());
-            if (proposal.prefill && isEmpty(values[field])) {
+            if (this.prefills && proposal.prefill && isEmpty(values[field])) {
                 round.prefill[field] = suggestion.value;
                 this.filled.add(field);
             }
+            const note = [this.note(proposal, values), shown ? this.promiseNote(proposal.promise) : undefined]
+                .filter((part) => part)
+                .join(' · ');
             round.fieldStates[field] = {
                 suggestions: [suggestion.value],
                 decline: this.strings.decline,
-                ...(this.note(proposal, values) ? { note: this.note(proposal, values) } : {}),
+                ...(note ? { note } : {}),
             };
         }
         return round;
@@ -138,14 +202,21 @@ export class Session {
      * on its own, in place of what the records suggest for the field. Answers what every field shows now.
      */
     applyFill(proposals) {
-        for (const { field, suggestion } of proposals) {
-            if (!suggestion)
+        for (const { field, suggestion, abstain } of proposals) {
+            if (!suggestion) {
+                // A value was given for the field that it cannot take: said beside the field, not dropped in silence.
+                const why = abstain ? this.strings.abstain[abstain] : '';
+                if (why)
+                    this.unfilled.set(field, why);
                 continue;
+            }
+            this.unfilled.delete(field);
             this.draft.show(field, suggestion);
             this.filled.delete(field);
             this.written.set(field, { suggestions: [suggestion.value], decline: this.strings.decline, note: this.strings.fromWriting });
         }
-        return Object.fromEntries(this.written);
+        const unfilled = [...this.unfilled].filter(([field]) => !this.written.has(field));
+        return { ...Object.fromEntries(this.written), ...Object.fromEntries(unfilled.map(([field, note]) => [field, { note }])) };
     }
     /** The person picked a field's offered value: what was offered from their writing has done its part. */
     picked(field) {
@@ -170,6 +241,7 @@ export class Session {
         this.draft.openAt(this.clock());
         this.seen = { ...this.draft.opened };
         this.drawn.clear();
+        this.promised.clear();
         this.filled.clear();
         this.written.clear();
         this.judgements.clear();
@@ -185,12 +257,38 @@ export class Session {
         if (!checkable)
             return false;
         this.drawn.add(field);
+        if (this.auditing) {
+            this.draft.hold(field, this.audit, { ...proposal, suggestion });
+            return true;
+        }
         if (this.rate > 0 && this.rate <= 1 && this.random() < this.rate) {
             this.draft.hold(field, this.rate, { ...proposal, suggestion });
             return true;
         }
         return false;
     }
+    /** How often promises are shown: `promises` when it is one, else never. */
+    promiseRate() {
+        return this.promises >= 0 && this.promises <= 1 ? this.promises : 0;
+    }
+    /** Whether the promise of the field's suggestion `value` is shown — drawn the first time that suggestion is shown. */
+    promiseShown(field, value) {
+        const drawn = this.promised.get(field);
+        if (drawn?.value === value)
+            return drawn.shown;
+        const rate = this.promiseRate();
+        const shown = rate >= 1 || (rate > 0 && this.random() < rate);
+        this.promised.set(field, { value, shown });
+        return shown;
+    }
+    /**
+     * A promise as a count out of ten, rounded down: a promise is never said higher than the records bear it out, and a
+     * count reads more plainly than a percentage.
+     */
+    promiseNote(promise) {
+        const right = Math.max(0, Math.min(10, Math.floor(promise * 10 + 1e-9)));
+        return this.strings.promise.replace('{right}', String(right));
+    }
     /** Where the suggestion comes from, in words. A field's value is shown as the record holds it now. */
     note(proposal, values) {
         const first = proposal.basis?.[0];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iyulab/lowline-form",
-  "version": "0.11.0",
+  "version": "0.12.1",
   "description": "The Lowline form element: a formdown form whose decided fields are suggested from the records people confirmed, talking to a Lowline host's routes.",
   "license": "MIT",
   "repository": {
@@ -40,12 +40,12 @@
     "bundle": "vite build --config vite.bundle.config.ts"
   },
   "dependencies": {
-    "@formdown/ui": "^0.26.0",
+    "@formdown/ui": "^0.26.1",
     "lit": "^3.3.3"
   },
   "devDependencies": {
-    "typescript": "^6.0.3",
-    "vite": "^8.3.1",
-    "vitest": "^5.0.2"
+    "typescript": "^7.0.2",
+    "vite": "^8.3.6",
+    "vitest": "^5.1.0"
   }
 }