@hosty-sdk/app 0.37.0 → 0.38.0

package/README.md

@@ -592,6 +592,32 @@ navigation/launcher and disabled tools until they provide a panel host. `panelLa
 rendering choice, not a disable policy: explicitly disable local tools or register a renderer.
 See [UI composition and browser acceptance](../../docs/features/sdk-ui-composition/feature.md).
 
+## Annotated feedback (Core 0.165.0 / SDK 0.38.0)
+
+`HostyUiRoot` includes an authenticated Annotate entry through the existing UI server adapter.
+Users can select an element/region or add a page comment, enter text beside it, edit that same note
+in the side panel and submit several annotations as one report. IndexedDB preserves text and image
+blobs by Core/app/installation/user. Storage failure is visible; confirmed submission clears the
+draft, while an uncertain response retains its exact UUID for retry.
+
+Screenshots use the standard Screen Capture API chooser, still-image preview/crop and explicit
+inclusion. Shared SDK frames delegate `display-capture` to their source; browser/webview support and
+parent policy still apply. Text feedback works when capture is unsupported or denied. Optional
+dictation requires an approved `providers.speech-to-text` permission and discovered provider.
+
+Own-app intake needs app access, not a management grant. Administrator clients can use
+`FeedbackServerClient` from `@hosty-sdk/app/feedback/server` with the reviewed `apps.feedback.manage`
+permission and the current app-user token; DTOs are exported from `@hosty-sdk/app/feedback`.
+These server methods expose fixed Core contracts, never a browser-accessible arbitrary proxy.
+
+A feedback-review client can mark its declared navigation item with `feedbackReview: true`. Core
+resolves its own endpoint/path through normal app launch with a `feedback=<report-id>` query. The
+client opens a review, not an automatic dispatch. The declaration grants no authority. Ordinary
+reporters get immediate submission confirmation but no processing inbox or notifications.
+
+See [App Feedback Inbox](../../docs/features/app-feedback-inbox/feature.md) for limits, access,
+manual chat dispatch, exact-prompt outcomes and workspace deletion retention.
+
 ## Child Core sandbox controls
 
 `@hosty-sdk/app/sandbox/react` exports `CoreEnvironmentPanel` for operator-facing child Core

package/dist/feedback-audio.d.ts

@@ -0,0 +1,3 @@
+/** Interoperable speech v1 baseline: mono PCM16 WAV at 16 kHz. */
+export declare function pcmWave(samples: Float32Array): Blob;
+export declare function recordingWave(recording: Blob): Promise<Blob>;

package/dist/feedback-audio.js

@@ -0,0 +1,40 @@
+/** Interoperable speech v1 baseline: mono PCM16 WAV at 16 kHz. */
+export function pcmWave(samples) {
+    if (!samples.length || samples.length > 120 * 16000)
+        throw new Error("Record between a moment and 120 seconds of audio.");
+    const bytes = new ArrayBuffer(44 + samples.length * 2), view = new DataView(bytes);
+    const text = (at, value) => { for (let i = 0; i < value.length; i++)
+        view.setUint8(at + i, value.charCodeAt(i)); };
+    text(0, "RIFF");
+    view.setUint32(4, bytes.byteLength - 8, true);
+    text(8, "WAVE");
+    text(12, "fmt ");
+    view.setUint32(16, 16, true);
+    view.setUint16(20, 1, true);
+    view.setUint16(22, 1, true);
+    view.setUint32(24, 16000, true);
+    view.setUint32(28, 32000, true);
+    view.setUint16(32, 2, true);
+    view.setUint16(34, 16, true);
+    text(36, "data");
+    view.setUint32(40, samples.length * 2, true);
+    samples.forEach((sample, i) => { const value = Math.max(-1, Math.min(1, sample)); view.setInt16(44 + i * 2, Math.round(value * (value < 0 ? 32768 : 32767)), true); });
+    return new Blob([bytes], { type: "audio/wav" });
+}
+export async function recordingWave(recording) {
+    const context = new AudioContext();
+    try {
+        const decoded = await context.decodeAudioData(await recording.arrayBuffer());
+        if (decoded.duration > 120.1)
+            throw new Error("Recordings may be up to 120 seconds.");
+        const offline = new OfflineAudioContext(1, Math.min(120 * 16000, Math.ceil(decoded.duration * 16000)), 16000);
+        const source = offline.createBufferSource();
+        source.buffer = decoded;
+        source.connect(offline.destination);
+        source.start();
+        return pcmWave((await offline.startRendering()).getChannelData(0));
+    }
+    finally {
+        await context.close();
+    }
+}

package/dist/feedback-capture.d.ts

@@ -0,0 +1,3 @@
+import type { FeedbackRect } from "./feedback-types.js";
+export declare function captureStill(hide: (hidden: boolean) => void, signal: AbortSignal): Promise<Blob>;
+export declare function cropStill(blob: Blob, crop: FeedbackRect | null): Promise<Blob>;

package/dist/feedback-capture.js

@@ -0,0 +1,80 @@
+export async function captureStill(hide, signal) {
+    if (!navigator.mediaDevices?.getDisplayMedia)
+        throw new Error("Screen capture is unavailable in this browser. You can still send comments.");
+    // Offer the application tab while retaining the browser-owned chooser and permission.
+    const options = {
+        video: true, audio: false, preferCurrentTab: true, selfBrowserSurface: "include",
+    };
+    const stream = await navigator.mediaDevices.getDisplayMedia(options);
+    const video = document.createElement("video");
+    const stop = () => { stream.getTracks().forEach(t => t.stop()); };
+    signal.addEventListener("abort", stop, { once: true });
+    try {
+        signal.throwIfAborted();
+        hide(true);
+        // Let the hidden overlay reach the compositor before consuming the live stream.
+        await new Promise(resolve => setTimeout(resolve, 100));
+        signal.throwIfAborted();
+        video.muted = true;
+        video.playsInline = true;
+        await new Promise((resolve, reject) => {
+            let frame, fallback;
+            const cleanup = () => {
+                clearTimeout(timeout);
+                clearTimeout(fallback);
+                signal.removeEventListener("abort", abort);
+                if (frame !== undefined)
+                    video.cancelVideoFrameCallback(frame);
+            };
+            const fail = (error) => { cleanup(); reject(error); };
+            const abort = () => fail(signal.reason);
+            const ready = () => { cleanup(); resolve(); };
+            const timeout = setTimeout(() => fail(new Error("The capture source did not produce a frame.")), 5000);
+            signal.addEventListener("abort", abort, { once: true });
+            // Register before play: static tab capture may deliver only one frame until pixels change.
+            if ("requestVideoFrameCallback" in video)
+                frame = video.requestVideoFrameCallback(ready);
+            video.srcObject = stream;
+            void video.play().then(() => {
+                if (!("requestVideoFrameCallback" in video))
+                    fallback = setTimeout(ready, 150);
+            }, fail);
+        });
+        signal.throwIfAborted();
+        if (!video.videoWidth || !video.videoHeight)
+            throw new Error("The selected capture surface has no image.");
+        const scale = Math.min(1, 2560 / Math.max(video.videoWidth, video.videoHeight));
+        const canvas = document.createElement("canvas");
+        canvas.width = Math.round(video.videoWidth * scale);
+        canvas.height = Math.round(video.videoHeight * scale);
+        canvas.getContext("2d").drawImage(video, 0, 0, canvas.width, canvas.height);
+        return await canvasBlob(canvas);
+    }
+    finally {
+        stop();
+        signal.removeEventListener("abort", stop);
+        video.srcObject = null;
+        hide(false);
+    }
+}
+export async function cropStill(blob, crop) {
+    if (!crop)
+        return blob;
+    const image = await createImageBitmap(blob);
+    try {
+        const x = Math.max(0, Math.min(image.width - 1, Math.floor(crop.x * image.width))), y = Math.max(0, Math.min(image.height - 1, Math.floor(crop.y * image.height)));
+        const width = Math.max(1, Math.min(image.width - x, Math.round(crop.width * image.width)));
+        const height = Math.max(1, Math.min(image.height - y, Math.round(crop.height * image.height)));
+        const canvas = document.createElement("canvas");
+        canvas.width = width;
+        canvas.height = height;
+        canvas.getContext("2d").drawImage(image, x, y, width, height, 0, 0, width, height);
+        return await canvasBlob(canvas);
+    }
+    finally {
+        image.close();
+    }
+}
+function canvasBlob(canvas) {
+    return new Promise((resolve, reject) => canvas.toBlob(blob => blob ? resolve(blob) : reject(new Error("Could not encode the screenshot.")), "image/png"));
+}

package/dist/feedback-draft.d.ts

@@ -0,0 +1,20 @@
+import type { FeedbackCapabilities, FeedbackNoteInput, FeedbackSubmit, FeedbackTarget } from "./feedback-types.js";
+export type DraftNote = Omit<FeedbackNoteInput, "image"> & {
+    image?: Blob;
+};
+export type FeedbackDraft = {
+    key: string;
+    revision: number;
+    requestId: string;
+    comment: string;
+    annotations: DraftNote[];
+    submitting: boolean;
+};
+export declare function draftKey(capabilities: FeedbackCapabilities): string;
+export declare function readDraft(key: string): Promise<FeedbackDraft | null>;
+/** Read-check-write is one transaction: an older tab cannot overwrite a newer draft. */
+export declare function saveDraft(draft: FeedbackDraft, expectedRevision: number, expectedRequestId: string | null): Promise<void>;
+export declare function deleteDraft(key: string, requestId: string, expectedRevision: number): Promise<void>;
+export declare function blankDraft(key: string): FeedbackDraft;
+export declare function makeNote(target: FeedbackTarget): DraftNote;
+export declare function submission(draft: FeedbackDraft): Promise<FeedbackSubmit>;

package/dist/feedback-draft.js

@@ -0,0 +1,104 @@
+const database = "hosty-feedback-v1";
+export function draftKey(capabilities) {
+    return JSON.stringify([capabilities.coreId, capabilities.appId, capabilities.installation, capabilities.userId]);
+}
+function open() {
+    return new Promise((resolve, reject) => {
+        if (!globalThis.indexedDB) {
+            reject(new Error("Local draft storage is unavailable."));
+            return;
+        }
+        const request = indexedDB.open(database, 1);
+        request.onupgradeneeded = () => { request.result.createObjectStore("drafts", { keyPath: "key" }); };
+        request.onsuccess = () => resolve(request.result);
+        request.onerror = () => reject(request.error ?? new Error("Could not open draft storage."));
+        request.onblocked = () => reject(new Error("Close older feedback tabs to update draft storage."));
+    });
+}
+export async function readDraft(key) {
+    const db = await open();
+    try {
+        return await new Promise((resolve, reject) => {
+            const tx = db.transaction("drafts", "readonly");
+            const request = tx.objectStore("drafts").get(key);
+            let value = null;
+            request.onsuccess = () => { value = request.result ?? null; };
+            tx.oncomplete = () => resolve(value);
+            tx.onerror = () => reject(tx.error);
+            tx.onabort = () => reject(tx.error);
+        });
+    }
+    finally {
+        db.close();
+    }
+}
+/** Read-check-write is one transaction: an older tab cannot overwrite a newer draft. */
+export async function saveDraft(draft, expectedRevision, expectedRequestId) {
+    const db = await open();
+    try {
+        await new Promise((resolve, reject) => {
+            const tx = db.transaction("drafts", "readwrite");
+            const store = tx.objectStore("drafts");
+            const read = store.get(draft.key);
+            let conflict = false;
+            read.onsuccess = () => {
+                if ((read.result?.revision ?? 0) !== expectedRevision || (read.result?.requestId ?? null) !== expectedRequestId) {
+                    conflict = true;
+                    tx.abort();
+                    return;
+                }
+                store.put(draft);
+            };
+            tx.oncomplete = () => resolve();
+            tx.onabort = tx.onerror = () => reject(conflict ? new Error("This draft changed in another tab. Reload to restore its latest saved version.") : tx.error ?? new Error("Draft could not be saved locally."));
+        });
+    }
+    finally {
+        db.close();
+    }
+}
+export async function deleteDraft(key, requestId, expectedRevision) {
+    const db = await open();
+    try {
+        await new Promise((resolve, reject) => {
+            const tx = db.transaction("drafts", "readwrite");
+            const store = tx.objectStore("drafts");
+            const read = store.get(key);
+            let conflict = false;
+            read.onsuccess = () => {
+                if (!read.result)
+                    return;
+                if (read.result.requestId !== requestId || read.result.revision !== expectedRevision) {
+                    conflict = true;
+                    tx.abort();
+                    return;
+                }
+                store.delete(key);
+            };
+            tx.oncomplete = () => resolve();
+            tx.onabort = tx.onerror = () => reject(conflict ? new Error("This draft changed in another tab. Reload before discarding its saved content.") : tx.error ?? new Error("Draft could not be removed locally."));
+        });
+    }
+    finally {
+        db.close();
+    }
+}
+export function blankDraft(key) {
+    return { key, revision: 0, requestId: crypto.randomUUID(), comment: "", annotations: [], submitting: false };
+}
+export function makeNote(target) {
+    return { id: crypto.randomUUID(), text: "", route: location.pathname, capturedAt: new Date().toISOString(), target };
+}
+export async function submission(draft) {
+    const [coreId, appId, installation, userId] = JSON.parse(draft.key);
+    return { scope: { coreId: coreId, appId: appId, installation: installation, userId: userId }, requestId: draft.requestId, comment: draft.comment, annotations: await Promise.all(draft.annotations.map(async (note) => {
+            const { image, ...data } = note;
+            if (!image)
+                return data;
+            const bytes = new Uint8Array(await image.arrayBuffer());
+            let binary = "";
+            for (let i = 0; i < bytes.length; i += 8192)
+                binary += String.fromCharCode(...bytes.subarray(i, i + 8192));
+            return { ...data, image: { mediaType: image.type, data: btoa(binary) } };
+        })) };
+}

package/dist/feedback-react.d.ts

@@ -0,0 +1,4 @@
+export declare function FeedbackCapture({ active, uiPath }: {
+    active: boolean;
+    uiPath?: string;
+}): import("react").JSX.Element | null;

package/dist/feedback-react.js

@@ -0,0 +1,390 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { useEffect, useRef, useState } from "react";
+import { createPortal } from "react-dom";
+import { APP_SESSION_RESTORED, appFetch } from "./browser-auth.js";
+import { SdkChromeStyles } from "./sdk-chrome.js";
+import { blankDraft, deleteDraft, draftKey, makeNote, readDraft, saveDraft, submission } from "./feedback-draft.js";
+import { FeedbackSpeech } from "./feedback-speech.js";
+import { captureStill, cropStill } from "./feedback-capture.js";
+function useBlobUrl(blob) {
+    const [url, setUrl] = useState("");
+    useEffect(() => { if (!blob) {
+        setUrl("");
+        return;
+    } const value = URL.createObjectURL(blob); setUrl(value); return () => URL.revokeObjectURL(value); }, [blob]);
+    return url;
+}
+function ImagePreview({ blob }) { const url = useBlobUrl(blob); return url ? _jsx("img", { src: url, alt: "Included screenshot" }) : null; }
+const rect = (b) => ({ x: b.x, y: b.y, width: b.width, height: b.height });
+const viewport = () => ({ width: innerWidth, height: innerHeight, scale: devicePixelRatio });
+const errorMessage = (e) => e instanceof Error ? e.message : "Feedback could not be saved.";
+export function FeedbackCapture({ active, uiPath = "/api/hosty/ui" }) {
+    const [capabilities, setCapabilities] = useState(null);
+    const [unavailable, setUnavailable] = useState("");
+    const [retry, setRetry] = useState(0);
+    useEffect(() => { const refresh = () => setRetry(r => r + 1); window.addEventListener(APP_SESSION_RESTORED, refresh); return () => window.removeEventListener(APP_SESSION_RESTORED, refresh); }, []);
+    const path = uiPath.replace(/\/$/, "") + "/feedback";
+    useEffect(() => {
+        setCapabilities(null);
+        setUnavailable("");
+        if (!active)
+            return;
+        const controller = new AbortController();
+        void appFetch(path, { signal: controller.signal }).then(async (response) => {
+            if (!response.ok)
+                throw new Error(response.status === 404 ? "Update Core and this app to enable feedback." : "Feedback is unavailable. Retry when access is restored.");
+            const value = await response.json();
+            if (value.version !== 1 || !value.userId || !value.appId || !value.installation || !value.coreId)
+                throw new Error("Feedback capability response is incompatible.");
+            if (!controller.signal.aborted)
+                setCapabilities(value);
+        }).catch(e => { if (!controller.signal.aborted)
+            setUnavailable(errorMessage(e)); });
+        return () => controller.abort();
+    }, [active, path, retry]);
+    if (!active || typeof document === "undefined")
+        return null;
+    return capabilities ? _jsx(FeedbackEditor, { capabilities: capabilities, path: path }, draftKey(capabilities))
+        : unavailable ? createPortal(_jsxs("div", { "data-hosty-feedback": true, "data-hosty-sdk": true, className: "hosty-feedback-launch", children: [_jsx(SdkChromeStyles, {}), _jsx("button", { title: unavailable, onClick: () => setRetry(r => r + 1), children: "Retry feedback" })] }), document.body) : null;
+}
+function FeedbackEditor({ capabilities, path }) {
+    const [dictating, setDictating] = useState(false);
+    const [reviewTargets, setReviewTargets] = useState([]);
+    const key = draftKey(capabilities);
+    const [draft, setDraft] = useState(() => blankDraft(key));
+    const current = useRef(draft), savedRevision = useRef(0), savedRequestId = useRef(null), queue = useRef(Promise.resolve()), saveFailure = useRef(null);
+    const live = useRef(true);
+    const [ready, setReady] = useState(false), [open, setOpen] = useState(false), [saving, setSaving] = useState(false);
+    const [error, setError] = useState(""), [notice, setNotice] = useState(""), [busy, setBusy] = useState(false);
+    const [picking, setPicking] = useState(null);
+    const [highlight, setHighlight] = useState(null);
+    const [edit, setEdit] = useState(null);
+    const [hidden, setHidden] = useState(false), [capturing, setCapturing] = useState(false);
+    const [preview, setPreview] = useState(null);
+    const elements = useRef(new Map());
+    const capture = useRef(null);
+    const root = useRef(null);
+    useEffect(() => {
+        live.current = true;
+        void readDraft(key).then(value => {
+            if (!live.current)
+                return;
+            if (value) {
+                current.current = value;
+                savedRevision.current = value.revision;
+                savedRequestId.current = value.requestId;
+                setDraft(value);
+                setNotice("Saved draft restored.");
+            }
+        }).catch(e => { if (live.current)
+            setError(errorMessage(e)); }).finally(() => { if (live.current)
+            setReady(true); });
+        return () => { live.current = false; capture.current?.abort(); };
+    }, [key]);
+    function update(change) {
+        const next = { ...current.current, ...change, revision: current.current.revision + 1 };
+        current.current = next;
+        setDraft(next);
+        setSaving(true);
+        setNotice("");
+        queue.current = queue.current.then(async () => {
+            try {
+                await saveDraft(next, savedRevision.current, savedRequestId.current);
+                savedRevision.current = next.revision;
+                savedRequestId.current = next.requestId;
+                saveFailure.current = null;
+                if (live.current) {
+                    setError("");
+                    setSaving(current.current.revision !== next.revision);
+                }
+            }
+            catch (e) {
+                saveFailure.current = new Error(errorMessage(e));
+                if (live.current) {
+                    setSaving(false);
+                    setError("Not saved locally: " + errorMessage(e));
+                }
+            }
+        });
+    }
+    async function flush() { await queue.current; if (saveFailure.current)
+        throw saveFailure.current; }
+    function noteChange(id, change) {
+        if (current.current.submitting)
+            return;
+        update({ annotations: current.current.annotations.map(n => n.id === id ? { ...n, ...change } : n) });
+    }
+    function add(target, element) {
+        if (current.current.annotations.length >= capabilities.maxAnnotations) {
+            setError("A report can contain at most 20 annotations.");
+            return;
+        }
+        const note = makeNote(target);
+        if (element)
+            elements.current.set(note.id, element);
+        update({ annotations: [...current.current.annotations, note] });
+        setEdit({ id: note.id, where: "anchor" });
+        setPicking(null);
+        setHighlight(target.bounds ?? null);
+    }
+    useEffect(() => {
+        if (!picking || draft.submitting || !open)
+            return;
+        let start = null;
+        const inside = (event) => event.composedPath().some(node => node instanceof Element && node.hasAttribute("data-hosty-feedback"));
+        const move = (event) => {
+            if (inside(event))
+                return;
+            if (picking === "region" && start)
+                setHighlight({ x: Math.min(start.x, event.clientX), y: Math.min(start.y, event.clientY),
+                    width: Math.abs(event.clientX - start.x), height: Math.abs(event.clientY - start.y) });
+            else if (picking === "element") {
+                const element = document.elementFromPoint(event.clientX, event.clientY);
+                if (element)
+                    setHighlight(rect(element.getBoundingClientRect()));
+            }
+        };
+        const down = (event) => {
+            if (inside(event))
+                return;
+            event.preventDefault();
+            event.stopImmediatePropagation();
+            // React may remove the picker effect before the native click follows pointerup.
+            const swallow = (click) => { click.preventDefault(); click.stopImmediatePropagation(); cleanup(); };
+            const cleanup = () => { document.removeEventListener("click", swallow, true); clearTimeout(timer); };
+            const timer = setTimeout(cleanup, 1500);
+            document.addEventListener("click", swallow, { capture: true, once: true });
+            if (picking === "region") {
+                start = { x: event.clientX, y: event.clientY };
+                return;
+            }
+            const element = document.elementFromPoint(event.clientX, event.clientY);
+            if (!element)
+                return;
+            // Never read input values, text content, or arbitrary data attributes into evidence.
+            const label = element.getAttribute("aria-label")?.slice(0, 200) || element.tagName.toLowerCase();
+            const selector = element.id ? "#" + CSS.escape(element.id) : element.tagName.toLowerCase();
+            add({ kind: "element", label, selector, bounds: rect(element.getBoundingClientRect()), viewport: viewport() }, element);
+        };
+        const up = (event) => {
+            if (!start)
+                return;
+            event.preventDefault();
+            event.stopImmediatePropagation();
+            const b = { x: Math.min(start.x, event.clientX), y: Math.min(start.y, event.clientY),
+                width: Math.abs(event.clientX - start.x), height: Math.abs(event.clientY - start.y) };
+            start = null;
+            if (b.width > 3 && b.height > 3)
+                add({ kind: "region", label: "Selected region", bounds: b, viewport: viewport() });
+        };
+        const click = (event) => { if (!inside(event)) {
+            event.preventDefault();
+            event.stopImmediatePropagation();
+        } };
+        const escape = (event) => { if (event.key === "Escape") {
+            setPicking(null);
+            setHighlight(null);
+        } };
+        document.addEventListener("pointermove", move, true);
+        document.addEventListener("pointerdown", down, true);
+        document.addEventListener("pointerup", up, true);
+        document.addEventListener("click", click, true);
+        document.addEventListener("keydown", escape, true);
+        const old = document.documentElement.style.cursor;
+        document.documentElement.style.cursor = "crosshair";
+        return () => {
+            document.removeEventListener("pointermove", move, true);
+            document.removeEventListener("pointerdown", down, true);
+            document.removeEventListener("pointerup", up, true);
+            document.removeEventListener("click", click, true);
+            document.removeEventListener("keydown", escape, true);
+            document.documentElement.style.cursor = old;
+        };
+    }, [picking, draft.submitting, open]);
+    const selected = draft.annotations.find(n => n.id === edit?.id);
+    useEffect(() => {
+        if (picking || !edit || !open)
+            return;
+        const refresh = () => {
+            const element = elements.current.get(edit.id);
+            setHighlight(element?.isConnected ? rect(element.getBoundingClientRect()) : current.current.annotations.find(n => n.id === edit.id)?.target?.bounds ?? null);
+        };
+        refresh();
+        window.addEventListener("scroll", refresh, true);
+        window.addEventListener("resize", refresh);
+        return () => { window.removeEventListener("scroll", refresh, true); window.removeEventListener("resize", refresh); };
+    }, [edit, picking, open]);
+    async function done() {
+        setEdit(null);
+        setHighlight(null);
+        try {
+            await flush();
+        }
+        catch (e) {
+            setError(errorMessage(e));
+        }
+    }
+    async function screenshot(id) {
+        if (capture.current || draft.submitting)
+            return;
+        const operation = new AbortController();
+        capture.current = operation;
+        setCapturing(true);
+        setError("");
+        try {
+            const blob = await captureStill(value => { if (root.current)
+                root.current.style.visibility = value ? "hidden" : ""; setHidden(value); }, operation.signal);
+            if (live.current && !operation.signal.aborted)
+                setPreview({ id, blob });
+        }
+        catch (e) {
+            if (live.current && !operation.signal.aborted)
+                setError(errorMessage(e));
+        }
+        finally {
+            if (capture.current === operation)
+                capture.current = null;
+            if (live.current)
+                setCapturing(false);
+        }
+    }
+    async function acceptImage(blob) {
+        if (!preview)
+            return;
+        if (blob.size > capabilities.maxImageBytes) {
+            setError("Crop a smaller area: each screenshot must fit within 2 MiB.");
+            return;
+        }
+        const total = current.current.annotations.filter(n => n.id !== preview.id).reduce((sum, n) => sum + (n.image?.size ?? 0), 0) + blob.size;
+        if (total > capabilities.maxTotalImageBytes) {
+            setError("Screenshots may total at most 8 MiB. Remove or crop an existing image.");
+            return;
+        }
+        noteChange(preview.id, { image: blob });
+        setPreview(null);
+    }
+    async function send() {
+        if (busy || !current.current.annotations.length || current.current.annotations.some(n => !n.text.trim()))
+            return;
+        setBusy(true);
+        setError("");
+        try {
+            update({ submitting: true });
+            await flush();
+            const frozen = current.current;
+            const response = await appFetch(path, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify(await submission(frozen)) });
+            const result = await response.json().catch(() => null);
+            if (!response.ok) {
+                if ([400, 413, 415].includes(response.status))
+                    update({ submitting: false, requestId: crypto.randomUUID() });
+                throw new Error(result?.message ?? "Submission was not confirmed. Retry the same feedback; your draft is retained.");
+            }
+            if (!result || !["submitted", "deleted"].includes(result.status ?? ""))
+                throw new Error("Submission was not confirmed. Retry the same feedback.");
+            await deleteDraft(key, frozen.requestId, frozen.revision);
+            const fresh = blankDraft(key);
+            savedRevision.current = 0;
+            savedRequestId.current = null;
+            current.current = fresh;
+            setDraft(fresh);
+            setReviewTargets([]);
+            if (capabilities.administrator && result.status === "submitted" && result.id) {
+                void appFetch(path + "/" + encodeURIComponent(result.id) + "/review-targets").then(async (response) => {
+                    if (!response.ok)
+                        return;
+                    const value = await response.json();
+                    if (live.current)
+                        setReviewTargets(value.targets ?? []);
+                }).catch(() => undefined);
+            }
+            setEdit(null);
+            setHighlight(null);
+            setNotice(result.status === "deleted" ? "This feedback was already submitted and subsequently removed with its workspace." : "Feedback submitted.");
+        }
+        catch (e) {
+            setError(errorMessage(e));
+        }
+        finally {
+            if (live.current)
+                setBusy(false);
+        }
+    }
+    async function discard() {
+        if (!window.confirm(current.current.submitting ? "This submission may already exist. Discard its local retry record? This does not delete a submitted feedback." : "Discard this local feedback draft and its screenshots?"))
+            return;
+        try {
+            await queue.current;
+            await deleteDraft(key, current.current.requestId, savedRevision.current);
+            const fresh = blankDraft(key);
+            savedRevision.current = 0;
+            savedRequestId.current = null;
+            saveFailure.current = null;
+            current.current = fresh;
+            setDraft(fresh);
+            setEdit(null);
+            setHighlight(null);
+            setError("");
+            setNotice("Draft discarded.");
+        }
+        catch (e) {
+            setError(errorMessage(e));
+        }
+    }
+    function editor(note) {
+        return _jsxs(_Fragment, { children: [_jsxs("label", { children: ["Comment", _jsx("textarea", { "aria-label": "Comment", autoFocus: true, maxLength: 2000, value: note.text, disabled: draft.submitting, onChange: event => noteChange(note.id, { text: event.target.value }), placeholder: "What should change here?" })] }), _jsx(FeedbackSpeech, { path: path, disabled: draft.submitting, onBusyChange: setDictating, onText: text => {
+                        const old = current.current.annotations.find(n => n.id === note.id);
+                        if (!old)
+                            return;
+                        const next = [old.text, text].filter(Boolean).join(" ");
+                        if (next.length > 2000) {
+                            setError("Dictation exceeds the comment limit. Shorten the comment before dictating again.");
+                            return;
+                        }
+                        noteChange(note.id, { text: next });
+                    } }), _jsxs("div", { className: "hf-actions", children: [_jsx("button", { onClick: () => void screenshot(note.id), disabled: capturing || draft.submitting, children: "Add screenshot" }), _jsx("button", { disabled: dictating, onClick: () => void done(), children: "Done" })] })] });
+    }
+    const popup = { left: Math.max(12, Math.min(highlight?.x ?? 24, innerWidth - 340)),
+        top: Math.max(12, Math.min((highlight?.y ?? 40) + (highlight?.height ?? 0) + 12, innerHeight - 250)) };
+    if (!ready)
+        return null;
+    return createPortal(_jsxs("div", { ref: root, "data-hosty-feedback": true, "data-hosty-sdk": true, style: { visibility: hidden ? "hidden" : undefined }, children: [_jsx(SdkChromeStyles, {}), _jsx("style", { children: feedbackStyles }), !open && _jsxs("button", { className: "hosty-feedback-launch", onClick: () => setOpen(true), children: ["Annotate", draft.annotations.length ? " · " + draft.annotations.length : ""] }), open && _jsxs(_Fragment, { children: [picking && _jsxs("div", { className: "hosty-feedback-launch", role: "status", children: [picking === "element" ? "Select an element" : "Drag a region", " \u00B7 Escape cancels ", _jsx("button", { onClick: () => { setPicking(null); setHighlight(null); }, children: "Cancel selection" })] }), _jsxs("aside", { className: "hf-panel", "aria-label": "Feedback draft", style: { visibility: picking ? "hidden" : undefined,
+                            ...(edit?.where === "anchor" && highlight && highlight.x > innerWidth - 400 ? { left: 12, right: "auto" } : {}) }, children: [_jsxs("header", { children: [_jsxs("div", { children: [_jsx("strong", { children: "Feedback" }), _jsx("small", { children: saving ? "Saving…" : saveFailure.current ? "Not saved locally" : draft.revision ? "Saved locally" : "New report" })] }), _jsx("button", { "aria-label": "Close feedback", onClick: () => { setOpen(false); setPicking(null); capture.current?.abort(); }, children: "\u00D7" })] }), _jsx("p", { children: "Collect related comments, then send them as one feedback." }), _jsxs("div", { className: "hf-actions", children: [_jsx("button", { disabled: draft.submitting, "aria-pressed": picking === "element", onClick: () => { setEdit(null); setPicking("element"); }, children: "Select element" }), _jsx("button", { disabled: draft.submitting, "aria-pressed": picking === "region", onClick: () => { setEdit(null); setPicking("region"); }, children: "Select region" }), _jsx("button", { disabled: draft.submitting, onClick: () => add({ kind: "page", label: "This page", viewport: viewport() }), children: "Page comment" })] }), picking && _jsxs("p", { role: "status", children: [picking === "element" ? "Click an element to annotate it." : "Drag over the area to annotate.", " Escape cancels selection."] }), _jsx("ol", { children: draft.annotations.map((note, index) => _jsxs("li", { children: [_jsxs("div", { className: "hf-note-heading", children: [_jsxs("button", { onClick: () => { setPicking(null); setEdit({ id: note.id, where: "anchor" }); elements.current.get(note.id)?.scrollIntoView({ block: "nearest" }); }, children: [index + 1, ". ", note.target?.label ?? "Annotation"] }), _jsx("button", { disabled: draft.submitting, onClick: () => { update({ annotations: current.current.annotations.filter(n => n.id !== note.id) }); if (edit?.id === note.id)
+                                                        setEdit(null); }, children: "Remove" })] }), edit?.id === note.id && edit.where === "side" ? editor(note) : _jsxs(_Fragment, { children: [_jsx("p", { children: note.text || "Add a comment…" }), _jsx("button", { onClick: () => { setPicking(null); setEdit({ id: note.id, where: "side" }); }, children: "Edit" })] }), note.image && _jsxs(_Fragment, { children: [_jsx(ImagePreview, { blob: note.image }), _jsx("button", { disabled: draft.submitting, onClick: () => noteChange(note.id, { image: undefined }), children: "Remove screenshot" })] })] }, note.id)) }), _jsxs("label", { children: ["Overall comment (optional)", _jsx("textarea", { maxLength: 5000, value: draft.comment, disabled: draft.submitting, onChange: event => update({ comment: event.target.value }) })] }), error && _jsx("p", { role: "alert", className: "hf-error", children: error }), notice && _jsx("p", { role: "status", children: notice }), reviewTargets.map(target => _jsx("p", { children: _jsxs("a", { href: target.href, target: "_blank", rel: "noopener noreferrer", children: ["Send to chat in ", target.label] }) }, target.href)), draft.submitting && !busy && _jsx("p", { children: "The submission may already have reached Core. Retry to recover its confirmation." }), _jsxs("footer", { children: [_jsx("button", { onClick: () => void discard(), disabled: busy, children: "Discard draft" }), _jsx("button", { className: "hf-primary", disabled: busy || dictating || capturing || !draft.annotations.length || draft.annotations.some(n => !n.text.trim()), onClick: () => void send(), children: busy ? "Sending…" : draft.submitting ? "Retry submission" : "Submit feedback" })] })] }), highlight && _jsx("div", { className: "hf-highlight", "aria-hidden": true, style: { left: highlight.x, top: highlight.y, width: highlight.width, height: highlight.height } }), selected && edit?.where === "anchor" && !picking && _jsxs("section", { className: "hf-popover", role: "dialog", "aria-label": "Annotation comment", style: popup, children: [_jsx("strong", { children: selected.target?.label ?? "Annotation" }), editor(selected)] }), preview && _jsx(CropPreview, { blob: preview.blob, onCancel: () => setPreview(null), onAccept: acceptImage })] })] }), document.body);
+}
+function CropPreview({ blob, onCancel, onAccept }) {
+    const url = useBlobUrl(blob);
+    const [crop, setCrop] = useState(null), [busy, setBusy] = useState(false), [error, setError] = useState("");
+    const dialog = useRef(null);
+    useEffect(() => {
+        const node = dialog.current;
+        node?.showModal();
+        return () => { node?.close(); };
+    }, []);
+    const start = useRef(null);
+    const point = (event) => {
+        const bounds = event.currentTarget.getBoundingClientRect();
+        return { x: Math.max(0, Math.min(1, (event.clientX - bounds.x) / bounds.width)), y: Math.max(0, Math.min(1, (event.clientY - bounds.y) / bounds.height)) };
+    };
+    return _jsxs("dialog", { ref: dialog, className: "hf-crop", "aria-label": "Review screenshot", onCancel: event => { event.preventDefault(); if (!busy)
+            onCancel(); }, children: [_jsx("h2", { children: "Review screenshot" }), _jsx("p", { children: "Check the selected source. Drag to crop, or adjust the percentages below. Only the approved image is included." }), _jsxs("div", { className: "hf-crop-image", onPointerDown: event => { start.current = point(event); event.currentTarget.setPointerCapture(event.pointerId); }, onPointerMove: event => {
+                    if (!start.current)
+                        return;
+                    const p = point(event);
+                    setCrop({ x: Math.min(p.x, start.current.x), y: Math.min(p.y, start.current.y),
+                        width: Math.abs(p.x - start.current.x), height: Math.abs(p.y - start.current.y) });
+                }, onPointerUp: () => { start.current = null; }, children: [url && _jsx("img", { src: url, alt: "Captured screen for review", draggable: false }), crop && _jsx("div", { className: "hf-crop-selection", style: { left: crop.x * 100 + "%", top: crop.y * 100 + "%", width: crop.width * 100 + "%", height: crop.height * 100 + "%" } })] }), _jsx("div", { className: "hf-actions", children: ["x", "y", "width", "height"].map(field => _jsxs("label", { children: [field === "x" ? "Left %" : field === "y" ? "Top %" : field === "width" ? "Width %" : "Height %", _jsx("input", { type: "number", min: 0, max: 100, value: Math.round((crop?.[field] ?? (field === "width" || field === "height" ? 1 : 0)) * 100), onChange: event => setCrop({ ...(crop ?? { x: 0, y: 0, width: 1, height: 1 }), [field]: Math.max(0, Math.min(1, Number(event.target.value) / 100)) }) })] }, field)) }), error && _jsx("p", { role: "alert", children: error }), _jsxs("footer", { children: [_jsx("button", { onClick: onCancel, disabled: busy, children: "Cancel" }), _jsx("button", { onClick: () => setCrop(null), children: "Use full image" }), _jsx("button", { className: "hf-primary", disabled: busy || !!crop && (!crop.width || !crop.height), onClick: () => { setBusy(true); void cropStill(blob, crop).then(onAccept).catch(e => setError(errorMessage(e))).finally(() => setBusy(false)); }, children: "Include screenshot" })] })] });
+}
+const feedbackStyles = [
+    "[data-hosty-feedback]{font-family:var(--hs-font);font-size:14px;color:#0f1b2d;line-height:1.45}",
+    ".hosty-feedback-launch{position:fixed;left:16px;bottom:16px;z-index:2147481000;background:#fff;border:1px solid #bdc8d6;border-radius:20px;padding:10px 16px;box-shadow:0 3px 14px #0f1b2d20}",
+    "[data-hosty-feedback] button{font:inherit;cursor:pointer;border:1px solid #cbd5e1;border-radius:7px;background:#fff;padding:6px 10px;color:#0f1b2d}",
+    "[data-hosty-feedback] button:disabled{opacity:.5;cursor:not-allowed}[data-hosty-feedback] button:focus-visible,[data-hosty-feedback] textarea:focus{outline:2px solid #65a30d;outline-offset:2px}",
+    "[data-hosty-feedback] textarea{box-sizing:border-box;display:block;width:100%;min-height:90px;font:inherit;color:#0f1b2d;background:#fff;border:1px solid #cbd5e1;border-radius:7px;padding:8px;resize:vertical;margin:6px 0}",
+    "[data-hosty-feedback] .hf-primary{background:#a3e635;border-color:#84cc16}[data-hosty-feedback] .hf-error{color:#b91c1c}",
+    ".hf-panel{box-sizing:border-box;position:fixed;right:12px;top:12px;bottom:12px;width:min(360px,calc(100vw - 24px));background:#fff;border:1px solid #cbd5e1;border-radius:12px;padding:16px;box-shadow:0 10px 45px #0f1b2d30;overflow:auto;z-index:2147481001}",
+    ".hf-panel header,.hf-note-heading,.hf-panel footer,.hf-crop footer{display:flex;justify-content:space-between;align-items:center;gap:8px}.hf-panel small{display:block;color:#64748b}.hf-panel ol{padding:0;list-style:none}.hf-panel li{border:1px solid #e2e8f0;border-radius:9px;padding:10px;margin:12px 0}.hf-panel p{white-space:pre-wrap;overflow-wrap:anywhere}.hf-panel img{max-width:100%;border-radius:6px;margin:8px 0}.hf-panel footer{margin-top:14px}",
+    ".hf-actions{display:flex;flex-wrap:wrap;gap:6px;margin:8px 0}.hf-highlight{position:fixed;border:2px solid #65a30d;box-shadow:0 0 0 2px #ecfccb;pointer-events:none;z-index:2147481000;background:#a3e63518;box-sizing:border-box}",
+    ".hf-popover>strong{display:block;margin-bottom:6px}.hf-popover{position:fixed;width:min(310px,calc(100vw - 32px));box-sizing:border-box;z-index:2147481002;background:#fff;border:1px solid #84cc16;border-radius:10px;padding:12px;box-shadow:0 8px 28px #0f1b2d35}",
+    ".hf-backdrop{position:fixed;inset:0;background:#0f1b2d88;display:grid;place-items:center;z-index:2147481003;padding:16px}.hf-crop::backdrop{background:#0f1b2d88}.hf-crop{border:0;color:#0f1b2d;background:#fff;border-radius:12px;padding:20px;width:min(760px,90vw);max-height:90vh;overflow:auto}.hf-crop-image{position:relative;display:table;max-width:100%;touch-action:none}.hf-crop-image img{display:block;max-width:100%;max-height:55vh;user-select:none}.hf-crop-selection{position:absolute;border:2px solid #65a30d;background:#a3e63530;pointer-events:none;box-sizing:border-box}.hf-crop input{display:block;width:70px}"
+].join("\n");

package/dist/feedback-server.d.ts

@@ -0,0 +1,31 @@
+import type { ProviderServerOptions } from "@hosty-sdk/app/providers/server";
+import { type FeedbackCapabilities, type FeedbackSubmit, type FeedbackReport, type FeedbackCollection, type FeedbackDispatch, type FeedbackDispatchInput, type FeedbackDelivery, type FeedbackOutcome } from "@hosty-sdk/app/feedback";
+export declare class FeedbackServerClient {
+    private readonly appId;
+    private readonly core;
+    private readonly service;
+    constructor(options?: ProviderServerOptions);
+    private response;
+    private request;
+    capabilities(token: string, signal?: AbortSignal): Promise<FeedbackCapabilities>;
+    submit(input: FeedbackSubmit, token: string, signal?: AbortSignal): Promise<{
+        id: string;
+        status: string;
+    }>;
+    reviewTargets(id: string, token: string, signal?: AbortSignal): Promise<{
+        targets: {
+            label: string;
+            href: string;
+        }[];
+    }>;
+    list(token: string, signal?: AbortSignal): Promise<FeedbackCollection>;
+    change(id: string, input: {
+        expectedRevision: number;
+        workspaceId: string | null;
+        disposition?: string | null;
+    }, token: string): Promise<FeedbackReport>;
+    reserve(input: FeedbackDispatchInput, token: string): Promise<FeedbackDispatch>;
+    delivery(id: string, input: FeedbackDelivery, token: string): Promise<FeedbackDispatch>;
+    outcomes(id: string, outcomes: FeedbackOutcome[], token: string): Promise<FeedbackDispatch>;
+    image(id: string, noteId: string, token: string, signal?: AbortSignal): Promise<Response>;
+}

package/dist/feedback-server.js

@@ -0,0 +1,48 @@
+import { FeedbackError } from "@hosty-sdk/app/feedback";
+export class FeedbackServerClient {
+    appId;
+    core;
+    service;
+    constructor(options = {}) {
+        this.appId = options.appId ?? process.env.HOSTY_APP_ID ?? "";
+        this.core = new URL(options.coreOrigin ?? process.env.HOSTY_CORE_ORIGIN ?? "http://127.0.0.1:7070");
+        this.service = options.serviceToken ?? process.env.HOSTY_APP_SERVICE_TOKEN ?? "";
+        if (!this.appId || !this.service)
+            throw new FeedbackError("hosty_misconfigured", "Hosty app credentials are unavailable.", 503);
+    }
+    async response(path, token, body, signal) {
+        if (!token)
+            throw new FeedbackError("identity_required", "Sign in to use feedback.", 401);
+        const response = await fetch(new URL("/api/internal/apps/" + encodeURIComponent(this.appId) + "/" + path, this.core), {
+            method: body === undefined ? "GET" : "POST", redirect: "error", cache: "no-store",
+            signal: signal ? AbortSignal.any([signal, AbortSignal.timeout(30_000)]) : AbortSignal.timeout(30_000),
+            headers: { authorization: "Bearer " + this.service, "X-Hosty-User-Token": token, "content-type": "application/json" },
+            body: body === undefined ? undefined : JSON.stringify(body),
+        });
+        if (!response.ok) {
+            const error = await response.json().catch(() => null);
+            throw new FeedbackError(error?.code ?? "feedback_unavailable", error?.message ?? "Feedback is unavailable. Your draft is retained.", response.status);
+        }
+        return response;
+    }
+    async request(path, token, body, signal) {
+        return (await this.response(path, token, body, signal)).json();
+    }
+    capabilities(token, signal) { return this.request("ui/feedback", token, undefined, signal); }
+    submit(input, token, signal) { return this.request("ui/feedback", token, input, signal); }
+    reviewTargets(id, token, signal) { return this.request("ui/feedback/" + encodeURIComponent(id) + "/review-targets", token, undefined, signal); }
+    list(token, signal) { return this.request("feedback", token, undefined, signal); }
+    change(id, input, token) {
+        return this.request("feedback/" + encodeURIComponent(id), token, input);
+    }
+    reserve(input, token) { return this.request("feedback/dispatches", token, input); }
+    delivery(id, input, token) {
+        return this.request("feedback/dispatches/" + encodeURIComponent(id) + "/delivery", token, input);
+    }
+    outcomes(id, outcomes, token) {
+        return this.request("feedback/dispatches/" + encodeURIComponent(id) + "/outcomes", token, { outcomes });
+    }
+    image(id, noteId, token, signal) {
+        return this.response("feedback/" + encodeURIComponent(id) + "/images/" + encodeURIComponent(noteId), token, undefined, signal);
+    }
+}

package/dist/feedback-speech.d.ts

@@ -0,0 +1,6 @@
+export declare function FeedbackSpeech({ path, disabled, onText, onBusyChange }: {
+    path: string;
+    disabled: boolean;
+    onText: (text: string) => void;
+    onBusyChange: (busy: boolean) => void;
+}): import("react").JSX.Element;

package/dist/feedback-speech.js

@@ -0,0 +1,119 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { useEffect, useRef, useState } from "react";
+import { appFetch } from "./browser-auth.js";
+import { recordingWave } from "./feedback-audio.js";
+const dispose = (op) => { if (!op)
+    return; op.controller.abort(); clearTimeout(op.timer); if (op.recorder?.state === "recording")
+    op.recorder.stop(); op.stream?.getTracks().forEach(t => t.stop()); };
+export function FeedbackSpeech({ path, disabled, onText, onBusyChange }) {
+    const [providers, setProviders] = useState([]), [choice, setChoice] = useState("");
+    const [phase, setPhase] = useState("idle"), [error, setError] = useState("");
+    const active = useRef(null), result = useRef(onText);
+    result.current = onText;
+    const endpoint = path + "/speech";
+    useEffect(() => { onBusyChange(phase !== "idle"); return () => onBusyChange(false); }, [phase, onBusyChange]);
+    useEffect(() => {
+        const abort = new AbortController();
+        void appFetch(endpoint, { credentials: "include", signal: abort.signal }).then(async (response) => {
+            const value = await response.json();
+            if (!response.ok)
+                throw new Error(value.message ?? "Speech input is unavailable.");
+            if (!abort.signal.aborted) {
+                setProviders(value.providers ?? []);
+                if (!value.granted)
+                    setError("Speech input is not enabled for this application.");
+            }
+        }).catch(e => { if (!abort.signal.aborted)
+            setError(e.message); });
+        return () => { abort.abort(); dispose(active.current); active.current = null; };
+    }, [endpoint]);
+    useEffect(() => { if (disabled) {
+        dispose(active.current);
+        active.current = null;
+        setPhase("idle");
+    } }, [disabled]);
+    const selected = providers.find(p => JSON.stringify([p.appId, p.key]) === choice) ?? (providers.length === 1 ? providers[0] : undefined);
+    function cancel() { dispose(active.current); active.current = null; setPhase("idle"); }
+    async function start() {
+        if (!selected?.available || disabled || active.current)
+            return;
+        const op = { controller: new AbortController() };
+        active.current = op;
+        const valid = () => active.current === op && !op.controller.signal.aborted;
+        setPhase("starting");
+        setError("");
+        try {
+            if (!navigator.mediaDevices?.getUserMedia || typeof MediaRecorder === "undefined")
+                throw new Error("This browser cannot record audio here. Type your comment instead.");
+            op.stream = await navigator.mediaDevices.getUserMedia({ audio: true });
+            if (!valid()) {
+                dispose(op);
+                return;
+            }
+            const recorder = new MediaRecorder(op.stream);
+            op.recorder = recorder;
+            const chunks = [];
+            let bytes = 0;
+            recorder.ondataavailable = e => { bytes += e.data.size; if (bytes > 16 * 1024 * 1024) {
+                cancel();
+                setError("Recording is too large. Try a shorter comment.");
+            }
+            else if (e.data.size)
+                chunks.push(e.data); };
+            recorder.onerror = () => { if (valid()) {
+                cancel();
+                setError("Recording failed. Type your comment or try again.");
+            } };
+            recorder.onstop = () => {
+                clearTimeout(op.timer);
+                op.stream?.getTracks().forEach(t => t.stop());
+                if (!valid())
+                    return;
+                setPhase("transcribing");
+                void (async () => {
+                    try {
+                        const wave = await recordingWave(new Blob(chunks, { type: recorder.mimeType }));
+                        if (!valid())
+                            return;
+                        const data = new Uint8Array(await wave.arrayBuffer());
+                        let binary = "";
+                        for (let at = 0; at < data.length; at += 8192)
+                            binary += String.fromCharCode(...data.subarray(at, at + 8192));
+                        const response = await appFetch(endpoint, { method: "POST", credentials: "include", signal: op.controller.signal,
+                            headers: { "content-type": "application/json" }, body: JSON.stringify({ appId: selected.appId, key: selected.key, audio: btoa(binary) }) });
+                        const value = await response.json();
+                        if (!response.ok)
+                            throw new Error(value.message ?? "Speech recognition failed.");
+                        if (valid()) {
+                            if (typeof value.text === "string" && value.text.trim())
+                                result.current(value.text.trim());
+                            else
+                                setError("No speech detected.");
+                        }
+                    }
+                    catch (e) {
+                        if (valid())
+                            setError(e instanceof Error ? e.message : "Speech recognition failed.");
+                    }
+                    finally {
+                        if (active.current === op)
+                            cancel();
+                    }
+                })();
+            };
+            recorder.start(1000);
+            setPhase("recording");
+            op.timer = setTimeout(() => { if (recorder.state === "recording")
+                recorder.stop(); }, 60_000);
+        }
+        catch (e) {
+            if (valid()) {
+                cancel();
+                setError(e instanceof Error ? e.message : "Microphone access failed.");
+            }
+        }
+    }
+    return _jsxs("div", { className: "hf-speech", children: [providers.length > 1 && _jsxs("label", { children: ["Speech provider", _jsxs("select", { value: choice, disabled: phase !== "idle" || disabled, onChange: e => setChoice(e.target.value), children: [_jsx("option", { value: "", children: "Choose provider" }), providers.map(p => _jsx("option", { value: JSON.stringify([p.appId, p.key]), disabled: !p.available, children: p.displayName }, JSON.stringify([p.appId, p.key])))] })] }), phase === "idle" ? _jsx("button", { disabled: disabled || !selected?.available, title: error || "Dictate up to one minute", onClick: () => void start(), children: "Dictate" })
+                : _jsxs(_Fragment, { children: [_jsx("button", { disabled: phase !== "recording", onClick: () => active.current?.recorder?.stop(), children: phase === "recording" ? "Stop and transcribe" : phase === "starting" ? "Opening microphone…" : "Transcribing…" }), _jsx("button", { onClick: cancel, children: "Cancel dictation" })] }), error && _jsx("small", { role: "status", children: error })] });
+}

package/dist/feedback-types.d.ts

@@ -0,0 +1,122 @@
+export type FeedbackRect = {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
+export type FeedbackTarget = {
+    kind: "element" | "region" | "page";
+    label?: string;
+    selector?: string;
+    bounds?: FeedbackRect;
+    viewport?: {
+        width: number;
+        height: number;
+        scale: number;
+    };
+};
+export type FeedbackNoteInput = {
+    id: string;
+    text: string;
+    route: string;
+    capturedAt: string;
+    target?: FeedbackTarget;
+    image?: {
+        mediaType: string;
+        data: string;
+    };
+};
+export type FeedbackSubmit = {
+    requestId: string;
+    comment: string;
+    annotations: FeedbackNoteInput[];
+    scope?: {
+        coreId: string;
+        appId: string;
+        installation: string;
+        userId: string;
+    };
+};
+export type FeedbackCapabilities = {
+    version: 1;
+    coreId: string;
+    appId: string;
+    installation: string;
+    userId: string;
+    maxAnnotations: number;
+    maxImageBytes: number;
+    maxTotalImageBytes: number;
+    administrator?: boolean;
+};
+export type FeedbackNote = Omit<FeedbackNoteInput, "image"> & {
+    mediaType: string | null;
+};
+export type FeedbackReport = {
+    id: string;
+    reporterId: string;
+    comment: string;
+    annotations: FeedbackNote[];
+    context: {
+        appId: string;
+        appName: string;
+        installation: string;
+        version: string | null;
+        observedAt: string;
+        executionKind: string;
+        workspaceId: string | null;
+        sourceRevision: string | null;
+    };
+    workspaceId: string | null;
+    revision: number;
+    status: string;
+    currentAttemptId: string | null;
+    disposition: string | null;
+};
+export type FeedbackSelection = {
+    id: string;
+    revision: number;
+};
+export type FeedbackDispatchInput = {
+    requestId: string;
+    sessionId: string;
+    workspaceId: string | null;
+    reports: FeedbackSelection[];
+    instruction: string;
+    appContextRevision?: number;
+    selectionRevision?: number;
+};
+export type FeedbackOutcome = {
+    reportId: string;
+    summary: string;
+    handledAnnotationIds: string[];
+    handled: boolean;
+};
+export type FeedbackDispatch = {
+    id: string;
+    callerAppId: string;
+    callerInstallation: string;
+    actorId: string;
+    input: FeedbackDispatchInput;
+    snapshot: FeedbackReport[];
+    createdAt: string;
+    state: string;
+    messageSequence: number | null;
+    workspaceId: string | null;
+    outcomes: FeedbackOutcome[] | null;
+    error: string | null;
+};
+export type FeedbackCollection = {
+    reports: FeedbackReport[];
+    dispatches: FeedbackDispatch[];
+};
+export type FeedbackDelivery = {
+    state: string;
+    messageSequence?: number;
+    workspaceId?: string | null;
+    error?: string;
+};
+export declare class FeedbackError extends Error {
+    readonly code: string;
+    readonly status: number;
+    constructor(code: string, message: string, status: number);
+}

package/dist/feedback-types.js

@@ -0,0 +1,9 @@
+export class FeedbackError extends Error {
+    code;
+    status;
+    constructor(code, message, status) {
+        super(message);
+        this.code = code;
+        this.status = status;
+    }
+}

package/dist/ui-frame.js

@@ -137,5 +137,5 @@ export function HostyAppFrame(props) {
     const insecure = typeof window !== "undefined" && window.location.protocol === "https:" && new URL(surface.origin).protocol === "http:";
     if (insecure)
         return _jsxs("div", { "data-hosty-sdk": true, role: "status", className: "hosty-panel-notice", children: [_jsx(SdkChromeStyles, {}), _jsxs("strong", { children: [title, " needs HTTPS to appear here"] }), _jsx("p", { children: "This app publishes an HTTP address. Configure its public HTTPS origin in Hosty." }), /^(localhost|127\.|\[::1\])/.test(new URL(surface.origin).hostname) && _jsx("p", { children: "This local address is reachable only from the Hosty computer." }), standaloneHref && _jsx("a", { href: standaloneHref, target: "_blank", rel: "noopener noreferrer", children: "Open separately" })] });
-    return _jsxs(_Fragment, { children: [review && _jsxs(_Fragment, { children: [_jsx(SdkChromeStyles, {}), _jsx("a", { "data-hosty-sdk": true, className: "hosty-panel-review", href: review, target: "_blank", rel: "noopener noreferrer", children: "Review access in Core" })] }), _jsx("iframe", { ref: ref, className: className, title: title, src: launch, sandbox: frameSandbox(surface.framePolicy), allow: surface.framePolicy.microphone ? "clipboard-write; microphone 'src'" : "clipboard-write", style: { border: 0, height: "100%", width: "100%", colorScheme: resolvedTheme }, onLoad: () => setLoaded(true) })] });
+    return _jsxs(_Fragment, { children: [review && _jsxs(_Fragment, { children: [_jsx(SdkChromeStyles, {}), _jsx("a", { "data-hosty-sdk": true, className: "hosty-panel-review", href: review, target: "_blank", rel: "noopener noreferrer", children: "Review access in Core" })] }), _jsx("iframe", { ref: ref, className: className, title: title, src: launch, sandbox: frameSandbox(surface.framePolicy), allow: surface.framePolicy.microphone ? "clipboard-write; display-capture 'src'; microphone 'src'" : "clipboard-write; display-capture 'src'", style: { border: 0, height: "100%", width: "100%", colorScheme: resolvedTheme }, onLoad: () => setLoaded(true) })] });
 }

package/dist/ui-react.js

@@ -1,5 +1,6 @@
 "use client";
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { FeedbackCapture } from "./feedback-react.js";
 import { SdkChromeStyles, SdkIcon } from "./sdk-chrome.js";
 import { useContext, useEffect, useId, useLayoutEffect, useRef, useState, useSyncExternalStore } from "react";
 import { bindUiClient, ui } from "./ui.js";
@@ -53,7 +54,7 @@ export function HostyUiRoot({ children, uiPath, panelLayout = "auto", active = t
     if (allowed)
         mounted.current = true;
     const content = _jsxs("div", { className: "hosty-app-layout", children: [navigation?.renderer !== "custom" && _jsx(HostyNavigation, {}), _jsxs("div", { className: "hosty-app-content", "data-hosty-content": true, tabIndex: -1, children: [_jsx(HostyToolLauncher, {}), children] })] });
-    return _jsx(UiHostContext.Provider, { value: host, children: _jsx(UiCompositionContext.Provider, { value: clientRef.current?.composition ?? null, children: _jsxs(UiFrameLayerContext.Provider, { value: layer, children: [_jsx("style", { children: `.hosty-app-layout{display:flex;width:100%;height:100%;min-width:0;min-height:0}.hosty-app-content{flex:1;min-width:0;min-height:0;overflow:auto;outline:none}` }), _jsx("div", { hidden: !allowed, inert: !allowed, style: { display: allowed ? "contents" : "none" }, children: mounted.current && (panelLayout === "auto" && host ? _jsx(HostyPanelWorkspace, { children: content }) : content) }), !allowed && _jsxs("div", { "data-hosty-sdk": true, role: "status", className: "hosty-panel-notice", children: [_jsx(SdkChromeStyles, {}), environment?.connection === "blocked" ? _jsxs(_Fragment, { children: [_jsx("strong", { children: environment.code === "actor_mismatch" ? "Use the same Hosty account in this app and its host" : "Cannot verify this app’s host" }), _jsx("p", { children: "Check your account and access in Hosty Core, then reconnect. Your existing discussion is unchanged." }), _jsx("button", { type: "button", onClick: () => window.location.reload(), children: "Reconnect" })] }) : "Connecting to the workspace…"] }), host && _jsx(HostyPresentationLayer, { layer: layer, host: host, active: !!allowed })] }) }) });
+    return _jsx(UiHostContext.Provider, { value: host, children: _jsx(UiCompositionContext.Provider, { value: clientRef.current?.composition ?? null, children: _jsxs(UiFrameLayerContext.Provider, { value: layer, children: [_jsx("style", { children: `.hosty-app-layout{display:flex;width:100%;height:100%;min-width:0;min-height:0}.hosty-app-content{flex:1;min-width:0;min-height:0;overflow:auto;outline:none}` }), _jsx("div", { hidden: !allowed, inert: !allowed, style: { display: allowed ? "contents" : "none" }, children: mounted.current && (panelLayout === "auto" && host ? _jsx(HostyPanelWorkspace, { children: content }) : content) }), !allowed && _jsxs("div", { "data-hosty-sdk": true, role: "status", className: "hosty-panel-notice", children: [_jsx(SdkChromeStyles, {}), environment?.connection === "blocked" ? _jsxs(_Fragment, { children: [_jsx("strong", { children: environment.code === "actor_mismatch" ? "Use the same Hosty account in this app and its host" : "Cannot verify this app’s host" }), _jsx("p", { children: "Check your account and access in Hosty Core, then reconnect. Your existing discussion is unchanged." }), _jsx("button", { type: "button", onClick: () => window.location.reload(), children: "Reconnect" })] }) : "Connecting to the workspace…"] }), _jsx(FeedbackCapture, { active: active && !!allowed, uiPath: uiPath }), host && _jsx(HostyPresentationLayer, { layer: layer, host: host, active: !!allowed })] }) }) });
 }
 const empty = { bootstrap: null, catalog: [], tools: [], selected: null, expanded: false, width: 360, error: null };
 const noop = () => () => { };

package/dist/ui-server.js

@@ -1,3 +1,7 @@
+import { FeedbackServerClient } from "@hosty-sdk/app/feedback/server";
+import { FeedbackError } from "@hosty-sdk/app/feedback";
+import { ProviderClient } from "@hosty-sdk/app/providers/server";
+import { ProviderError } from "@hosty-sdk/app/providers";
 import { UiError } from "@hosty-sdk/app/ui/types";
 /** Server transport for generic UI metadata. Credentials never appear in returned metadata. */
 export class UiServerClient {
@@ -63,7 +67,38 @@ export async function createHostyUiResponse(request, context, options = {}) {
         const route = url.pathname.startsWith(prefix + "/") ? url.pathname.slice(prefix.length + 1) : "";
         const client = new UiServerClient(options);
         let result;
-        if (request.method === "GET" && route === "bootstrap") {
+        if (/^feedback\/[a-f0-9]{64}\/review-targets$/.test(route) && request.method === "GET") {
+            result = await new FeedbackServerClient(options).reviewTargets(route.split("/")[1], context.token, request.signal);
+        }
+        else if (route === "feedback/speech" && request.method === "GET") {
+            const speech = new ProviderClient(options), permissions = await speech.permissions(request.signal);
+            const granted = permissions.granted.includes("providers.speech-to-text");
+            result = { granted, providers: granted ? await speech.list("speech-to-text", request.signal) : [] };
+        }
+        else if (route === "feedback/speech" && request.method === "POST") {
+            if (!sameOrigin(request) || request.headers.get("content-type")?.split(";", 1)[0]?.trim() !== "application/json")
+                throw new UiError("origin_denied", "Dictate from this application page.", 403);
+            const speech = new ProviderClient(options), roster = await speech.list("speech-to-text", request.signal);
+            const input = JSON.parse(await boundedBody(request, 6 * 1024 * 1024));
+            if (!input || typeof input.appId !== "string" || typeof input.key !== "string" || typeof input.audio !== "string")
+                throw new UiError("speech_invalid", "Choose a speech provider and a recording.", 400);
+            if (!roster.some(p => p.appId === input.appId && p.key === input.key && p.available))
+                throw new UiError("speech_unavailable", "The selected speech provider is unavailable.", 409);
+            const bytes = Uint8Array.from(Buffer.from(input.audio, "base64"));
+            if (bytes.length < 44 || bytes.length > 120 * 16000 * 2 + 4096 || String.fromCharCode(...bytes.subarray(0, 4)) !== "RIFF" || String.fromCharCode(...bytes.subarray(8, 12)) !== "WAVE")
+                throw new UiError("speech_invalid", "Use a bounded WAV recording.", 400);
+            result = await speech.transcribe(input, new Blob([bytes], { type: "audio/wav" }), { signal: request.signal });
+        }
+        else if (route === "feedback" && request.method === "GET") {
+            result = await new FeedbackServerClient(options).capabilities(context.token, request.signal);
+        }
+        else if (route === "feedback" && request.method === "POST") {
+            if (!sameOrigin(request) || request.headers.get("content-type")?.split(";", 1)[0]?.trim() !== "application/json")
+                throw new UiError("origin_denied", "Submit feedback from this application page.", 403);
+            const body = await boundedBody(request, 12 * 1024 * 1024);
+            result = await new FeedbackServerClient(options).submit(JSON.parse(body), context.token, request.signal);
+        }
+        else if (request.method === "GET" && route === "bootstrap") {
             if ([...url.searchParams.keys()].some(k => k !== "parentOrigin") || url.searchParams.getAll("parentOrigin").length > 1)
                 throw new UiError("ui_request_invalid", "Invalid bootstrap request.", 400);
             result = await client.bootstrap({ parentOrigin: url.searchParams.get("parentOrigin") ?? undefined }, context.token, request.signal);
@@ -93,12 +128,12 @@ export async function createHostyUiResponse(request, context, options = {}) {
         return Response.json(result, { headers: responseHeaders });
     }
     catch (error) {
-        const known = error instanceof UiError;
+        const known = error instanceof UiError || error instanceof FeedbackError || error instanceof ProviderError;
         return Response.json({ code: known ? error.code : error instanceof SyntaxError ? "ui_request_invalid" : "ui_unavailable",
             message: known ? error.message : "Application panels are unavailable. Retry opening the same target." }, { status: known ? error.status : error instanceof SyntaxError ? 400 : 503, headers: responseHeaders });
     }
 }
-async function boundedBody(request) {
+async function boundedBody(request, limit = 16_384) {
     const reader = request.body?.getReader();
     if (!reader)
         return "";
@@ -110,7 +145,7 @@ async function boundedBody(request) {
             if (done)
                 break;
             length += value.byteLength;
-            if (length > 16_384) {
+            if (length > limit) {
                 await reader.cancel();
                 throw new UiError("ui_request_invalid", "Panel request is too large.", 413);
             }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hosty-sdk/app",
-  "version": "0.37.0",
+  "version": "0.38.0",
   "description": "Hosty app auth: session state machine, recovery bridge, Core revalidation, and the embedder responder.",
   "license": "AGPL-3.0-only",
   "type": "module",
@@ -140,6 +140,14 @@
     "./tasks/server": {
       "types": "./dist/tasks-server.d.ts",
       "default": "./dist/tasks-server.js"
+    },
+    "./feedback": {
+      "types": "./dist/feedback-types.d.ts",
+      "default": "./dist/feedback-types.js"
+    },
+    "./feedback/server": {
+      "types": "./dist/feedback-server.d.ts",
+      "default": "./dist/feedback-server.js"
     }
   },
   "scripts": {