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

package/src/help/types.ts

@@ -0,0 +1,124 @@
+/**
+ * "Need help?": the pill a host shows every signed-in person, and the panel it opens. The person writes what
+ * they need, may add pictures of the page, and sends; the host records the request wherever it keeps them
+ * (`submit`) and may show the person what they have sent (`list`). Nothing here signs in to the comment
+ * toolbar or calls Comment Tool: the two hooks are the host's own.
+ */
+
+export type HelpTheme = "light" | "dark" | "auto";
+export type HelpPosition = "bottom-right" | "bottom-left";
+
+/** A picture as the capture script returns it (`../capture/picture.ts`). */
+export type HelpImage = {
+  blob: Blob;
+  name: string;
+  width: number;
+  height: number;
+  markedUp: boolean;
+};
+
+export type HelpRequest = {
+  /** Made once per request and sent again unchanged on a retry, so a host can make it safe to repeat. */
+  id: string;
+  /** 1 to 4,000 characters. */
+  message: string;
+  /** The page's address, with anything that looks like a credential in its query taken out. */
+  pageUrl: string;
+  /** The page's path. */
+  route: string;
+  /** What the person pointed at, when they did. */
+  pointed: { label: string } | null;
+  /** At most 3 pictures. */
+  images: readonly HelpImage[];
+  client: { userAgent: string; language: string; viewport: { width: number; height: number } };
+};
+
+export type HelpReceipt = {
+  /** The request's number in the host's words. Given, the person reads "Request I00042 received." */
+  reference?: string;
+  /** Where the request opens in the host, when it has such a page. `http:` or `https:` only. */
+  url?: string;
+  /** One more plain sentence for the person: "1 picture could not be kept." */
+  note?: string;
+};
+
+export type SubmittedRequestStatus = "received" | "in_progress" | "resolved";
+
+export type SubmittedRequest = {
+  id: string;
+  reference?: string;
+  /** The person's own first words. */
+  summary: string;
+  /** ISO-8601. */
+  createdAt: string;
+  status: SubmittedRequestStatus;
+  /** The host's own word for the status, shown in place of ours when given. */
+  statusLabel?: string;
+  /**
+   * True when the team already tracks this issue in another request and has merged this one into it. The
+   * person is told so, and `status` and `statusLabel` are then where that other request stands. Give
+   * nothing else of the other request: it may be somebody else's.
+   */
+  consolidated?: boolean;
+  /** Where the request opens in the host, when it has such a page. `http:` or `https:` only. */
+  url?: string;
+};
+
+export type HelpOptions = {
+  /**
+   * Records the request wherever the host keeps them. Rejecting shows the person a failure and keeps their
+   * draft. A rejection that is a `HelpError` (or any error named "HelpError") shows its own message; any
+   * other shows one fixed sentence, because an exception's text is not written for the person.
+   */
+  submit(request: HelpRequest): Promise<HelpReceipt>;
+  /** What this person has submitted. Given, the panel has "Your requests". */
+  list?(): Promise<readonly SubmittedRequest[]>;
+  /** Default "Need help?". */
+  label?: string;
+  /** Default "bottom-right". */
+  position?: HelpPosition;
+  /** Default "auto": the system's light or dark setting. */
+  theme?: HelpTheme;
+  /**
+   * Whether pictures are offered right now. A host turns them off on screens that must not be pictured.
+   * Default true. A function is asked each time the panel is drawn and again when a picture is asked for.
+   */
+  captures?: boolean | (() => boolean);
+  /** Where "More options" leads when the host has a fuller form; it is given the text typed so far. */
+  moreOptions?: (draft: { message: string }) => void;
+};
+
+export type HelpHandle = { open(): void; close(): void; unmount(): void };
+
+/** `submit` and `list` over one same-origin route (`./requests.ts`, `../server/support.ts`). */
+export type SupportRequests = {
+  submit(request: HelpRequest): Promise<HelpReceipt>;
+  list(): Promise<readonly SubmittedRequest[]>;
+};
+
+export type CommentToolHelpApi = {
+  /** Shows the pill. Calling it again replaces the options; the pill, an open panel and a draft stay. */
+  mount(options: HelpOptions): HelpHandle;
+  /** The two hooks for a host whose server route is `handleSupportRequest`. */
+  supportRequestsAt(url: string): SupportRequests;
+  /** A failure whose message is written for the person. */
+  HelpError: typeof HelpError;
+};
+
+/**
+ * A failure whose message is one plain sentence for the person who pressed Send. The panel shows it as it
+ * is. Recognised by its name, not its class, so one thrown by the package is known to the script and back.
+ */
+export class HelpError extends Error {
+  override readonly name = "HelpError";
+}
+
+export function isHelpError(error: unknown): error is Error {
+  return (
+    typeof error === "object" &&
+    error !== null &&
+    (error as { name?: unknown }).name === "HelpError" &&
+    typeof (error as { message?: unknown }).message === "string" &&
+    (error as { message: string }).message.trim().length > 0
+  );
+}

package/src/help/wire.ts

@@ -0,0 +1,55 @@
+/**
+ * A help request as it travels from the browser to the host's own route (`./requests.ts` writes it,
+ * `../server/support.ts` reads it): JSON, with each picture's bytes as base64. No DOM and no server API
+ * here, so both sides import it.
+ */
+
+export const HELP_LIMITS = {
+  /** A request's own id: letters, digits, `.`, `_`, `:` and `-`. */
+  id: 100,
+  message: 4000,
+  images: 3,
+  /** One picture, before base64. */
+  imageBytes: 5 * 1024 * 1024,
+  name: 200,
+  label: 200,
+  url: 1000,
+  /** "Your requests" shows at most this many. */
+  listed: 50,
+} as const;
+
+/** The whole body: three pictures as base64, the text, and room for the rest. */
+export const HELP_BODY_BYTES =
+  Math.ceil((HELP_LIMITS.images * HELP_LIMITS.imageBytes * 4) / 3) + 256 * 1024;
+
+export const HELP_ID = /^[A-Za-z0-9._:-]+$/;
+
+/** The picture types a request may carry. Checked on the server against each file's first bytes. */
+export const HELP_IMAGE_TYPES = ["image/png", "image/jpeg", "image/webp"] as const;
+export type HelpImageType = (typeof HELP_IMAGE_TYPES)[number];
+
+export type HelpImageWire = {
+  name: string;
+  contentType: string;
+  width: number;
+  height: number;
+  markedUp: boolean;
+  /** The file's bytes, base64. */
+  data: string;
+};
+
+export type HelpRequestWire = {
+  id: string;
+  message: string;
+  pageUrl: string;
+  route: string;
+  pointed: { label: string } | null;
+  images: readonly HelpImageWire[];
+  client: { userAgent: string; language: string; viewport: { width: number; height: number } };
+};
+
+/** What the route answers a `POST` with. */
+export type HelpReceiptWire = { reference?: string; url?: string; note?: string };
+
+/** What the route answers when it refuses or fails: one plain sentence. */
+export type HelpFailureWire = { error: string };

package/src/native-wire.ts

@@ -0,0 +1,124 @@
+/**
+ * The wire contract between native (iOS / Android) comment clients and the App comments service.
+ *
+ * One owner for the worker, the host session route, a connection's own workspace and
+ * `@devaccel-labs/app-comments-native`. DOM-free and dependency-free.
+ *
+ * A native app has no web origin. It identifies itself with an app origin, `<scheme>://app`, where `<scheme>`
+ * is one of the environment's `appSchemes` (for example `my-app-staging`). It sends that value in the
+ * `x-comment-service-origin` header and never sends `Origin`. Browsers always send `Origin` on cross-origin
+ * requests, so a web page can never take the app-origin path. Native threads store their screen as an app URL,
+ * `<scheme>://app/<route>`, so `url` pathname still equals `route`.
+ */
+
+/** Which client wrote a comment. Web clients may omit it; the service treats a missing value as `web`. */
+export type ClientPlatform = "web" | "ios" | "android";
+
+/** Device and build facts a native client sends with a new thread (`POST /v1/threads` body `client`). */
+export type ClientInfo = {
+  platform: ClientPlatform;
+  /** The host app's build variant, e.g. `staging`, `staging2`. */
+  appVariant?: string | null;
+  /** Marketing version, e.g. `0.6.9`. */
+  appVersion?: string | null;
+  /** Build number, e.g. `123`. */
+  build?: string | null;
+  /** OS name and version, e.g. `iOS 26.1`, `Android 16`. */
+  os?: string | null;
+  /** Device model, e.g. `iPhone 17 Pro`, `Pixel 10`. */
+  device?: string | null;
+};
+
+/** Header a native client sends instead of `Origin`. */
+export const APP_ORIGIN_HEADER = "x-comment-service-origin";
+
+/** The host the app origin uses: `<scheme>://app`. */
+export const APP_ORIGIN_HOST = "app";
+
+/** Most schemes an environment may list. */
+export const MAX_APP_SCHEMES = 10;
+
+const SCHEME = /^[a-z][a-z0-9+.-]{1,39}$/;
+const RESERVED = new Set([
+  "http",
+  "https",
+  "ws",
+  "wss",
+  "file",
+  "data",
+  "blob",
+  "javascript",
+  "vbscript",
+  "about",
+  "mailto",
+  "tel",
+  "sms",
+  "intent",
+  "content",
+  "chrome",
+  "chrome-extension",
+]);
+
+/** Whether `value` is a scheme an environment may list (lowercase, no `:`, not a web or system scheme). */
+export function isAppScheme(value: string): boolean {
+  return SCHEME.test(value) && !RESERVED.has(value);
+}
+
+/** A list of app schemes as typed (trimmed, lowercased, deduped), or what is wrong with it. */
+export function normalizeAppSchemes(
+  value: unknown,
+):
+  | { readonly ok: true; readonly schemes: string[] }
+  | { readonly ok: false; readonly message: string } {
+  if (!Array.isArray(value)) return { ok: false, message: "App schemes must be a list." };
+  const schemes: string[] = [];
+  for (const item of value) {
+    if (typeof item !== "string") return { ok: false, message: "Each app scheme must be text." };
+    const scheme = item.trim().toLowerCase();
+    if (!isAppScheme(scheme))
+      return {
+        ok: false,
+        message: `Not an app scheme: ${item}. Use lowercase letters, numbers and hyphens, like my-app-staging.`,
+      };
+    if (!schemes.includes(scheme)) schemes.push(scheme);
+  }
+  if (schemes.length > MAX_APP_SCHEMES)
+    return { ok: false, message: `Add up to ${MAX_APP_SCHEMES} app schemes.` };
+  return { ok: true, schemes };
+}
+
+/** `my-app-staging` → `my-app-staging://app`. */
+export function appOrigin(scheme: string): string {
+  return `${scheme}://${APP_ORIGIN_HOST}`;
+}
+
+/**
+ * The scheme of an app origin (`<scheme>://app`, nothing after it), or null. Does not check the environment's
+ * list; callers compare the scheme with `appSchemes`.
+ */
+export function appOriginScheme(value: string): string | null {
+  const match = /^([a-z][a-z0-9+.-]{1,39}):\/\/app$/.exec(value);
+  const scheme = match?.[1];
+  return scheme && isAppScheme(scheme) ? scheme : null;
+}
+
+/** The app URL a native thread stores: `<scheme>://app` + route. `route` starts with `/`. */
+export function appScreenUrl(scheme: string, route: string): string {
+  return `${appOrigin(scheme)}${route.startsWith("/") ? route : `/${route}`}`;
+}
+
+/**
+ * Splits an app URL (`<scheme>://app/<path>?<query>`) into its scheme and pathname, or null when it is not one.
+ * `new URL()` gives `origin === "null"` for non-special schemes, so callers use this instead.
+ */
+export function parseAppUrl(value: string): { scheme: string; pathname: string } | null {
+  const match = /^([a-z][a-z0-9+.-]{1,39}):\/\/app(\/[^?#]*)?(?:[?#].*)?$/.exec(value);
+  const scheme = match?.[1];
+  if (!scheme || !isAppScheme(scheme)) return null;
+  return { scheme, pathname: match[2] ?? "/" };
+}
+
+/** Where the sign-in callback returns a native client: `<scheme>://app/app-comments/auth`. */
+export function appAuthReturnUrl(scheme: string): string {
+  return `${appOrigin(scheme)}/app-comments/auth`;
+}

package/src/native.ts

@@ -0,0 +1,282 @@
+/**
+ * The toolbar's portable (DOM-free) logic, for native clients: `@devaccel-labs/app-comments-toolbar/native`,
+ * re-exported by `@devaccel-labs/app-comments-native` (its `src/shared.ts`). It ships as TypeScript source, like
+ * `./native-wire`, `./dictation` and `./replay`; React Native's Metro compiles it in the host app.
+ *
+ * Every module re-exported here must stay DOM-free at import time (no `react-dom`, no DOM components, no
+ * top-level `window` / `document`). Where a web module mixes portable helpers with DOM UI, the helpers live in a
+ * pure module here and the web file re-exports them, so web imports don't change.
+ */
+export * from "./native-wire.js";
+export type { Anchor, Candidate, Resolution, ResolutionStatus, Sketch } from "./core/index.js";
+export { describeAnchor, validateAnchor } from "./core/index.js";
+
+// Request functions and wire types (`api.ts`, the DOM-free half of the web `client.ts`). Member tokens go
+// through `MemberTokenStore`; a session's `clientOrigin` is sent as `x-comment-service-origin` on every call.
+export {
+  ApiError,
+  base64Url,
+  checkClarity,
+  createThread,
+  editMessage,
+  fetchTicketForm,
+  finishMsfSignIn,
+  getProfile,
+  listMembers,
+  listThreads,
+  memberIsCurrent,
+  msfAuthorizeUrl,
+  msfHandoffFrom,
+  openLive,
+  readMemberToken,
+  replyToThread,
+  saveSettings,
+  signInOptions,
+  storageKey,
+  transcribeAudio,
+  updateProfile,
+  updateThread,
+  uploadAttachment,
+} from "./runtime/api.js";
+export type {
+  Access,
+  Attachment,
+  Capture,
+  CommentMessage,
+  Delivery,
+  Details,
+  FieldDef,
+  FieldValue,
+  Member,
+  MemberTokenStore,
+  Mentioned,
+  MsfHandoff,
+  PostExtras,
+  Profile,
+  Revision,
+  Settings,
+  SignInOptions,
+  Thread,
+  TicketBadge,
+} from "./runtime/api.js";
+export { readJwt, sessionFrom, sessionSource } from "./runtime/session-source.js";
+export type { GetSession, Session } from "./runtime/session-source.js";
+
+export { fieldIsSensitive, redactText } from "./runtime/redact.js";
+export { relatedTo } from "./runtime/related.js";
+export type { Related } from "./runtime/related.js";
+export { MAX_POLL_MS, nextPoll } from "./runtime/freshness.js";
+export type { PollState } from "./runtime/freshness.js";
+export {
+  ago,
+  colorFor,
+  deliveryText,
+  initials,
+  paintThreadStatuses,
+  statusNote,
+  targetName,
+} from "./runtime/format.js";
+
+// Replay model (types, buffer, parsing). `watchActivity` is web-only; native activity lives in src/activity.
+export {
+  ReplayBuffer,
+  consoleText,
+  parseReplay,
+  redactSecretSearchParams,
+  replayLine,
+  replayStamp,
+} from "./runtime/replay-model.js";
+export type {
+  ReplayBufferOptions,
+  ReplayClip,
+  ReplayDraft,
+  ReplayEvent,
+  ReplayFile,
+} from "./runtime/replay-model.js";
+
+// Debug context: the file, its redaction and its limits, and the capture core every platform feeds. Native
+// hooks live in src/activity.
+export * from "./debug-context.js";
+export {
+  argText,
+  createDebugCore,
+  errorOf,
+  type DebugCaptureStats,
+  type DebugCore,
+  type RequestReaders,
+} from "./runtime/debug-context-core.js";
+
+// Drafts: the store with a native `DraftBackend` (src/drafts).
+export {
+  MAX_DRAFT_BYTES,
+  MAX_DRAFT_CAPTURES,
+  createDraftStore,
+  describeDraft,
+  readStoredDraft,
+} from "./runtime/draft-model.js";
+export type {
+  DraftBackend,
+  DraftStore,
+  StoredCapture,
+  StoredDraft,
+  StoredRecording,
+} from "./runtime/draft-model.js";
+
+// Markup shape model, hit-testing and history. Drawing is native (react-native-svg); flattening is native.
+export {
+  DEFAULT_HIGHLIGHT,
+  DEFAULT_INK,
+  HIGHLIGHT_ALPHA,
+  HISTORY_LIMIT,
+  MARKUP_COLORS,
+  arrowHead,
+  commitHistory,
+  contrastText,
+  createHistory,
+  flattenedName,
+  hitTest,
+  isMeaningful,
+  markupMetrics,
+  moveShape,
+  normalizeBox,
+  redoHistory,
+  shapeBounds,
+  snapAngle,
+  strokeWidth,
+  textLayout,
+  toRect,
+  undoHistory,
+} from "./runtime/markup-model.js";
+export type {
+  ArrowShape,
+  Box,
+  BoxShape,
+  MarkupHistory,
+  MarkupMetrics,
+  MarkupShape,
+  MarkupSize,
+  MarkupTool,
+  MeasureText,
+  StrokeShape,
+  TextLayout,
+  TextShape,
+} from "./runtime/markup-model.js";
+
+// Dictation text helpers. Audio capture is native (expo-audio, m4a takes).
+export {
+  decibels,
+  dictationPrompt,
+  insertDictated,
+  meterLevel,
+  voiceRecordingName,
+} from "./runtime/dictation-model.js";
+
+// Who wrote, who is named, and how a thread reads in lists.
+export {
+  agoPhrase,
+  fromYou,
+  involved,
+  isMine,
+  leadSentence,
+  mentionOfYou,
+  namesYou,
+  versionsOf,
+} from "./runtime/thread-model.js";
+
+// Attachment limits, names and sizes.
+export {
+  ATTACHMENT_MAX_BYTES,
+  ATTACHMENT_MAX_FILES,
+  ATTACHMENT_TYPES,
+  attachmentStamp,
+  formatSize,
+  isReplayFile,
+} from "./runtime/attachment-model.js";
+
+// Live socket protocol and timing (web `useThreadsSync` and the native live loop).
+export {
+  KEEPALIVE_MS,
+  MAX_QUICK_RETRIES,
+  OPEN_WAIT_MS,
+  PUSH_BATCH_MS,
+  RETRY_LATER_MS,
+  parseLiveMessage,
+} from "./runtime/live-model.js";
+export type { LiveMessage } from "./runtime/live-model.js";
+
+// Composer helpers.
+export {
+  insertMention,
+  mentionMatches,
+  mentionParts,
+  mentionQueryAt,
+  mentionsIn,
+} from "./runtime/mention-parse.js";
+export {
+  CHIP_OPTIONS_MAX,
+  missingTicketFields,
+  ticketDraftPayload,
+  ticketFieldOptions,
+  ticketFieldVisibility,
+  ticketValueFilled,
+} from "./runtime/ticket-form-model.js";
+export type {
+  TicketDraft,
+  TicketForm,
+  TicketFormField,
+  TicketValue,
+  TicketValues,
+} from "./runtime/ticket-form-model.js";
+export {
+  detailsEnabled,
+  detailsPayload,
+  hasFieldValues,
+  noDetails,
+} from "./runtime/details-model.js";
+export { REPORT_KINDS, readReportKind } from "./runtime/kind-model.js";
+export type { ReportKind } from "./runtime/kind-model.js";
+
+// The clarity check's decisions before a new comment is sent (docs/adr/0002-clarity-check.md). The panel is native.
+export {
+  CLARITY_ANSWER_MAX_LENGTH,
+  CLARITY_MAX_ASSUMED,
+  CLARITY_MAX_QUESTIONS,
+  CLARITY_MAX_ROUNDS,
+  CLARITY_WAIT_MS,
+  CLARITY_WORDS,
+  COMMENT_MESSAGE_MAX_LENGTH,
+  answerRoom,
+  askClarity,
+  canSendAsIs,
+  clarityAfterCheck,
+  clarityAnnouncement,
+  clarityBody,
+  clarityChecks,
+  clarityGroups,
+  clarityReader,
+  clarityStep,
+  draftMark,
+  openQuestions,
+  passMark,
+  questionAudience,
+  readClarityHold,
+  readClarityMode,
+  readClarityResponse,
+  whoWouldAsk,
+  withAnswer,
+} from "./runtime/clarity-model.js";
+export type {
+  ClarityAnswer,
+  ClarityAnswerCheck,
+  ClarityAudience,
+  ClarityDraft,
+  ClarityFacts,
+  ClarityGap,
+  ClarityHold,
+  ClarityMode,
+  ClarityOutcome,
+  ClarityQuestion,
+  ClarityReport,
+  ClaritySend,
+  ClarityStep,
+} from "./runtime/clarity-model.js";

package/src/react.ts

@@ -0,0 +1,27 @@
+export { CommentToolbar } from "./runtime/loader.js";
+export type { ToolbarPosition, ToolbarProps, ToolbarTheme } from "./runtime/toolbar.js";
+export { queryCacheSummary, reportToolbarError } from "./runtime/debug-context-host.js";
+export type {
+  DebugAudience,
+  DebugContextConfig,
+  DebugContextOptions,
+  DebugSignal,
+  HostBuild,
+  HostContext,
+  QuerySummary,
+} from "./runtime/debug-context-model.js";
+export { HelpPill } from "./help/react.js";
+export type { HelpPillProps } from "./help/react.js";
+export { supportRequestsAt } from "./help/requests.js";
+export { HelpError } from "./help/types.js";
+export type {
+  HelpImage,
+  HelpOptions,
+  HelpPosition,
+  HelpReceipt,
+  HelpRequest,
+  HelpTheme,
+  SubmittedRequest,
+  SubmittedRequestStatus,
+  SupportRequests,
+} from "./help/types.js";

package/src/replay.ts

@@ -0,0 +1,13 @@
+/**
+ * The replay file a clip carries, for an inbox and for the service: parse it, pair it with its clip, and word
+ * each event. These come from the DOM-free half (`runtime/replay-model`), so a Worker can import them.
+ * Source only, like `./dictation`: not built into `dist`.
+ */
+export {
+  parseReplay,
+  replayLine,
+  replayStamp,
+  type ReplayClip,
+  type ReplayEvent,
+  type ReplayFile,
+} from "./runtime/replay-model.js";