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

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

@@ -0,0 +1,35 @@
+/**
+ * What a host may set on the loader's `<script>` tag, and with `CommentTool.configure`. The same four things
+ * `<CommentToolbar>` takes as props. There the compiler refuses a wrong value; a `data-` attribute is only
+ * text, so the loader checks it and loads nothing when one is wrong.
+ */
+import type { ToolbarPosition, ToolbarTheme } from "../runtime/toolbar.js";
+export declare const DEFAULT_SESSION_PATH = "/api/comment-service/session";
+export type EmbedOptions = {
+    sessionPath: string;
+    position?: ToolbarPosition;
+    theme?: ToolbarTheme;
+    pollMs?: number;
+    /** `data-screen-params`: the query parameters that select a screen of the app. */
+    screen?: {
+        params: string[];
+    };
+};
+export type ReadOptions = {
+    ok: true;
+    options: EmbedOptions;
+} | {
+    ok: false;
+    problem: string;
+};
+export declare function isPosition(value: unknown): value is ToolbarPosition;
+export declare function isTheme(value: unknown): value is ToolbarTheme;
+export declare const POSITION_NAMES: string;
+export declare const THEME_NAMES: string;
+/**
+ * Reads `data-session-path`, `data-position`, `data-theme`, `data-poll-ms` and `data-screen-params` (as
+ * `dataset` names them). An
+ * attribute that is absent takes the component's default; one that is present and wrong is a refusal that names
+ * it. Other `data-` attributes are the host's own and are not read.
+ */
+export declare function readOptions(data: Readonly<Record<string, string | undefined>>, pageUrl: string): ReadOptions;

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

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

package/dist/types/help/panel-index.d.ts

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

package/dist/types/help/panel-styles.d.ts

@@ -0,0 +1 @@
+export declare const HELP_PANEL_CSS = "\n.cth .cth-panel {\n  position: fixed; z-index: 2147482001;\n  bottom: calc(var(--cth-edge) + 52px + env(safe-area-inset-bottom, 0px) + var(--cth-lift, 0px));\n  display: flex; flex-direction: column; width: 380px; max-width: calc(100vw - 2 * var(--cth-edge));\n  max-height: min(620px, calc(100vh - var(--cth-edge) - 76px - var(--cth-lift, 0px)));\n  border-radius: 18px; background: var(--cth-card); color: var(--cth-ink); overflow: hidden;\n  box-shadow: 0 0 0 1px var(--cth-ring), var(--cth-shadow);\n}\n.cth[data-position=\"bottom-right\"] .cth-panel { right: calc(var(--cth-edge) + env(safe-area-inset-right, 0px)); }\n.cth[data-position=\"bottom-left\"] .cth-panel { left: calc(var(--cth-edge) + env(safe-area-inset-left, 0px)); }\n.cth .cth-panel:focus { outline: none; }\n.cth .cth-content { display: contents; }\n.cth .cth-head { display: flex; align-items: center; gap: 8px; padding: 14px 12px 10px 18px; }\n.cth .cth-title { display: block; flex: 1; min-width: 0; font-size: 15px; font-weight: 650; letter-spacing: -0.01em; }\n.cth .cth-x {\n  display: inline-flex; flex: none; align-items: center; justify-content: center; width: 28px; height: 28px;\n  border-radius: 50%; color: var(--cth-muted); cursor: pointer;\n}\n.cth .cth-x:hover { background: var(--cth-fill); color: var(--cth-ink); }\n.cth .cth-icon { display: block; flex: none; width: 16px; height: 16px; fill: none; stroke: currentColor; stroke-width: 1.6; stroke-linecap: round; stroke-linejoin: round; }\n.cth .cth-tabs { display: flex; flex: none; margin: 0 18px 10px; padding: 3px; border-radius: 10px; background: var(--cth-track); }\n.cth .cth-tab {\n  display: block; flex: 1; padding: 6px 8px; border-radius: 8px; color: var(--cth-muted);\n  font-size: 12.5px; font-weight: 600; text-align: center; cursor: pointer;\n}\n.cth .cth-tab[aria-selected=\"true\"] { background: var(--cth-raised); color: var(--cth-ink); box-shadow: 0 1px 2px rgba(20, 20, 30, 0.14); }\n.cth .cth-body {\n  display: flex; flex: 1; flex-direction: column; gap: 10px; min-height: 0; padding: 2px 18px 16px;\n  overflow-y: auto; overscroll-behavior: contain;\n}\n.cth .cth-form { display: flex; flex-direction: column; gap: 10px; }\n.cth .cth-q { display: block; font-size: 13px; font-weight: 600; }\n.cth .cth-text {\n  display: block; width: 100%; min-height: 104px; max-height: 220px; padding: 10px 12px; border-radius: 12px;\n  background: var(--cth-field); box-shadow: inset 0 0 0 1px var(--cth-line); font-size: 14px; line-height: 1.45;\n  white-space: pre-wrap; overflow-wrap: anywhere; overflow: auto; resize: vertical; cursor: text;\n}\n.cth .cth-text::placeholder { color: var(--cth-muted); }\n.cth .cth-text:focus { outline: none; box-shadow: inset 0 0 0 2px var(--cth-accent); }\n.cth .cth-text[readonly] { opacity: 0.7; }\n.cth .cth-count { display: block; margin-top: -4px; color: var(--cth-muted); font-size: 12px; text-align: right; }\n.cth .cth-tools { display: flex; flex-direction: column; gap: 6px; }\n.cth .cth-tool {\n  display: flex; align-items: center; gap: 9px; padding: 9px 11px; border-radius: 10px; background: var(--cth-fill);\n  font-size: 13px; font-weight: 550; cursor: pointer;\n}\n.cth .cth-tool:hover { background: var(--cth-fill-2); }\n.cth .cth-tool-more { display: block; margin-left: auto; color: var(--cth-muted); font-size: 12px; font-weight: 400; }\n.cth :is(.cth-tool, .cth-send, .cth-plain)[disabled] { opacity: 0.5; cursor: default; }\n.cth .cth-chip {\n  display: flex; align-items: center; gap: 6px; padding: 5px 5px 5px 11px; border-radius: 10px;\n  box-shadow: inset 0 0 0 1px var(--cth-line); font-size: 12.5px;\n}\n.cth .cth-chip-text { display: block; flex: 1; min-width: 0; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }\n.cth .cth-chip-what { font-weight: 600; }\n.cth .cth-thumbs { display: flex; flex-wrap: wrap; gap: 8px; }\n.cth .cth-thumb {\n  position: relative; display: block; width: 104px; height: 68px; border-radius: 10px; overflow: hidden;\n  background: var(--cth-fill); box-shadow: 0 0 0 1px var(--cth-line);\n}\n.cth .cth-thumb-img { display: block; width: 100%; height: 100%; object-fit: cover; object-position: top left; }\n.cth .cth-thumb-x {\n  position: absolute; top: 4px; right: 4px; display: inline-flex; align-items: center; justify-content: center;\n  width: 22px; height: 22px; border-radius: 50%; background: rgba(20, 20, 22, 0.74); color: #ffffff; cursor: pointer;\n}\n.cth .cth-thumb-x .cth-icon, .cth .cth-chip .cth-icon { width: 12px; height: 12px; stroke-width: 2; }\n.cth .cth-alert { display: block; color: var(--cth-danger); font-size: 12.5px; font-weight: 550; }\n.cth .cth-hint { display: block; color: var(--cth-muted); font-size: 12.5px; }\n.cth .cth-foot { display: flex; align-items: center; gap: 10px; margin-top: 2px; }\n.cth .cth-plain { display: inline-block; color: var(--cth-link); font-size: 13px; font-weight: 550; cursor: pointer; }\n.cth .cth-plain:hover { text-decoration: underline; }\n.cth .cth-send {\n  display: inline-flex; align-items: center; justify-content: center; min-width: 84px; height: 36px; margin-left: auto;\n  padding: 0 16px; border-radius: 999px; background: var(--cth-accent); color: var(--cth-accent-ink);\n  font-size: 13px; font-weight: 650; cursor: pointer;\n}\n.cth .cth-sent { display: flex; flex-direction: column; align-items: flex-start; gap: 8px; padding: 6px 0 2px; }\n.cth .cth-sent-mark {\n  display: inline-flex; align-items: center; justify-content: center; width: 32px; height: 32px; border-radius: 50%;\n  background: var(--cth-ok); color: #ffffff;\n}\n.cth .cth-sent-mark .cth-icon { stroke-width: 2.2; }\n.cth .cth-sent-title { display: block; font-size: 15px; font-weight: 650; letter-spacing: -0.01em; }\n.cth .cth-sent-actions { display: flex; align-items: center; gap: 16px; margin-top: 4px; }\n.cth .cth-list { display: flex; flex-direction: column; }\n.cth .cth-row { display: block; border-top: 1px solid var(--cth-line); }\n.cth .cth-row:first-child { border-top: 0; }\n.cth .cth-row-main { display: grid; grid-template-columns: minmax(0, 1fr) auto; align-items: center; gap: 2px 10px; padding: 10px 4px; border-radius: 8px; }\n.cth a.cth-row-main { cursor: pointer; }\n.cth a.cth-row-main:hover { background: var(--cth-fill); }\n.cth .cth-row-summary { display: block; grid-column: 1; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; font-size: 13px; font-weight: 600; }\n.cth .cth-row-meta { display: block; grid-column: 1; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; color: var(--cth-muted); font-size: 12px; font-variant-numeric: tabular-nums; }\n.cth .cth-row-note { display: block; grid-column: 1 / -1; margin-top: 4px; color: var(--cth-muted); font-size: 12px; line-height: 1.4; }\n.cth .cth-status {\n  display: inline-block; grid-column: 2; grid-row: 1 / span 2; padding: 3px 9px; border-radius: 999px;\n  background: var(--cth-received-bg); color: var(--cth-received-ink); font-size: 11.5px; font-weight: 650; white-space: nowrap;\n}\n.cth .cth-status[data-status=\"in_progress\"] { background: var(--cth-progress-bg); color: var(--cth-progress-ink); }\n.cth .cth-status[data-status=\"resolved\"] { background: var(--cth-resolved-bg); color: var(--cth-resolved-ink); }\n.cth .cth-empty { display: flex; flex-direction: column; align-items: center; gap: 8px; padding: 22px 0 14px; color: var(--cth-muted); font-size: 13px; text-align: center; }\n.cth .cth-live { position: absolute; display: block; width: 1px; height: 1px; overflow: hidden; clip-path: inset(50%); white-space: nowrap; }\n@media (max-width: 480px) {\n  .cth .cth-panel, .cth[data-position] .cth-panel {\n    left: 0; right: 0; bottom: var(--cth-sheet-lift, 0px); width: auto; max-width: none;\n    max-height: calc(100vh - 48px - var(--cth-sheet-lift, 0px)); max-height: calc(100dvh - 48px - var(--cth-sheet-lift, 0px));\n    padding-bottom: env(safe-area-inset-bottom, 0px); border-radius: 18px 18px 0 0;\n  }\n  .cth .cth-text { font-size: 16px; }\n}\n@media (prefers-reduced-motion: no-preference) {\n  .cth .cth-panel { animation: cth-in 0.24s cubic-bezier(0.2, 0.8, 0.2, 1); transform-origin: bottom right; }\n  .cth[data-position=\"bottom-left\"] .cth-panel { transform-origin: bottom left; }\n  .cth :is(.cth-tool, .cth-tab, .cth-x, .cth-send) { transition: background-color 0.16s ease, color 0.16s ease, opacity 0.16s ease; }\n  @keyframes cth-in { from { opacity: 0; transform: translateY(4px) scale(0.98); } }\n}\n";

package/dist/types/help/panel.d.ts

@@ -0,0 +1,4 @@
+import { type PanelHost, type PanelView } from "./pill.js";
+/** "Just now", "5 minutes ago", "Yesterday", then the date. */
+export declare function whenWords(iso: string, now: number): string;
+export declare function createPanel(host: PanelHost): PanelView;

package/dist/types/help/pill-styles.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The pill's CSS, and the ground the panel's CSS stands on (`./panel-styles.ts`): the reset and the colours.
+ *
+ * The pill lives in the page's own document, not in a shadow tree: a toolbar on the same page reads keys
+ * from `window` and tells "the person is typing" by the event's target, which a shadow tree would hide from
+ * it. So every element here is first cleared of whatever the host's stylesheet gives its kind (`all: unset`)
+ * and then styled by a rule under `.cth`, which outranks a host rule written for a bare element.
+ */
+/** Above the page, below the comment toolbar (2147483000) and its capture UI. */
+export declare const HELP_Z_INDEX = 2147482000;
+export declare const HELP_BASE_CSS = "\n.cth {\n  all: initial; display: contents;\n  --cth-card: #ffffff; --cth-ink: #141416; --cth-muted: #62625e; --cth-line: #e2e2dd; --cth-ring: rgba(20, 20, 30, 0.08);\n  --cth-fill: #f3f3f0; --cth-fill-2: #e9e9e4; --cth-track: #e9e9e4; --cth-raised: #ffffff; --cth-field: #ffffff;\n  --cth-accent: #2563eb; --cth-accent-ink: #ffffff; --cth-link: #1d4ed8; --cth-danger: #b42318; --cth-ok: #1f7a3d;\n  --cth-received-bg: #eeeeea; --cth-received-ink: #4a4a47; --cth-progress-bg: #fff1cc; --cth-progress-ink: #7a4f00;\n  --cth-resolved-bg: #e0f4e6; --cth-resolved-ink: #17612f;\n  --cth-shadow: 0 2px 6px rgba(20, 20, 30, 0.08), 0 16px 48px rgba(20, 20, 30, 0.18);\n  --cth-pill-shadow: 0 1px 2px rgba(20, 20, 30, 0.08), 0 8px 24px rgba(20, 20, 30, 0.14);\n  --cth-edge: 20px;\n  color: var(--cth-ink);\n  font: 400 13px/1.4 -apple-system, BlinkMacSystemFont, \"SF Pro Text\", \"Segoe UI\", Inter, system-ui, sans-serif;\n  letter-spacing: -0.005em; -webkit-font-smoothing: antialiased; text-align: left; direction: ltr;\n}\n.cth[data-theme=\"dark\"] {\n  --cth-card: #1c1c20; --cth-ink: #f5f5f7; --cth-muted: #a8a8ad; --cth-line: rgba(255, 255, 255, 0.14);\n  --cth-ring: rgba(255, 255, 255, 0.1); --cth-fill: rgba(255, 255, 255, 0.08); --cth-fill-2: rgba(255, 255, 255, 0.13);\n  --cth-track: rgba(0, 0, 0, 0.34); --cth-raised: #3a3a41; --cth-field: #131316; --cth-link: #8ab4ff;\n  --cth-danger: #ff8a80; --cth-ok: #1f7a3d; --cth-received-bg: rgba(255, 255, 255, 0.1); --cth-received-ink: #d7d7dc;\n  --cth-progress-bg: rgba(255, 190, 60, 0.18); --cth-progress-ink: #ffd27a; --cth-resolved-bg: rgba(70, 200, 110, 0.18);\n  --cth-resolved-ink: #8fe0a8; --cth-shadow: 0 2px 6px rgba(0, 0, 0, 0.4), 0 16px 48px rgba(0, 0, 0, 0.5);\n  --cth-pill-shadow: 0 1px 2px rgba(0, 0, 0, 0.4), 0 8px 24px rgba(0, 0, 0, 0.45);\n}\n@media (prefers-color-scheme: dark) { .cth[data-theme=\"auto\"] {\n  --cth-card: #1c1c20; --cth-ink: #f5f5f7; --cth-muted: #a8a8ad; --cth-line: rgba(255, 255, 255, 0.14);\n  --cth-ring: rgba(255, 255, 255, 0.1); --cth-fill: rgba(255, 255, 255, 0.08); --cth-fill-2: rgba(255, 255, 255, 0.13);\n  --cth-track: rgba(0, 0, 0, 0.34); --cth-raised: #3a3a41; --cth-field: #131316; --cth-link: #8ab4ff;\n  --cth-danger: #ff8a80; --cth-ok: #1f7a3d; --cth-received-bg: rgba(255, 255, 255, 0.1); --cth-received-ink: #d7d7dc;\n  --cth-progress-bg: rgba(255, 190, 60, 0.18); --cth-progress-ink: #ffd27a; --cth-resolved-bg: rgba(70, 200, 110, 0.18);\n  --cth-resolved-ink: #8fe0a8; --cth-shadow: 0 2px 6px rgba(0, 0, 0, 0.4), 0 16px 48px rgba(0, 0, 0, 0.5);\n  --cth-pill-shadow: 0 1px 2px rgba(0, 0, 0, 0.4), 0 8px 24px rgba(0, 0, 0, 0.45);\n} }\n.cth :is(a, button, div, form, h2, header, img, label, li, p, section, span, svg, textarea, time, ul) {\n  all: unset; box-sizing: border-box;\n}\n.cth :focus-visible { outline: 2px solid var(--cth-accent); outline-offset: 2px; }\n.cth .cth-pill {\n  position: fixed; z-index: 2147482000;\n  bottom: calc(var(--cth-edge) + env(safe-area-inset-bottom, 0px) + var(--cth-lift, 0px));\n  display: inline-flex; align-items: center; gap: 8px; height: 40px; max-width: calc(100vw - 2 * var(--cth-edge));\n  padding: 0 16px 0 9px; border-radius: 999px; background: var(--cth-card); color: var(--cth-ink);\n  box-shadow: 0 0 0 1px var(--cth-ring), var(--cth-pill-shadow);\n  font-size: 13px; font-weight: 600; white-space: nowrap; cursor: pointer;\n  -webkit-user-select: none; user-select: none; -webkit-tap-highlight-color: transparent;\n}\n.cth[data-position=\"bottom-right\"] .cth-pill { right: calc(var(--cth-edge) + env(safe-area-inset-right, 0px)); }\n.cth[data-position=\"bottom-left\"] .cth-pill { left: calc(var(--cth-edge) + env(safe-area-inset-left, 0px)); }\n.cth .cth-pill:hover { background: var(--cth-raised); box-shadow: 0 0 0 1px var(--cth-ring), var(--cth-shadow); }\n.cth .cth-mark {\n  display: inline-flex; flex: none; align-items: center; justify-content: center; width: 22px; height: 22px;\n  border-radius: 50%; background: var(--cth-accent); color: var(--cth-accent-ink); font-size: 13px; font-weight: 700;\n}\n.cth .cth-label { display: block; overflow: hidden; text-overflow: ellipsis; }\n.cth .cth-note {\n  position: fixed; z-index: 2147482000;\n  bottom: calc(var(--cth-edge) + 50px + env(safe-area-inset-bottom, 0px) + var(--cth-lift, 0px));\n  display: block; max-width: 240px; padding: 8px 12px; border-radius: 10px; background: var(--cth-ink);\n  color: var(--cth-card); font-size: 12px;\n}\n.cth[data-position=\"bottom-right\"] .cth-note { right: var(--cth-edge); }\n.cth[data-position=\"bottom-left\"] .cth-note { left: var(--cth-edge); }\n@media (prefers-reduced-motion: no-preference) {\n  .cth .cth-pill { transition: box-shadow 0.2s ease, transform 0.2s ease, bottom 0.2s ease; }\n  .cth .cth-pill:active { transform: scale(0.97); }\n  .cth .cth-pill[aria-busy=\"true\"] .cth-mark { animation: cth-wait 0.9s ease-in-out infinite alternate; }\n  @keyframes cth-wait { to { opacity: 0.45; } }\n}\n";

package/dist/types/help/pill.d.ts

@@ -0,0 +1,44 @@
+/**
+ * The pill: all that `help.js` puts on a page before anyone asks for help. A labelled button fixed to a
+ * bottom corner, a few kilobytes with its CSS, no React.
+ *
+ * The panel it opens (`./panel.ts`, served as `help-panel.js`) and the capture script (`../capture`, served
+ * as `capture.js`) are fetched the first time the pointer rests on the pill, it takes focus, or it is opened.
+ *
+ * There is one pill per page. `mount` called again changes its options and keeps the pill, an open panel and
+ * a draft; every handle `mount` has returned speaks for that one pill.
+ */
+import type { CommentToolCaptureApi } from "../capture/api.js";
+import { type CommentToolHelpApi, type HelpOptions } from "./types.js";
+/** What the panel is given: where to draw, what the host said, and the capture tools. */
+export type PanelHost = {
+    /** The pill's root. The panel is appended to it, after the pill. */
+    root: HTMLElement;
+    pill: HTMLButtonElement;
+    /** The host's options as they are now. */
+    options(): HelpOptions;
+    /** The capture script's API, fetched when it is not on the page yet. Rejects when it cannot be. */
+    capture(): Promise<CommentToolCaptureApi>;
+    /** Hides the pill and the panel while a capture is open, and brings them back. */
+    hide(hidden: boolean): void;
+};
+/** The panel, as the pill drives it. Additive only: a page may hold a `help.js` older than its panel. */
+export type PanelView = {
+    readonly isOpen: boolean;
+    open(): void;
+    close(): void;
+    /** The host's options changed. */
+    update(): void;
+    destroy(): void;
+};
+export type HelpPanelApi = {
+    create(host: PanelHost): PanelView;
+};
+export type HelpEnvironment = {
+    /** Where this script's siblings are served: `<service>/v1/toolbar/`. */
+    base: string;
+    /** Adds a classic script to the page. Default: a `<script async>` in `<head>`. */
+    loadScript?: (url: string) => Promise<void>;
+};
+export declare function ensureHelpStyles(id: string, css: string): void;
+export declare function createHelp(environment: HelpEnvironment): CommentToolHelpApi;

package/dist/types/help/react.d.ts

@@ -0,0 +1,12 @@
+import type { HelpOptions } from "./types.js";
+export type HelpPillProps = HelpOptions & {
+    /**
+     * Comment Tool's address: `https://comment-tool.example.com`. Left out, it is the one the session route
+     * names, which is how `<CommentToolbar>` learns it. That route says so only to people the comment toolbar
+     * is on for, so a host that shows the pill to everyone gives the address here.
+     */
+    serviceUrl?: string;
+    /** The session route asked when `serviceUrl` is left out. Default `/api/comment-service/session`. */
+    sessionPath?: string;
+};
+export declare function HelpPill(props: HelpPillProps): null;

package/dist/types/help/requests.d.ts

@@ -0,0 +1,2 @@
+import { type SupportRequests } from "./types.js";
+export declare function supportRequestsAt(url: string): SupportRequests;

package/dist/types/help/types.d.ts

@@ -0,0 +1,119 @@
+/**
+ * "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 declare class HelpError extends Error {
+    readonly name = "HelpError";
+}
+export declare function isHelpError(error: unknown): error is Error;

package/dist/types/help/wire.d.ts

@@ -0,0 +1,61 @@
+/**
+ * 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 declare const HELP_LIMITS: {
+    /** A request's own id: letters, digits, `.`, `_`, `:` and `-`. */
+    readonly id: 100;
+    readonly message: 4000;
+    readonly images: 3;
+    /** One picture, before base64. */
+    readonly imageBytes: number;
+    readonly name: 200;
+    readonly label: 200;
+    readonly url: 1000;
+    /** "Your requests" shows at most this many. */
+    readonly listed: 50;
+};
+/** The whole body: three pictures as base64, the text, and room for the rest. */
+export declare const HELP_BODY_BYTES: number;
+export declare const HELP_ID: RegExp;
+/** The picture types a request may carry. Checked on the server against each file's first bytes. */
+export declare const HELP_IMAGE_TYPES: readonly ["image/png", "image/jpeg", "image/webp"];
+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/dist/types/native-wire.d.ts

@@ -0,0 +1,63 @@
+/**
+ * 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 declare const APP_ORIGIN_HEADER = "x-comment-service-origin";
+/** The host the app origin uses: `<scheme>://app`. */
+export declare const APP_ORIGIN_HOST = "app";
+/** Most schemes an environment may list. */
+export declare const MAX_APP_SCHEMES = 10;
+/** Whether `value` is a scheme an environment may list (lowercase, no `:`, not a web or system scheme). */
+export declare function isAppScheme(value: string): boolean;
+/** A list of app schemes as typed (trimmed, lowercased, deduped), or what is wrong with it. */
+export declare function normalizeAppSchemes(value: unknown): {
+    readonly ok: true;
+    readonly schemes: string[];
+} | {
+    readonly ok: false;
+    readonly message: string;
+};
+/** `my-app-staging` → `my-app-staging://app`. */
+export declare function appOrigin(scheme: string): string;
+/**
+ * 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 declare function appOriginScheme(value: string): string | null;
+/** The app URL a native thread stores: `<scheme>://app` + route. `route` starts with `/`. */
+export declare function appScreenUrl(scheme: string, route: string): string;
+/**
+ * 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 declare function parseAppUrl(value: string): {
+    scheme: string;
+    pathname: string;
+} | null;
+/** Where the sign-in callback returns a native client: `<scheme>://app/app-comments/auth`. */
+export declare function appAuthReturnUrl(scheme: string): string;

package/dist/types/native.d.ts

@@ -0,0 +1,43 @@
+/**
+ * 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";
+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";
+export { ReplayBuffer, consoleText, parseReplay, redactSecretSearchParams, replayLine, replayStamp, } from "./runtime/replay-model.js";
+export type { ReplayBufferOptions, ReplayClip, ReplayDraft, ReplayEvent, ReplayFile, } from "./runtime/replay-model.js";
+export * from "./debug-context.js";
+export { argText, createDebugCore, errorOf, type DebugCaptureStats, type DebugCore, type RequestReaders, } from "./runtime/debug-context-core.js";
+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";
+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";
+export { decibels, dictationPrompt, insertDictated, meterLevel, voiceRecordingName, } from "./runtime/dictation-model.js";
+export { agoPhrase, fromYou, involved, isMine, leadSentence, mentionOfYou, namesYou, versionsOf, } from "./runtime/thread-model.js";
+export { ATTACHMENT_MAX_BYTES, ATTACHMENT_MAX_FILES, ATTACHMENT_TYPES, attachmentStamp, formatSize, isReplayFile, } from "./runtime/attachment-model.js";
+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";
+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";
+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/dist/types/react.d.ts

@@ -1,2 +1,9 @@
-export { CommentToolbar, type ToolbarSource } from "./runtime/loader.js";
+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/dist/types/replay.d.ts

@@ -0,0 +1,6 @@
+/**
+ * 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";