pipeup 0.5.4 → 0.7.0-beta.1

package/dist/types/core.d.ts

@@ -1,4 +1,6 @@
-export declare const VERSION = "0.5.4";
+export declare const VERSION = "0.7.0-beta.1";
+/** The day this version was made (set with the version): Pipeup says so, once, in the console when it is over a year old. */
+export declare const BUILT = "2026-10-13";
 export { PipeupDocument, UnsavedChangeError, type Listener, type OpenOptions } from "./document";
 export { DEFAULT_PROFILE_NAME, MemoryStore, loadOrCreateProfile, type OpStore, type Profile, } from "./storage/store";
 export { IndexedDbStore } from "./storage/indexeddb";

package/dist/types/crypto/portable.d.ts

@@ -0,0 +1,15 @@
+import type { Identity } from "./identity";
+/** A new identity the reviewer can back up, and its recovery code. */
+export declare function makePortable(): Promise<{
+    identity: Identity;
+    code: string;
+}>;
+/** The recovery code of an identity that was made portable; null for an ordinary one, which can't be exported. */
+export declare function codeOf(identity: Identity): Promise<string | null>;
+export type CodeProblem = "shape" | "mistake";
+/** The identity a recovery code stands for, or what is wrong with the code, in a word the UI turns into a sentence. */
+export declare function identityFromCode(text: string): Promise<{
+    identity: Identity;
+} | {
+    problem: CodeProblem;
+}>;

package/dist/types/document.d.ts

@@ -1,5 +1,5 @@
 import { type Identity } from "./crypto/identity";
-import type { Anchor, SignedOp, Thread } from "./model/types";
+import type { Anchor, Mention, SignedOp, Thread } from "./model/types";
 import type { OpStore } from "./storage/store";
 export interface OpenOptions {
     doc: string;
@@ -42,10 +42,26 @@ export declare class PipeupDocument {
     /** Every verified op this browser holds, as {body, sig}. A new array each call; don't change the ops. */
     ops(): readonly SignedOp[];
     onChange(fn: Listener): () => void;
-    comment(anchor: Anchor, text: string): Promise<string>;
-    reply(parentId: string, text: string): Promise<string>;
-    edit(commentId: string, text: string): Promise<void>;
+    comment(anchor: Anchor, text: string, mentions?: Mention[]): Promise<string>;
+    reply(parentId: string, text: string, mentions?: Mention[]): Promise<string>;
+    edit(commentId: string, text: string, mentions?: Mention[]): Promise<void>;
     remove(commentId: string): Promise<void>;
+    /** Shares a way to reach this reviewer (an email address, or `gh:<GitHub name>`) with everyone who has the comments. */
+    contact(value: string): Promise<void>;
+    /** Stops sharing it: people who learn of this later won't see it. */
+    uncontact(): Promise<void>;
+    /** The ways people have chosen to be reached, by writer: the latest each shared, unless they stopped sharing. */
+    contacts(): Map<string, string>;
+    /** This reviewer's identity was made portable, so it has a recovery code (an ordinary one can't leave the browser). */
+    get portable(): boolean;
+    /** The recovery code of a portable identity; null for an ordinary one. */
+    identityCode(): Promise<string | null>;
+    /** Marks comments read by this reviewer (one `seen` op each, for those not already marked), so every device knows. */
+    seen(commentIds: readonly string[]): Promise<void>;
+    /** Reacts to a comment with one emoji; reacting twice with the same emoji changes nothing. */
+    react(commentId: string, emoji: string): Promise<void>;
+    /** Takes back this reviewer's own reaction. */
+    unreact(commentId: string, emoji: string): Promise<void>;
     resolve(threadId: string): Promise<void>;
     reopen(threadId: string): Promise<void>;
     /**

package/dist/types/export/agent.d.ts

@@ -0,0 +1,35 @@
+import { type ExportItem, type ExportMeta } from "./format";
+/** One thread as an agent reads it. */
+export interface AgentThread {
+    /** The id to answer a thread by. */
+    id: string;
+    state: "open" | "addressed" | "resolved";
+    where: string;
+    /** The page's `data-pipeup-id` for the block, when it has one. */
+    element?: string;
+    quote?: string;
+    pin?: string;
+    addressed?: {
+        note: string;
+        by: string;
+    };
+    comments: {
+        id: string;
+        by: string;
+        agent: boolean;
+        at: string;
+        text: string;
+        /** Who reacted with what; absent when nobody did. */
+        reactions?: {
+            emoji: string;
+            by: string[];
+        }[];
+    }[];
+}
+export interface AgentComments {
+    /** The same Markdown as Copy as Markdown. */
+    markdown: string;
+    threads: AgentThread[];
+}
+/** The page's comments as an agent reads them: the Markdown, and the threads as data. */
+export declare function agentComments(items: ExportItem[], meta: ExportMeta): AgentComments;

package/dist/types/export/format.d.ts

@@ -1,5 +1,5 @@
 import type { Location } from "../anchor/locate";
-import type { Thread } from "../model/types";
+import type { Comment, Thread } from "../model/types";
 export type CopyAs = "ai" | "text";
 export interface ExportItem {
     thread: Thread;
@@ -9,9 +9,13 @@ export interface ExportMeta {
     title: string;
     url: string;
     exportedAt: Date;
+    /** Also the resolved threads (default: open ones only). */
+    all?: boolean;
 }
 export declare function formatAgo(at: number, now: number): string;
 /** Copy one thread — always the whole thread. */
 export declare function copyThread(item: ExportItem, as: CopyAs, page: string, now: number): string;
 /** Copy every open thread, in the order given (page or slide order). */
 export declare function copyAll(items: ExportItem[], as: CopyAs, meta: ExportMeta): string;
+/** A comment's reactions as one line: "👍 2 (Sam, Red Fox) · ❤️ 1 (Lee)"; empty when nobody reacted. */
+export declare function reactionsLine(c: Comment): string;

package/dist/types/index.d.ts

@@ -1,4 +1,7 @@
 export * from "./core";
-export { mount, type MountOptions, type PipeupInstance } from "./ui/mount";
-export { ADDON_API, addons, use, type AddonDocument, type AddonHost, type AddonInfo, type Capability, type ComposerHandle, type ComposerTool, type Dictation, type ItemHandle, type MenuItem, type NetworkUse, type Off, type PanelHandle, type PanelOptions, type PipeupAddon, type Status, type Teardown, type UiSnapshot, } from "./ui/addons";
+export { comments, mount, type MountOptions, type PipeupInstance } from "./ui/mount";
+export type { Appearance } from "./ui/legible";
+export { setPeople, type Person } from "./ui/mentions";
+export { ADDON_API, addons, use, type AddonDocument, type AddonHost, type AddonInfo, type Capability, type ComposerHandle, type ComposerTool, type Dictation, type ItemHandle, type ListNote, type ReactionPicker, type MenuItem, type NetworkUse, type Off, type PanelHandle, type PanelOptions, type PipeupAddon, type Status, type Teardown, type UiSnapshot, } from "./ui/addons";
+export { type AgentComments, type AgentThread } from "./export/agent";
 export { onReveal, setViewState, type SlideHook, type ViewState } from "./ui/here";

package/dist/types/model/animals.d.ts

@@ -13,10 +13,16 @@ export declare const animalOf: (author: string) => number;
 export declare const colourOf: (author: string) => number;
 /** A reviewer's animal in its colour, such as "Red Fox". */
 export declare const animalName: (author: string) => string;
-/** What to call a comment's writer: their name, or their animal until they add one. */
+/** A short, stable tag from a reviewer's key ("4F2A"), shown beside a name only where two people share it. */
+export declare function shortId(author: string): string;
+/**
+ * What to call a comment's writer: their name, or their animal until they add one; with their short tag when another
+ * person in the document has the same name. An agent shows as "Claude", not "AI assistant · Claude".
+ */
 export declare const nameOf: (c: {
     author: string;
     name: string;
+    alike?: boolean;
 }) => string;
 /** The name an assistant's replies carry: a person can't choose it, and a reply under it is drawn as an AI's. */
 export declare const AI_NAME = "AI assistant";

package/dist/types/model/fold.d.ts

@@ -1,4 +1,6 @@
 import type { SignedOp, Thread } from "./types";
+/** At most this many different emoji on one comment, so a comment can't be flooded; later ones are ignored. */
+export declare const MAX_REACTIONS = 12;
 /**
  * Turns ops into threads. Deterministic: peers holding the same ops see the same threads,
  * whatever order the ops arrived in. Assumes ops are already well formed and authentic.

package/dist/types/model/ops.d.ts

@@ -18,7 +18,12 @@ export declare const LIMITS: {
     readonly viewEntries: 16;
     readonly viewKey: 64;
     readonly viewValue: 200;
+    readonly mentions: 20;
 };
+/** Who a mention names: a writer's key, or a person the page or an add-on supplied (`host:<id>`, `gh:<name>`). */
+/** A way to reach someone that they chose to share: an email address, or a GitHub name (`gh:octocat`). */
+export declare const CONTACT: RegExp;
+export declare const isEmoji: (s: unknown) => s is string;
 export declare function signOp(body: OpBody, identity: Identity): Promise<SignedOp>;
 export declare function isAnchor(a: unknown): boolean;
 /** Shape checks that need nothing but the op itself. */

package/dist/types/model/types.d.ts

@@ -23,7 +23,13 @@ export interface Anchor {
     /** A short plain-text excerpt of what the reviewer saw. */
     snapshot: string;
 }
-export type OpKind = "create" | "reply" | "edit" | "delete" | "resolve" | "reopen";
+export type OpKind = "create" | "reply" | "edit" | "delete" | "resolve" | "reopen" | "addressed" | "react" | "unreact" | "seen" | "contact" | "uncontact";
+/** A person named in a comment's words: `text.slice(start, end)` is the "@Name"; `ref` says who (a key, or a supplied person). */
+export interface Mention {
+    start: number;
+    end: number;
+    ref: string;
+}
 export interface OpBody {
     v: 1;
     id: string;
@@ -31,9 +37,12 @@ export interface OpBody {
     doc: string;
     /** Thread id: the id of the thread's create op. */
     thread: string;
-    /** reply: the comment answered. edit/delete: the comment changed. */
+    /** reply: the comment answered. edit/delete: the comment changed. react/unreact: the comment reacted to. */
     target?: string;
+    /** The words; for react and unreact, the one emoji. */
     text?: string;
+    /** create, reply and edit: the people named in the words. Signed with them, so it can't be altered. */
+    mentions?: Mention[];
     /** create only. */
     anchor?: Anchor;
     /** Author's public key. */
@@ -61,10 +70,34 @@ export interface Comment {
     edited: boolean;
     deleted: boolean;
     replies: Comment[];
+    /** Emoji people reacted with, in the order they first appeared; none for a comment nobody reacted to. */
+    reactions: Reaction[];
+    /** Another person in the document has the same name: show this writer's short tag too. */
+    alike?: true;
+    /** The people named in the words; absent when none. */
+    mentions?: Mention[];
+    /** The writers who have marked this comment seen (their `seen` ops); absent when none. */
+    seenBy?: string[];
+}
+export interface Reaction {
+    emoji: string;
+    /** Who gave it, in the order they did; the name is "" for someone who hasn't added one. */
+    by: {
+        author: string;
+        name: string;
+        alike?: true;
+    }[];
 }
 export interface Thread {
     id: string;
     anchor: Anchor;
     root: Comment;
     resolved: boolean;
+    /** An agent has said it dealt with this thread. Not resolved: a person closes it, and reopening clears it. */
+    addressed?: {
+        text: string;
+        author: string;
+        name: string;
+        at: number;
+    };
 }

package/dist/types/ui/addons.d.ts

@@ -7,7 +7,7 @@ import type { ViewState } from "./here";
 export declare const ADDON_API = 1;
 export type Teardown = () => void;
 export type Off = () => void;
-export type Capability = "sync" | "menu" | "notify" | "note" | "composer" | "panel" | "styles" | "status" | "overlay" | "here" | "sign";
+export type Capability = "sync" | "menu" | "notify" | "note" | "composer" | "panel" | "styles" | "status" | "overlay" | "here" | "sign" | "listnote" | "reactions";
 export interface NetworkUse {
     when: "never" | "after-consent" | "page-configured";
     /** Hosts; "page" is an address the page names. */
@@ -47,6 +47,8 @@ export interface AddonDocument {
     readonly name: string;
     threads(): readonly Thread[];
     ops(): readonly SignedOp[];
+    /** The ways people chose to be reached (an email address, or `gh:<name>`), by writer's key. */
+    contacts(): ReadonlyMap<string, string>;
     onChange(fn: Listener): Off;
 }
 export interface MenuItem {
@@ -83,6 +85,14 @@ export interface Status {
         view?: ViewState;
     }[];
 }
+/** A quiet line under the All comments header: words, and optionally one text button ("Check for replies"). */
+export interface ListNote {
+    text: string;
+    action?: {
+        label: string;
+        run(): Promise<void>;
+    };
+}
 export interface UiSnapshot {
     /** Comments are showing. */
     shown: boolean;
@@ -94,6 +104,8 @@ export interface UiSnapshot {
     /** null: not writing; "": the new-comment box; else that thread's reply line. */
     writing: string | null;
 }
+import type { ReactionPicker } from "./reactions";
+export type { ReactionPicker } from "./reactions";
 export type { ComposerHandle, ComposerTool, Dictation } from "./composer";
 export interface AddonHost {
     readonly api: number;
@@ -126,6 +138,10 @@ export interface AddonHost {
     openPanel(content: Node, options: PanelOptions): PanelHandle;
     addStyles(css: string): Off;
     setStatus(status: Status | null): void;
+    /** Shows (or, with null, removes) this add-on's line under the All comments header. */
+    setListNote(note: ListNote | null): void;
+    /** Offers the full set of emoji for reactions: the quick row then ends with a button that opens it. */
+    setReactionPicker(picker: ReactionPicker | null): void;
     overlay(): HTMLElement;
     onFrame(fn: () => void): Off;
     /** What a comment on `at` would save. */
@@ -156,6 +172,10 @@ export declare class Surface {
     private readonly marked;
     private paint;
     readonly statuses: Map<string, Status>;
+    readonly listNotes: Map<string, ListNote>;
+    /** The emoji picker an add-on brought, if any (the latest to set one). */
+    picker: ReactionPicker | null;
+    private pickerOwner;
     private readonly toolList;
     private readonly frames;
     private readonly uis;
@@ -182,6 +202,7 @@ export declare class Surface {
     private repaint;
     /** Sets (or, with null, removes) one add-on's note or status. */
     setIn<T>(map: Map<string, T>, id: string, value: T | null): void;
+    setPicker(id: string, picker: ReactionPicker | null): void;
     addTool(id: string, tool: ComposerTool): Off;
     /** Comments are closed: only the control shows, so a notice waits for the reviewer to open Pipeup. */
     private closed;

package/dist/types/ui/animals.d.ts

@@ -11,7 +11,7 @@ export declare const faceOf: (author: string, name: string) => string;
  * A squircle avatar: the writer's animal drawn in its colour on a tint of it, or their initial in the same colours once they have a
  * name. Decorative: the name is always written beside it, so screen readers skip it.
  */
-export declare function avatar(author: string, name: string, busy?: boolean): HTMLElement;
+export declare function avatar(author: string, name: string): HTMLElement;
 /** Removes an avatar that a new one is easing in over, once it is covered; never leaves its spot empty. */
 export declare function retire(el: HTMLElement, done?: () => void): void;
 /** Eases a new avatar in once it is on the page (it starts faded and slightly small; .in brings it to rest). */

package/dist/types/ui/app.d.ts

@@ -1,12 +1,18 @@
 import { type PipeupDocument } from "../document";
+import type { Identity } from "../crypto/identity";
 import type { Ctx, UiState, View } from "./context";
+import { type Appearance } from "./legible";
 export interface AppOptions {
     doc: PipeupDocument;
     root: Element;
     onName(name: string): Promise<void>;
+    /** Keeps another identity for this browser (a new portable one, or one restored from a recovery code). */
+    onIdentity(identity: Identity): Promise<void>;
 }
 export interface App {
     readonly ctx: Ctx;
+    /** How Pipeup looks and why: its look, who chose it, and what the page's styles do to it. */
+    appearance(): Appearance;
     destroy(): void;
 }
 /** Documents with free space beside them get a column; everything else gets bubbles and popovers. */

package/dist/types/ui/composer.d.ts

@@ -1,3 +1,5 @@
+import { type Person } from "./mentions";
+import type { Mention } from "../model/types";
 export interface ComposerOptions {
     label: string;
     /** A new comment, or a reply in `thread()`. */
@@ -5,8 +7,11 @@ export interface ComposerOptions {
     thread?: () => string;
     /** Something to show before the line instead, such as the writer's avatar. */
     before?: Node;
-    onSend(text: string): Promise<void> | void;
+    /** `mentions`: the people named in the words, found after trimming. */
+    onSend(text: string, mentions: Mention[]): Promise<void> | void;
     onCancel?(): void;
+    /** Who can be mentioned with `@`; without it, `@` is just a character. */
+    people?(): Person[];
 }
 export interface Composer {
     element: HTMLElement;

package/dist/types/ui/context.d.ts

@@ -1,10 +1,11 @@
 import type { Resolved } from "../anchor/resolve";
 import type { PipeupDocument } from "../document";
 import type { CopyAs, ExportItem } from "../export/format";
-import type { Anchor, Thread } from "../model/types";
+import type { Anchor, Mention, Thread } from "../model/types";
 import type { Surface } from "./addons";
 import type { DraftBox } from "./draft-view";
 import type { Here } from "./here";
+import type { Person } from "./mentions";
 import type { ThreadActions } from "./thread-view";
 /** A comment being written: what it's on, and where that is now. */
 export interface Draft {
@@ -19,6 +20,8 @@ export interface UiState {
     active: string | null;
     hot: string | null;
     showResolved: boolean;
+    /** All comments shows only the threads that name this reviewer. */
+    mine: boolean;
     /** Comments are out of sight: comment mode is off and All comments is closed. */
     hidden: boolean;
     mode: "column" | "bubbles";
@@ -41,12 +44,19 @@ export interface View {
 export interface MenuActions {
     copyAll(as: CopyAs): Promise<void>;
     toggleResolved(): void;
+    toggleMine(): void;
+    /** Opens the dialog for making the identity portable, backing it up, or using one that was backed up. */
+    identity(): void;
     rename(name: string): Promise<void>;
     /** The reviewer's name; "" until they add one. */
     name(): string;
     /** Every thread in page order, with where each one is. */
     all(): ExportItem[];
+    /** The reviewer's choice of look, kept in their browser: Automatic follows the author, then the page. */
+    look(): LookChoice;
+    setLook(choice: LookChoice): void;
 }
+export type LookChoice = "auto" | "light" | "dark";
 /** What every view shares: the document, state, and the few things views can ask the app to do. */
 export interface Ctx {
     readonly doc: PipeupDocument;
@@ -94,7 +104,11 @@ export interface Ctx {
     keepCaret(fn: () => void): void;
     /** Goes back to the open draft: to its slide or view if that has gone, then focus and the caret into it. */
     backToDraft(): void;
-    postDraft(text: string): Promise<void>;
+    postDraft(text: string, mentions?: Mention[]): Promise<void>;
+    /** This reviewer has read the comments in `t` that name them: marks them seen, so every device knows. */
+    seen(t: Thread): void;
+    /** Who can be mentioned with `@`: people in this document, agents the page lists, and people supplied. */
+    people(): Person[];
     cancelDraft(): void;
     /** Turns comment mode on or off; comments show while it is on. `keys`: from the keyboard (the block cursor starts). */
     setCommenting(on: boolean, keys?: boolean): void;

package/dist/types/ui/draft-view.d.ts

@@ -1,4 +1,6 @@
+import type { Mention } from "../model/types";
 import type { Ctx, Draft } from "./context";
+import type { Person } from "./mentions";
 export interface DraftOptions {
     /** What the comment is on: a quote or an element label. */
     label: string;
@@ -8,8 +10,10 @@ export interface DraftOptions {
     name(): string;
     /** Saves a new name (the same path as the menu's Your name). */
     rename(name: string): Promise<void>;
-    onSend(text: string): Promise<void>;
+    onSend(text: string, mentions: Mention[]): Promise<void>;
     onCancel(): void;
+    /** Who can be mentioned with `@`. */
+    people?(): Person[];
 }
 export interface DraftBox {
     element: HTMLElement;

package/dist/types/ui/highlights.d.ts

@@ -6,6 +6,8 @@ export interface PageSheet {
     gutter(px: number | null): void;
     /** How strongly highlights are painted, 0 to 1. */
     fade(k: number): void;
+    /** Paints the highlights for a dark page (true) or a light one. */
+    dark(on: boolean): void;
     /**
      * Makes room for the All comments panel: a right margin of `px` on the page, easing in and out unless
      * `still`; 0 takes it away (the page eases back, then the rule goes). The width is also published as

package/dist/types/ui/icons.d.ts

@@ -11,7 +11,9 @@ declare const PATHS: {
     readonly shrink: readonly ["M20 10h-6V4M14 10l6-6M4 14h6v6M10 14l-6 6M14 20v-6h6M14 14l6 6M10 4v6H4M10 10L4 4"];
     readonly bubble: readonly ["M20.5 11.5a8 8 0 0 1-11.7 7.1L4 19.8l1.2-4.4A8 8 0 1 1 20.5 11.5z"];
     readonly close: readonly ["M6 6l12 12M18 6L6 18"];
+    readonly smile: readonly ["M12 3a9 9 0 1 0 0 18a9 9 0 0 0 0-18z", "M8.5 14a4.5 4.5 0 0 0 7 0", "M9 9.6h.01M15 9.6h.01"];
     readonly edit: readonly ["M4 20h4L19 9l-4-4L4 16z"];
+    readonly look: readonly ["M12 3a9 9 0 1 0 0 18a9 9 0 0 0 0-18z", "M12 3v18"];
 };
 export type IconName = keyof typeof PATHS;
 /** Outline icons drawn from constant path data; `stroke` thins or thickens the line (in 24-unit terms). */

package/dist/types/ui/identity.d.ts

@@ -0,0 +1,27 @@
+import type { CodeProblem } from "../crypto/portable";
+export interface IdentityDeps {
+    /** This identity was made portable: it has a recovery code. */
+    portable: boolean;
+    /** The recovery code of a portable identity. */
+    code(): Promise<string | null>;
+    /** Makes a new portable identity, keeps it, and returns its recovery code. */
+    make(): Promise<string>;
+    /** Keeps the identity a code stands for, or says what is wrong with the code. */
+    use(code: string): Promise<CodeProblem | null>;
+    copy(text: string): Promise<void>;
+    /** Starts over with the identity now kept (the page reloads). */
+    reload(): void;
+    /** Whether the comments on this page were written by the current identity (so a change is felt). */
+    hasComments: boolean;
+    /** The way to reach this reviewer they have shared ("" when none), and how to share or stop sharing one. */
+    contact: {
+        value: string;
+        share(value: string): Promise<boolean>;
+        stop(): Promise<void>;
+    };
+}
+/**
+ * A small dialog over the page for what a reviewer can do with their identity: make it portable or back it up (see the
+ * code, copy it, save it as a file), or use one they backed up. Plain words say what each does.
+ */
+export declare function openIdentity(layer: HTMLElement, deps: IdentityDeps): void;

package/dist/types/ui/launcher.d.ts

@@ -1,7 +1,2 @@
 import type { Ctx, View } from "./context";
-/**
- * The comment control: one round button in the corner (the comment icon, or the open count inside a comment
- * bubble) that opens a menu, Comment nearest it. All comments is a panel on the right that stays open while
- * choosing threads reveals them, so every counted thread can be reached.
- */
 export declare function createLauncher(ctx: Ctx): View;

package/dist/types/ui/legible.d.ts

@@ -0,0 +1,27 @@
+import { type Look } from "./theme";
+/** Pipeup's own words and surface in each look, as in the stylesheet (a test keeps the two equal). */
+export declare const PAIRS: Record<Look, [string, string]>;
+export interface Appearance {
+    /** The look Pipeup is showing. */
+    look: Look;
+    /** Who chose it: the reviewer (the Look row), the author (data-pipeup-theme) or what the page shows. */
+    source: "reviewer" | "author" | "page";
+    /** Contrast of Pipeup's words on its own surface, as the page's styles leave it; 3 is the least that reads. */
+    ratio: number;
+    /** The page's styles on <html> that change everything under it, as "property: value". */
+    effects: string[];
+}
+/**
+ * How well Pipeup's words read in `look` when the page fades <html> to `opacity` over its canvas: both the words
+ * and their surface are blended toward the canvas, which is what the eye gets.
+ */
+export declare function reading(look: Look, opacity: number, canvas: number[]): number;
+/**
+ * Looks at what the page's own styles on <html> do to Pipeup, which sits under it: how well Pipeup's words still read
+ * when the page fades <html> over its canvas, and every other effect (filters, blending, transforms, zoom). Pipeup
+ * can't undo any of them from inside, so it reports them; switching look wouldn't help, since fading costs both looks
+ * about the same.
+ */
+export declare function inspect(doc: Document, look: Look, source: Appearance["source"]): Appearance;
+/** The line for the console when the page's styles change how Pipeup looks, or null when they don't. */
+export declare function warning(a: Appearance): string | null;

package/dist/types/ui/mentions.d.ts

@@ -0,0 +1,46 @@
+import type { Comment, Mention, Thread } from "../model/types";
+/** Someone who can be mentioned: `ref` says who (a writer's key, or `host:<id>` / `gh:<name>` for a supplied person). */
+export interface Person {
+    ref: string;
+    name: string;
+    /** An AI agent. */
+    agent?: boolean;
+}
+/** People the page or an add-on supplies (a company's directory, a repository's members), shown in the `@` list. */
+export declare function setPeople(list: readonly Person[]): void;
+export declare const heardPeople: (fn: () => void) => (() => void);
+/**
+ * Everyone who can be mentioned here: the people who have commented or reacted in this document, the agents the page
+ * lists, and the people the page or an add-on supplied; not this reviewer. A person comes once.
+ */
+export declare function peopleFor(threads: readonly Thread[], me: string): Person[];
+/** The `@name` being typed at the end of `before`: where it starts and what has been typed after the `@`. */
+export declare function mentionToken(before: string): {
+    start: number;
+    query: string;
+} | null;
+/** The people matching what was typed: names that start with it first, then names that contain it. */
+export declare function filterPeople(list: readonly Person[], query: string): Person[];
+/**
+ * Where each chosen person is still named in the final words. A person whose `@Name` was edited away is no longer
+ * mentioned; the same name twice takes its places in the order chosen.
+ */
+export declare function locate(text: string, chosen: readonly {
+    label: string;
+    ref: string;
+}[]): Mention[];
+/** Whether a comment names any of `refs`. */
+export declare const names: (c: Comment, refs: readonly string[]) => boolean;
+/** Who the page says this reviewer is (`host:<id>`), so comments naming them there count as naming this reviewer. */
+export declare function setIdentity(who: {
+    id: string;
+} | null): void;
+/** Every way a comment can name this reviewer: their key, and the page's own name for them. */
+export declare const myRefs: (me: string) => string[];
+/** Comments by others that name this reviewer and that they haven't marked seen, with their threads. */
+export declare function unseenMentions(threads: readonly Thread[], me: string): {
+    thread: Thread;
+    comment: Comment;
+}[];
+/** Whether a thread has a comment by someone else naming this reviewer. */
+export declare const mentionsMe: (t: Thread, me: string) => boolean;

package/dist/types/ui/mount.d.ts

@@ -1,6 +1,8 @@
 import { PipeupDocument } from "../document";
 import { type OpStore } from "../storage/store";
 import { type SlideHook } from "./here";
+import { type AgentComments } from "../export/agent";
+import type { Appearance } from "./legible";
 export interface MountOptions {
     /** The area people can comment on. Default: document.body. */
     root?: Element;
@@ -13,10 +15,20 @@ export interface MountOptions {
 }
 export interface PipeupInstance {
     readonly document: PipeupDocument;
+    /** The page's comments, for an agent: open threads, or every thread with `all`. */
+    comments(options?: {
+        all?: boolean;
+    }): AgentComments;
+    /** How Pipeup looks and why (for `pipeup check` and agents): its look, who chose it, and what the page's styles do to it. */
+    appearance(): Appearance;
     flush(): Promise<void>;
     unmount(): void;
 }
 /** Adds Pipeup to the page. Calling it again returns the same instance. */
 export declare function mount(options?: MountOptions): Promise<PipeupInstance>;
+/** The page's comments for an agent that is looking at the page: waits for Pipeup to start, then reads them. */
+export declare function comments(options?: {
+    all?: boolean;
+}): Promise<AgentComments>;
 /** Pages that carry data-pipeup-doc mount themselves, unless data-pipeup-auto="off". */
 export declare function autoMount(): void;

package/dist/types/ui/reactions.d.ts

@@ -0,0 +1,31 @@
+import type { Comment } from "../model/types";
+/** The quick row: what a reviewer can react with at a tap. (The full set of emoji is the emoji add-on's.) */
+export declare const QUICK: readonly ["👍", "❤️", "😂", "🎉", "😮", "🙏"];
+/** The full emoji picker, when an add-on provides one: Pipeup draws the popover, the add-on fills it. */
+export interface ReactionPicker {
+    /** Fills the popover; `pick` hears the chosen emoji. May return a function that tears the picker down. */
+    fill(into: HTMLElement, pick: (emoji: string) => void): void | (() => void);
+    /** The emoji's name, for screen readers. */
+    name(emoji: string): string | undefined;
+}
+/** Opens the picker in a popover beside `anchor`; it closes on a choice, Escape, a click elsewhere or when asked. */
+export declare function openPicker(anchor: HTMLElement, picker: ReactionPicker, pick: (emoji: string) => void): void;
+export interface ReactionOptions {
+    /** The full picker, when an add-on has one: the quick row then ends with a button that opens it. */
+    picker?: ReactionPicker | null;
+    /** This reviewer's key, to mark their own reactions. */
+    me: string;
+    /** Reactions can't be added or taken back on a resolved thread; they still show. */
+    resolved: boolean;
+    /** The quick row is open under this comment. */
+    quick: boolean;
+    /** Gives or takes back a reaction. */
+    react(emoji: string, on: boolean): void;
+    /** Chips and quick buttons already on the page once, so only new ones ease in. */
+    seen: Set<string>;
+}
+/**
+ * What people reacted to a comment with, quietly beneath its words: each emoji with how many gave it (yours marked;
+ * pointing at one says who), and, when asked for, the quick row. Nothing for a comment nobody reacted to.
+ */
+export declare function reactionRow(c: Comment, o: ReactionOptions): HTMLElement | null;