@hachej/boring-feedback 0.0.0-stage → 0.2.4

package/dist/ui/session.js

@@ -0,0 +1,762 @@
+// The feedback session (FEEDBACK.md, "UX"): one entry point, **Feedback**, in the chat composer. Pressing it enters feedback mode on the
+// application page. The person hovers (the picker's box and label), clicks to drop a numbered pin and types a note in a bubble beside
+// it (Enter saves, Esc discards the pin); the click never reaches the page (the picker's event blocking). Holding ⌥/Alt, or the "Use
+// app" toggle, suspends the picker so clicks and keys reach the app; those interactions are recorded as steps between the notes
+// (element labels through the privacy policy, route templates, named keys only). An optional voice recording is transcribed on Done
+// and aligned with the pointer trail and the pins (`alignSpeech`), on ONE clock (`performance.now()`). While recording, a click drops
+// a numbered pin WITHOUT the bubble: what the person says around that moment becomes its note (the pin wins in `alignSpeech`); a pin
+// nothing was said about stays as an empty note to type into in the review. Done closes feedback mode and
+// leaves one draft for the composer's chip: notes in order, editable and removable, each able to highlight its element; Send
+// attaches the `feedback@1` report (saved first when the host has a store).
+//
+// Headless and framework-light like the rest of `./ui`: `subscribe`/`getSnapshot`, no view-layer import. The bar, bubble, chip and
+// review are registry components over this state.
+import { FEEDBACK_LIMITS, draftReport, feedbackText, } from '../format/index.js';
+import { alignSpeech, anchorOf, createOverlay, createPicker, isExcluded, pickRefusal, pickerLabel, routeFor, serializePage, } from '../page/index.js';
+import { copyToClipboard } from '@hachej/boring-files/platform';
+import { draftId, observePage, operationId } from './annotate.js';
+import { createState } from './state.js';
+const finiteNumber = (value) => typeof value === 'number' && Number.isFinite(value);
+const timedText = (value) => {
+    const item = value;
+    if (!item || typeof item !== 'object' || !finiteNumber(item.start) || !finiteNumber(item.end) || typeof item.text !== 'string')
+        return null;
+    return { start: item.start, end: item.end, text: item.text };
+};
+/** The host's answer read leniently: usable timed segments, else plain text, else null (nothing usable came back). */
+function readTranscription(answer) {
+    if (!answer || typeof answer !== 'object')
+        return null;
+    const { segments, text } = answer;
+    const timed = (Array.isArray(segments) ? segments : []).flatMap(raw => {
+        const segment = timedText(raw);
+        if (!segment || !segment.text.trim())
+            return [];
+        const words = raw.words;
+        const kept = (Array.isArray(words) ? words : []).flatMap(word => { const read = timedText(word); return read ? [read] : []; });
+        return [kept.length ? { ...segment, words: kept } : segment];
+    });
+    if (timed.length)
+        return { segments: timed };
+    return typeof text === 'string' ? { text } : null;
+}
+const NAMED_KEYS = new Set(['Enter', 'Escape', 'Tab', 'ArrowUp', 'ArrowDown', 'ArrowLeft', 'ArrowRight', 'PageUp', 'PageDown', 'Home', 'End']);
+const MAX_ELEMENTS = 500;
+const MAX_TRAIL = 5000;
+/** Point mode is on (or finishing): the host hides its panel while this is true and shows it again when it turns false. */
+export function isPointing(state) {
+    return state.mode === 'point' && (state.phase === 'active' || state.phase === 'processing');
+}
+/** A pin number as drawn on the page: ①…⑳, then the plain number. */
+export function pinMark(number) {
+    return number >= 1 && number <= 20 ? String.fromCodePoint(0x245f + number) : String(number);
+}
+export function createFeedbackSession(options) {
+    const { root, policy } = options;
+    const now = options.now ?? (() => performance.now());
+    const document = root.ownerDocument;
+    const view = document.defaultView;
+    const voiceAvailable = options.voice !== undefined && options.transcribe !== undefined;
+    const routeNow = () => routeFor({ pathname: (options.location?.() ?? view?.location ?? { pathname: '/' }).pathname }, policy);
+    const state = createState({
+        phase: 'idle', mode: 'feedback', using: false, useToggle: false, notes: [], general: '', generalOpen: false, route: routeNow(), stepCount: 0,
+        voice: { kind: 'off' }, voiceAvailable, transcribing: false, send: { kind: 'idle' }, copy: { kind: 'idle' },
+    });
+    // --- session data (reset by start) ---------------------------------------------------------------------------------------------
+    let elements = [];
+    const anchors = new Map();
+    /** Each session element's label when it was last hovered or pinned, for notes about elements that later left the page. */
+    const labels = new Map();
+    let notes = [];
+    let timeline = [];
+    let pointer = [];
+    let pins = [];
+    let recordings = [];
+    let nextId = 1;
+    let bubble;
+    /** Text typed in a bubble whose selection was cancelled: offered to the general question, dropped by anything else. */
+    let stash = '';
+    let alt = false;
+    let lastRoute = '';
+    let lastHover;
+    let observed;
+    let problem;
+    let hoverLabel;
+    // Save: one operation id per draft; kept while it may have reached the store (as in createAnnotation).
+    let operation = operationId();
+    let mayHaveSent = false;
+    let saved;
+    let picker;
+    let pinsOverlay;
+    const removers = [];
+    const indexOf = (element) => {
+        const found = elements.indexOf(element);
+        if (found >= 0)
+            return found;
+        if (elements.length >= MAX_ELEMENTS)
+            return null;
+        elements.push(element);
+        return elements.length - 1;
+    };
+    /** The element's anchor against a fresh page snapshot, captured once per session element. */
+    const capture = (index) => {
+        const known = anchors.get(index);
+        if (known)
+            return { anchor: known };
+        const element = elements[index];
+        if (!element)
+            return { reason: 'the element is gone' };
+        const captured = anchorOf(element, policy, { root, page: serializePage(root, policy) });
+        if (captured.kind !== 'captured')
+            return { reason: captured.reason };
+        const anchor = captured.anchor;
+        anchors.set(index, anchor);
+        return { anchor };
+    };
+    const ordered = () => [...notes].sort((a, b) => a.t - b.t || a.id - b.id);
+    const labelOf = (note) => note.label ?? (note.element ? pickerLabel(note.element, policy) : note.target !== undefined && anchors.get(note.target) ? String(anchors.get(note.target)['fallback']) : 'the page');
+    const publish = (change = {}) => {
+        const list = ordered();
+        const views = list.map((note, index) => {
+            const anchor = note.target !== undefined ? anchors.get(note.target) : undefined;
+            const signals = anchor?.['signals'];
+            const found = signals !== null && typeof signals === 'object' && !Array.isArray(signals) ? signals.source : undefined;
+            const source = typeof found === 'string' ? found : undefined;
+            return Object.freeze({ id: note.id, number: index + 1, text: note.text, label: labelOf(note), ...(anchor ? { fallback: String(anchor['fallback']) } : {}),
+                ...(source !== undefined ? { source } : {}), ...(note.from ? { from: note.from } : {}), ...(note.recorded ? { recorded: true } : {}) });
+        });
+        const open = bubble ? list.find(note => note.id === bubble.noteId) : undefined;
+        const { bubble: _bubble, problem: _problem, hover: _hover, ...base } = { ...state.getSnapshot(), ...change };
+        const showHover = hoverLabel !== undefined && base.phase === 'active' && !base.using;
+        state.replace({
+            ...base,
+            notes: Object.freeze(views),
+            stepCount: timeline.filter(entry => 'step' in entry).length,
+            ...(open && bubble && open.element ? { bubble: Object.freeze({ noteId: open.id, number: list.indexOf(open) + 1, element: open.element, label: labelOf(open), text: bubble.text, fresh: bubble.fresh }) } : {}),
+            ...(problem !== undefined ? { problem } : {}),
+            ...(showHover ? { hover: hoverLabel } : {}),
+        });
+        drawPins();
+    };
+    const drawPins = () => {
+        if (!pinsOverlay)
+            return;
+        if (state.getSnapshot().phase !== 'active') {
+            pinsOverlay.clear();
+            return;
+        }
+        pinsOverlay.draw(ordered().flatMap((note, index) => note.element ? [{ element: note.element, label: pinMark(index + 1), tone: 'pinned' }] : []));
+    };
+    const clip = (text) => [...text].slice(0, FEEDBACK_LIMITS.stepCharacters).join('');
+    const record = (step) => {
+        if (timeline.length >= FEEDBACK_LIMITS.steps * 2)
+            return;
+        const clipped = step.kind === 'route' ? { kind: 'route', route: clip(step.route) }
+            : step.kind === 'click' ? { kind: 'click', target: clip(step.target) }
+                : step.kind === 'key' && step.target !== undefined ? { kind: 'key', key: step.key, target: clip(step.target) } : step;
+        timeline.push({ t: now(), step: clipped });
+    };
+    const checkRoute = () => {
+        const route = routeNow();
+        if (route === lastRoute)
+            return;
+        lastRoute = route;
+        record({ kind: 'route', route });
+        publish({ route });
+    };
+    // --- the bubble ---------------------------------------------------------------------------------------------------------------
+    /** An empty note (or a new pin dismissed) is no note: remove it, its pin mark and its place on the timeline. */
+    const removeRecord = (note) => {
+        notes = notes.filter(item => item !== note);
+        timeline = timeline.filter(entry => !('noteId' in entry) || entry.noteId !== note.id);
+        pins = pins.filter(mark => !(mark.target === note.target && Math.abs(mark.t - note.t) < 1));
+    };
+    const closeBubble = (keep) => {
+        if (!bubble)
+            return;
+        const open = bubble;
+        bubble = undefined;
+        const note = notes.find(item => item.id === open.noteId);
+        if (!note)
+            return;
+        const text = keep ? open.text : open.before;
+        // A pin dropped while recording stays even when empty: its note is what was said there, or what the person types in the review.
+        if (!text.trim() && !(note.recorded && !open.fresh)) {
+            // A new pin dismissed keeps what was typed for a general question instead of losing it.
+            if (!keep && open.fresh && open.text.trim())
+                stash = open.text;
+            removeRecord(note);
+        }
+        else {
+            note.text = text;
+            if (open.fresh && !timeline.some(entry => 'noteId' in entry && entry.noteId === note.id))
+                timeline.push({ t: note.t, noteId: note.id });
+        }
+    };
+    const cancelSelection = () => {
+        if (!bubble)
+            return;
+        const open = bubble;
+        const note = notes.find(item => item.id === open.noteId);
+        bubble = undefined;
+        if (!note)
+            return;
+        if (open.text.trim())
+            stash = open.text;
+        removeRecord(note);
+    };
+    const withStash = (general) => {
+        const carried = stash.trim();
+        stash = '';
+        return carried && !general.includes(carried) ? [general.trim(), carried].filter(Boolean).join('\n') : general;
+    };
+    const onPick = (element) => {
+        if (state.getSnapshot().phase !== 'active')
+            return;
+        problem = undefined;
+        // Clicking the selected zone again cancels the selection (its bubble is open); a pinned zone whose bubble is closed reopens it.
+        const toggled = bubble ? notes.find(note => note.id === bubble.noteId && note.element === element) : undefined;
+        if (toggled) {
+            cancelSelection();
+            publish();
+            return;
+        }
+        stash = '';
+        if (state.getSnapshot().generalOpen)
+            state.set({ generalOpen: false });
+        closeBubble(true);
+        const recording = state.getSnapshot().voice.kind === 'recording';
+        const existing = notes.find(note => note.element === element);
+        // While recording an existing pin is already numbered; speech near it lands on it. No bubble interrupts the person talking.
+        if (existing && recording) {
+            publish();
+            return;
+        }
+        if (existing) {
+            bubble = { noteId: existing.id, text: existing.text, fresh: false, before: existing.text };
+            publish();
+            return;
+        }
+        const refused = pickRefusal(element, root);
+        const target = refused === undefined ? indexOf(element) : null;
+        if (target === null) {
+            problem = `This element cannot be pointed at: ${refused ?? 'too many elements in one session'}.`;
+            publish();
+            return;
+        }
+        if (new Set(notes.flatMap(note => note.target !== undefined ? [note.target] : [])).size >= FEEDBACK_LIMITS.anchors) {
+            problem = `At most ${FEEDBACK_LIMITS.anchors} pinned elements per feedback.`;
+            publish();
+            return;
+        }
+        const captured = capture(target);
+        if (!captured.anchor) {
+            problem = `This element cannot be pointed at: ${captured.reason ?? 'unknown reason'}.`;
+            publish();
+            return;
+        }
+        const t = now();
+        pins.push({ t, target });
+        const note = { id: nextId++, element, target, label: pickerLabel(element, policy), text: '', t, ...(recording ? { recorded: true } : {}) };
+        notes.push(note);
+        if (recording)
+            timeline.push({ t, noteId: note.id });
+        else
+            bubble = { noteId: note.id, text: '', fresh: true, before: '' };
+        checkRoute();
+        publish();
+    };
+    const onHover = (element) => {
+        const target = element ? indexOf(element) : null;
+        if (target === lastHover)
+            return;
+        lastHover = target;
+        if (pointer.length < MAX_TRAIL)
+            pointer.push({ t: now(), target });
+        // Hovered elements get anchors too while recording, so speech that lands on them can become a pinned note.
+        if (target !== null && state.getSnapshot().voice.kind === 'recording')
+            capture(target);
+        hoverLabel = element ? pickerLabel(element, policy) : undefined;
+        if (target !== null && hoverLabel !== undefined)
+            labels.set(target, hoverLabel);
+        publish();
+    };
+    // --- using the app (⌥ / the toggle) -------------------------------------------------------------------------------------------
+    const applyUsing = () => {
+        const current = state.getSnapshot();
+        const using = current.phase === 'active' && (alt || current.useToggle);
+        if (using === current.using)
+            return;
+        if (using) {
+            closeBubble(true);
+            lastHover = undefined;
+            hoverLabel = undefined;
+        }
+        picker?.suspend(using);
+        publish({ using });
+    };
+    const inApp = (target) => {
+        const element = target && target.nodeType === 1 ? target : target?.parentElement ?? undefined;
+        if (!element || isExcluded(element) || pickRefusal(element, root) !== undefined)
+            return undefined;
+        return element;
+    };
+    const later = (run) => { if (view)
+        view.setTimeout(run, 0);
+    else
+        run(); };
+    const onKeyDown = (event) => {
+        const key = event;
+        if (key.key === 'Alt') {
+            if (!alt) {
+                alt = true;
+                applyUsing();
+            }
+            return;
+        }
+        const current = state.getSnapshot();
+        if (current.using) {
+            if (NAMED_KEYS.has(key.key)) {
+                const element = inApp(event.target);
+                record({ kind: 'key', key: key.key, ...(element ? { target: pickerLabel(element, policy) } : {}) });
+                later(checkRoute);
+                publish();
+            }
+            return;
+        }
+        // Esc on the page closes the bubble and never ends feedback mode by accident; in the bubble, the bubble handles it.
+        if (key.key === 'Escape' && !event.composedPath().some(item => item.hasAttribute?.('data-feedback-ignore'))) {
+            event.preventDefault();
+            event.stopImmediatePropagation();
+            if (bubble) {
+                closeBubble(false);
+                publish();
+            }
+            else if (current.generalOpen) {
+                state.set({ generalOpen: false });
+                publish();
+            }
+        }
+    };
+    const onKeyUp = (event) => { if (event.key === 'Alt' && alt) {
+        alt = false;
+        applyUsing();
+    } };
+    const onBlur = () => { if (alt) {
+        alt = false;
+        applyUsing();
+    } };
+    const onClick = (event) => {
+        if (!state.getSnapshot().using)
+            return;
+        const element = inApp(event.target);
+        if (!element)
+            return;
+        record({ kind: 'click', target: pickerLabel(element, policy) });
+        later(checkRoute);
+        publish();
+    };
+    const onRoute = () => { checkRoute(); };
+    const listen = (type, handler) => {
+        if (!view)
+            return;
+        view.addEventListener(type, handler, { capture: true });
+        removers.push(() => view.removeEventListener(type, handler, { capture: true }));
+    };
+    const stopPicking = () => {
+        for (const remove of removers.splice(0))
+            remove();
+        picker?.dispose();
+        picker = undefined;
+        pinsOverlay?.dispose();
+        pinsOverlay = undefined;
+        alt = false;
+    };
+    let sessionGeneration = 0;
+    const reset = () => {
+        sessionGeneration++;
+        elements = [];
+        anchors.clear();
+        labels.clear();
+        notes = [];
+        timeline = [];
+        pointer = [];
+        pins = [];
+        recordings = [];
+        bubble = undefined;
+        stash = '';
+        lastHover = undefined;
+        hoverLabel = undefined;
+        observed = undefined;
+        problem = undefined;
+        saved = undefined;
+        operation = operationId();
+        mayHaveSent = false;
+    };
+    const start = (startOptions = {}) => {
+        const current = state.getSnapshot();
+        const mode = startOptions.mode === 'point' ? 'point' : 'feedback';
+        if (current.phase === 'active' || current.phase === 'processing')
+            return;
+        stopPicking();
+        reset();
+        lastRoute = routeNow();
+        record({ kind: 'route', route: lastRoute });
+        // Keys belong to feedback mode from now on: focus left on the Feedback button (an ignored subtree) would keep them from it.
+        const focused = document.activeElement;
+        if (focused && focused !== document.body && isExcluded(focused) && typeof focused.blur === 'function')
+            focused.blur();
+        // Listeners first, so they see Alt and Esc before the picker takes them.
+        for (const [type, handler] of [['keydown', onKeyDown], ['keyup', onKeyUp], ['click', onClick], ['popstate', onRoute], ['hashchange', onRoute]])
+            listen(type, handler);
+        if (view) {
+            view.addEventListener('blur', onBlur);
+            removers.push(() => view.removeEventListener('blur', onBlur));
+        }
+        pinsOverlay = createOverlay({ document, ...(options.styles !== undefined ? { styles: options.styles } : {}) });
+        picker = createPicker({
+            root, policy, onPick, wheel: false, keys: 'outside-ignored', ...(mode === 'point' ? { tap: 'pick' } : {}),
+            ...(options.styles !== undefined ? { styles: options.styles } : {}),
+            ...(options.hitTest ? { hitTest: options.hitTest } : {}),
+            onChange: next => { if (next.mode === 'picking' && !next.suspended)
+                onHover(next.current); },
+        });
+        void picker.start();
+        state.set({ phase: 'active', mode, using: false, useToggle: false, general: '', generalOpen: false, voice: { kind: 'off' }, transcribing: false, send: { kind: 'idle' }, copy: { kind: 'idle' }, route: lastRoute });
+        publish();
+    };
+    // --- voice --------------------------------------------------------------------------------------------------------------------
+    // Stop shows "stopping" at once, but the capture hands the audio over later (the recorder's last chunk, decoding its duration): Done
+    // pressed meanwhile must wait for it, or the recording would be silently lost. One stop at a time; a discard in between drops it.
+    let stopping;
+    const stopRecording = () => {
+        if (stopping)
+            return stopping;
+        if (!options.voice || state.getSnapshot().voice.kind !== 'recording')
+            return Promise.resolve();
+        const voice = options.voice;
+        const generation = sessionGeneration;
+        state.set({ voice: { kind: 'stopping' } });
+        stopping = (async () => {
+            let recording = null, failed = false;
+            try {
+                recording = await voice.stop();
+            }
+            catch {
+                failed = true;
+            }
+            if (generation !== sessionGeneration)
+                return;
+            if (recording)
+                recordings.push(recording);
+            else
+                problem = failed ? 'The recording could not be finished. Your pins are kept.' : 'Nothing was recorded: the microphone gave no sound. Your pins are kept.';
+            if (state.getSnapshot().voice.kind === 'stopping')
+                state.set({ voice: { kind: 'off' } });
+            publish();
+        })().finally(() => { stopping = undefined; });
+        return stopping;
+    };
+    const toggleVoice = async () => {
+        const current = state.getSnapshot();
+        if (!options.voice || !voiceAvailable || current.phase !== 'active')
+            return;
+        if (current.voice.kind === 'recording') {
+            await stopRecording();
+            publish();
+            return;
+        }
+        if (current.voice.kind === 'starting' || current.voice.kind === 'stopping')
+            return;
+        // Called straight from the click: nothing is awaited before the capture asks for the microphone, so the permission prompt keeps
+        // the person's gesture. The bubble closes (its text kept): while recording, pins take no bubble.
+        let starting;
+        try {
+            starting = options.voice.start();
+        }
+        catch (error) {
+            starting = Promise.reject(error);
+        }
+        closeBubble(true);
+        problem = undefined;
+        state.set({ voice: { kind: 'starting' } });
+        publish();
+        let started;
+        try {
+            started = await starting;
+        }
+        catch {
+            started = { kind: 'refused', code: 'failed', reason: 'The microphone could not be started.' };
+        }
+        if (state.getSnapshot().phase !== 'active') {
+            if (started.kind === 'recording')
+                options.voice.cancel();
+            return;
+        }
+        state.set({ voice: started.kind === 'recording' ? { kind: 'recording' } : { kind: 'refused', reason: started.reason, ...(started.code ? { code: started.code } : {}) } });
+        // The element under the pointer when recording starts is the first sample of the trail.
+        if (started.kind === 'recording' && lastHover !== undefined && lastHover !== null) {
+            pointer.push({ t: now(), target: lastHover });
+            capture(lastHover);
+        }
+        publish();
+    };
+    /** Speech merged into the notes: on a pinned element it extends that note; on a hovered element it becomes a pin note marked voice;
+     * anywhere else it becomes part of the general note. A transcription with text but no timed segments cannot be placed in time,
+     * so all of it goes to the general note (pins made while recording stay as empty notes to type into). Throws when nothing usable
+     * came back. */
+    const merge = async (recording) => {
+        const answer = readTranscription(await options.transcribe(recording.audio, recording.mimeType));
+        if (!answer)
+            throw new TypeError(''); // nothing usable: the plain "could not be transcribed" message
+        const general = [];
+        const aligned = 'segments' in answer ? alignSpeech({ segments: answer.segments, audioStartedAt: recording.startedAt, pointer, pins }) : [];
+        if ('text' in answer && answer.text.trim())
+            general.push(answer.text.trim());
+        for (const piece of aligned) {
+            const text = piece.text.trim();
+            if (!text)
+                continue;
+            const pinned = piece.target === null ? undefined : notes.find(note => note.target === piece.target && note.element !== undefined && note.from === undefined);
+            if (pinned) {
+                // A pin dropped while recording with nothing typed: its note is what was said, so it is a voice note.
+                if (pinned.recorded && !pinned.text.trim())
+                    pinned.from = 'voice';
+                pinned.text = pinned.text.trim() ? `${pinned.text}\n${text}` : text;
+                continue;
+            }
+            const anchor = piece.target === null ? undefined : anchors.get(piece.target) ?? capture(piece.target).anchor;
+            const pinnedCount = new Set(notes.flatMap(note => note.target !== undefined ? [note.target] : [])).size;
+            if (piece.target !== null && anchor && (notes.some(note => note.target === piece.target) || pinnedCount < FEEDBACK_LIMITS.anchors)) {
+                const voiced = notes.find(note => note.target === piece.target && note.from === 'voice');
+                if (voiced) {
+                    voiced.text = `${voiced.text}\n${text}`;
+                    continue;
+                }
+                const element = elements[piece.target];
+                const note = { id: nextId++, target: piece.target, text, t: piece.at, from: 'voice', ...(element ? { element, label: labels.get(piece.target) ?? pickerLabel(element, policy) } : {}) };
+                notes.push(note);
+                timeline.push({ t: piece.at, noteId: note.id });
+                continue;
+            }
+            general.push(text);
+        }
+        if (general.length) {
+            const current = state.getSnapshot().general;
+            state.set({ general: [current.trim(), general.join(' ')].filter(Boolean).join('\n') });
+        }
+    };
+    const done = async () => {
+        if (state.getSnapshot().phase !== 'active')
+            return;
+        closeBubble(true);
+        checkRoute();
+        await stopRecording();
+        stopPicking();
+        const transcribing = recordings.length > 0 && options.transcribe !== undefined;
+        state.set({ phase: 'processing', using: false, useToggle: false, generalOpen: false, transcribing });
+        publish();
+        if (transcribing) {
+            for (const recording of recordings) {
+                try {
+                    await merge(recording);
+                }
+                catch (error) {
+                    const pinned = notes.some(note => note.recorded);
+                    problem = `Voice could not be transcribed${error instanceof Error && error.message ? ` (${error.message})` : ''}. ${pinned ? 'Your pins are kept: type a note for each in the review.' : 'Your typed notes are kept.'}`;
+                }
+            }
+        }
+        recordings = [];
+        state.set({ transcribing: false });
+        try {
+            observed = (await observePage(options)).observed;
+        }
+        catch {
+            problem = 'The page could not be observed.';
+        }
+        state.set({ phase: notes.length || state.getSnapshot().general.trim() ? 'review' : 'idle', route: observed?.subject.route ?? routeNow() });
+        publish();
+    };
+    const discard = () => {
+        if (options.voice && state.getSnapshot().voice.kind === 'recording')
+            options.voice.cancel();
+        stopPicking();
+        reset();
+        state.set({ phase: 'idle', using: false, useToggle: false, general: '', generalOpen: false, voice: { kind: 'off' }, transcribing: false, send: { kind: 'idle' }, copy: { kind: 'idle' } });
+        publish();
+    };
+    // --- the draft ----------------------------------------------------------------------------------------------------------------
+    const edited = () => {
+        // A changed draft may take a fresh operation id unless the current one may already have reached the store.
+        if (!mayHaveSent && state.getSnapshot().send.kind !== 'saved')
+            operation = operationId();
+        state.set({ copy: { kind: 'idle' }, ...(state.getSnapshot().send.kind !== 'saved' ? { send: { kind: 'idle' } } : {}) });
+    };
+    const draft = () => {
+        if (!observed)
+            throw new TypeError('Press Done first: there is no feedback draft yet.');
+        const list = ordered().filter(note => note.text.trim());
+        const targets = [];
+        const draftNotes = list.map(note => {
+            const anchored = note.target !== undefined && anchors.has(note.target);
+            if (anchored && !targets.includes(note.target))
+                targets.push(note.target);
+            return { text: note.text, ...(anchored ? { anchor: targets.indexOf(note.target) } : {}), ...(note.from ? { from: note.from } : {}) };
+        });
+        const noteIndex = new Map(list.map((note, index) => [note.id, index]));
+        const steps = [...timeline].sort((a, b) => a.t - b.t).flatMap((entry) => {
+            if ('step' in entry)
+                return [entry.step];
+            const index = noteIndex.get(entry.noteId);
+            return index === undefined ? [] : [{ kind: 'note', note: index }];
+        }).slice(0, FEEDBACK_LIMITS.steps);
+        const general = state.getSnapshot().general;
+        if (!draftNotes.length && !general.trim())
+            throw new TypeError('There is nothing to send: every note is empty.');
+        return {
+            observed, anchors: targets.map(target => anchors.get(target)), said: general,
+            ...(draftNotes.length ? { notes: draftNotes } : {}),
+            ...(steps.some(step => step.kind !== 'route') || steps.length > 1 ? { steps } : {}),
+        };
+    };
+    const reportText = () => feedbackText(draftReport(draft(), { id: draftId(), created: new Date().toISOString() }));
+    const copy = async () => {
+        let text;
+        try {
+            text = reportText();
+        }
+        catch (error) {
+            state.set({ copy: { kind: 'refused', reason: error instanceof Error ? error.message : 'The report could not be rendered.' } });
+            publish();
+            return state.getSnapshot().copy;
+        }
+        let copied = false;
+        try {
+            copied = await (options.copyText ?? copyToClipboard)(text);
+        }
+        catch {
+            copied = false;
+        }
+        state.set({ copy: copied ? { kind: 'copied', text } : { kind: 'manual', text } });
+        publish();
+        return state.getSnapshot().copy;
+    };
+    const attach = async () => {
+        if (state.getSnapshot().phase !== 'review')
+            return { kind: 'refused', reason: 'There is no feedback to send.' };
+        let current;
+        try {
+            current = draft();
+        }
+        catch (error) {
+            return { kind: 'refused', reason: error instanceof Error ? error.message : 'There is nothing to send.' };
+        }
+        if (!options.save) {
+            try {
+                return { kind: 'inline', text: reportText() };
+            }
+            catch (error) {
+                return { kind: 'refused', reason: error instanceof Error ? error.message : 'The report could not be rendered.' };
+            }
+        }
+        if (saved)
+            return options.mention ? { kind: 'mention', id: saved.id, path: options.mention(saved.id) } : { kind: 'inline', text: reportText() };
+        if (state.getSnapshot().send.kind === 'sending')
+            return { kind: 'refused', reason: 'Already sending.' };
+        state.set({ send: { kind: 'sending' } });
+        mayHaveSent = true;
+        let result;
+        try {
+            result = await options.save({ operationId: operation, draft: current });
+        }
+        catch {
+            result = { kind: 'unknown', reason: 'The save did not answer; Send again to reconcile it.' };
+        }
+        if (result.kind === 'denied' || result.kind === 'unavailable' || result.kind === 'invalid')
+            mayHaveSent = false;
+        state.set({ send: result });
+        if (result.kind !== 'saved')
+            return { kind: 'refused', reason: result.kind === 'unknown' ? `${result.reason} Nothing is lost: Send again uses the same operation, so it cannot be stored twice.` : `Not saved: ${result.reason}` };
+        saved = { id: result.id };
+        return options.mention ? { kind: 'mention', id: result.id, path: options.mention(result.id) } : { kind: 'inline', text: reportText() };
+    };
+    const highlight = (id) => {
+        pinsOverlay ??= createOverlay({ document, ...(options.styles !== undefined ? { styles: options.styles } : {}) });
+        if (id === undefined) {
+            pinsOverlay.clear();
+            return 'none';
+        }
+        const list = ordered();
+        const note = list.find(item => item.id === id);
+        if (!note || !note.element) {
+            pinsOverlay.clear();
+            return note ? 'not-on-page' : 'none';
+        }
+        if (!note.element.isConnected || !root.contains(note.element)) {
+            pinsOverlay.clear();
+            return 'not-on-page';
+        }
+        pinsOverlay.highlight(note.element, `${pinMark(list.indexOf(note) + 1)} ${note.text.split('\n')[0] ?? ''}`.trim());
+        return 'shown';
+    };
+    return {
+        getSnapshot: state.getSnapshot,
+        subscribe: state.subscribe,
+        start,
+        done,
+        discard,
+        setBubbleText: text => { if (bubble) {
+            bubble.text = text;
+            publish();
+        } },
+        saveBubble: () => { closeBubble(true); publish(); },
+        cancelBubble: () => { closeBubble(false); publish(); },
+        cancelSelection: () => { cancelSelection(); publish(); },
+        askGeneral: () => {
+            if (state.getSnapshot().phase !== 'active')
+                return;
+            problem = undefined;
+            if (bubble?.fresh)
+                closeBubble(false);
+            else
+                closeBubble(true);
+            state.set({ general: withStash(state.getSnapshot().general), generalOpen: true });
+            publish();
+        },
+        closeGeneral: () => { if (state.getSnapshot().generalOpen) {
+            state.set({ generalOpen: false });
+            publish();
+        } },
+        setUseToggle: on => { state.set({ useToggle: on }); applyUsing(); publish(); },
+        toggleVoice,
+        setNoteText: (id, text) => { const note = notes.find(item => item.id === id); if (note && note.text !== text) {
+            note.text = text;
+            edited();
+            publish();
+        } },
+        removeNote: id => {
+            notes = notes.filter(item => item.id !== id);
+            timeline = timeline.filter(entry => !('noteId' in entry) || entry.noteId !== id);
+            edited();
+            if (state.getSnapshot().phase === 'review' && !notes.length && !state.getSnapshot().general.trim()) {
+                discard();
+                return;
+            }
+            publish();
+        },
+        setGeneral: text => { if (text !== state.getSnapshot().general) {
+            state.set({ general: text });
+            edited();
+            publish();
+        } },
+        highlight,
+        draft,
+        reportText,
+        copy,
+        attach,
+        sent: () => { pinsOverlay?.clear(); discard(); },
+        trail: () => ({ pointer: Object.freeze([...pointer]), pins: Object.freeze([...pins]) }),
+        dispose: () => { discard(); pinsOverlay?.dispose(); pinsOverlay = undefined; },
+    };
+}