@seams/voice-capture 0.68.1 → 0.69.1

package/dist/esm/card/surface.js

@@ -8,7 +8,30 @@ import { VoicePrompt, leaveSurface } from "./prompt.js";
 //#region src/card/surface.ts
 const LABEL = "Say this with your voice";
 const PROMPT_LABEL = "Say this sentence";
-const PROMPT_MESSAGE = "Read it naturally, then pause.";
+/**
+* The status line before a recording: empty, so the sentence is the one text to read. It holds
+* "Opening microphone…", a loading line or a problem with the recording.
+*/
+const PROMPT_MESSAGE = "";
+/** The colours that a phrase card reads. */
+const PHRASE_CARD_COLORS = [
+	"colorBackground",
+	"textPrimary",
+	"textSecondary",
+	"textMuted",
+	"borderPrimary",
+	"surface",
+	"surface3",
+	"buttonBackground",
+	"textButton",
+	"error",
+	"info",
+	"voiceLine",
+	"voiceEcho",
+	"voiceEchoDeep",
+	"voiceFill",
+	"voicePixelBackground"
+];
 /**
 * Shows the given sentence in the prompt. The surface records clips with the quality check, and
 * stays open so the caller can show its check and the result in the same card. A too quiet or
@@ -27,6 +50,14 @@ var CardSurface = class {
 	pressed;
 	/** Back, when the card shows it apart from Close. */
 	back;
+	/** Minimize, when the host can hide the card. */
+	minimize;
+	minimizedHook;
+	progressedHook;
+	/** The person pressed Minimize, and the card has not asked to show again since. */
+	minimized = false;
+	/** The last stage that the host heard, as a key. */
+	progress = "";
 	recorder = null;
 	recording = null;
 	choice = null;
@@ -55,8 +86,10 @@ var CardSurface = class {
 		this.element.setAttribute("role", "dialog");
 		this.element.setAttribute("aria-modal", "true");
 		this.element.setAttribute("aria-label", LABEL);
+		paintColors(this.element, input.colors);
 		this.prompt = new VoicePrompt(document, LABEL, sentence);
-		this.prompt.title.textContent = PROMPT_LABEL;
+		const promptLabel = input.context?.sentenceLabel ?? PROMPT_LABEL;
+		this.prompt.title.textContent = promptLabel;
 		const shown = /[.!?]$/.test(sentence) ? sentence : `${sentence}.`;
 		this.prompt.phrase.textContent = shown;
 		delete this.prompt.phrase.dataset.voiceidPhrase;
@@ -65,7 +98,11 @@ var CardSurface = class {
 		const controls = frame.controls ?? "close";
 		this.pressed = frame.pressed;
 		const back = controls === "close" ? null : this.prompt.showBack(controls === "back_and_close");
+		if (input.context) this.prompt.showContext(input.context.label, input.context.text);
 		this.back = back === this.prompt.cancel ? null : back;
+		this.minimizedHook = frame.minimized;
+		this.progressedHook = frame.progressed;
+		this.minimize = frame.minimized ? this.prompt.showMinimize() : null;
 		const handedOverPrompt = handedOver?.querySelector(":scope > .seams-voiceid-prompt") ?? null;
 		const rows = handedOverPrompt ? handedOverRows(handedOverPrompt) : null;
 		if (handedOverPrompt) {
@@ -74,7 +111,7 @@ var CardSurface = class {
 			this.autoStart = false;
 		}
 		this.card = new PhraseCard(this.prompt, {
-			label: PROMPT_LABEL,
+			label: promptLabel,
 			sentence: shown,
 			message: PROMPT_MESSAGE,
 			action: "Record"
@@ -89,10 +126,13 @@ var CardSurface = class {
 		const corner = controls === "back" ? this.pressBack : this.pressClose;
 		this.prompt.cancel.addEventListener("click", corner);
 		this.back?.addEventListener("click", this.pressBack);
+		this.minimize?.addEventListener("click", this.pressMinimize);
 		this.element.addEventListener("cancel", this.cancel);
 		outer.addEventListener("abort", this.cancel);
 		if (handedOver) handedOver.replaceWith(this.element);
 		else parent.appendChild(this.element);
+		const voiceLine = input.voiceLine ?? themeVoiceLine(this.prompt.element);
+		if (voiceLine === "pixels") this.prompt.useVoiceLine(voiceLine);
 		if (frame.hugged) this.element.classList.add("seams-voiceid-hugged");
 		this.unmounted = frame.mounted?.(this.element);
 		if (rows || this.autoStart) this.prompt.element.focus({ preventScroll: true });
@@ -107,6 +147,11 @@ var CardSurface = class {
 		this.recording = recording;
 		if (this.view) {
 			this.view = null;
+			this.report({
+				stage: "recording",
+				done: 0,
+				total: 0
+			});
 			this.card.showPrompt();
 		} else if (this.autoStart) this.begin(recording);
 		this.autoStart = false;
@@ -117,6 +162,21 @@ var CardSurface = class {
 		if (this.closed) return Promise.resolve("closed");
 		this.settleChoice("replaced");
 		this.view = view;
+		if (view.kind === "check") {
+			const done = view.segments.filter((state) => state === "done" || state === "skip").length;
+			this.report({
+				stage: "checking",
+				done,
+				total: view.segments.length
+			});
+		} else {
+			this.report({
+				stage: "result",
+				done: 0,
+				total: 0
+			});
+			this.needPerson();
+		}
 		this.card.show(view);
 		return new Promise((resolve) => {
 			this.choice = resolve;
@@ -135,6 +195,7 @@ var CardSurface = class {
 		this.prompt.cancel.removeEventListener("click", this.pressBack);
 		this.prompt.cancel.removeEventListener("click", this.pressClose);
 		this.back?.removeEventListener("click", this.pressBack);
+		this.minimize?.removeEventListener("click", this.pressMinimize);
 		this.card.dispose();
 		this.prompt.dispose();
 		leaveSurface(this.element);
@@ -150,6 +211,11 @@ var CardSurface = class {
 	};
 	begin(recording) {
 		this.started = true;
+		this.report({
+			stage: "recording",
+			done: 0,
+			total: 0
+		});
 		this.prompt.record.disabled = true;
 		this.prompt.status.textContent = this.speechDetectorReady ? "Opening microphone…" : `Loading ${captureConfig().label}…`;
 		this.attempt(recording, this.autoStart);
@@ -198,8 +264,14 @@ var CardSurface = class {
 	};
 	/** The end of speech starts the check in place; every other capture event is the prompt's. */
 	capture = (event) => {
-		if (event.kind === "processing") this.card.beginCheck();
-		else this.prompt.capture(event);
+		if (event.kind === "processing") {
+			this.report({
+				stage: "checking",
+				done: 0,
+				total: 0
+			});
+			this.card.beginCheck();
+		} else this.prompt.capture(event);
 	};
 	retry(message, action = "Try again") {
 		this.started = false;
@@ -207,6 +279,31 @@ var CardSurface = class {
 		this.prompt.record.textContent = action;
 		this.prompt.ready(message);
 		this.prompt.record.focus();
+		this.report({
+			stage: "recording",
+			done: 0,
+			total: 0
+		});
+		this.needPerson();
+	}
+	/** Tells the host each new stage of the card. */
+	report(progress) {
+		const key = `${progress.stage}:${progress.done}:${progress.total}`;
+		if (key === this.progress || this.closed) return;
+		this.progress = key;
+		this.progressedHook?.(progress);
+	}
+	/** The person asks the host to hide the card. A host that showed it again can hide it again. */
+	pressMinimize = () => {
+		if (this.closed) return;
+		this.minimized = true;
+		this.minimizedHook?.(true);
+	};
+	/** The card needs the person: the host shows the card that it hid. */
+	needPerson() {
+		if (!this.minimized) return;
+		this.minimized = false;
+		this.minimizedHook?.(false);
 	}
 	settleChoice(choice) {
 		const settle = this.choice;
@@ -233,6 +330,18 @@ var CardSurface = class {
 		if (this.outer.aborted) this.close();
 	};
 };
+/** Sets the card's own colours. Keys that a card does not read are left out. */
+function paintColors(element, colors) {
+	if (!colors) return;
+	for (const key of PHRASE_CARD_COLORS) {
+		const value = colors[key];
+		if (value) element.style.setProperty(`--seams-colors-${key}`, value);
+	}
+}
+/** The theme's `--seams-shape-voiceLine`: `pixels`, or else the wave lines. */
+function themeVoiceLine(element) {
+	return getComputedStyle(element).getPropertyValue("--seams-shape-voiceLine").trim() === "pixels" ? "pixels" : "wave";
+}
 /** A failed early load runs again when Record needs the detector, and shows its error there. */
 function ignoreEarlyLoad() {}
 /** The rows that the handed-over card shows now. */

package/dist/esm/card/visual.js

@@ -1,2 +1,2 @@
-import { n as beamPalette, t as VoiceVisual } from "../chunks/visual-CeEQ8QkM.js";
+import { n as beamPalette, t as VoiceVisual } from "../chunks/visual-rOVJCP2w.js";
 export { VoiceVisual, beamPalette };

package/dist/esm/chunks/{visual-CeEQ8QkM.js → visual-rOVJCP2w.js}

@@ -1450,7 +1450,7 @@ const GREY_BAND = {
 		below: "#536471"
 	}
 };
-/** The theme's `voiceBeam`, the name of a Beam palette, or the default one. */
+/** The theme's `voiceBeam`, the name of a Beam palette, or the default one. (`none`: no Beam.) */
 function beamPalette(value) {
 	const name = value.trim();
 	return Object.hasOwn(Va, name) ? name : DEFAULT_BEAM;
@@ -1472,6 +1472,7 @@ var VoiceVisual = class {
 		this.glow.className = "seams-voiceid-glow";
 		this.glow.setAttribute("aria-hidden", "true");
 		this.render();
+		queueMicrotask(this.render);
 		const nonce = styleNonce();
 		if (nonce) for (const style of this.glow.querySelectorAll("style")) style.nonce = nonce;
 		this.themeObserver = new MutationObserver(this.render);
@@ -1484,6 +1485,10 @@ var VoiceVisual = class {
 			attributeFilter: ["data-theme"]
 		});
 	}
+	/** Draws the voice as wave lines (the default) or as columns of pixels. */
+	setLineStyle(style) {
+		this.ribbon.setLineStyle(style);
+	}
 	listen() {
 		this.setPhase("listening");
 	}
@@ -1528,8 +1533,14 @@ var VoiceVisual = class {
 	}
 	render = () => {
 		if (this.disposed) return;
+		const beam = getComputedStyle(this.prompt).getPropertyValue("--seams-colors-voiceBeam").trim();
+		this.glow.hidden = beam === "none";
+		if (this.glow.hidden) {
+			render(null, this.glow);
+			return;
+		}
 		const mode = (this.prompt.closest("[data-theme]")?.getAttribute("data-theme") ?? this.prompt.ownerDocument.documentElement.getAttribute("data-theme")) === "light" ? "light" : "dark";
-		const palette = beamPalette(getComputedStyle(this.prompt).getPropertyValue("--seams-colors-voiceBeam"));
+		const palette = beamPalette(beam);
 		render(createElement(VoiceBeamView, {
 			className: "seams-voiceid-beam",
 			theme: mode,

package/dist/types/card/index.d.ts

@@ -1,6 +1,6 @@
-export { openPhraseCard, type PhraseCardControl, type PhraseCardControls, type PhraseCardFrame, type PhraseCardInput, } from './surface';
+export { openPhraseCard, type PhraseCardColor, type PhraseCardColors, type PhraseCardContext, type PhraseCardControl, type PhraseCardControls, type PhraseCardFrame, type PhraseCardInput, type PhraseCardProgress, } from './surface';
 export type { PhraseCheckView, PhraseChoice, PhraseRecording, PhraseResultView, PhraseSegmentState, PhraseSurface, PhraseText, PhraseView, } from './types';
 export { leaveSurface, VoicePrompt, type PhraseDisplay, type PromptChange } from './prompt';
 export { PhraseCard, type HandedOverRows, type PromptCopy } from './phraseCard';
-export { VoiceRibbon, type VoiceCheckingStyle } from './ribbon';
+export { VoiceRibbon, type VoiceCheckingStyle, type VoiceLineStyle } from './ribbon';
 export { VoiceVisual } from './visual';

package/dist/types/card/prompt.d.ts

@@ -1,5 +1,5 @@
 import type { VoiceCaptureEvent } from '../microphone';
-import type { VoiceCheckingStyle } from './ribbon';
+import type { VoiceCheckingStyle, VoiceLineStyle } from './ribbon';
 /** How the card shows a phrase: by default as it is, with a capital letter and a full stop. */
 export type PhraseDisplay = (phrase: string) => string;
 /** A new state of the card's rows. Rows that it leaves out keep their content. */
@@ -45,12 +45,24 @@ export declare class VoicePrompt {
     constructor(document: Document, label: string, phrase: string, checking?: VoiceCheckingStyle, 
     /** The text to show for a phrase, such as the phrase with its commas. */
     display?: PhraseDisplay);
+    /** Draws the voice as wave lines (the default) or as columns of pixels. */
+    useVoiceLine(style: VoiceLineStyle): void;
+    /**
+     * Shows the text that the sentence speaks for, such as the note that a spoken summary signs,
+     * above the sentence. It stays for the check and the result.
+     */
+    showContext(label: string, text: string): void;
     /**
      * In an app's dialog with a step before this card, Back in the leading corner returns to that
      * step. With `close`, Close stays in the trailing corner and ends the whole dialog; without it,
      * Back takes Close's place. Each one ends the card as cancelled. The result is the Back control.
      */
     showBack(close: boolean): HTMLButtonElement;
+    /**
+     * Minimize in the trailing corner, beside Close. It stays in the check, where Close is hidden,
+     * so the person can hide the card while the check goes on. The result is the control.
+     */
+    showMinimize(): HTMLButtonElement;
     /**
      * Moves the rows to a new state. The rows whose content changes fade out together, take their
      * new content and fade in one after another; the other rows stay still. A change that comes

package/dist/types/card/ribbon.d.ts

@@ -2,6 +2,8 @@ import type { VoiceActivityEvent } from '../microphone';
 type RibbonPhase = 'idle' | 'listening' | 'processing';
 /** How the line shows that the voice is being checked. */
 export type VoiceCheckingStyle = 'ring' | 'segments';
+/** How the card draws the voice while it listens: sine wave lines, or columns of pixels. */
+export type VoiceLineStyle = 'wave' | 'pixels';
 /** Visual feedback from recorder activity. Never opens or retains an audio stream. */
 export declare class VoiceRibbon {
     private readonly checking;
@@ -25,8 +27,19 @@ export declare class VoiceRibbon {
     private target;
     private level;
     private stopped;
+    private lineStyle;
+    /** The pixel style's dots by column, top row first. Made when the style is first chosen. */
+    private pixels;
+    /** The level of each column, the newest at the right end. */
+    private readonly pixelLevels;
+    /** The rows that each column shows now, above and below the middle row. */
+    private readonly pixelHeights;
+    private pixelClock;
     constructor(document: Document, checking?: VoiceCheckingStyle);
     readonly readLevel: () => number;
+    /** Draws the voice as wave lines (the default) or as columns of pixels. */
+    setLineStyle(style: VoiceLineStyle): void;
+    private makePixels;
     /** The voice line's width now: 1, or the theme's `voiceLineWidth`. */
     private lineWidth;
     setPhase(phase: RibbonPhase): void;
@@ -43,8 +56,12 @@ export declare class VoiceRibbon {
     private wake;
     private readonly draw;
     private idleAmplitude;
+    /** Adds the level of each step at the right end; the older columns move left. */
+    private stepPixels;
     private paint;
     private paintLine;
+    /** Each column shows the middle dot and as many rows above and below it as its level. */
+    private paintPixels;
     private paintSegments;
     /** Each segment brightens one beat after the one before it, from the resting line's opacity. */
     private segmentOpacity;

package/dist/types/card/rowMotion.d.ts

@@ -1,5 +1,5 @@
 export declare const ROW_OUT_MS = 150;
-export declare const ROW_IN_MS = 200;
-export declare const ROW_IN_DELAY_MS = 20;
-export declare const ROW_STAGGER_MS = 30;
+export declare const ROW_IN_MS = 140;
+export declare const ROW_IN_DELAY_MS = 0;
+export declare const ROW_STAGGER_MS = 20;
 export declare const ROW_EASE = "cubic-bezier(0.2, 0, 0, 1)";

package/dist/types/card/surface.d.ts

@@ -1,4 +1,5 @@
 import { type VoiceRecordingOptions } from '../microphone';
+import type { VoiceLineStyle } from './ribbon';
 import type { PhraseSurface } from './types';
 /** What the host page adds around the card. Every field is optional. */
 export type PhraseCardFrame = Readonly<{
@@ -14,6 +15,16 @@ export type PhraseCardFrame = Readonly<{
     controls?: PhraseCardControls;
     /** Runs when the person presses Back or Close, before the card ends. Escape is not a press. */
     pressed?(control: PhraseCardControl): void;
+    /**
+     * With it, the card draws Minimize in the trailing corner, beside Close, also in the check.
+     * A press runs `minimized(true)`. The card does not hide itself: the host hides it, and the
+     * recording, the check and the caller's work go on. The card runs `minimized(false)` when it
+     * needs the person again: on a result, and when a recording needs another try. The host can
+     * show the card again before that.
+     */
+    minimized?(minimized: boolean): void;
+    /** Runs on each new stage of the card, so the host can show the progress of a hidden card. */
+    progressed?(progress: PhraseCardProgress): void;
     /** The host sizes its frame to the surface, so the card follows the frame. */
     hugged?: boolean;
     /** Runs when the surface is in the document. Its return value runs when the surface closes. */
@@ -23,6 +34,16 @@ export type PhraseCardFrame = Readonly<{
 export type PhraseCardControls = 'close' | 'back' | 'back_and_close';
 /** One corner control of a phrase card. */
 export type PhraseCardControl = 'back' | 'close';
+/**
+ * The stage of a phrase card: it records the sentence (or waits for Record), it checks the
+ * recording, or it shows a result.
+ */
+export type PhraseCardProgress = Readonly<{
+    stage: 'recording' | 'checking' | 'result';
+    /** The parts of the check that are over, of `total`. Both are 0 outside a check. */
+    done: number;
+    total: number;
+}>;
 export type PhraseCardInput = Readonly<{
     sentence: string;
     signal: AbortSignal;
@@ -35,6 +56,49 @@ export type PhraseCardInput = Readonly<{
      * start audio without a press, the card stays with its Record button.
      */
     autoStart?: boolean;
+    /**
+     * The text that the sentence speaks for, such as the note that a spoken summary signs. With
+     * it, the card is a form: the text in a soft box under its label, the sentence centred in a
+     * box under its own label, and one button at the foot that is the voice line while the card
+     * records. The text stays for the check and the result.
+     */
+    context?: PhraseCardContext;
+    /**
+     * How the card draws the voice while it listens: `wave`, sine wave lines (the default), or
+     * `pixels`, columns of dots in blue tones. Without it, the theme value `--seams-shape-voiceLine`
+     * (`wave` or `pixels`) decides, so a Wallet host can choose it with its theme.
+     */
+    voiceLine?: VoiceLineStyle;
+    /**
+     * The card's colours, as CSS colours, for example `{ buttonBackground: '#1d9bf0' }`. Each one
+     * sets the CSS variable `--seams-colors-<key>` on this card, over the page's own value. A
+     * Seams Wallet app sets the same keys in `appearance.theme.colors`.
+     */
+    colors?: PhraseCardColors;
+}>;
+/** The colours that a phrase card reads. */
+declare const PHRASE_CARD_COLORS: readonly [
+/** The card, its text, its lines and its soft boxes. */
+'colorBackground', 'textPrimary', 'textSecondary', 'textMuted', 'borderPrimary', 'surface', 
+/** The segments of a check that have not run yet. */
+'surface3', 
+/** The main button (Record, the voice line of a form card, Done) and its text. */
+'buttonBackground', 'textButton', 
+/** A failed check, and a held one. */
+'error', 'info', 
+/** The voice line, its echoes, and the bands of the pixel style. */
+'voiceLine', 'voiceEcho', 'voiceEchoDeep', 
+/** A form card: the fill of the sentence's box, and the button behind the pixels. */
+'voiceFill', 'voicePixelBackground'];
+export type PhraseCardColor = (typeof PHRASE_CARD_COLORS)[number];
+export type PhraseCardColors = Partial<Readonly<Record<PhraseCardColor, string>>>;
+/** The text that a phrase card shows above its sentence. */
+export type PhraseCardContext = Readonly<{
+    /** The label above the text, such as "Your note on @alice". */
+    label: string;
+    text: string;
+    /** The label above the sentence, such as "Read this aloud to post". Default: "Say this sentence". */
+    sentenceLabel?: string;
 }>;
 /**
  * Shows the given sentence in the prompt. The surface records clips with the quality check, and
@@ -42,3 +106,4 @@ export type PhraseCardInput = Readonly<{
  * interrupted recording stays on the surface for another try.
  */
 export declare function openPhraseCard(input: PhraseCardInput): PhraseSurface;
+export {};

package/dist/types/card/visual.d.ts

@@ -1,7 +1,7 @@
 import { type VoiceBeamColorVariant } from 'voice-glow';
 import type { VoiceActivityEvent } from '../microphone';
-import { type VoiceCheckingStyle } from './ribbon';
-/** The theme's `voiceBeam`, the name of a Beam palette, or the default one. */
+import { type VoiceCheckingStyle, type VoiceLineStyle } from './ribbon';
+/** The theme's `voiceBeam`, the name of a Beam palette, or the default one. (`none`: no Beam.) */
 export declare function beamPalette(value: string): VoiceBeamColorVariant;
 /** Shared by enrollment, unlock and signing. The recorder remains the only audio owner. */
 export declare class VoiceVisual {
@@ -13,6 +13,8 @@ export declare class VoiceVisual {
     private phase;
     private disposed;
     constructor(document: Document, prompt: HTMLElement, checking: VoiceCheckingStyle);
+    /** Draws the voice as wave lines (the default) or as columns of pixels. */
+    setLineStyle(style: VoiceLineStyle): void;
     listen(): void;
     add(event: VoiceActivityEvent): void;
     checking(): void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seams/voice-capture",
-  "version": "0.68.1",
+  "version": "0.69.1",
   "type": "module",
   "description": "Records one spoken sentence in the browser, with speech detection, a quality check and a phrase card",
   "license": "Apache-2.0",