@hachej/boring-feedback 0.0.0-stage → 0.2.4

package/dist/ui/save.d.ts

@@ -0,0 +1,45 @@
+import { type FeedbackDraft, type FeedbackReport } from '../format/index.js';
+/** What the browser sends. */
+export interface SaveRequest {
+    /** Stable across retries of one draft. */
+    readonly operationId: string;
+    readonly draft: FeedbackDraft;
+}
+/** What the host answers. `unknown` means the outcome is not known: retry later with the same operation id to reconcile. */
+export type SaveResult = {
+    readonly kind: 'saved';
+    readonly id: string;
+    readonly revision: string;
+} | {
+    readonly kind: 'denied' | 'unavailable' | 'conflict' | 'unknown' | 'invalid';
+    readonly reason: string;
+};
+/** The host's save endpoint, as the annotate state calls it. A throw counts as `unknown`. */
+export type SaveEndpoint = (request: SaveRequest) => Promise<SaveResult>;
+/** A save endpoint over Fetch: POSTs the request as JSON to `url` and reads a `SaveResult` back. Transport failures are `unknown`. */
+export declare function fetchSaveEndpoint(url: string | URL, fetcher?: (request: Request) => Promise<Response>): SaveEndpoint;
+/** A well-formed `SaveResult`, or undefined. */
+export declare function saveResultOf(value: unknown): SaveResult | undefined;
+/** For the host route: the request body as a `SaveRequest`, or the reason it is refused. The draft is fully checked by `store.create`. */
+export declare function parseSaveRequest(value: unknown): {
+    readonly ok: true;
+    readonly request: SaveRequest;
+} | {
+    readonly ok: false;
+    readonly reason: string;
+};
+/** The store's create result (`@hachej/boring-feedback/store`), structurally, so this browser module needs no store import. */
+export type StoreCreateResult = {
+    readonly kind: 'applied';
+    readonly report: FeedbackReport;
+    readonly revision: string;
+} | {
+    readonly kind: 'denied' | 'unavailable' | 'conflict' | 'unknown';
+    readonly reason: string;
+};
+/** For the host route: the store's create result as the `SaveResult` the browser reads, with an HTTP status. */
+export declare function saveResponseOf(result: StoreCreateResult): {
+    readonly status: number;
+    readonly body: SaveResult;
+};
+//# sourceMappingURL=save.d.ts.map

package/dist/ui/save.js

@@ -0,0 +1,65 @@
+// The human Save path (FEEDBACK.md, "Storage": operations and replay). The browser keeps one operation id per draft across retries and
+// sends it with the draft; the host route admits it with the request's access (`store.operationKey('create', draft, access)`) and calls
+// `store.create`. This module holds the wire shapes on both sides and imports no store code: the route maps the store's result itself.
+import { draftProblems } from '../format/index.js';
+const OPERATION_ID = /^[A-Za-z0-9_.:-]{8,128}$/;
+const REFUSALS = new Set(['denied', 'unavailable', 'conflict', 'unknown', 'invalid']);
+/** A save endpoint over Fetch: POSTs the request as JSON to `url` and reads a `SaveResult` back. Transport failures are `unknown`. */
+export function fetchSaveEndpoint(url, fetcher = request => fetch(request)) {
+    return async (request) => {
+        let response;
+        try {
+            response = await fetcher(new Request(url, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(request) }));
+        }
+        catch {
+            return { kind: 'unknown', reason: 'The save request did not complete; retrying reconciles it.' };
+        }
+        let body;
+        try {
+            body = await response.json();
+        }
+        catch {
+            body = undefined;
+        }
+        return saveResultOf(body) ?? (response.status === 401 || response.status === 403
+            ? { kind: 'denied', reason: 'You are not signed in or may not leave feedback here.' }
+            : { kind: 'unknown', reason: `The save answered ${response.status}; retrying reconciles it.` });
+    };
+}
+/** A well-formed `SaveResult`, or undefined. */
+export function saveResultOf(value) {
+    if (typeof value !== 'object' || value === null)
+        return undefined;
+    const record = value;
+    if (record['kind'] === 'saved' && typeof record['id'] === 'string' && typeof record['revision'] === 'string')
+        return { kind: 'saved', id: record['id'], revision: record['revision'] };
+    if (typeof record['kind'] === 'string' && REFUSALS.has(record['kind']) && typeof record['reason'] === 'string')
+        return { kind: record['kind'], reason: record['reason'] };
+    return undefined;
+}
+/** For the host route: the request body as a `SaveRequest`, or the reason it is refused. The draft is fully checked by `store.create`. */
+export function parseSaveRequest(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return { ok: false, reason: 'The request must be a JSON object' };
+    const record = value;
+    const extra = Object.keys(record).filter(key => key !== 'operationId' && key !== 'draft');
+    if (extra.length)
+        return { ok: false, reason: `Unexpected fields: ${extra.join(', ')}` };
+    const operationId = record['operationId'];
+    if (typeof operationId !== 'string' || !OPERATION_ID.test(operationId))
+        return { ok: false, reason: 'operationId must be 8 to 128 letters, digits or _.:-' };
+    const problems = draftProblems(record['draft']);
+    if (problems.length)
+        return { ok: false, reason: problems.map(problem => `${problem.at}: ${problem.message}`).join('; ') };
+    return { ok: true, request: { operationId, draft: record['draft'] } };
+}
+/** For the host route: the store's create result as the `SaveResult` the browser reads, with an HTTP status. */
+export function saveResponseOf(result) {
+    switch (result.kind) {
+        case 'applied': return { status: 200, body: { kind: 'saved', id: result.report.id, revision: result.revision } };
+        case 'denied': return { status: 403, body: { kind: 'denied', reason: result.reason } };
+        case 'conflict': return { status: 409, body: { kind: 'conflict', reason: result.reason } };
+        case 'unavailable': return { status: 503, body: { kind: 'unavailable', reason: result.reason } };
+        default: return { status: 202, body: { kind: 'unknown', reason: result.reason } };
+    }
+}

package/dist/ui/session.d.ts

@@ -0,0 +1,186 @@
+import { type FeedbackDraft } from '../format/index.js';
+import { type PinMark, type PointerSample, type SpeechSegment, type VoiceCapture, type VoiceRefusal } from '../page/index.js';
+import { type AnnotateHost, type CopyState } from './annotate.js';
+import type { SaveEndpoint, SaveResult } from './save.js';
+import { type ExternalState } from './state.js';
+/**
+ * What the host's transcription answers. `segments` (times in seconds from the start of the audio, optionally with word timings)
+ * let speech be aligned with the pointer and the pins; without them `text` becomes the general note.
+ */
+export interface TranscribeResult {
+    readonly text: string;
+    readonly segments?: readonly SpeechSegment[];
+}
+/**
+ * Transcription is a host capability, not part of this library: the host passes any function from the recorded audio to text
+ * (its own server route, a shared service, a provider SDK). The session never checks a provider's schema beyond reading these
+ * fields: extra fields are ignored, missing or malformed ones are tolerated, and an answer with neither usable segments nor text
+ * is reported as "could not be transcribed" with the pins kept.
+ */
+export type Transcribe = (audio: Blob, mimeType: string) => Promise<TranscribeResult>;
+export interface FeedbackSessionOptions extends AnnotateHost {
+    /** Optional voice: both a capture (`createVoiceCapture()`) and the host's `transcribe` are needed for the 🎙 toggle; without
+     * `transcribe` the Record button is simply not offered. */
+    readonly voice?: VoiceCapture;
+    readonly transcribe?: Transcribe;
+    /** Optional storage: Send saves the report first (one operation id per draft across retries). */
+    readonly save?: SaveEndpoint;
+    /** With `save`: the `@` mention of a saved report (`id => 'feedback/<id>.md'`), so the host's mention resolver inlines it. */
+    readonly mention?: (id: string) => string;
+    /** Extra CSS for the overlays' shadow roots (the registry's `pickerOverlayStyles`). */
+    readonly styles?: string;
+    /** The one clock of pins, pointer samples and recordings. Defaults to `performance.now()`. */
+    readonly now?: () => number;
+    /** Elements at a viewport point (tests); defaults to `document.elementsFromPoint`. */
+    readonly hitTest?: (x: number, y: number) => readonly Element[];
+    /** Defaults to `copyToClipboard` from `@hachej/boring-files/platform`. */
+    readonly copyText?: (text: string) => Promise<boolean>;
+}
+export type SessionPhase = 'idle' | 'active' | 'processing' | 'review';
+/**
+ * `feedback`: the desktop feedback mode, its bar docked in the composer. `point` (phones): the host's panel gets out of the way while the
+ * person taps elements in the app (`isPointing`), one tap per pick; the same notes, draft and attachment.
+ */
+export type SessionMode = 'feedback' | 'point';
+export interface SessionStartOptions {
+    readonly mode?: SessionMode;
+}
+export interface SessionNote {
+    /** Stable for the session; never reused. */
+    readonly id: number;
+    /** Its number on the page and in the review (1-based, in order). */
+    readonly number: number;
+    readonly text: string;
+    /** The privacy-policy label of its element ("SettingsPage · button «Save profile»"), or "the page" for a general note. */
+    readonly label: string;
+    /** The anchor's fallback, when it has an anchor. */
+    readonly fallback?: string;
+    /** The anchor's development source location (`src/settings/SaveBar.tsx:42`), when it has one. */
+    readonly source?: string;
+    readonly from?: 'voice';
+    /** Pinned while recording: its note is what was said there (empty until transcribed, or when nothing was). */
+    readonly recorded?: true;
+}
+export type VoiceState = {
+    readonly kind: 'off';
+} | {
+    readonly kind: 'starting';
+} | {
+    readonly kind: 'recording';
+}
+/** Stop was pressed; the audio is being handed over. */
+ | {
+    readonly kind: 'stopping';
+} | {
+    readonly kind: 'refused';
+    readonly reason: string;
+    readonly code?: VoiceRefusal;
+};
+/** The note being typed in the bubble. */
+export interface SessionBubble {
+    readonly noteId: number;
+    readonly number: number;
+    readonly element: Element;
+    readonly label: string;
+    readonly text: string;
+    /** A new pin (Esc removes it) or an existing note being edited (Esc keeps it as it was). */
+    readonly fresh: boolean;
+}
+export type SendState = {
+    readonly kind: 'idle';
+} | {
+    readonly kind: 'sending';
+} | SaveResult;
+export interface FeedbackSessionSnapshot {
+    readonly phase: SessionPhase;
+    /** How the current or last session was started. */
+    readonly mode: SessionMode;
+    /** Clicks and keys reach the app (⌥ held or the "Use app" toggle). */
+    readonly using: boolean;
+    readonly useToggle: boolean;
+    readonly notes: readonly SessionNote[];
+    readonly bubble?: SessionBubble;
+    /** The general note: unaligned speech, what the person types in the review, or a question asked with no element (`askGeneral`). */
+    readonly general: string;
+    /** The general question field is open (feedback mode, no element attached). */
+    readonly generalOpen: boolean;
+    /** The route template now (active) or when Done was pressed (review). */
+    readonly route: string;
+    /** How many steps were recorded between the notes. */
+    readonly stepCount: number;
+    readonly voice: VoiceState;
+    /** Voice can be offered: the host gave both a capture and a transcription. */
+    readonly voiceAvailable: boolean;
+    /** Done was pressed with a recording: it is being transcribed and merged into the notes. */
+    readonly transcribing: boolean;
+    /** Something the person should know (a refused pin, a failed transcription), until the next action. */
+    readonly problem?: string;
+    readonly send: SendState;
+    /** The label of the element under the pointer, from the privacy policy (active only). */
+    readonly hover?: string;
+    readonly copy: CopyState;
+}
+/** What Send puts into the message. */
+export type FeedbackAttachment = {
+    readonly kind: 'mention';
+    readonly id: string;
+    readonly path: string;
+} | {
+    readonly kind: 'inline';
+    readonly text: string;
+} | {
+    readonly kind: 'refused';
+    readonly reason: string;
+};
+export interface FeedbackSession extends ExternalState<FeedbackSessionSnapshot> {
+    /** Enters feedback mode; `{ mode: 'point' }` for point mode on phones (a tap picks at once). */
+    readonly start: (options?: SessionStartOptions) => void;
+    /** Done: closes feedback mode, transcribes and aligns voice, and leaves the draft for review. */
+    readonly done: () => Promise<void>;
+    /** ✕: discards everything (feedback mode or the attached draft). */
+    readonly discard: () => void;
+    readonly setBubbleText: (text: string) => void;
+    /** Enter in the bubble: keeps the note (an empty new note removes its pin). */
+    readonly saveBubble: () => void;
+    /** Esc in the bubble: removes a new pin, or leaves an edited note as it was. */
+    readonly cancelBubble: () => void;
+    /**
+     * Cancels the selection of the open bubble (the "Cancel selection" button, or clicking the selected zone again): the pin and its
+     * note go, the person is back in feedback mode with nothing selected. What was typed is kept for a general question (`askGeneral`).
+     */
+    readonly cancelSelection: () => void;
+    /** "Ask a general question": opens a note with NO element attached (any open bubble closes; text typed there carries over). */
+    readonly askGeneral: () => void;
+    /** Closes the general question field, keeping what was typed. */
+    readonly closeGeneral: () => void;
+    /** The "Use app" toggle (touch, no ⌥). */
+    readonly setUseToggle: (on: boolean) => void;
+    readonly toggleVoice: () => Promise<void>;
+    readonly setNoteText: (id: number, text: string) => void;
+    readonly removeNote: (id: number) => void;
+    readonly setGeneral: (text: string) => void;
+    /** Hovering a note in the review: highlights its element in the page, or says it is not on this page. Undefined clears. */
+    readonly highlight: (id: number | undefined) => 'shown' | 'not-on-page' | 'none';
+    /** The draft the report is made from. Throws when there is nothing to send. */
+    readonly draft: () => FeedbackDraft;
+    /** The never-stored report text (Copy, inline). */
+    readonly reportText: () => string;
+    /** Copy report: the never-stored report on the clipboard. Needs no store, route or agent (FEEDBACK-2). */
+    readonly copy: () => Promise<CopyState>;
+    /** Send: saves first when the host has a store, then says what to put in the message. */
+    readonly attach: () => Promise<FeedbackAttachment>;
+    /** The message was accepted: the draft is done. */
+    readonly sent: () => void;
+    /** For journeys and tests: the pointer trail and pin marks so far, on the session clock. */
+    readonly trail: () => {
+        readonly pointer: readonly PointerSample[];
+        readonly pins: readonly PinMark[];
+    };
+    readonly dispose: () => void;
+}
+/** Point mode is on (or finishing): the host hides its panel while this is true and shows it again when it turns false. */
+export declare function isPointing(state: Pick<FeedbackSessionSnapshot, 'mode' | 'phase'>): boolean;
+/** A pin number as drawn on the page: ①…⑳, then the plain number. */
+export declare function pinMark(number: number): string;
+export declare function createFeedbackSession(options: FeedbackSessionOptions): FeedbackSession;
+//# sourceMappingURL=session.d.ts.map