pipeup 0.0.1 → 0.3.1

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

@@ -0,0 +1,70 @@
+export interface TextQuote {
+    exact: string;
+    prefix: string;
+    suffix: string;
+}
+/** Everything needed to find a comment's content again. See design §3. */
+export interface Anchor {
+    /** data-pipeup-id of the nearest marked element, or of the element itself. */
+    id?: string;
+    /** CSS path from the marked element (or the page root) to the target element. '' means the base itself. */
+    path: string;
+    /** Commented text with surrounding context, for text comments. */
+    quote?: TextQuote;
+    /** Position inside the element as fractions of its box, for pins. */
+    point?: {
+        x: number;
+        y: number;
+    };
+    /** Where the reviewer was: slide ("1"-based), tab, route, plus anything the page reports. */
+    view?: Record<string, string>;
+    /** Fingerprint of the commented block's text when the comment was made. */
+    fingerprint: string;
+    /** A short plain-text excerpt of what the reviewer saw. */
+    snapshot: string;
+}
+export type OpKind = "create" | "reply" | "edit" | "delete" | "resolve" | "reopen";
+export interface OpBody {
+    v: 1;
+    id: string;
+    kind: OpKind;
+    doc: string;
+    /** Thread id: the id of the thread's create op. */
+    thread: string;
+    /** reply: the comment answered. edit/delete: the comment changed. */
+    target?: string;
+    text?: string;
+    /** create only. */
+    anchor?: Anchor;
+    /** Author's public key. */
+    author: string;
+    /** Author's display name when the op was made; "" until they add one. */
+    name: string;
+    /** Lamport clock. */
+    clock: number;
+    /** Wall-clock ms, for display only. */
+    at: number;
+}
+export interface SignedOp {
+    body: OpBody;
+    sig: string;
+}
+export interface Comment {
+    id: string;
+    author: string;
+    /** The writer's name: the one on the comment, else the latest they used here; "" while they have none. */
+    name: string;
+    /** The comment's own op carried no name (so `name`, if any, was filled in from the writer's others). */
+    unnamed?: true;
+    text: string;
+    at: number;
+    edited: boolean;
+    deleted: boolean;
+    replies: Comment[];
+}
+export interface Thread {
+    id: string;
+    anchor: Anchor;
+    root: Comment;
+    resolved: boolean;
+}

package/dist/types/storage/feedback-file.d.ts

@@ -0,0 +1,13 @@
+import type { SignedOp } from "../model/types";
+/** The file a reviewer sends back with "Send feedback". */
+export interface FeedbackFile {
+    pipeup: 1;
+    doc: string;
+    sealed: boolean;
+    iv?: string;
+    data?: string;
+    ops?: SignedOp[];
+}
+export declare function writeFeedbackFile(doc: string, ops: SignedOp[], key: CryptoKey | null): Promise<string>;
+/** Returns the file's ops, untrusted: pass them to OpLog.add, which validates and verifies each one. */
+export declare function readFeedbackFile(json: string, doc: string, key: CryptoKey | null): Promise<unknown[]>;

package/dist/types/storage/indexeddb.d.ts

@@ -0,0 +1,15 @@
+import type { SignedOp } from "../model/types";
+import type { OpStore, Profile } from "./store";
+/** Ops and profile in this browser's IndexedDB. The private key is stored as a non-extractable CryptoKey. */
+export declare class IndexedDbStore implements OpStore {
+    private readonly db;
+    private constructor();
+    static open(name?: string): Promise<IndexedDbStore>;
+    close(): void;
+    load(doc: string): Promise<SignedOp[]>;
+    append(doc: string, ops: SignedOp[]): Promise<void>;
+    loadProfile(): Promise<Profile | null>;
+    saveProfile(profile: Profile): Promise<void>;
+    saveProfileIfAbsent(profile: Profile): Promise<Profile>;
+    private request;
+}

package/dist/types/storage/store.d.ts

@@ -0,0 +1,28 @@
+import { type Identity } from "../crypto/identity";
+import type { SignedOp } from "../model/types";
+export interface Profile {
+    identity: Identity;
+    name: string;
+}
+/** Where a browser keeps ops and the reviewer's profile. Implementations must not leave the machine. */
+export interface OpStore {
+    load(doc: string): Promise<SignedOp[]>;
+    append(doc: string, ops: SignedOp[]): Promise<void>;
+    loadProfile(): Promise<Profile | null>;
+    saveProfile(profile: Profile): Promise<void>;
+    /** Saves `profile` only if none is stored yet, atomically, and returns whichever profile is stored afterwards. */
+    saveProfileIfAbsent(profile: Profile): Promise<Profile>;
+}
+export declare class MemoryStore implements OpStore {
+    private readonly docs;
+    private profile;
+    load(doc: string): Promise<SignedOp[]>;
+    append(doc: string, ops: SignedOp[]): Promise<void>;
+    loadProfile(): Promise<Profile | null>;
+    saveProfile(profile: Profile): Promise<void>;
+    saveProfileIfAbsent(profile: Profile): Promise<Profile>;
+}
+/** A new reviewer has no name: they show as their animal until they add one. */
+export declare const DEFAULT_PROFILE_NAME = "";
+/** The reviewer's profile, created with a new identity the first time. */
+export declare function loadOrCreateProfile(store: OpStore, name?: string): Promise<Profile>;

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

@@ -0,0 +1,18 @@
+import { type Animal } from "../model/animals";
+export declare const ANIMAL_ICONS: Record<Animal, string>;
+/**
+ * The first letter or digit of a name, as a capital, always one character and the same in every locale
+ * ("ß" stays "ß"); "" when it has none (it might be all symbols or emoji).
+ */
+export declare function initial(name: string): string;
+/** What an avatar shows: the same key means the same picture. */
+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): 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). */
+export declare function easeIn(el: HTMLElement): HTMLElement;

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

@@ -0,0 +1,15 @@
+import { type PipeupDocument } from "../document";
+import type { Ctx, UiState, View } from "./context";
+export interface AppOptions {
+    doc: PipeupDocument;
+    root: Element;
+    onName(name: string): Promise<void>;
+}
+export interface App {
+    readonly ctx: Ctx;
+    destroy(): void;
+}
+/** Documents with free space beside them get a column; everything else gets bubbles and popovers. */
+export declare function chooseMode(root: Element, showing?: boolean): UiState["mode"];
+export declare function viewsFor(ctx: Ctx): View[];
+export declare function startApp(o: AppOptions): App;

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

@@ -0,0 +1,10 @@
+import type { Ctx, View } from "./context";
+/** How long a preview waits after the pointer leaves, so the pointer can reach it and click. */
+export declare const PREVIEW_GRACE_MS = 400;
+/**
+ * Bubbles for element and pin comments, a hover preview, and (unless the document column is showing
+ * threads) a popover. Text comments have no bubble: their highlight is what you hover and click.
+ */
+export declare function createBubbles(ctx: Ctx, opts: {
+    popovers: boolean;
+}): View;

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

@@ -0,0 +1,15 @@
+import type { Thread } from "../model/types";
+import type { Ctx, View } from "./context";
+/** Free width needed beside the content before comments get their own column. */
+export declare const COLUMN_MIN = 300;
+/** Width of the gutter that pages with data-pipeup-reserve keep for comments. */
+export declare const GUTTER = 320;
+/** Where the column goes (viewport x and width), or null when the page should use bubbles. */
+export declare function columnSpot(root: Element, showing?: boolean): {
+    x: number;
+    width: number;
+} | null;
+/** The thread's content is gone (not just waiting for its fuzzy match). */
+export declare function lost(ctx: Ctx, t: Thread): boolean;
+/** Threads beside the document, level with what they're about; the open one aligns exactly. */
+export declare function createColumn(ctx: Ctx): View;

package/dist/types/ui/comment-mode.d.ts

@@ -0,0 +1,15 @@
+import type { Ctx, View } from "./context";
+import { type Look } from "./pick";
+/** Comment mode's view; `back()` is Escape's step for it: clears a chosen block, false when none was chosen. */
+export interface CommentMode extends View {
+    back(): boolean;
+}
+/**
+ * Comment mode: the page goes quiet, an outline glides to the obvious block under the pointer, and a click
+ * chooses it. Listeners are on window in the capture phase and stop propagation there, so the page's own
+ * handlers never run while Pipeup's other window listeners (selection, the menu) still do, whatever their order.
+ *
+ * Known limits: the page's CSS `:hover` still applies; page listeners on window in the capture phase that were
+ * added before comment mode started still hear events; Escape still reaches the page's own handlers.
+ */
+export declare function createCommentMode(ctx: Ctx, look?: Look): CommentMode;

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

@@ -0,0 +1,15 @@
+export interface ComposerOptions {
+    label: string;
+    /** Something to show before the line instead, such as the writer's avatar. */
+    before?: Node;
+    onSend(text: string): Promise<void> | void;
+    onCancel?(): void;
+}
+export interface Composer {
+    element: HTMLElement;
+    input: HTMLTextAreaElement;
+    focus(): void;
+    clear(): void;
+}
+/** A writing line: no placeholder, Enter sends, Shift+Enter breaks, Esc cancels, a paper plane appears with text. */
+export declare function composer(o: ComposerOptions): Composer;

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

@@ -0,0 +1,93 @@
+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 { DraftBox } from "./draft-view";
+import type { ThreadActions } from "./thread-view";
+/** A comment being written: what it's on, and where that is now. */
+export interface Draft {
+    anchor: Anchor;
+    label: string;
+    /** Text being commented on (highlighted while drafting). */
+    ranges: Range[];
+    /** Where the draft's content is: its range for text, its element for blocks and pins. */
+    resolved: Resolved;
+}
+export interface UiState {
+    active: string | null;
+    hot: string | null;
+    showResolved: boolean;
+    /** Comments are out of sight: comment mode is off and All comments is closed. */
+    hidden: boolean;
+    mode: "column" | "bubbles";
+    draft: Draft | null;
+    /** Comment mode: the page is quiet and a click chooses a block to comment on. */
+    commenting: boolean;
+    /** All comments is open on the right: in the column layout it takes the column's place. */
+    listing: boolean;
+    /** A thread chosen from All comments on a narrow screen is open: comments show until it closes. */
+    reading: boolean;
+}
+/** Something that draws: rebuilt on render, repositioned every frame. */
+export interface View {
+    render(threads: readonly Thread[]): void;
+    frame(): void;
+    destroy(): void;
+}
+export interface MenuActions {
+    copyAll(as: CopyAs): Promise<void>;
+    toggleResolved(): 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[];
+}
+/** What every view shares: the document, state, and the few things views can ask the app to do. */
+export interface Ctx {
+    readonly doc: PipeupDocument;
+    readonly root: Element;
+    readonly layer: HTMLElement;
+    readonly host: HTMLElement;
+    readonly state: UiState;
+    readonly resolved: ReadonlyMap<string, Resolved>;
+    /** Threads whose fuzzy match hasn't had its turn yet: not placed, but not lost either. */
+    readonly pending: ReadonlySet<string>;
+    readonly actions: ThreadActions;
+    readonly menu: MenuActions;
+    visible(t: Thread): boolean;
+    /** The shown text comment whose highlight is at (x, y), if any. */
+    quoteAt(x: number, y: number): Thread | null;
+    /**
+     * A highlight takes the pointer (previews on hover, opens on click) unless a comment with words in it is being
+     * written. One rule for hover and click, and for comment mode, which leaves such clicks to the highlight.
+     */
+    readsAt(x: number, y: number): Thread | null;
+    /** The event happened inside Pipeup's own UI. */
+    owns(e: Event): boolean;
+    /** A view handled this page event; the app won't treat it as a click elsewhere. */
+    claim(e: Event): void;
+    open(id: string | null): void;
+    /** Puts the cursor in thread `id`'s reply line, unless the reader is typing elsewhere. */
+    focusReply(id: string): void;
+    hot(id: string | null): void;
+    startDraft(d: Draft): void;
+    /** Moves the open draft to another block, keeping its words (starts one if none is open). */
+    moveDraft(d: Draft): void;
+    /** Nothing has been typed in the open draft. */
+    draftEmpty(): boolean;
+    /** Runs `fn`, then puts focus and the caret back in the open draft as they were. */
+    keepCaret(fn: () => void): void;
+    postDraft(text: string): Promise<void>;
+    cancelDraft(): void;
+    /** Turns comment mode on or off; comments show while it is on. */
+    setCommenting(on: boolean): void;
+    /** What a click on the page does: cancels an empty draft, else closes the open thread. */
+    dismiss(): void;
+    registerDraft(box: DraftBox | null): void;
+    toast(message: string): void;
+    /** Tells the reviewer what went wrong. */
+    report(e: unknown): void;
+    pulse(id: string): void;
+    render(): void;
+}

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

@@ -0,0 +1,16 @@
+type Child = Node | string | null | undefined | false;
+/** Creates an element. Children are nodes or plain text — strings are never parsed as HTML. */
+export declare function h<K extends keyof HTMLElementTagNameMap>(tag: K, props?: Record<string, string | boolean | undefined>, ...children: Child[]): HTMLElementTagNameMap[K];
+/** Takes `el` out of (or back into) the keyboard's reach; focus never stays on something that goes inert. */
+export declare function inert(el: HTMLElement, on: boolean): void;
+export declare function clip(text: string, n: number): string;
+/** Sizes a fixed overlay (outline, pulse, mark) to a box, with padding around it. */
+export declare function fit(el: HTMLElement, r: {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+}, pad?: number): void;
+/** Text with its http(s) addresses as links. Built from nodes: nothing is ever parsed as HTML. */
+export declare function linkify(text: string): (Node | string)[];
+export {};

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

@@ -0,0 +1,35 @@
+import type { Ctx, Draft } from "./context";
+export interface DraftOptions {
+    /** What the comment is on: a quote or an element label. */
+    label: string;
+    /** The writer's public key, which picks their animal. */
+    me: string;
+    /** The writer's name; "" until they add one. */
+    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>;
+    onCancel(): void;
+}
+export interface DraftBox {
+    element: HTMLElement;
+    focus(): void;
+    setLabel(label: string): void;
+    /** The naming bar already says what the box is on: its label row takes no space. */
+    hideLabel(on: boolean): void;
+    /** Remembers the caret; the returned function focuses the box and puts it back. */
+    caret(): () => void;
+    isEmpty(): boolean;
+}
+/**
+ * The box for a new comment: what it's on, then the writing line with the writer's avatar beside it. Nobody
+ * has to give a name; a quiet line says who they are ("You're Otter · add your name") and opens a name
+ * field in its place.
+ */
+export declare function renderDraft(o: DraftOptions): DraftBox;
+/**
+ * The box for the app's current draft. While it holds words, a click elsewhere won't throw them away.
+ * The caller focuses it as soon as it is in the page: a deferred focus could land after the reader has
+ * already moved on, taking their typing or the new selection they just made.
+ */
+export declare function draftBox(ctx: Ctx, d: Draft): DraftBox;

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

@@ -0,0 +1,2 @@
+/** Copies on the user's action; falls back to a hidden field inside Pipeup's own layer. */
+export declare function copyText(text: string, container: HTMLElement): Promise<void>;

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

@@ -0,0 +1,19 @@
+import type { Resolved } from "../anchor/resolve";
+import type { Anchor } from "../model/types";
+import type { AnchorPoint } from "./layout";
+/** Where an element or pin comment's bubble sits (viewport coordinates). Text comments have no bubble. */
+export declare function bubblePoint(a: Anchor, r: Resolved): {
+    x: number;
+    y: number;
+} | null;
+export declare function quoteRects(r: Resolved): DOMRect[];
+/** The top edge a column thread or draft aligns with (viewport y), or null when the content is gone. */
+export declare function anchorTop(a: Anchor, r: Resolved): number | null;
+/** Where a preview or popover attaches: below the last quoted line, or beside the bubble or pin. */
+export declare function popoverAnchor(a: Anchor, r: Resolved): AnchorPoint | null;
+export declare function hit(x: number, y: number, rects: Iterable<{
+    left: number;
+    top: number;
+    right: number;
+    bottom: number;
+}>): boolean;

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

@@ -0,0 +1,28 @@
+export declare function highlightsSupported(): boolean;
+export interface PageSheet {
+    /** Shows the picking cursor over the page while comment mode is on. */
+    picking(on: boolean): void;
+    /** Publishes --pipeup-gutter in px, for pages that reserve a gutter; null publishes nothing. */
+    gutter(px: number | null): void;
+    /** How strongly highlights are painted, 0 to 1. */
+    fade(k: number): 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).
+     */
+    room(px: number, still: boolean): void;
+    remove(): void;
+}
+/**
+ * Pipeup's only styles on the page itself: text highlights (painted by the browser, so the page's DOM is
+ * never touched), the picking cursor in comment mode, room for the open All comments panel (a right margin on
+ * the page) and, on pages that ask for it, the gutter width. They live in a constructed stylesheet
+ * adopted by the document — no <style> element is added and no inline style is written.
+ */
+export declare function installPageSheet(doc?: Document, dark?: boolean): PageSheet;
+export declare function paintHighlights(g: {
+    quote: Range[];
+    on: Range[];
+    done: Range[];
+}): void;
+export declare function clearHighlights(): void;

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

@@ -0,0 +1,12 @@
+import { type Theme } from "./theme";
+export interface Host {
+    element: HTMLElement;
+    shadow: ShadowRoot;
+    layer: HTMLElement;
+    destroy(): void;
+}
+/**
+ * Pipeup's only element in the page: a fixed, click-through <pipeup-root> under <html> with an open shadow
+ * root (open so tools like `pipeup check` can measure it). It never changes the page's layout.
+ */
+export declare function createHost(theme: Theme, doc?: Document): Host;

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

@@ -0,0 +1,19 @@
+declare const PATHS: {
+    readonly comment: 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", "M12.3 8.2v6.6M9 11.5h6.6"];
+    readonly send: readonly ["M21 12L3.5 4.5 6.2 12l-2.7 7.5zM6.2 12H13"];
+    readonly copy: readonly ["M10 8h8a2 2 0 0 1 2 2v8a2 2 0 0 1-2 2h-8a2 2 0 0 1-2-2v-8a2 2 0 0 1 2-2z", "M16 8V6a2 2 0 0 0-2-2H6a2 2 0 0 0-2 2v8a2 2 0 0 0 2 2h2"];
+    readonly resolve: readonly ["M5 12.5l4.5 4.5L19 7.5"];
+    readonly reopen: readonly ["M3 12a9 9 0 1 0 3-6.7", "M3 4v5h5"];
+    readonly lines: readonly ["M4 7h16M4 12h10M4 17h7"];
+    readonly list: readonly ["M3 6.5a1.5 1.5 0 1 0 3 0a1.5 1.5 0 1 0-3 0M3 12a1.5 1.5 0 1 0 3 0a1.5 1.5 0 1 0-3 0M3 17.5a1.5 1.5 0 1 0 3 0a1.5 1.5 0 1 0-3 0M9 6.5h11M9 12h11M9 17.5h7"];
+    readonly expand: readonly ["M14 4h6v6M20 4l-6 6M10 20H4v-6M4 20l6-6M20 14v6h-6M20 20l-6-6M4 10V4h6M4 4l6 6"];
+    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 edit: readonly ["M4 20h4L19 9l-4-4L4 16z"];
+};
+export type IconName = keyof typeof PATHS;
+/** Outline icons drawn from constant path data; `stroke` thins or thickens the line (in 24-unit terms). */
+export declare function icon(name: IconName, size?: number, stroke?: number): SVGSVGElement;
+/** An outline drawing from constant path data (never from text people wrote). */
+export declare function draw(paths: readonly string[], size: number): SVGSVGElement;
+export {};

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

@@ -0,0 +1,7 @@
+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/layout.d.ts

@@ -0,0 +1,62 @@
+export interface StackItem {
+    id: string;
+    /** Where the thread wants its top edge (page coordinates). */
+    want: number;
+    height: number;
+}
+export interface Box {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+}
+export interface Viewport {
+    width: number;
+    height: number;
+}
+export interface AnchorPoint {
+    x: number;
+    y: number;
+    /** Text comments open below their line; element comments open beside. */
+    below: boolean;
+}
+/** Threads sit level with what they're about; overlaps push down; the open thread aligns exactly. */
+export declare function stackColumn(items: StackItem[], activeId: string | null, gap?: number): Map<string, number>;
+/**
+ * All comments' width, and a popover's (threads, drafts, the side popover). The only place they are set: the
+ * host writes them onto Pipeup's layer as --pu-panel and --pu-pop for the stylesheet.
+ */
+export declare const PANEL = 320;
+export declare const POPOVER = 300;
+/** On screens this narrow or less, All comments takes the whole width (it gets .full). */
+export declare const NARROW = 480;
+export declare const narrow: () => boolean;
+/** The viewport left for popovers: All comments, when open, takes its width from the right. */
+export declare function room(listing: boolean): Viewport;
+export declare function placePopover(at: AnchorPoint, size: {
+    width: number;
+    height: number;
+}, vp: Viewport, margin?: number): {
+    left: number;
+    top: number;
+};
+/**
+ * An element draft: just below its block, above it when there is no room below, never over the block or the
+ * naming bar (which sits above the block, or below it when there is no room above).
+ */
+export declare function placeDraft(block: Box, size: {
+    width: number;
+    height: number;
+}, vp: Viewport, margin?: number, bar?: number): {
+    left: number;
+    top: number;
+    above: boolean;
+};
+/** The selection bar: centred above the target, or below it when there's no room; never covering it. */
+export declare function placeBar(target: Box, size: {
+    width: number;
+    height: number;
+}, vp: Viewport): {
+    left: number;
+    top: number;
+};

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

@@ -0,0 +1,19 @@
+import { PipeupDocument } from "../document";
+import { type OpStore } from "../storage/store";
+export interface MountOptions {
+    /** The area people can comment on. Default: document.body. */
+    root?: Element;
+    /** The reviewer's name. Without one they show as their animal until they add a name. */
+    name?: string;
+    /** Where comments are kept. Default: this browser's IndexedDB. */
+    store?: OpStore;
+}
+export interface PipeupInstance {
+    readonly document: PipeupDocument;
+    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>;
+/** Pages that carry data-pipeup-doc mount themselves, unless data-pipeup-auto="off". */
+export declare function autoMount(): void;

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

@@ -0,0 +1,21 @@
+/** What picking needs to know about the page's layout (faked in unit tests). */
+export interface Look {
+    box(el: Element): {
+        left: number;
+        top: number;
+        width: number;
+        height: number;
+    };
+    /** The element draws something of its own — a background, border or shadow — so it reads as a block. */
+    drawn(el: Element): boolean;
+    viewport(): {
+        width: number;
+        height: number;
+    };
+}
+/** The obvious block under `from`: what the outline glides to in comment mode. */
+export declare function pickBlock(from: Element, root: Element, look: Look): Element | null;
+/** The next block out from `el` with a different box (wrappers the same size are skipped). */
+export declare function parentBlock(el: Element, root: Element, look: Look): Element | null;
+/** The real page: boxes from layout, "drawn" from computed backgrounds, borders and shadows. */
+export declare function pageLook(win?: Window): Look;

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

@@ -0,0 +1,3 @@
+import type { Ctx, View } from "./context";
+/** In comment mode, selecting text offers commenting: one comment icon, centred above the selection, never over it. */
+export declare function createSelection(ctx: Ctx): View;

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

@@ -0,0 +1,27 @@
+/** The comment-mode shortcut: change the key, or its labels, here and nowhere else. */
+export declare const SHORTCUT: {
+    /** The physical key (`KeyboardEvent.code`): Option changes the typed character on a Mac. */
+    readonly code: "KeyC";
+    /** The modifiers that must be down, and only those (Shift, Alt/Option, Command, Ctrl). */
+    readonly mods: {
+        readonly shift: true;
+        readonly alt: true;
+        readonly meta: false;
+        readonly ctrl: false;
+    };
+    readonly mac: {
+        readonly label: "⇧⌥C";
+        readonly aria: "Shift+Alt+C";
+    };
+    readonly other: {
+        readonly label: "Shift+Alt+C";
+        readonly aria: "Shift+Alt+C";
+    };
+};
+export declare const SHORTCUT_LABEL: string;
+export declare const SHORTCUT_ARIA: string;
+/**
+ * Shift+Option+C (Shift+Alt+C): never a key repeat, Command or Ctrl, or AltGr (which types characters).
+ * Callers must not claim it inside text fields: on a Mac it types a character there.
+ */
+export declare function isShortcut(e: KeyboardEvent): boolean;