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

package/dist/types/runtime/screen.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Which screen of the host app an address is, and so which threads' pins belong on the page. DOM-free.
+ *
+ * A thread stores the address it was left on (`url`: path, query and hash) next to its `route` (the path). Two
+ * addresses are one screen when they have the same path, the same hash route (a hash that starts with `#/` or
+ * `#!/`, as hash routers write them; any other hash is a place on the page and does not count), and the same
+ * values for every query parameter that names a screen.
+ *
+ * Without a rule from the host, every query parameter names a screen except the ones that never do: tracking
+ * (`utm_*`, `gclid`, …), paging, sorting, searching and filtering by their usual names, and the toolbar's own.
+ * A host whose screens differ by fewer parameters names them (`{ params: ["view"] }`), and one whose screens
+ * are not in the address that way names each screen itself with a function.
+ *
+ * A thread whose address is a bare path (no query, no hash route) was stored before addresses were kept, or was
+ * left where the path was all there was: it shows on every screen at that path, as every thread did before. A
+ * host function decides for those too.
+ */
+/** What the host says identifies a screen: the query parameters that do, or a function that names it. */
+export type ScreenRule = {
+    readonly params: readonly string[];
+} | ((address: URL) => string);
+/**
+ * The screen `url` is, as a string two addresses of one screen share. A host function that throws names
+ * nothing, and the address is read by the parameters instead.
+ */
+export declare function screenKey(url: URL, rule?: ScreenRule | null): string;
+/** True for an address that is only a path: no query and no hash route. */
+export declare function isBarePath(address: string): boolean;
+/** The address a thread was left on, as the toolbar reads it: its `url`, else its `route`. */
+export type Placed = {
+    readonly route: string;
+    readonly url?: string | null;
+};
+export type Here = {
+    /** The page's path, which anchors are captured and resolved against. */
+    readonly route: string;
+    /** The screen the page is on. */
+    readonly key: string;
+    /** Whether `thread` was left on this screen, so its pin belongs here. */
+    has(thread: Placed): boolean;
+};
+/**
+ * The screen at `href` (the page's whole address), and which threads belong on it. A thread is only ever on
+ * a screen at its own path, because its anchor is found among that path's elements. One whose `url` is not a
+ * page of this app (a native app's screen) belongs here by its `route` alone, as before.
+ */
+export declare function screenAt(href: string, rule?: ScreenRule | null): Here;

package/dist/types/runtime/screenshot.d.ts

@@ -1,12 +1,66 @@
+import type { Sketch } from "../core/index.js";
 import type { Capture } from "./client.js";
 /** The page, viewport and browser a screenshot is being taken in. */
 export declare function describeCapture(url: string): Capture;
-/** The visible page as a canvas, toolbar left out. `timeout` bounds a slow frame. */
+/** A box in CSS pixels from the top-left of the viewport. */
+export type Frame = {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+};
+export type Viewport = {
+    width: number;
+    height: number;
+};
+/** `rect` as a frame, or null when none of it is inside the viewport. */
+export declare function frameOf(rect: DOMRect | Frame, viewport: Viewport): Frame | null;
+/** The ring drawn around `frame`, in output pixels, when the picture is `scale` output pixels per CSS pixel. */
+export declare function ringFor(frame: Frame, scale: number, origin?: {
+    left: number;
+    top: number;
+}): {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+};
+/**
+ * The part of the viewport a crop around `frame` shows: the element and its drawing with room around them, at
+ * least `CROP_MIN`, never beyond the viewport, centred on the element as far as the viewport allows.
+ */
+export declare function cropFor(frame: Frame, viewport: Viewport, sketch?: Sketch): Frame;
+/**
+ * The page as it was at one instant: a copy of its DOM and, if an element was being pointed at, that element's
+ * box in the viewport at the same instant. Drawing the copy happens later and takes a while; measuring the
+ * element then instead would put its ring wherever the element had moved to in the meantime.
+ */
+export type PageShot = {
+    /** The highlighted element's box when the page was copied; null when nothing was, or it was off screen. */
+    frame: Frame | null;
+    viewport: Viewport;
+    /** Device pixels per CSS pixel the drawing is made at. */
+    scale: number;
+    /** The drawing, made once on the first request and shared by every picture cut from this shot. */
+    render: () => Promise<HTMLCanvasElement>;
+};
+/**
+ * Copies the visible page now, synchronously, with `highlight`'s box measured at the same moment. The toolbar is
+ * left out. Nothing is drawn until `render` is first called (see `shotPage`, `shotAround`).
+ */
+export declare function takeShot(highlight?: Element | null, timeout?: number): PageShot;
+/** The visible page as a canvas, toolbar left out, drawn from the page as it is now. `timeout` bounds a slow frame. */
 export declare function renderViewport(scale: number, timeout?: number): Promise<HTMLCanvasElement>;
-/** The whole visible page as a JPEG, toolbar left out. If `highlight` is on screen it's outlined. */
-export declare function capturePage(highlight?: Element | null): Promise<Blob | null>;
 /**
- * Capture what the person sees around `element`, with the toolbar left out, the rest dimmed,
- * and the element outlined. Returns a JPEG data URL, or null if the element isn't on screen or capture fails.
+ * The whole visible page as a JPEG, from `shot`. If the shot framed an element it's outlined, or `sketch`
+ * (drawn against it) is painted on instead.
+ */
+export declare function shotPage(shot: PageShot, sketch?: Sketch): Promise<Blob | null>;
+/**
+ * What the person saw around the framed element, cut from `shot`, with the rest dimmed and the element
+ * outlined, or with `sketch` painted on instead. A JPEG data URL, or null when nothing was framed or the
+ * page couldn't be drawn.
  */
-export declare function captureAround(element: Element): Promise<string | null>;
+export declare function shotAround(shot: PageShot, sketch?: Sketch): Promise<string | null>;
+/** `shotAround` for the page as it is now. */
+export declare function captureAround(element: Element, sketch?: Sketch): Promise<string | null>;

package/dist/types/runtime/session-source.d.ts

@@ -0,0 +1,45 @@
+/**
+ * The host session (which comment service, project and environment, and the 15-minute host token) and the
+ * cache that reuses it until the token is about to expire. DOM-free: the web toolbar loads the session route
+ * with `fetch` from the page (`./session.ts`); native clients load it with the app's own bearer auth.
+ */
+export type Session = {
+    apiUrl: string;
+    project: string;
+    environment: string;
+    hostToken: string;
+    /**
+     * Native clients only: their app origin (`<scheme>://app`), sent as `x-comment-service-origin` on every
+     * request. Web leaves it unset; the browser sends `Origin`.
+     */
+    clientOrigin?: string;
+    /**
+     * Web, script-tag loader only (`../embed`): the origin the session route says `embed.js` may be loaded from
+     * when that is not `apiUrl`'s origin. Without it the loader mounts nothing for such a session.
+     */
+    loaderOrigin?: string;
+};
+/** Returns this page's session, or null when comments are off. `refresh` skips the cached one. */
+export type GetSession = (options?: {
+    refresh?: boolean;
+}) => Promise<Session | null>;
+export declare function readJwt(token: string): {
+    exp?: number;
+    typ?: string;
+    name?: string;
+    email?: string;
+    memberId?: string;
+    origin?: string;
+} | null;
+export declare function sessionFrom(payload: unknown): Session | null;
+/**
+ * The session route answered, and its answer was "comments are off" with a reason (`{ enabled: false, error }`),
+ * most often because nobody is signed in. Not a failure to reach it.
+ */
+export declare class SessionOff extends Error {
+}
+/**
+ * Reads the session route at most once at a time and reuses the answer until its host token is about to expire.
+ * "Comments are off" is kept for the source's lifetime. A failed request is not kept, so the next call retries.
+ */
+export declare function sessionSource(path: string, load: (path: string) => Promise<unknown>, now?: () => number): GetSession;

package/dist/types/runtime/session.d.ts

@@ -1,21 +1,12 @@
-export type Session = {
-    apiUrl: string;
-    project: string;
-    environment: string;
-    hostToken: string;
-};
-/** Returns this page's session, or null when comments are off. `refresh` skips the cached one. */
-export type GetSession = (options?: {
-    refresh?: boolean;
-}) => Promise<Session | null>;
-export declare function readJwt(token: string): {
-    exp?: number;
-    typ?: string;
-    name?: string;
-    email?: string;
-    memberId?: string;
-} | null;
-export declare function sessionFrom(payload: unknown): Session | null;
+import { type GetSession, type Session } from "./session-source.js";
+export { readJwt, sessionFrom, SessionOff } from "./session-source.js";
+export type { GetSession, Session } from "./session-source.js";
+/**
+ * Forgets every toolbar sign-in this page's origin holds. Run when the host app says nobody is signed in: a
+ * sign-in is kept per browser, not per person of the host app, so the next person to sign in to the app must
+ * not find the last one's.
+ */
+export declare function forgetSignIns(storage?: Storage): void;
 /**
  * Reads the session route at most once at a time and reuses the answer until its host token is about to expire.
  * "Comments are off" is kept for the page's lifetime. A failed request is not kept, so the next call retries.
@@ -23,3 +14,14 @@ export declare function sessionFrom(payload: unknown): Session | null;
 export declare function sessionSource(path: string, load?: (path: string) => Promise<unknown>, now?: () => number): GetSession;
 /** The page-wide session source for a session route path. */
 export declare function sessionFor(path: string): GetSession;
+/** What the host app says now: comments are on (with the session), off, or it could not be asked. */
+export type HostAnswer = {
+    readonly state: "on";
+    readonly session: Session;
+} | {
+    readonly state: "off";
+} | {
+    readonly state: "unknown";
+};
+/** Asks the session route again, past any kept answer, or takes the kept one when `fresh` is false. */
+export declare function askHost(get: GetSession, fresh?: boolean): Promise<HostAnswer>;

package/dist/types/runtime/shield.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Keeps the page from reacting to the toolbar. Presses on the toolbar never reach the page, so an open menu,
+ * popover, or dialog does not treat them as an outside press, and buttons do not pull focus out of it. Focus
+ * moving into the toolbar is hidden from document-level focus traps (Radix FocusScope listens for focusin and
+ * focusout on document), which would otherwise pull it straight back into an open modal so the composer never
+ * takes input. The focus listeners sit on document, so the page's and the toolbar's own React handlers still
+ * run; call this before any app dialog opens so stopImmediatePropagation runs ahead of the trap's listeners.
+ */
+export declare function shieldFromPage(): () => void;

package/dist/types/runtime/shot.d.ts

@@ -0,0 +1,45 @@
+import { type ReactNode } from "react";
+import { type Pending, type PreviewFile } from "./attachments.js";
+import { type MarkupShape } from "./markup.js";
+import { type MarkupResult } from "./markup-editor.js";
+import { type ReplayEvent } from "./replay.js";
+/** The captures a draft holds: pictures (marked up on the stage) and clips. */
+export type ShotCapture = PreviewFile;
+/**
+ * The flattened picture `item` needs before it is sent, given the shapes drawn on it: null when the file already
+ * shows them, the original when every shape is gone, else a fresh flatten. Rejects when the image can't be read.
+ */
+export declare function flattenCapture(item: Pending, shapes: MarkupShape[]): Promise<MarkupResult | null>;
+/** Where an event sits on a clip's timeline, 0..1, or null when it falls outside the clip. */
+export declare function timelinePosition(event: ReplayEvent, clip: {
+    startedAt: number;
+    durationMs: number;
+}): number | null;
+/**
+ * A draft of captures as a comment: the selected capture fills the surface (a picture with the markup tools live
+ * on it, or a clip playing), the others sit in a filmstrip, and the composer (`children`) is a column beside it.
+ * Nothing has to be typed, and there is no Done to press: posting flattens whatever was drawn (see the composer's
+ * submit in `toolbar.tsx`). "Another page" and "Record" minimise the surface to the dock so the draft can collect
+ * more from elsewhere in the app.
+ */
+export declare function ShotSurface({ captures, selectedId, shapes, savedAt, onSelect, onRemove, onShapes, onAnother, onRecord, onDictate, dictating, onMinimise, onDiscard, confirmDiscard, onSubmit, children, }: {
+    captures: ShotCapture[];
+    selectedId: string | null;
+    /** Shapes drawn on each picture so far, by capture id; a picture not listed shows its flattened shapes. */
+    shapes: ReadonlyMap<string, MarkupShape[]>;
+    savedAt: number | null;
+    onSelect: (id: string) => void;
+    onRemove: (id: string) => void;
+    onShapes: (id: string, shapes: MarkupShape[]) => void;
+    onAnother: () => void;
+    onRecord: () => void;
+    /** Starts (or stops) typing what the person says into the comment; absent when dictation is not available. */
+    onDictate?: (() => void) | undefined;
+    dictating?: boolean | undefined;
+    onMinimise: () => void;
+    onDiscard: () => void;
+    confirmDiscard: boolean;
+    /** Cmd+Enter on the picture: post, as it does in the comment box. */
+    onSubmit: () => void;
+    children: ReactNode;
+}): import("react/jsx-runtime").JSX.Element;

package/dist/types/runtime/sketch.d.ts

@@ -0,0 +1,26 @@
+import type { Sketch } from "../core/index.js";
+import { type Point } from "./ink.js";
+export { INK, INK_HALO, type Point } from "./ink.js";
+export type InkBox = {
+    left: number;
+    top: number;
+    right: number;
+    bottom: number;
+};
+/** Drops points within `tolerance` px of the line through their neighbours (Ramer–Douglas–Peucker). */
+export declare function simplify(points: Point[], tolerance?: number): Point[];
+export declare function inkBox(points: Point[]): InkBox;
+export declare function isTap(box: InkBox): boolean;
+/**
+ * The element a drawing is about: under the middle of the drawing, widened to the nearest ancestor that covers
+ * a fair share of it. Circling a button picks the button; circling a whole card picks the card.
+ */
+export declare function elementUnder(box: InkBox): Element | null;
+/** Strokes in viewport coordinates, stored relative to `element`'s box. */
+export declare function sketchFor(element: Element, strokes: Point[][]): Sketch;
+/** The drawing's box, relative to the element it is stored against. */
+export declare function sketchBox(sketch: Sketch): InkBox;
+/** A smooth SVG path through a flat x, y list: quadratic curves through each pair of midpoints. */
+export declare function pathData(path: number[], dx?: number, dy?: number): string;
+/** Paints `sketch` on a canvas, given where its element's top-left corner lands and the canvas scale. */
+export declare function paintSketch(ctx: CanvasRenderingContext2D, sketch: Sketch, origin: Point, scale: number): void;