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

package/dist/server.js

@@ -1,3 +1,34 @@
+// src/native-wire.ts
+var APP_ORIGIN_HEADER = "x-comment-service-origin";
+var SCHEME = /^[a-z][a-z0-9+.-]{1,39}$/;
+var RESERVED = /* @__PURE__ */ new Set([
+  "http",
+  "https",
+  "ws",
+  "wss",
+  "file",
+  "data",
+  "blob",
+  "javascript",
+  "vbscript",
+  "about",
+  "mailto",
+  "tel",
+  "sms",
+  "intent",
+  "content",
+  "chrome",
+  "chrome-extension"
+]);
+function isAppScheme(value) {
+  return SCHEME.test(value) && !RESERVED.has(value);
+}
+function appOriginScheme(value) {
+  const match = /^([a-z][a-z0-9+.-]{1,39}):\/\/app$/.exec(value);
+  const scheme = match?.[1];
+  return scheme && isAppScheme(scheme) ? scheme : null;
+}
+
 // src/server/index.ts
 function readCommentServiceConfig(env = process.env) {
   const url = env.COMMENT_SERVICE_URL?.replace(/\/$/, "");
@@ -8,21 +39,13 @@ function readCommentServiceConfig(env = process.env) {
   const linked = (env.COMMENT_SERVICE_LINKED ?? "").split(/[\s,]+/).filter(Boolean);
   return { url, project, environment, secret, linked };
 }
-function declaredOrigin(request) {
-  const value = request.headers.get("origin") ?? request.headers.get("x-comment-service-origin");
-  if (!value) return null;
-  try {
-    const origin = new URL(value).origin;
-    return origin === "null" ? null : origin;
-  } catch {
-    return null;
+function requestedOrigin(request) {
+  const declared = request.headers.get(APP_ORIGIN_HEADER);
+  if (request.headers.get("origin") === null && declared !== null && appOriginScheme(declared) !== null) {
+    return declared;
   }
-}
-function requestOrigin(request) {
-  const declared = declaredOrigin(request);
-  if (declared) return declared;
   const url = new URL(request.url);
-  const host = request.headers.get("x-forwarded-host") ?? request.headers.get("host");
+  const host = request.headers.get("x-forwarded-host") ?? request.headers.get("host") ?? url.host;
   if (!host || host.includes("/")) return url.origin;
   const proto = (request.headers.get("x-forwarded-proto") ?? url.protocol.replace(":", "")).split(",")[0].trim();
   return `${proto}://${host}`;
@@ -30,7 +53,7 @@ function requestOrigin(request) {
 async function handleSessionRequest(request, config = readCommentServiceConfig()) {
   const headers = { "cache-control": "no-store" };
   if (!config) return Response.json({ enabled: false }, { headers });
-  const origin = requestOrigin(request);
+  const origin = requestedOrigin(request);
   let response;
   try {
     response = await fetch(`${config.url}/v1/host/session`, {
@@ -81,7 +104,312 @@ async function handleSessionRequest(request, config = readCommentServiceConfig()
     { headers }
   );
 }
+
+// src/help/wire.ts
+var HELP_LIMITS = {
+  /** A request's own id: letters, digits, `.`, `_`, `:` and `-`. */
+  id: 100,
+  message: 4e3,
+  images: 3,
+  /** One picture, before base64. */
+  imageBytes: 5 * 1024 * 1024,
+  name: 200,
+  label: 200,
+  url: 1e3,
+  /** "Your requests" shows at most this many. */
+  listed: 50
+};
+var HELP_BODY_BYTES = Math.ceil(HELP_LIMITS.images * HELP_LIMITS.imageBytes * 4 / 3) + 256 * 1024;
+var HELP_ID = /^[A-Za-z0-9._:-]+$/;
+var HELP_IMAGE_TYPES = ["image/png", "image/jpeg", "image/webp"];
+
+// src/server/support.ts
+var HEADERS = { "cache-control": "no-store", "x-content-type-options": "nosniff" };
+var UNAVAILABLE = "Support requests are not available right now. Try again in a moment.";
+var TOO_MANY = "Too many requests right now. Try again in a few minutes.";
+var NOT_ACCEPTED = "The request could not be accepted. Check it and try again.";
+var UNREADABLE = "The request could not be read.";
+var TOO_LARGE = "That is too large to send. Remove a picture and try again.";
+var NOT_A_PICTURE = "Only pictures can be attached: PNG, JPEG or WebP.";
+var PICTURE_TOO_LARGE = "A picture is too large. Pictures can be up to 5 MB.";
+var SERVICE = { name: 80, accountName: 120, id: 200, fieldValue: 200 };
+var Refusal = class extends Error {
+  constructor(status, message) {
+    super(message);
+    this.status = status;
+  }
+  status;
+};
+function answer(body, status = 200, extra = {}) {
+  return Response.json(body, { status, headers: { ...HEADERS, ...extra } });
+}
+function failure(status, error, extra) {
+  const body = { error };
+  return answer(body, status, extra);
+}
+function storable(value) {
+  return value.replaceAll("\0", "");
+}
+function oneLine(value, limit) {
+  return typeof value === "string" ? storable(value).replace(/\s+/g, " ").trim().slice(0, limit) : "";
+}
+function isId(value) {
+  return typeof value === "string" && value.length > 0 && value.length <= SERVICE.id && !/\s/.test(value) && !value.includes("\0");
+}
+function note(op, reason) {
+  console.warn(`[comment-service] ${op} was refused: ${reason}.`);
+}
+async function bodyWithin(request, limit) {
+  if (Number(request.headers.get("content-length") ?? "0") > limit) return null;
+  if (!request.body) return new Uint8Array();
+  const reader = request.body.getReader();
+  const chunks = [];
+  let size = 0;
+  for (; ; ) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    size += value.byteLength;
+    if (size > limit) {
+      await reader.cancel().catch(() => {
+      });
+      return null;
+    }
+    chunks.push(value);
+  }
+  const bytes = new Uint8Array(size);
+  let offset = 0;
+  for (const chunk of chunks) {
+    bytes.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  return bytes;
+}
+function sniff(head) {
+  const starts = (...bytes) => bytes.every((byte, index) => head[index] === byte);
+  if (starts(137, 80, 78, 71, 13, 10, 26, 10)) return "image/png";
+  if (starts(255, 216, 255)) return "image/jpeg";
+  if (starts(82, 73, 70, 70) && head[8] === 87 && head[9] === 69 && head[10] === 66 && head[11] === 80) {
+    return "image/webp";
+  }
+  return null;
+}
+var BASE64 = /^[A-Za-z0-9+/]*={0,2}$/;
+function picture(given, index, taken) {
+  const image = typeof given === "object" && given !== null ? given : {};
+  const data = image["data"];
+  if (typeof data !== "string" || data.length === 0 || data.length % 4 !== 0) {
+    throw new Refusal(400, NOT_A_PICTURE);
+  }
+  const padding = data.endsWith("==") ? 2 : data.endsWith("=") ? 1 : 0;
+  if (data.length / 4 * 3 - padding > HELP_LIMITS.imageBytes) {
+    throw new Refusal(413, PICTURE_TOO_LARGE);
+  }
+  if (!BASE64.test(data)) throw new Refusal(400, NOT_A_PICTURE);
+  const head = Uint8Array.from(atob(data.slice(0, 16)), (character) => character.charCodeAt(0));
+  const contentType = sniff(head);
+  if (!contentType || !HELP_IMAGE_TYPES.includes(contentType)) {
+    throw new Refusal(415, NOT_A_PICTURE);
+  }
+  const extension = contentType.slice("image/".length).replace("jpeg", "jpg");
+  const name = oneLine(image["name"], HELP_LIMITS.name) || `picture-${index + 1}.${extension}`;
+  const stem = name.replace(/[^A-Za-z0-9._-]+/g, "_").slice(0, 150) || `picture-${index + 1}`;
+  let id = stem;
+  for (let copy = 2; taken.has(id); copy += 1) id = `${stem}-${copy}`;
+  taken.add(id);
+  return { id, name, contentType, bytes: { $bytes: data } };
+}
+var OWNER_AS_IS = SERVICE.id - HELP_LIMITS.id - 1;
+async function ownerOf(userId) {
+  if (userId.length <= OWNER_AS_IS && !userId.includes(":") && !userId.startsWith("~")) {
+    return userId;
+  }
+  const digest = new Uint8Array(
+    await crypto.subtle.digest("SHA-256", new TextEncoder().encode(userId))
+  );
+  let binary = "";
+  for (const byte of digest) binary += String.fromCharCode(byte);
+  return `~${btoa(binary).replaceAll("+", "-").replaceAll("/", "_").replaceAll("=", "")}`;
+}
+function reportIdOf(owner, id) {
+  return `${owner}:${id}`;
+}
+function reportOf(given, config, owner) {
+  if (typeof given !== "object" || given === null || Array.isArray(given)) {
+    throw new Refusal(400, UNREADABLE);
+  }
+  const sent = given;
+  const id = sent["id"];
+  if (typeof id !== "string" || id.length === 0 || id.length > HELP_LIMITS.id || !HELP_ID.test(id)) {
+    throw new Refusal(400, NOT_ACCEPTED);
+  }
+  const message = typeof sent["message"] === "string" ? storable(sent["message"]).trim() : "";
+  if (message.length === 0) throw new Refusal(400, "Write what you need help with.");
+  if (message.length > HELP_LIMITS.message) {
+    throw new Refusal(400, "That is too long. Shorten it to 4,000 characters.");
+  }
+  const images = sent["images"] ?? [];
+  if (!Array.isArray(images)) throw new Refusal(400, NOT_ACCEPTED);
+  if (images.length > HELP_LIMITS.images) {
+    throw new Refusal(400, `At most ${HELP_LIMITS.images} pictures can be sent.`);
+  }
+  const taken = /* @__PURE__ */ new Set();
+  const attachments = images.map((image, index) => picture(image, index, taken));
+  const fields = [];
+  const field = (label, value) => {
+    if (value) fields.push({ label, value: value.slice(0, SERVICE.fieldValue) });
+  };
+  const pointed = sent["pointed"];
+  if (typeof pointed === "object" && pointed !== null) {
+    field("Pointed at", oneLine(pointed.label, HELP_LIMITS.label));
+  }
+  const client = typeof sent["client"] === "object" && sent["client"] !== null ? sent["client"] : {};
+  const viewport = typeof client.viewport === "object" && client.viewport !== null ? client.viewport : {};
+  field("Browser", oneLine(client.userAgent, SERVICE.fieldValue));
+  if (Number.isFinite(viewport.width) && Number.isFinite(viewport.height)) {
+    field(
+      "Window",
+      `${Math.round(Number(viewport.width))} \xD7 ${Math.round(Number(viewport.height))}`
+    );
+  }
+  field("Language", oneLine(client.language, 40));
+  let pageUrl;
+  const page = sent["pageUrl"];
+  if (typeof page === "string" && page.length <= HELP_LIMITS.url) {
+    try {
+      const url = new URL(page);
+      if (url.protocol === "http:" || url.protocol === "https:") pageUrl = url.href;
+    } catch {
+    }
+  }
+  if (pageUrl && pageUrl.length > HELP_LIMITS.url) pageUrl = void 0;
+  const name = oneLine(config.reporter.name, SERVICE.name) || "Someone";
+  const account = config.account ? { id: config.account.id, name: oneLine(config.account.name, SERVICE.accountName) } : void 0;
+  return {
+    reportId: reportIdOf(owner, id),
+    reporter: { userId: config.reporter.userId, name },
+    ...account?.name ? { account } : {},
+    ...pageUrl ? { pageUrl } : {},
+    ...fields.length > 0 ? { fields } : {},
+    messages: [
+      {
+        id,
+        author: name,
+        role: "reporter",
+        body: message,
+        ...attachments.length > 0 ? { attachments } : {}
+      }
+    ]
+  };
+}
+async function callOp(config, op, input) {
+  const send = config.fetch ?? fetch;
+  let response;
+  try {
+    response = await send(`${config.serviceUrl.replace(/\/+$/, "")}/api/v1/ops/${op}`, {
+      method: "POST",
+      headers: {
+        authorization: `Bearer ${config.connectionToken}`,
+        "content-type": "application/json"
+      },
+      body: JSON.stringify({ project: config.project, input })
+    });
+  } catch {
+    note(op, "the service could not be reached");
+    throw new Refusal(502, UNAVAILABLE);
+  }
+  const payload = await response.json().catch(() => null);
+  if (!response.ok) {
+    note(
+      op,
+      `HTTP ${response.status}${typeof payload?.error?.code === "string" ? ` ${payload.error.code}` : ""}`
+    );
+    if (response.status === 413) throw new Refusal(413, TOO_LARGE);
+    if (response.status === 429) throw new Refusal(429, TOO_MANY);
+    throw new Refusal(502, UNAVAILABLE);
+  }
+  if (payload?.ok === true) return payload.value;
+  const reason = typeof payload?.reason === "string" ? payload.reason : "an answer that could not be read";
+  note(op, reason);
+  if (reason === "invalid_input") throw new Refusal(400, NOT_ACCEPTED);
+  if (reason === "rate_limited") throw new Refusal(429, TOO_MANY);
+  throw new Refusal(502, UNAVAILABLE);
+}
+async function file(request, config) {
+  if (!/^application\/json\b/i.test(request.headers.get("content-type") ?? "")) {
+    return failure(415, UNREADABLE);
+  }
+  const body = await bodyWithin(request, HELP_BODY_BYTES);
+  if (body === null) return failure(413, TOO_LARGE);
+  let sent;
+  try {
+    sent = JSON.parse(new TextDecoder().decode(body));
+  } catch {
+    return failure(400, UNREADABLE);
+  }
+  const report = reportOf(sent, config, await ownerOf(config.reporter.userId));
+  const filed = await callOp(config, "fileReport", report);
+  const refused = Array.isArray(filed?.refused) ? filed.refused.length : 0;
+  const receipt = refused === 0 ? {} : {
+    note: refused === 1 ? "1 picture could not be kept." : `${refused} pictures could not be kept.`
+  };
+  return answer(receipt);
+}
+function standingOf(report) {
+  const into = report.consolidated;
+  return typeof into === "object" && into !== null ? { stands: into, consolidated: true } : { stands: report, consolidated: false };
+}
+function statusOf(report) {
+  if (report.status === "resolved") return "resolved";
+  const ticket = report.ticket?.status;
+  return typeof ticket === "string" && ticket !== "" && ticket !== "new" ? "in_progress" : "received";
+}
+async function list(config) {
+  const mine = reportIdOf(await ownerOf(config.reporter.userId), "");
+  const read = await callOp(config, "reportsBy", {
+    reporterUserId: config.reporter.userId,
+    limit: HELP_LIMITS.listed
+  });
+  const requests = (Array.isArray(read?.reports) ? read.reports : []).filter(
+    (report) => typeof report?.reportId === "string" && typeof report.createdAt === "string"
+  ).map((report) => {
+    const reportId = report.reportId;
+    const { stands, consolidated } = standingOf(report);
+    const label = oneLine(stands.ticket?.statusLabel, 80);
+    return {
+      id: reportId.startsWith(mine) && reportId.length > mine.length ? reportId.slice(mine.length) : reportId,
+      ...Number.isInteger(report.ticket?.displaySeq) ? { reference: String(report.ticket?.displaySeq) } : {},
+      summary: oneLine(report.firstWords, 200) || oneLine(report.title, 200),
+      createdAt: report.createdAt,
+      status: statusOf(stands),
+      ...label ? { statusLabel: label } : {},
+      ...consolidated ? { consolidated: true } : {}
+    };
+  });
+  return answer({ requests });
+}
+async function handleSupportRequest(request, config) {
+  if (!isId(config?.reporter?.userId) || !config.serviceUrl || !config.connectionToken || !config.project || config.account !== void 0 && !isId(config.account?.id)) {
+    console.error(
+      "[comment-service] handleSupportRequest needs serviceUrl, connectionToken, project, reporter.userId and, when an account is given, its id."
+    );
+    return failure(500, UNAVAILABLE);
+  }
+  try {
+    switch (request.method) {
+      case "POST":
+        return await file(request, config);
+      case "GET":
+        return await list(config);
+      default:
+        return failure(405, "Use GET or POST.", { allow: "GET, POST" });
+    }
+  } catch (error) {
+    if (error instanceof Refusal) return failure(error.status, error.message);
+    throw error;
+  }
+}
 export {
   handleSessionRequest,
+  handleSupportRequest,
   readCommentServiceConfig
 };

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

@@ -0,0 +1,30 @@
+import { type CapturedImage } from "./picture.js";
+import { type CaptureTheme } from "./surface.js";
+export type { CapturedImage } from "./picture.js";
+export type { CaptureTheme } from "./surface.js";
+export type CaptureOptions = {
+    /** The look of the capture UI. `auto` (the default) follows the system's light or dark setting. */
+    theme?: CaptureTheme;
+};
+export type CapturedTarget = {
+    /** What a person would call it: the toolbar's own name for an anchor ("button › Save"). */
+    label: string;
+    /** The page's path. */
+    route: string;
+    /** The visible page with the element outlined, or null when the page could not be drawn. */
+    image: CapturedImage | null;
+};
+export type CommentToolCaptureApi = {
+    /**
+     * Takes a picture of the page as it is now and opens the toolbar's drawing editor over it. Resolves with
+     * the picture, drawn on or not, when the person presses Done; null when they close it. Rejects when the
+     * page could not be drawn.
+     */
+    screenshot(options?: CaptureOptions): Promise<CapturedImage | null>;
+    /**
+     * Lets the person point at one thing on the page, as the toolbar's "comment on this" does. Resolves with
+     * what they pointed at and a picture of the page with it outlined; null on Escape.
+     */
+    pick(options?: CaptureOptions): Promise<CapturedTarget | null>;
+};
+export declare function createCapture(): CommentToolCaptureApi;

package/dist/types/capture/editor.d.ts

@@ -0,0 +1,10 @@
+import { type CapturedImage } from "./picture.js";
+export type EditorProps = {
+    /** The picture to draw on, or null while the page is still being drawn. */
+    picture: CapturedImage | null;
+    /** Done: the picture as it now is. */
+    onDone: (image: CapturedImage) => void;
+    /** Cancel, or Escape with nothing drawn. */
+    onCancel: () => void;
+};
+export declare function Editor({ picture, onDone, onCancel }: EditorProps): import("react/jsx-runtime").JSX.Element;

package/dist/types/capture/ignore.d.ts

@@ -0,0 +1,19 @@
+/**
+ * What is not the page, to a capture: Comment Tool's own UI and the host's floating UI.
+ *
+ * The toolbar's root is `#cs-root`, and the toolbar leaves that id out of its pictures, keeps its presses and
+ * its focus from the page, and never offers it to point at. The capture script's root carries the same id on
+ * purpose (`./surface.tsx`), so every toolbar build treats it as its own, and this script treats the toolbar the
+ * same way: neither is in the other's pictures.
+ *
+ * A host marks its own floating UI (a help button, the panel that asked for the capture) with
+ * `data-cs-capture-ignore`. Only this script reads the attribute: the toolbar still pictures a marked element,
+ * because to a reviewer it is part of the app.
+ */
+export declare const IGNORE_ATTRIBUTE = "data-cs-capture-ignore";
+/** True for the root of a subtree a picture leaves out. */
+export declare function leftOut(element: Element): boolean;
+/** True when `target` is Comment Tool's UI or the host's marked UI, or inside either. */
+export declare function notThePage(target: EventTarget | null): boolean;
+/** The page's own element at a point of the viewport, as the toolbar's `elementAt` finds it. */
+export declare function pageElementAt(x: number, y: number): Element | null;

package/dist/types/capture/index.d.ts

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

package/dist/types/capture/picker.d.ts

@@ -0,0 +1,9 @@
+export type PickerProps = {
+    /** The element the person clicked. */
+    onPick: (element: Element) => void;
+    /** Escape, or the hint's Cancel. */
+    onCancel: () => void;
+};
+export declare function Picker({ onPick, onCancel }: PickerProps): import("react/jsx-runtime").JSX.Element;
+/** What stays on screen while the picture of a chosen element is drawn. */
+export declare function Capturing(): import("react/jsx-runtime").JSX.Element;

package/dist/types/capture/picture.d.ts

@@ -0,0 +1,29 @@
+import { type PageShot } from "../runtime/screenshot.js";
+/** What a host gets back for a picture. */
+export type CapturedImage = {
+    blob: Blob;
+    name: string;
+    /** The picture's own size, in its pixels. */
+    width: number;
+    height: number;
+    /** True when the person drew on it. */
+    markedUp: boolean;
+};
+/**
+ * Copies the visible page now, synchronously, as the toolbar's `takeShot` does, with `highlight`'s box measured
+ * at the same moment. Comment Tool's UI and the host's marked UI are left out.
+ */
+export declare function shootPage(highlight?: Element | null, timeout?: number): PageShot;
+/**
+ * Draws `shot` into a file: the whole visible page as a JPEG, the framed element outlined when there is one.
+ * Null when the page could not be drawn.
+ */
+export declare function pictureOf(shot: PageShot): Promise<CapturedImage | null>;
+/** The size of an encoded picture, or `fallback` where the browser cannot decode it. */
+export declare function sizeOf(blob: Blob, fallback: {
+    width: number;
+    height: number;
+}): Promise<{
+    width: number;
+    height: number;
+}>;

package/dist/types/capture/surface.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Where the capture script draws its own UI: a root of the toolbar's kind, mounted for one capture and removed
+ * when it ends.
+ *
+ * The root is `<div id="cs-root">`, the toolbar's id, on purpose. The toolbar's stylesheet is written against
+ * that id, so the editor and the picker look as they do in the toolbar with no second copy of the CSS. And
+ * every toolbar build already treats that id as Comment Tool's own UI: it leaves it out of pictures and
+ * recordings drawn from the page, keeps its presses from the page, and does not read keys typed in it as page
+ * shortcuts. So a toolbar on the same page needs no change to live beside this script.
+ *
+ * While both are on the page there are two elements with that id. The toolbar's is in `<body>` and this one
+ * sits after `<body>`, so `document.getElementById("cs-root")` still finds the toolbar's, whichever came
+ * first.
+ *
+ * The one exception is a page with a modal `<dialog>` open. The browser draws that above everything else and
+ * makes everything outside it inert, so the root goes inside the dialog, as the toolbar's own does
+ * (`../runtime/placement.ts`). It is still fixed to the window, unless the dialog's own CSS makes it the
+ * containing block of fixed-position content (a transform, a filter), in which case it fills the dialog.
+ */
+import { type ReactNode } from "react";
+export type CaptureTheme = "light" | "dark" | "auto";
+/**
+ * Tells a screen reader what opened. The region is on the page first and gets its text a moment later: a live
+ * region that arrives already filled is not read by every screen reader.
+ */
+export declare function Announce({ text }: {
+    text: string;
+}): import("react/jsx-runtime").JSX.Element;
+export type Surface = {
+    /** Draws `node` in the root, in place of what was there. */
+    show(node: ReactNode): void;
+    /** Removes the root and gives the focus back to what had it. Safe to call twice. */
+    close(): void;
+};
+/**
+ * Mounts an empty root for one capture. `onLost` is called when the page takes the root away while it is
+ * open: the modal dialog it was mounted in has closed.
+ */
+export declare function openSurface(theme: CaptureTheme, onLost: () => void): Surface;

package/dist/types/core/index.d.ts

@@ -1,2 +1,2 @@
-export { describeAnchor, dropAncestors, resolveAnchor, validateAnchor } from "./resolve.js";
-export type { Anchor, Candidate, Resolution, ResolutionStatus } from "./types.js";
+export { describeAnchor, dropAncestors, resolveAnchor, validateAnchor, validateSketch, } from "./resolve.js";
+export type { Anchor, Candidate, Resolution, ResolutionStatus, Sketch } from "./types.js";

package/dist/types/core/resolve.d.ts

@@ -1,4 +1,4 @@
-import type { Anchor, Candidate, Resolution } from "./types.js";
+import type { Anchor, Candidate, Resolution, Sketch } from "./types.js";
 /**
  * Drop elements that contain another match, so a wrapping div doesn't steal the button.
  *
@@ -27,3 +27,4 @@ export declare function dropAncestors(candidates: Candidate[]): Candidate[];
 export declare function resolveAnchor(anchor: Anchor, candidates: Candidate[], inside?: (root: Candidate) => Candidate[]): Resolution;
 export declare function describeAnchor(anchor: Anchor): string;
 export declare function validateAnchor(input: unknown): Anchor | null;
+export declare function validateSketch(input: unknown): Sketch | null;

package/dist/types/core/types.d.ts

@@ -29,6 +29,17 @@ export type Anchor = {
     tag: string;
     /** Sibling path inside the component. Stored for agents, never used to choose a match. */
     intra: string | null;
+    /** A freehand drawing the comment was left with. Never used to choose a match. */
+    sketch?: Sketch;
+};
+/**
+ * Strokes drawn on the page, in CSS pixels from the top-left corner of the anchored element.
+ * Each path is a flat list of x, y pairs. `w` and `h` are the element's size when it was drawn.
+ */
+export type Sketch = {
+    w: number;
+    h: number;
+    paths: number[][];
 };
 export type Candidate = {
     key: string;

package/dist/types/debug-context.d.ts

@@ -0,0 +1,7 @@
+/**
+ * The debug context file a comment carries (`context-<stamp>.json`), for an inbox, a destination and the
+ * service: read it back safely, redact it again, and turn it into the brief a coding agent reads. DOM-free, so
+ * a Worker can import it. Source only, like `./replay`: not built into `dist`.
+ */
+export { DEBUG_CONTEXT_MAX_BYTES, DEBUG_CONTEXT_PREFIX, DEBUG_SIGNALS, DEFAULT_SIGNALS, OPT_IN_SIGNALS, debugContextBrief, debugContextBytes, debugContextKey, debugContextName, fitDebugContext, isDebugContextName, liveDebugOptions, newReportId, resolveDebugContext, sanitizeDebugContext, type BriefMeta, type DebugAudience, type DebugContextConfig, type DebugContextFile, type DebugContextOptions, type DebugError, type DebugRequest, type DebugSignal, type DebugStep, type HostBuild, type HostContext, type QuerySummary, type RealtimeState, type ResolvedDebugContext, } from "./runtime/debug-context-model.js";
+export { ID_HEADERS, idHeaderNames, newTally, scrubId, scrubText, scrubUrl, scrubValue, type JsonBag, type RedactionTally, } from "./runtime/debug-context-redact.js";

package/dist/types/dictation.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The toolbar's dictation engine, for a connection's own composers (an inbox's reply box). The
+ * `./dictation` export points at this source for the monorepo only: it is not built into `dist`, so the npm
+ * package does not ship it. `ApiError` is what a `transcribe` callback throws so the engine can tell a retry from a
+ * stop (`rate_limited`, `dictation_unavailable`, 401, 403).
+ */
+export { Dictation, dictationSupported, idleDictation, MAX_TAKE_MS, voiceRecordingSupported, type DictationDeps, type DictationState, } from "./runtime/dictation-engine.js";
+export { dictationPrompt, insertDictated } from "./runtime/dictation.js";
+export { ApiError } from "./runtime/client.js";

package/dist/types/embed/controller.d.ts

@@ -0,0 +1,61 @@
+/**
+ * The script-tag loader's state: one toolbar per page, brought up by the same steps as `<CommentToolbar>`
+ * (`../runtime/boot.ts`), and the three things a single-page app may ask of it afterwards.
+ *
+ * ## Which service the toolbar may come from
+ *
+ * `<CommentToolbar>` imports the toolbar from the service the host's own session route names (`apiUrl`), and
+ * so does this loader: nothing on the page, and no attribute of the tag, can name another one. The loader also
+ * knows where it was itself loaded from. The two are the same service in every ordinary install, so a session
+ * that names another origin than the loader's own is refused: nothing is imported and nothing mounts. The one
+ * way to allow it is for the session route to say so itself, by naming the loader's origin in `loaderOrigin`.
+ *
+ * ## Following the host's sign-in
+ *
+ * While the toolbar is on the page it follows the host's sign-in itself (`ToolbarApp`). While it is not, because
+ * nobody was signed in when the page loaded, this loader asks the session route again at the same moments
+ * (`watchHost`), so a sign-in that loads no page still brings the toolbar. Not after the host's own `unmount()`.
+ */
+import { type Runtime, type Wait } from "../runtime/boot.js";
+import type { ScreenRule } from "../runtime/screen.js";
+import type { GetSession } from "../runtime/session-source.js";
+import type { ToolbarPosition, ToolbarTheme } from "../runtime/toolbar.js";
+import type { DebugContextConfig } from "../runtime/debug-context-model.js";
+import { type EmbedOptions } from "./options.js";
+/** What `window.CommentTool` is. */
+export type CommentToolApi = {
+    /**
+     * Asks the session route again. Mounts the toolbar when comments are now on and it is not on the page,
+     * removes it when they are now off, and has a toolbar that stays ask again too. Resolves once that is done.
+     * Call it after a sign-in or a sign-out that did not reload the page.
+     */
+    refresh(): Promise<void>;
+    /** Removes the toolbar. `refresh()` brings it back. */
+    unmount(): void;
+    /**
+     * `navigate` is the router's client-side navigation, as the component's `navigate` prop (null takes it away
+     * again); `position`, `theme` and `screen` are the component's props of those names (null takes `screen`
+     * away). A wrong value throws a TypeError and changes nothing.
+     */
+    configure(options: {
+        navigate?: ((href: string) => void) | null;
+        position?: ToolbarPosition;
+        theme?: ToolbarTheme;
+        screen?: ScreenRule | null;
+        /** The component's `debugContext` prop: `true`, `false`, or its options. Null, or any other value, turns it off. */
+        debugContext?: DebugContextConfig | null;
+    }): void;
+};
+export type EmbedInput = {
+    /** The origin `embed.js` was loaded from. */
+    serviceOrigin: string;
+    options: EmbedOptions;
+    /** The page-wide session source for a path. Default: the one the toolbar itself uses. */
+    sessions?: (path: string) => GetSession;
+    load?: (apiUrl: string) => Promise<Runtime>;
+    /** When the first attempt starts. Default: when the page is idle. */
+    wait?: Wait;
+};
+export declare function createEmbed(input: EmbedInput): CommentToolApi & {
+    start(): void;
+};

package/dist/types/embed/index.d.ts

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