@intellectif/lk-react 13.0.0 → 14.1.0

package/dist/components/PronunciationFeedback.d.cts

@@ -0,0 +1,67 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReadAloudData, SpeechAssessment, GradeRecord, ThemeTokens } from '@intellectif/lk-core';
+import { a as LkStringsOverride } from '../strings-wjAF2ONm.cjs';
+import '../machine-CuwKqWXC.cjs';
+
+interface PronunciationFeedbackProps {
+    /**
+     * The item's reading and its language. Only these two fields, because they
+     * are the only ones a mark depends on — everything else about the activity
+     * belongs to whoever rendered it.
+     */
+    data: Pick<ReadAloudData, 'referenceText' | 'locale'>;
+    /**
+     * The assessor's evidence. Checked with `validateSpeechAssessment` before it
+     * is aligned: see the note on this component about what a bad one costs.
+     */
+    assessment: SpeechAssessment;
+    /**
+     * The grade the evidence produced, when one exists. Its `criteria` are what
+     * the dimensions are read from, because they are the numbers the learner was
+     * actually graded on. A grade that cannot be read — a score that is not a
+     * number between 0 and its maximum, a `passed` that is not a boolean — is
+     * shown as could-not-be-graded, never as a percentage made up from it.
+     */
+    grade?: GradeRecord;
+    /**
+     * The learner's own take, playable. With it, each word that carries timings
+     * gets a button that plays just that word. A take the page refuses to play —
+     * a `blob:` URL under a Content-Security-Policy whose `media-src` does not
+     * allow one, most often — offers no such button, and the panel says the take
+     * cannot be played here.
+     */
+    audioUrl?: string;
+    /**
+     * Confidence above which a break note is shown, 0..1. **No default**: how
+     * confident an engine has to be before a pause is worth telling a learner
+     * about is a calibration, and the SDK has no calibrated answer. Without it no
+     * break note is shown at all.
+     */
+    breakThreshold?: number;
+    /** The same, for the monotone note read off `assessment.prosody`. */
+    monotoneThreshold?: number;
+    /**
+     * BCP 47 tag stamped as `lang` on the root: the INTERFACE language, the one
+     * this component's own sentences are written in. It is not `data.locale`,
+     * which is the language of the reading and is put on the words themselves.
+     */
+    locale?: string;
+    /** Per-instance token overrides, applied as inline CSS vars on the root. */
+    theme?: Partial<ThemeTokens>;
+    /** Overrides the SDK's chrome text for this panel. See {@link LkIntlProvider}. */
+    strings?: LkStringsOverride;
+}
+
+/**
+ * Public pronunciation-feedback panel: the core wrapped in
+ * `ActivityErrorBoundary` so a render failure (the dev throw for evidence
+ * `validateSpeechAssessment` refuses among them) degrades to an accessible
+ * fallback instead of crashing the host.
+ *
+ * **No `activityTitle`.** Its `data` is two fields of a read-aloud item and
+ * carries no title, so the production fallback is the unnamed one. Naming it
+ * would mean inventing a title for a panel that never had one.
+ */
+declare function PronunciationFeedback(props: PronunciationFeedbackProps): react_jsx_runtime.JSX.Element;
+
+export { PronunciationFeedback, type PronunciationFeedbackProps };

package/dist/components/PronunciationFeedback.d.ts

@@ -0,0 +1,67 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReadAloudData, SpeechAssessment, GradeRecord, ThemeTokens } from '@intellectif/lk-core';
+import { a as LkStringsOverride } from '../strings-l8Wv1Xax.js';
+import '../machine-CuwKqWXC.js';
+
+interface PronunciationFeedbackProps {
+    /**
+     * The item's reading and its language. Only these two fields, because they
+     * are the only ones a mark depends on — everything else about the activity
+     * belongs to whoever rendered it.
+     */
+    data: Pick<ReadAloudData, 'referenceText' | 'locale'>;
+    /**
+     * The assessor's evidence. Checked with `validateSpeechAssessment` before it
+     * is aligned: see the note on this component about what a bad one costs.
+     */
+    assessment: SpeechAssessment;
+    /**
+     * The grade the evidence produced, when one exists. Its `criteria` are what
+     * the dimensions are read from, because they are the numbers the learner was
+     * actually graded on. A grade that cannot be read — a score that is not a
+     * number between 0 and its maximum, a `passed` that is not a boolean — is
+     * shown as could-not-be-graded, never as a percentage made up from it.
+     */
+    grade?: GradeRecord;
+    /**
+     * The learner's own take, playable. With it, each word that carries timings
+     * gets a button that plays just that word. A take the page refuses to play —
+     * a `blob:` URL under a Content-Security-Policy whose `media-src` does not
+     * allow one, most often — offers no such button, and the panel says the take
+     * cannot be played here.
+     */
+    audioUrl?: string;
+    /**
+     * Confidence above which a break note is shown, 0..1. **No default**: how
+     * confident an engine has to be before a pause is worth telling a learner
+     * about is a calibration, and the SDK has no calibrated answer. Without it no
+     * break note is shown at all.
+     */
+    breakThreshold?: number;
+    /** The same, for the monotone note read off `assessment.prosody`. */
+    monotoneThreshold?: number;
+    /**
+     * BCP 47 tag stamped as `lang` on the root: the INTERFACE language, the one
+     * this component's own sentences are written in. It is not `data.locale`,
+     * which is the language of the reading and is put on the words themselves.
+     */
+    locale?: string;
+    /** Per-instance token overrides, applied as inline CSS vars on the root. */
+    theme?: Partial<ThemeTokens>;
+    /** Overrides the SDK's chrome text for this panel. See {@link LkIntlProvider}. */
+    strings?: LkStringsOverride;
+}
+
+/**
+ * Public pronunciation-feedback panel: the core wrapped in
+ * `ActivityErrorBoundary` so a render failure (the dev throw for evidence
+ * `validateSpeechAssessment` refuses among them) degrades to an accessible
+ * fallback instead of crashing the host.
+ *
+ * **No `activityTitle`.** Its `data` is two fields of a read-aloud item and
+ * carries no title, so the production fallback is the unnamed one. Naming it
+ * would mean inventing a title for a panel that never had one.
+ */
+declare function PronunciationFeedback(props: PronunciationFeedbackProps): react_jsx_runtime.JSX.Element;
+
+export { PronunciationFeedback, type PronunciationFeedbackProps };

package/dist/components/PronunciationFeedback.js

@@ -0,0 +1,7 @@
+'use client';
+export { PronunciationFeedback } from '../chunk-TUVEJLOT.js';
+import '../chunk-YORQQXGO.js';
+import '../chunk-B4BCEQNO.js';
+import '../chunk-AWQ53DON.js';
+//# sourceMappingURL=PronunciationFeedback.js.map
+//# sourceMappingURL=PronunciationFeedback.js.map

package/dist/components/PronunciationFeedback.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"PronunciationFeedback.js"}

package/dist/components/ReadAloud.cjs

@@ -0,0 +1,21 @@
+'use client';
+'use strict';
+
+var chunkKIO6QXGT_cjs = require('../chunk-KIO6QXGT.cjs');
+require('../chunk-YM64MS4G.cjs');
+require('../chunk-UDCQTOVU.cjs');
+require('../chunk-OD65OZIW.cjs');
+require('../chunk-BRPEB43C.cjs');
+require('../chunk-DPEY7DSE.cjs');
+require('../chunk-UMDWVMB5.cjs');
+require('../chunk-XOR4MPEN.cjs');
+require('../chunk-VSFHJ7FB.cjs');
+
+
+
+Object.defineProperty(exports, "ReadAloud", {
+  enumerable: true,
+  get: function () { return chunkKIO6QXGT_cjs.ReadAloud; }
+});
+//# sourceMappingURL=ReadAloud.cjs.map
+//# sourceMappingURL=ReadAloud.cjs.map

package/dist/components/ReadAloud.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"ReadAloud.cjs"}

package/dist/components/ReadAloud.d.cts

@@ -0,0 +1,15 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { c as ReadAloudProps } from '../strings-wjAF2ONm.cjs';
+export { R as ReadAloudAssessResult, d as RecordingBinding } from '../strings-wjAF2ONm.cjs';
+export { R as RecordedTake } from '../machine-CuwKqWXC.cjs';
+import '@intellectif/lk-core';
+
+/**
+ * Public Read Aloud activity: the core wrapped in `ActivityErrorBoundary` so a
+ * render failure (including the dev schema-validation throw and the
+ * missing-`upload` guard) degrades to an accessible fallback instead of
+ * crashing the host.
+ */
+declare function ReadAloud(props: ReadAloudProps): react_jsx_runtime.JSX.Element;
+
+export { ReadAloud, ReadAloudProps };

package/dist/components/ReadAloud.d.ts

@@ -0,0 +1,15 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { c as ReadAloudProps } from '../strings-l8Wv1Xax.js';
+export { R as ReadAloudAssessResult, d as RecordingBinding } from '../strings-l8Wv1Xax.js';
+export { R as RecordedTake } from '../machine-CuwKqWXC.js';
+import '@intellectif/lk-core';
+
+/**
+ * Public Read Aloud activity: the core wrapped in `ActivityErrorBoundary` so a
+ * render failure (including the dev schema-validation throw and the
+ * missing-`upload` guard) degrades to an accessible fallback instead of
+ * crashing the host.
+ */
+declare function ReadAloud(props: ReadAloudProps): react_jsx_runtime.JSX.Element;
+
+export { ReadAloud, ReadAloudProps };

package/dist/components/ReadAloud.js

@@ -0,0 +1,12 @@
+'use client';
+export { ReadAloud } from '../chunk-5JFMXBH7.js';
+import '../chunk-TUVEJLOT.js';
+import '../chunk-MCO52PV5.js';
+import '../chunk-YORQQXGO.js';
+import '../chunk-RCMYEWBE.js';
+import '../chunk-B4BCEQNO.js';
+import '../chunk-DB4DLHN6.js';
+import '../chunk-6N43WDVG.js';
+import '../chunk-AWQ53DON.js';
+//# sourceMappingURL=ReadAloud.js.map
+//# sourceMappingURL=ReadAloud.js.map

package/dist/components/ReadAloud.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"ReadAloud.js"}

package/dist/components/StimulusPanel.cjs

@@ -1,15 +1,15 @@
 'use client';
 'use strict';
 
-var chunk74QXBWCI_cjs = require('../chunk-74QXBWCI.cjs');
-require('../chunk-SBIJJ374.cjs');
-require('../chunk-MA7GXUWC.cjs');
+var chunkCTW3G3EH_cjs = require('../chunk-CTW3G3EH.cjs');
+require('../chunk-UMDWVMB5.cjs');
+require('../chunk-VSFHJ7FB.cjs');
 
 
 
 Object.defineProperty(exports, "StimulusPanel", {
   enumerable: true,
-  get: function () { return chunk74QXBWCI_cjs.StimulusPanel; }
+  get: function () { return chunkCTW3G3EH_cjs.StimulusPanel; }
 });
 //# sourceMappingURL=StimulusPanel.cjs.map
 //# sourceMappingURL=StimulusPanel.cjs.map

package/dist/components/StimulusPanel.d.cts

@@ -1,5 +1,6 @@
 import { Stimulus, InteractionEvent } from '@intellectif/lk-core';
-import { H as HtmlSanitizer, R as RenderMode, M as MediaBudgetBinding, b as MediaTransportStrings, a as LkStringsOverride } from '../strings-DPTyLpHt.cjs';
+import { H as HtmlSanitizer, e as RenderMode, M as MediaBudgetBinding, b as MediaTransportStrings, a as LkStringsOverride } from '../strings-wjAF2ONm.cjs';
+import '../machine-CuwKqWXC.cjs';
 
 interface StimulusPanelProps {
     stimulus: Stimulus;

package/dist/components/StimulusPanel.d.ts

@@ -1,5 +1,6 @@
 import { Stimulus, InteractionEvent } from '@intellectif/lk-core';
-import { H as HtmlSanitizer, R as RenderMode, M as MediaBudgetBinding, b as MediaTransportStrings, a as LkStringsOverride } from '../strings-DPTyLpHt.js';
+import { H as HtmlSanitizer, e as RenderMode, M as MediaBudgetBinding, b as MediaTransportStrings, a as LkStringsOverride } from '../strings-l8Wv1Xax.js';
+import '../machine-CuwKqWXC.js';
 
 interface StimulusPanelProps {
     stimulus: Stimulus;

package/dist/components/StimulusPanel.js

@@ -1,6 +1,6 @@
 'use client';
-export { StimulusPanel } from '../chunk-NVP6UEQQ.js';
-import '../chunk-R7DI5UMU.js';
-import '../chunk-3Q4I4KT6.js';
+export { StimulusPanel } from '../chunk-AS2QGND5.js';
+import '../chunk-DB4DLHN6.js';
+import '../chunk-AWQ53DON.js';
 //# sourceMappingURL=StimulusPanel.js.map
 //# sourceMappingURL=StimulusPanel.js.map

package/dist/components/WrittenResponse.cjs

@@ -1,17 +1,18 @@
 'use client';
 'use strict';
 
-var chunkUU2NV6SU_cjs = require('../chunk-UU2NV6SU.cjs');
-require('../chunk-K3EA547J.cjs');
-require('../chunk-SBIJJ374.cjs');
+var chunk4Y5TELVU_cjs = require('../chunk-4Y5TELVU.cjs');
+require('../chunk-BRPEB43C.cjs');
+require('../chunk-DPEY7DSE.cjs');
+require('../chunk-UMDWVMB5.cjs');
 require('../chunk-XOR4MPEN.cjs');
-require('../chunk-MA7GXUWC.cjs');
+require('../chunk-VSFHJ7FB.cjs');
 
 
 
 Object.defineProperty(exports, "WrittenResponse", {
   enumerable: true,
-  get: function () { return chunkUU2NV6SU_cjs.WrittenResponse; }
+  get: function () { return chunk4Y5TELVU_cjs.WrittenResponse; }
 });
 //# sourceMappingURL=WrittenResponse.cjs.map
 //# sourceMappingURL=WrittenResponse.cjs.map

package/dist/components/WrittenResponse.d.cts

@@ -1,8 +1,9 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
-import { W as WrittenResponseProps } from '../WrittenResponse-DWtS4tOL.cjs';
-export { a as WrittenResponseSubmission } from '../WrittenResponse-DWtS4tOL.cjs';
-export { H as HtmlSanitizer, R as RenderMode, c as Renderable } from '../strings-DPTyLpHt.cjs';
+import { W as WrittenResponseProps } from '../WrittenResponse-rRpOr9W1.cjs';
+export { a as WrittenResponseSubmission } from '../WrittenResponse-rRpOr9W1.cjs';
+export { H as HtmlSanitizer, e as RenderMode, f as Renderable } from '../strings-wjAF2ONm.cjs';
 import '@intellectif/lk-core';
+import '../machine-CuwKqWXC.cjs';
 
 /**
  * Public Written Response activity: a labelled textarea with a live word

package/dist/components/WrittenResponse.d.ts

@@ -1,8 +1,9 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
-import { W as WrittenResponseProps } from '../WrittenResponse-B5p_-RnJ.js';
-export { a as WrittenResponseSubmission } from '../WrittenResponse-B5p_-RnJ.js';
-export { H as HtmlSanitizer, R as RenderMode, c as Renderable } from '../strings-DPTyLpHt.js';
+import { W as WrittenResponseProps } from '../WrittenResponse-DrzI89Wg.js';
+export { a as WrittenResponseSubmission } from '../WrittenResponse-DrzI89Wg.js';
+export { H as HtmlSanitizer, e as RenderMode, f as Renderable } from '../strings-l8Wv1Xax.js';
 import '@intellectif/lk-core';
+import '../machine-CuwKqWXC.js';
 
 /**
  * Public Written Response activity: a labelled textarea with a live word

package/dist/components/WrittenResponse.js

@@ -1,8 +1,9 @@
 'use client';
-export { WrittenResponse } from '../chunk-YZWXVZB3.js';
-import '../chunk-DQERNAWI.js';
-import '../chunk-R7DI5UMU.js';
+export { WrittenResponse } from '../chunk-U432HTUW.js';
+import '../chunk-RCMYEWBE.js';
+import '../chunk-B4BCEQNO.js';
+import '../chunk-DB4DLHN6.js';
 import '../chunk-6N43WDVG.js';
-import '../chunk-3Q4I4KT6.js';
+import '../chunk-AWQ53DON.js';
 //# sourceMappingURL=WrittenResponse.js.map
 //# sourceMappingURL=WrittenResponse.js.map

package/dist/hooks/useSpeechRecorder.cjs

@@ -0,0 +1,17 @@
+'use client';
+'use strict';
+
+var chunkUDCQTOVU_cjs = require('../chunk-UDCQTOVU.cjs');
+
+
+
+Object.defineProperty(exports, "CAPTURE_PROCESSOR_SOURCE", {
+  enumerable: true,
+  get: function () { return chunkUDCQTOVU_cjs.CAPTURE_PROCESSOR_SOURCE; }
+});
+Object.defineProperty(exports, "useSpeechRecorder", {
+  enumerable: true,
+  get: function () { return chunkUDCQTOVU_cjs.useSpeechRecorder; }
+});
+//# sourceMappingURL=useSpeechRecorder.cjs.map
+//# sourceMappingURL=useSpeechRecorder.cjs.map

package/dist/hooks/useSpeechRecorder.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"useSpeechRecorder.cjs"}

package/dist/hooks/useSpeechRecorder.d.cts

@@ -0,0 +1,127 @@
+import { a as SpeechRecorderStatus, S as SpeechRecorderError, R as RecordedTake } from '../machine-CuwKqWXC.cjs';
+
+/**
+ * The audio worklet module `useSpeechRecorder` captures through, as source
+ * text — exported so an application with a strict Content-Security-Policy can
+ * serve it itself.
+ *
+ * By default the hook loads this text from a `blob:` URL. A worklet module is
+ * loaded as a script, so it is `script-src` that must allow `blob:` —
+ * `worker-src` does not govern it. Where that is refused, write this string to
+ * a file your policy's `script-src` does allow, at build time and from the
+ * installed package so it moves with the version you run, and pass that file's
+ * URL as `workletUrl`:
+ *
+ * ```ts
+ * import { writeFileSync } from 'node:fs';
+ * import { CAPTURE_PROCESSOR_SOURCE } from '@intellectif/lk-react/hooks/useSpeechRecorder';
+ *
+ * writeFileSync('public/lk-speech-capture.js', CAPTURE_PROCESSOR_SOURCE);
+ * ```
+ *
+ * **The contract** a module at `workletUrl` must meet, which this source does:
+ * register an `AudioWorkletProcessor` under the name `lk-speech-capture`, and
+ * from its `process(inputs)` post the first input's channels to its `port` as
+ * an array with one `Float32Array` per channel, **copied** — the render
+ * quantum's buffers belong to the audio thread and are overwritten on the next
+ * quantum, so a block posted without copying arrives as whatever the
+ * microphone heard some milliseconds later. Return `true`, which keeps the
+ * processor alive while its source is silent. Anything else changes what is
+ * recorded, so serve this text unchanged rather than a copy of your own.
+ */
+declare const CAPTURE_PROCESSOR_SOURCE: string;
+
+interface SpeechRecorderOptions {
+    /** The longest a take may be. Reached, the recording stops itself. */
+    maxDurationMs: number;
+    /** Shorter than this and the take is refused as `too-short`. */
+    minDurationMs?: number;
+    /** How many takes the learner may make. Unbounded when absent. */
+    maxTakes?: number;
+    /**
+     * The URL of a self-hosted copy of {@link CAPTURE_PROCESSOR_SOURCE}, for an
+     * application whose Content-Security-Policy does not allow `blob:` in
+     * `script-src`. Serve that string unchanged; the contract a module here must
+     * meet is written on it.
+     *
+     * **A URL that does not work is not reported.** If the module fails to load,
+     * or loads without registering `lk-speech-capture`, the hook records through
+     * the deprecated `ScriptProcessorNode` on the main thread instead — the
+     * fallback it keeps for engines without audio worklets — and a recorder with
+     * a broken `workletUrl` looks like a working one. Only an engine with neither
+     * path reports `error: 'unsupported'`. Check that the module is actually
+     * fetched.
+     */
+    workletUrl?: string;
+}
+interface SpeechRecorder {
+    status: SpeechRecorderStatus;
+    error: SpeechRecorderError | null;
+    /** The loudest block since the last update, 0..1. */
+    level: number;
+    /** How much audio has been captured, from the sample count. */
+    elapsedMs: number;
+    take: RecordedTake | null;
+    takesUsed: number;
+    /** Whether a take remains. Not whether a `start()` would be accepted now. */
+    canRecord: boolean;
+    /** Opens the microphone and begins capturing. **Never rejects.** */
+    start(): Promise<void>;
+    /** Ends the capture and encodes the take. */
+    stop(): void;
+    /** Throws the take away and releases the microphone. */
+    discard(): void;
+    /**
+     * Starts over: releases the microphone, throws the take away **and gives the
+     * budget back**.
+     *
+     * That last part is the whole difference from {@link SpeechRecorder.discard},
+     * which deliberately refunds nothing — a budget a re-record gave back would
+     * bound nothing. A reset is for a recorder that has been handed a different
+     * reading while it stayed mounted: the takes belong to the activity, so the
+     * next activity's are its own. Calling it for the same reading hands a
+     * learner takes they have already spent.
+     */
+    reset(): void;
+}
+/**
+ * Records a take of speech as mono 16-bit PCM WAV at 16 kHz.
+ *
+ * That is the one format the SDK measures directly: `inspectWav` reads it
+ * without a decoding library, and it is what every mainstream pronunciation
+ * assessor accepts. A take is captured at whatever rate the device runs at,
+ * downmixed to mono, low-pass filtered and resampled, then encoded — so what a
+ * server measures is what this hook produced, not a claim about it.
+ *
+ * **Server rendering.** `status`, `error` and `canRecord` are derived from the
+ * take count alone and never from a browser global, so the markup a server
+ * produces is the markup the browser's first render produces. Support is
+ * discovered inside {@link SpeechRecorder.start} and reported as
+ * `error: 'unsupported'`; the obvious `!!navigator.mediaDevices` guard at
+ * render time would make a server render and its hydration disagree.
+ *
+ * **Identity.** `start`, `stop`, `discard` and `reset` keep one identity for the
+ * life of the hook, so they are safe in a dependency array. The returned object keeps
+ * one identity for as long as none of its values changes, so a render caused
+ * by something else does not invalidate an effect that depends on it.
+ *
+ * `start()` does nothing when no take remains, so `canRecord` is presentation:
+ * mark the control `aria-disabled` rather than `disabled`, which would take it
+ * out of the tab order and leave a learner nothing to read.
+ *
+ * ```tsx
+ * const recorder = useSpeechRecorder({ maxDurationMs: 20_000, maxTakes: 3 });
+ * <button
+ *   type="button"
+ *   aria-disabled={!recorder.canRecord}
+ *   onClick={() => {
+ *     void recorder.start();
+ *   }}
+ * >
+ *   Record
+ * </button>
+ * ```
+ */
+declare function useSpeechRecorder(options: SpeechRecorderOptions): SpeechRecorder;
+
+export { CAPTURE_PROCESSOR_SOURCE, RecordedTake, type SpeechRecorder, SpeechRecorderError, type SpeechRecorderOptions, SpeechRecorderStatus, useSpeechRecorder };

package/dist/hooks/useSpeechRecorder.d.ts

@@ -0,0 +1,127 @@
+import { a as SpeechRecorderStatus, S as SpeechRecorderError, R as RecordedTake } from '../machine-CuwKqWXC.js';
+
+/**
+ * The audio worklet module `useSpeechRecorder` captures through, as source
+ * text — exported so an application with a strict Content-Security-Policy can
+ * serve it itself.
+ *
+ * By default the hook loads this text from a `blob:` URL. A worklet module is
+ * loaded as a script, so it is `script-src` that must allow `blob:` —
+ * `worker-src` does not govern it. Where that is refused, write this string to
+ * a file your policy's `script-src` does allow, at build time and from the
+ * installed package so it moves with the version you run, and pass that file's
+ * URL as `workletUrl`:
+ *
+ * ```ts
+ * import { writeFileSync } from 'node:fs';
+ * import { CAPTURE_PROCESSOR_SOURCE } from '@intellectif/lk-react/hooks/useSpeechRecorder';
+ *
+ * writeFileSync('public/lk-speech-capture.js', CAPTURE_PROCESSOR_SOURCE);
+ * ```
+ *
+ * **The contract** a module at `workletUrl` must meet, which this source does:
+ * register an `AudioWorkletProcessor` under the name `lk-speech-capture`, and
+ * from its `process(inputs)` post the first input's channels to its `port` as
+ * an array with one `Float32Array` per channel, **copied** — the render
+ * quantum's buffers belong to the audio thread and are overwritten on the next
+ * quantum, so a block posted without copying arrives as whatever the
+ * microphone heard some milliseconds later. Return `true`, which keeps the
+ * processor alive while its source is silent. Anything else changes what is
+ * recorded, so serve this text unchanged rather than a copy of your own.
+ */
+declare const CAPTURE_PROCESSOR_SOURCE: string;
+
+interface SpeechRecorderOptions {
+    /** The longest a take may be. Reached, the recording stops itself. */
+    maxDurationMs: number;
+    /** Shorter than this and the take is refused as `too-short`. */
+    minDurationMs?: number;
+    /** How many takes the learner may make. Unbounded when absent. */
+    maxTakes?: number;
+    /**
+     * The URL of a self-hosted copy of {@link CAPTURE_PROCESSOR_SOURCE}, for an
+     * application whose Content-Security-Policy does not allow `blob:` in
+     * `script-src`. Serve that string unchanged; the contract a module here must
+     * meet is written on it.
+     *
+     * **A URL that does not work is not reported.** If the module fails to load,
+     * or loads without registering `lk-speech-capture`, the hook records through
+     * the deprecated `ScriptProcessorNode` on the main thread instead — the
+     * fallback it keeps for engines without audio worklets — and a recorder with
+     * a broken `workletUrl` looks like a working one. Only an engine with neither
+     * path reports `error: 'unsupported'`. Check that the module is actually
+     * fetched.
+     */
+    workletUrl?: string;
+}
+interface SpeechRecorder {
+    status: SpeechRecorderStatus;
+    error: SpeechRecorderError | null;
+    /** The loudest block since the last update, 0..1. */
+    level: number;
+    /** How much audio has been captured, from the sample count. */
+    elapsedMs: number;
+    take: RecordedTake | null;
+    takesUsed: number;
+    /** Whether a take remains. Not whether a `start()` would be accepted now. */
+    canRecord: boolean;
+    /** Opens the microphone and begins capturing. **Never rejects.** */
+    start(): Promise<void>;
+    /** Ends the capture and encodes the take. */
+    stop(): void;
+    /** Throws the take away and releases the microphone. */
+    discard(): void;
+    /**
+     * Starts over: releases the microphone, throws the take away **and gives the
+     * budget back**.
+     *
+     * That last part is the whole difference from {@link SpeechRecorder.discard},
+     * which deliberately refunds nothing — a budget a re-record gave back would
+     * bound nothing. A reset is for a recorder that has been handed a different
+     * reading while it stayed mounted: the takes belong to the activity, so the
+     * next activity's are its own. Calling it for the same reading hands a
+     * learner takes they have already spent.
+     */
+    reset(): void;
+}
+/**
+ * Records a take of speech as mono 16-bit PCM WAV at 16 kHz.
+ *
+ * That is the one format the SDK measures directly: `inspectWav` reads it
+ * without a decoding library, and it is what every mainstream pronunciation
+ * assessor accepts. A take is captured at whatever rate the device runs at,
+ * downmixed to mono, low-pass filtered and resampled, then encoded — so what a
+ * server measures is what this hook produced, not a claim about it.
+ *
+ * **Server rendering.** `status`, `error` and `canRecord` are derived from the
+ * take count alone and never from a browser global, so the markup a server
+ * produces is the markup the browser's first render produces. Support is
+ * discovered inside {@link SpeechRecorder.start} and reported as
+ * `error: 'unsupported'`; the obvious `!!navigator.mediaDevices` guard at
+ * render time would make a server render and its hydration disagree.
+ *
+ * **Identity.** `start`, `stop`, `discard` and `reset` keep one identity for the
+ * life of the hook, so they are safe in a dependency array. The returned object keeps
+ * one identity for as long as none of its values changes, so a render caused
+ * by something else does not invalidate an effect that depends on it.
+ *
+ * `start()` does nothing when no take remains, so `canRecord` is presentation:
+ * mark the control `aria-disabled` rather than `disabled`, which would take it
+ * out of the tab order and leave a learner nothing to read.
+ *
+ * ```tsx
+ * const recorder = useSpeechRecorder({ maxDurationMs: 20_000, maxTakes: 3 });
+ * <button
+ *   type="button"
+ *   aria-disabled={!recorder.canRecord}
+ *   onClick={() => {
+ *     void recorder.start();
+ *   }}
+ * >
+ *   Record
+ * </button>
+ * ```
+ */
+declare function useSpeechRecorder(options: SpeechRecorderOptions): SpeechRecorder;
+
+export { CAPTURE_PROCESSOR_SOURCE, RecordedTake, type SpeechRecorder, SpeechRecorderError, type SpeechRecorderOptions, SpeechRecorderStatus, useSpeechRecorder };

package/dist/hooks/useSpeechRecorder.js

@@ -0,0 +1,4 @@
+'use client';
+export { CAPTURE_PROCESSOR_SOURCE, useSpeechRecorder } from '../chunk-MCO52PV5.js';
+//# sourceMappingURL=useSpeechRecorder.js.map
+//# sourceMappingURL=useSpeechRecorder.js.map

package/dist/hooks/useSpeechRecorder.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"useSpeechRecorder.js"}