@hosty-sdk/app 0.37.0 → 0.39.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/agent-sessions.d.ts

@@ -0,0 +1,73 @@
+/** Local-to-Core identities. Never infer an app, conversation, native session or run from another ID. */
+export type ProviderRef = {
+    appId: string;
+    installationId: string;
+    key: string;
+};
+export type ConversationRef = {
+    provider: ProviderRef;
+    id: string;
+};
+export type NativeSessionRef = {
+    provider: ProviderRef;
+    id: string;
+};
+export type RunRef = {
+    provider: ProviderRef;
+    id: string;
+};
+/** Decimal strings avoid integer truncation across language boundaries. */
+export type Revision = string;
+export type AgentSession = {
+    ref: NativeSessionRef;
+    revision: Revision;
+    activeRuns: RunRef[];
+    capabilities: string[];
+    conversation?: ConversationRef | null;
+};
+export type AgentRun = {
+    ref: RunRef;
+    revision: Revision;
+    state: "queued" | "running" | "waiting_for_input" | "succeeded" | "failed" | "cancelled" | "unknown";
+    observedAt: string;
+    freshness: "current" | "last_known" | "unavailable";
+    stopConfirmed: boolean;
+    nativeSession?: NativeSessionRef | null;
+    conversation?: ConversationRef | null;
+};
+export type AgentSessionPage = {
+    sessions: AgentSession[];
+    nextCursor: string | null;
+    availability: "available" | "partial" | "unavailable";
+    observedAt: string;
+};
+export type AgentSessionQuery = {
+    provider: ProviderRef;
+    conversation?: ConversationRef;
+    cursor?: string;
+    limit?: number;
+};
+export type RunCancel = {
+    run: RunRef;
+    requestId: string;
+    expectedRevision: Revision;
+};
+export type RunCancelReceipt = {
+    requestId: string;
+    state: "accepted" | "completed";
+    run: AgentRun;
+};
+export type AgentRunNotification = {
+    run: AgentRun;
+    cursor: string;
+    rescanRequired: boolean;
+};
+export type AgentRunSubscription = {
+    handle: string;
+    expiresAt: string;
+    initial: AgentRunNotification;
+};
+export type AgentRunSubscriptionCreate = {
+    run: RunRef;
+    cursor?: string;
+};

package/dist/agent-sessions.js

@@ -0,0 +1 @@
+export {};

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;