@devaccel-labs/app-comments-toolbar 1.1.0 → 1.3.0

package/dist/types/runtime/api.d.ts

@@ -0,0 +1,250 @@
+/**
+ * The comment service's HTTP API: wire types and request functions. DOM-free, so native clients
+ * (`@devaccel-labs/app-comments-native`) share it; `./client.ts` re-exports it with the browser-only sign-in
+ * relay and storage helpers.
+ */
+import type { Anchor } from "../core/index.js";
+import type { ClarityDraft, ClarityMode } from "./clarity-model.js";
+import type { ReportKind } from "./kind-model.js";
+import { type Session } from "./session-source.js";
+import type { TicketDraft, TicketForm } from "./ticket-form-model.js";
+export type Mentioned = {
+    id: string;
+    name: string;
+};
+/** Where a page screenshot was taken. */
+export type Capture = {
+    url: string;
+    viewport?: {
+        width: number;
+        height: number;
+    };
+    browser?: string;
+};
+export type Attachment = {
+    id: string;
+    name: string;
+    contentType: string;
+    size: number;
+    url: string;
+    capture?: Capture;
+};
+/** An earlier version of a message. `createdAt` is when that version was written. */
+export type Revision = {
+    body: string;
+    mentions?: Mentioned[];
+    createdAt: string;
+};
+export type CommentMessage = {
+    id: string;
+    body: string;
+    author: string;
+    /** Missing on messages written before author ids were stored. */
+    authorId?: string | null;
+    createdAt: string;
+    editedAt?: string | null;
+    mentions?: Mentioned[];
+    attachments?: Attachment[];
+    /** Earlier versions, oldest first. The current body is the version after the last one. */
+    revisions?: Revision[];
+};
+export type Member = {
+    id: string;
+    name: string;
+    email: string;
+};
+export type Delivery = {
+    emailed: Mentioned[];
+    skipped: Array<Mentioned & {
+        reason: "rate_limited" | "muted" | "disabled" | string;
+    }>;
+};
+export type Profile = {
+    name: string;
+    email: string | null;
+    mentionEmails: boolean;
+};
+export type PostExtras = {
+    mentions?: string[];
+    screenshot?: string | null;
+    attachments?: string[];
+};
+export type FieldDef = {
+    id: string;
+    label: string;
+};
+export type FieldValue = FieldDef & {
+    value: string;
+};
+export type Settings = {
+    roles: {
+        enabled: boolean;
+        options: string[];
+    };
+    fields: {
+        enabled: boolean;
+        items: FieldDef[];
+    };
+};
+/** Role and custom field values for a new or edited comment, keyed by field id. */
+export type Details = {
+    role: string | null;
+    fields: Record<string, string>;
+};
+export type Thread = {
+    id: string;
+    /** The environment the comment was left in. Differs from the session's for comments from a linked environment. */
+    environment?: string;
+    route: string;
+    /** The page the comment was left on, including query and hash. */
+    url: string;
+    role: string | null;
+    fields: FieldValue[];
+    anchor: Anchor;
+    status: "open" | "resolved";
+    createdBy: string;
+    createdAt: string;
+    updatedAt: string;
+    messages: CommentMessage[];
+    /** Set when the team turned this comment into a ticket in their tracker. */
+    ticket?: TicketBadge;
+};
+/** A comment's support ticket, as the commenter sees it: number and status only. */
+export type TicketBadge = {
+    number: string;
+    status: string;
+    label: string;
+};
+export declare class ApiError extends Error {
+    readonly status: number;
+    readonly code: string;
+    constructor(status: number, code: string, message: string);
+}
+export declare function storageKey(session: Pick<Session, "apiUrl" | "project" | "environment">): string;
+/**
+ * Where a client keeps its member token, keyed by `storageKey(session)`. The web toolbar keeps it in the page's
+ * `localStorage` itself; native clients pass the device keychain.
+ */
+export type MemberTokenStore = {
+    read(key: string): Promise<string | null>;
+    write(key: string, token: string): Promise<void>;
+    remove(key: string): Promise<void>;
+};
+/** The stored member token for `session`, or null when there is none or it has expired. */
+export declare function readMemberToken(session: Pick<Session, "apiUrl" | "project" | "environment">, store: MemberTokenStore): Promise<string | null>;
+export declare function memberIsCurrent(token: string): boolean;
+/**
+ * How people can sign in here: through the service's identity connection, or not at all. Passphrase sign-in is
+ * gone. The wire keeps the connection under `msf`, its name from before.
+ */
+export type SignInOptions = {
+    passphrase: false;
+    /** `label` names the account to sign in with; "your account" when the service names none. */
+    msf: {
+        authorizeUrl: string;
+        label: string;
+    } | null;
+    /** The options request failed. */
+    unavailable?: boolean;
+    /** The status it failed with, when the service answered. */
+    status?: number;
+};
+export declare function signInOptions(session: Session): Promise<SignInOptions>;
+/** Base64url without padding, as OAuth PKCE wants for the state, verifier and challenge. */
+export declare function base64Url(bytes: Uint8Array): string;
+/**
+ * The identity connection's authorize URL for an OAuth 2.0 request with PKCE (S256). The sign-in callback sends the code
+ * back to `returnTo` (a page of this app, without a hash, or a native app's `<scheme>://app/app-comments/auth`).
+ */
+export declare function msfAuthorizeUrl(authorizeUrl: string, returnTo: string, state: string, challenge: string): string;
+/** Trades the authorization code for a member token. */
+export declare function finishMsfSignIn(session: Session, input: {
+    state: string;
+    verifier: string;
+    code: string;
+}): Promise<string>;
+/** What the sign-in window hands back to the app (a code, or an error such as access_denied). */
+export type MsfHandoff = {
+    state: string;
+    code?: string;
+    error?: string;
+    at: number;
+};
+/** The sign-in result the callback puts in the return address's hash (`cs-msf-state`, `cs-msf-code`, `cs-msf-error`). */
+export declare function msfHandoffFrom(hash: string, at?: number): MsfHandoff | null;
+export declare function createInvite(session: Session, memberToken: string): Promise<{
+    invite: string;
+    invitedBy: string;
+    expiresAt: string;
+}>;
+export declare function getProfile(session: Session, memberToken: string): Promise<Profile>;
+export declare function updateProfile(session: Session, memberToken: string, patch: {
+    displayName?: string;
+    email?: string;
+    mentionEmails?: boolean;
+}): Promise<Profile & {
+    token: string;
+}>;
+export declare function uploadAttachment(session: Session, memberToken: string, file: Blob, name: string, environment?: string, capture?: Capture, 
+/** The image was drawn on in the markup editor; the comment service shows it to the title model first. */
+markedUp?: boolean): Promise<Attachment>;
+/**
+ * One dictated piece to text, sent as its blob's type (`audio/wav`, `audio/mp4`, `audio/x-m4a`; WAV when the
+ * blob is untyped). `prompt` is the writing just before it, for continuity.
+ */
+export declare function transcribeAudio(session: Session, memberToken: string, audio: Blob, prompt: string, signal: AbortSignal, environment?: string): Promise<string>;
+export declare function listMembers(session: Session, memberToken: string, environment?: string): Promise<Member[]>;
+/** "view": this person may read but not comment. Older services don't send it, which means "edit". */
+export type Access = "edit" | "view";
+export declare function listThreads(session: Session, memberToken: string): Promise<{
+    threads: Thread[];
+    settings: Settings;
+    environment?: string | null;
+    linked?: string[];
+    access?: Access;
+    /** Set by the project's people settings. A tester comments with the ticket form. */
+    memberType?: "client" | "tester";
+    /**
+     * Whether this environment checks a new comment before it is posted (`./clarity-model.ts`). A service
+     * that predates the check doesn't send it, and is never asked to check.
+     */
+    clarity?: ClarityMode;
+}>;
+/**
+ * Asks whether a comment that has not been posted yet says enough for a reader to act on. Resolves with the
+ * service's answer as it came (`readClarityResponse` reads it) and rejects on any other status; the caller
+ * posts the comment either way (`askClarity`).
+ */
+export declare function checkClarity(session: Session, memberToken: string, draft: ClarityDraft, signal?: AbortSignal): Promise<unknown>;
+/** The tracker's ticket form, for testers only. */
+export declare function fetchTicketForm(session: Session, memberToken: string): Promise<TicketForm>;
+/** A socket that says "changed" whenever comments change in this environment or one it links to. */
+export declare function openLive(session: Session, memberToken: string): WebSocket;
+export declare function saveSettings(session: Session, memberToken: string, settings: Settings): Promise<Settings>;
+export declare function createThread(session: Session, memberToken: string, anchor: Anchor, body: string, extras?: PostExtras & Partial<Details> & {
+    url?: string;
+    ticket?: TicketDraft;
+    kind?: ReportKind;
+}): Promise<{
+    thread: Thread;
+    delivery?: Delivery;
+}>;
+export declare function replyToThread(session: Session, memberToken: string, threadId: string, body: string, extras?: PostExtras): Promise<{
+    message: CommentMessage;
+    delivery?: Delivery;
+}>;
+export declare function updateThread(session: Session, memberToken: string, threadId: string, patch: {
+    status?: "open" | "resolved";
+    anchor?: Anchor;
+    url?: string;
+} & Partial<Details>): Promise<{
+    id: string;
+}>;
+export declare function editMessage(session: Session, memberToken: string, threadId: string, messageId: string, body: string, mentions: string[]): Promise<{
+    message: {
+        id: string;
+        body: string;
+        editedAt: string | null;
+    };
+    delivery: Delivery | null;
+}>;

package/dist/types/runtime/attachment-model.d.ts

@@ -0,0 +1,16 @@
+/** How attachments are limited, named and described. DOM-free, so native clients share it. */
+/** Largest file one message may carry. */
+export declare const ATTACHMENT_MAX_BYTES: number;
+/** Most files one message may carry. */
+export declare const ATTACHMENT_MAX_FILES = 5;
+/** The file types a message may carry (the file picker's `accept` list). */
+export declare const ATTACHMENT_TYPES: readonly string[];
+/** `2026-10-31-13-56-37` (UTC): the stamp in `recording-…`, `replay-…` and other attachment names. */
+export declare function attachmentStamp(at: number | Date): string;
+/** `512 B`, `40 KB`, `2.4 MB`. */
+export declare function formatSize(bytes: number): string;
+/** A `replay-*.json` activity file (an instant replay or a clip's timeline). */
+export declare function isReplayFile(file: {
+    name: string;
+    contentType: string;
+}): boolean;

package/dist/types/runtime/attachments.d.ts

@@ -1,6 +1,16 @@
-import { type ClipboardEvent } from "react";
+import { type ButtonHTMLAttributes, type ClipboardEvent } from "react";
 import { type Attachment, type Capture } from "./client.js";
+import type { MarkupShape } from "./markup.js";
+import { type MarkupResult } from "./markup-editor.js";
 import type { Session } from "./session.js";
+export { ATTACHMENT_MAX_BYTES, formatSize, isReplayFile } from "./attachment-model.js";
+/** The file an image was marked up from, so markup stays editable until the message is sent. */
+export type MarkupSource = {
+    blob: Blob;
+    url: string;
+    name: string;
+    shapes: MarkupShape[];
+};
 export type Pending = {
     key: string;
     name: string;
@@ -8,11 +18,12 @@ export type Pending = {
     contentType: string;
     preview: string | null;
     status: "uploading" | "ready" | "failed";
+    blob: Blob;
     id?: string;
     error?: string;
-    capture?: Capture;
+    capture?: Capture | undefined;
+    markup?: MarkupSource | undefined;
 };
-export declare function formatSize(bytes: number): string;
 /** Files attached to one draft. Each upload starts immediately so posting doesn't wait on the network. */
 export declare function useAttachments(session: Session | null, memberToken: string | null, onError: (message: string) => void, environment?: string): {
     items: Pending[];
@@ -20,9 +31,22 @@ export declare function useAttachments(session: Session | null, memberToken: str
         blob: Blob;
         name: string;
         capture?: Capture;
-    }>) => void;
+    }>) => string[];
+    replace: (key: string, result: MarkupResult) => string | null;
     remove: (key: string) => void;
     reset: () => void;
+    restore: (files: Array<{
+        key: string;
+        blob: Blob;
+        name: string;
+        capture?: Capture | undefined;
+        markup?: {
+            blob: Blob;
+            name: string;
+            shapes: MarkupShape[];
+        } | undefined;
+    }>) => void;
+    settled: () => Promise<Pending[]>;
     ids: string[];
     uploading: boolean;
 };
@@ -35,7 +59,13 @@ export type PreviewFile = {
     name: string;
     contentType: string;
     url: string;
-    capture?: Capture;
+    capture?: Capture | undefined;
+    /** A draft image's unmarked original and its markup, for the editor. */
+    markup?: {
+        src: string;
+        name: string;
+        shapes: MarkupShape[];
+    } | undefined;
 };
 /** Images, videos, and replays waiting in a draft, in tray order, for the preview beside the composer. */
 export declare function pendingPreviews(items: Pending[]): PreviewFile[];
@@ -45,6 +75,7 @@ export declare function AttachmentTray({ items, activeKey, onPreview, onRemove,
     onPreview?: (item: Pending) => void;
     onRemove: (key: string) => void;
 }): import("react/jsx-runtime").JSX.Element | null;
+export declare function AttachButton({ onPointerDown, onPointerLeave, ...props }: ButtonHTMLAttributes<HTMLButtonElement>): import("react/jsx-runtime").JSX.Element;
 export declare function AttachButtons({ onFiles, onSnapshot, onRecord, onReplay, capturing, }: {
     onFiles: (files: Array<{
         blob: Blob;
@@ -64,10 +95,15 @@ export declare function MessageAttachments({ attachments, activeId, onPreview, }
     activeId?: string | null;
     onPreview: (file: Attachment) => void;
 }): import("react/jsx-runtime").JSX.Element | null;
-/** The image, video, or replay open beside a thread. Arrows walk the thread's other previewable files. */
-export declare function MediaPane({ files, fileId, onSelect, onClose, }: {
+/**
+ * The image, video, or replay open beside a thread. Arrows walk the thread's other previewable files. With
+ * `onMarkup`, a draft image can be marked up; `onMarkingUp` hears when the editor opens and closes.
+ */
+export declare function MediaPane({ files, fileId, onSelect, onClose, onMarkup, onMarkingUp, }: {
     files: PreviewFile[];
     fileId: string;
     onSelect: (fileId: string) => void;
     onClose: () => void;
+    onMarkup?: (fileId: string, result: MarkupResult) => void;
+    onMarkingUp?: (open: boolean) => void;
 }): import("react/jsx-runtime").JSX.Element | null;

package/dist/types/runtime/boot.d.ts

@@ -0,0 +1,39 @@
+import type { RuntimeProps, ToolbarHandle } from "./runtime.js";
+import type { Session } from "./session-source.js";
+export type Runtime = {
+    mount(container: HTMLElement, props: RuntimeProps): ToolbarHandle;
+};
+/** The session request waits for the page to go idle, but no longer than this after the loader starts. */
+export declare const IDLE_TIMEOUT_MS = 3000;
+/** Runs `task` later and returns a function that cancels it. */
+export type Wait = (task: () => void) => () => void;
+declare const importModule: (url: string) => Promise<unknown>;
+/**
+ * The toolbar always comes from the App comments worker, never from the host's own bundle: every deploy of the
+ * service serves the new build, open toolbars swap to it on their own, and a host never needs an update for it.
+ */
+export declare function loadRuntime(apiUrl: string, load?: typeof importModule): Promise<Runtime>;
+export type Boot = {
+    /** Asks the session route, or reuses its kept answer. Null, or a rejection, means no toolbar. */
+    getSession: () => Promise<Session | null>;
+    /** Read when the toolbar mounts, so it starts with the host's latest props. */
+    props: () => RuntimeProps;
+    /** Called once the toolbar is mounted, with its handle and the element it is mounted in. */
+    onMount?: (handle: ToolbarHandle, container: HTMLElement) => void;
+    /** Called when this attempt is over: the toolbar is mounted, or it will not be. */
+    onSettled?: () => void;
+    /** When to start. Default: when the page is idle, or after IDLE_TIMEOUT_MS at the latest. */
+    wait?: Wait;
+    /** Where the runtime comes from. Default: `loadRuntime`. */
+    load?: (apiUrl: string) => Promise<Runtime>;
+};
+/**
+ * One attempt to bring the toolbar up. Does nothing until `wait` runs it; then asks for the session once, and
+ * only when comments are on loads the runtime and mounts it in a new `<div data-cs-runtime="latest">` at the
+ * end of `<body>`.
+ *
+ * Returns `stop`: before the mount it calls the attempt off, after it it unmounts the toolbar and removes the
+ * element.
+ */
+export declare function bootToolbar(boot: Boot): () => void;
+export {};

package/dist/types/runtime/browser-label.d.ts

@@ -0,0 +1,5 @@
+/** "Chrome 142" from a user agent, or undefined. Only the name and major version: never the full string. */
+export declare function browserName(agent: string): string | undefined;
+export declare function systemName(agent: string): string | undefined;
+/** "Chrome 142 · macOS", or undefined when neither is known. */
+export declare function browserLabel(agent: string): string | undefined;

package/dist/types/runtime/build-id.d.ts

@@ -2,5 +2,6 @@
  * Identifies this build of the runtime. `scripts/app-comments/build-toolbar.mjs` defines it from a hash of the
  * runtime's source and writes the same value to `/v1/toolbar/build.json` next to the bundle, so a running toolbar
  * can tell when the worker started serving a newer build. "dev" when the bundle was built without it (tests).
+ * Any change under src/runtime or src/core changes the id, so every deploy that touches the toolbar is announced.
  */
 export declare const runtimeBuild: string;

package/dist/types/runtime/capture-ui.d.ts

@@ -4,32 +4,56 @@ type AddFiles = (files: Array<{
     name: string;
     capture?: Capture;
 }>) => void;
-/** Records the current tab, then asks before the file is attached. Nothing is uploaded here. */
-export declare function useTabRecording(onError: (message: string) => void): {
-    phase: "idle" | "recording" | "review";
-    elapsed: number;
-    review: {
-        url: string;
+/** What a take tells the world while it runs, and what goes with the file when it is kept. */
+export type RecordingExtras = {
+    /** Every chunk as it lands (see `RecordOptions.onChunk`). */
+    onChunk?: (chunk: Blob, index: number, mime: string) => void;
+    /** Files to attach beside the recording, named after the same stamp (a replay of what happened in it). */
+    companions?: (info: {
+        stamp: string;
+        startedAt: number;
+        durationMs: number;
+        name: string;
+    }) => Array<{
         blob: Blob;
-    } | null;
-    tooBig: boolean;
-    begin: (add: AddFiles) => Promise<void>;
+        name: string;
+    }>;
+};
+/**
+ * The recording's sound: `on` and `muted` while the mic is in the take, `off` when the person chose no sound,
+ * `refused` when they wanted it but the mic wasn't given.
+ */
+export type RecordingSound = "on" | "muted" | "off" | "refused";
+/**
+ * Records the current tab and attaches the file to the draft as soon as it stops. Nothing is uploaded here. `sound` is the
+ * person's saved choice to record the mic; `onSoundChange` saves a new one.
+ */
+export declare function useTabRecording(onError: (message: string) => void, sound: boolean, onSoundChange: (sound: boolean) => void): {
+    phase: "idle" | "recording";
+    elapsed: number;
+    sound: RecordingSound;
+    /** What the next recording will do about sound. */
+    soundNext: boolean;
+    toggleSound: () => void;
+    begin: (add: AddFiles, more?: RecordingExtras) => Promise<void>;
     stop: () => void | undefined;
     cancel: () => void;
-    keep: () => void;
-    again: () => void;
 };
-export declare function RecordChrome({ phase, elapsed, review, tooBig, onStop, onCancel, onKeep, onAgain, }: {
-    phase: "recording" | "review";
+/** Dictation into the comment the recording belongs to, driven from the record bar. */
+export type RecordDictation = {
+    listening: boolean;
+    /** Pieces still being written. */
+    queued: number;
+    toggle: () => void;
+};
+export declare function RecordChrome({ elapsed, sound, soundNext, dictation, onToggleSound, onStop, onCancel, }: {
     elapsed: number;
-    review: {
-        url: string;
-        blob: Blob;
-    } | null;
-    tooBig: boolean;
+    sound: RecordingSound;
+    soundNext: boolean;
+    /** Absent when there is no comment box to type into. */
+    dictation?: RecordDictation;
+    onToggleSound: () => void;
     onStop: () => void;
     onCancel: () => void;
-    onKeep: () => void;
-    onAgain: () => void;
-}): import("react/jsx-runtime").JSX.Element | null;
+}): import("react/jsx-runtime").JSX.Element;
 export {};