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

package/dist/types/runtime/markup-editor.d.ts

@@ -0,0 +1,54 @@
+import { type ReactNode, type Ref } from "react";
+import { type MarkupShape } from "./markup.js";
+export type MarkupResult = {
+    /** The image with the markup flattened in. */
+    blob: Blob;
+    /** File name for `blob` (`flattenedName` of the original). */
+    name: string;
+    /** The shapes, kept so the image can be marked up again from the original. */
+    shapes: MarkupShape[];
+}
+/** Every shape was removed: the attachment goes back to the original file. */
+ | {
+    blob: null;
+    name: string;
+    shapes: [];
+};
+/** What an inline editor's owner can ask of it (see `MarkupEditorProps.mode`). */
+export type MarkupEditorHandle = {
+    /**
+     * Flattens what has been drawn since the editor opened or last saved. Resolves null when nothing changed, and
+     * rejects when the image can't be flattened (the reason is shown in the editor).
+     */
+    save(): Promise<MarkupResult | null>;
+};
+export type MarkupEditorProps = {
+    /**
+     * `dialog` (default): a header with Cancel and Done; Done hands the result over once and the owner closes the
+     * editor. `inline`: no header, the editor stays open after a save, its owner saves through `ref` (`save`) and
+     * Cmd+Enter calls `onSubmit`. Escape with nothing drawn still calls `onCancel`.
+     */
+    mode?: "dialog" | "inline";
+    /** Inline mode's handle on the editor (`save`), for an owner that flattens on its own schedule. */
+    handle?: Ref<MarkupEditorHandle>;
+    /** URL of the original, unmarked image (a blob: URL from the draft tray). */
+    src: string;
+    /** The original's file name, shown in the header and used to name the result. */
+    name: string;
+    /** Shapes from an earlier markup of this image; the editor starts with them so they stay editable. */
+    shapes: MarkupShape[];
+    /** Largest file the result may be (the upload limit). */
+    maxBytes: number;
+    /** Leaves without changing the attachment. */
+    onCancel: () => void;
+    /** Called once with the flattened image. The editor stays mounted until the parent closes it. */
+    onSave: (result: MarkupResult) => void;
+    /** Inline mode's Cmd+Enter: the result of saving first (null when nothing changed), then the owner's turn. */
+    onSubmit?: (result: MarkupResult | null) => void;
+    /** Every change to the shapes, as they stand, so the owner can keep them somewhere safe. */
+    onChange?: (shapes: MarkupShape[]) => void;
+    /** Inline mode's ribbon draws its own groups; the owner's groups (captures, narration) go after them. */
+    ribbon?: ReactNode;
+};
+/** Markup mode for an image in the media pane: replaces the pane's header and stage while open. */
+export declare function MarkupEditor({ mode, handle, src, name, shapes: initialShapes, maxBytes, onCancel, onSave, onSubmit, onChange: onChangeProp, ribbon, }: MarkupEditorProps): import("react/jsx-runtime").JSX.Element;

package/dist/types/runtime/markup-model.d.ts

@@ -0,0 +1,126 @@
+/**
+ * The markup model: shapes in the image's own pixel space, sizes, colours, label layout, hit-testing, moves and
+ * undo history. DOM-free, so native clients draw the same shapes with their own renderer; the web toolbar's
+ * canvas renderer and flattening are in `./markup.ts`.
+ */
+import { type Point } from "./ink.js";
+export type { Point };
+export type Box = {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+};
+export type MarkupTool = "select" | "pen" | "highlight" | "arrow" | "rect" | "ellipse" | "text";
+export type MarkupSize = "s" | "m" | "l";
+type ShapeBase = {
+    id: string;
+    color: string;
+    size: MarkupSize;
+};
+export type StrokeShape = ShapeBase & {
+    kind: "pen" | "highlight";
+    points: Point[];
+};
+export type ArrowShape = ShapeBase & {
+    kind: "arrow";
+    from: Point;
+    to: Point;
+};
+export type BoxShape = ShapeBase & {
+    kind: "rect" | "ellipse";
+    box: Box;
+};
+export type TextShape = ShapeBase & {
+    kind: "text";
+    at: Point;
+    text: string;
+};
+export type MarkupShape = StrokeShape | ArrowShape | BoxShape | TextShape;
+/** Colours offered in the editor. The first is the toolbar's sketch ink. */
+export declare const MARKUP_COLORS: ReadonlyArray<{
+    name: string;
+    value: string;
+}>;
+export declare const DEFAULT_INK = "#ff3b30";
+export declare const DEFAULT_HIGHLIGHT = "#ffcc00";
+/** Highlighter strokes are drawn at this opacity so the page under them stays readable. */
+export declare const HIGHLIGHT_ALPHA = 0.38;
+/** Most undo steps kept. */
+export declare const HISTORY_LIMIT = 100;
+/**
+ * Sizes in image pixels for one image. `unit` is max(1, longest side / 1000), so markup looks the same on a 1x
+ * screenshot and a 3x one. Pen and arrow strokes: s 2u, m 4u, l 8u. Highlighter: 5x the pen width. Text font:
+ * s 14u, m 20u, l 30u.
+ */
+export type MarkupMetrics = {
+    unit: number;
+    stroke: (size: MarkupSize) => number;
+    highlight: (size: MarkupSize) => number;
+    font: (size: MarkupSize) => number;
+};
+/** Width in px of one line of text at `fontPx`, set in `markupFont(fontPx)`. */
+export type MeasureText = (text: string, fontPx: number) => number;
+/** Laid-out text label: the filled box in image px, its lines, and where each line's top-left sits. */
+export type TextLayout = {
+    box: Box;
+    lines: string[];
+    font: number;
+    pad: number;
+    lineHeight: number;
+};
+export declare function markupMetrics(width: number, height: number): MarkupMetrics;
+/** CSS font for labels: `600 <px>px` in the system UI stack. */
+export declare function markupFont(px: number): string;
+/**
+ * Label text for a fill: `#ffffff` while it keeps at least 3:1 contrast (WCAG AA for large bold text, which
+ * labels are), else whichever of white and `#1d1d1f` reads better. Red, blue, and purple keep white text;
+ * orange, green, yellow, and white get dark text.
+ */
+export declare function contrastText(color: string): string;
+/** Lays a label out: lines split on "\n", line height 1.25 em, padding 0.4 em, top-left at `shape.at`. */
+export declare function textLayout(shape: TextShape, metrics: MarkupMetrics, measure: MeasureText): TextLayout;
+/** The area a shape paints, stroke width included, in image px. */
+export declare function shapeBounds(shape: MarkupShape, metrics: MarkupMetrics, measure: MeasureText): Box;
+/**
+ * Id of the topmost shape under `point` (later shapes are on top), or null. Strokes and arrows hit within half
+ * their width plus `tolerance` of the line; rectangles and ellipses within that of their outline (not their
+ * inside, so a box drawn around something never hides it); text anywhere in its label box.
+ */
+export declare function hitTest(shapes: MarkupShape[], point: Point, tolerance: number, metrics: MarkupMetrics, measure: MeasureText): string | null;
+/** The same shape moved by (dx, dy); a new object, the input is left alone. */
+export declare function moveShape<T extends MarkupShape>(shape: T, dx: number, dy: number): T;
+/** The box between two drag points, any direction. `square` makes it w = h = the larger side, kept on the drag side. */
+export declare function normalizeBox(a: Point, b: Point, square: boolean): Box;
+/** `to` moved onto the nearest 45° ray from `from`, keeping its distance. */
+export declare function snapAngle(from: Point, to: Point): Point;
+/**
+ * Whether a just-drawn shape is worth keeping: a stroke must span `minSize` px in at least one direction, an
+ * arrow must be at least `minSize` long, a box must be at least `minSize` both ways, and text must have
+ * non-blank text.
+ */
+export declare function isMeaningful(shape: MarkupShape, minSize: number): boolean;
+/** The original's base name with `.png` or `.jpg` for the flattened type ("shot.jpeg" → "shot.png"). */
+export declare function flattenedName(name: string, type: "image/png" | "image/jpeg"): string;
+/** Undo history. `present` is what is on screen. */
+export type MarkupHistory = {
+    past: MarkupShape[][];
+    present: MarkupShape[];
+    future: MarkupShape[][];
+};
+export declare function createHistory(shapes: MarkupShape[]): MarkupHistory;
+/** Pushes `next` as a new step and clears redo; returns `history` itself when `next === history.present`. */
+export declare function commitHistory(history: MarkupHistory, next: MarkupShape[]): MarkupHistory;
+/** Returns `history` itself when there is nothing to undo. */
+export declare function undoHistory(history: MarkupHistory): MarkupHistory;
+/** Returns `history` itself when there is nothing to redo. */
+export declare function redoHistory(history: MarkupHistory): MarkupHistory;
+/** Width a stroke paints, before any hit tolerance. Highlighter is wider by design. */
+export declare function strokeWidth(shape: StrokeShape, metrics: MarkupMetrics): number;
+/** Arrow head length and half width, both from the shaft width and the image's unit. */
+export declare function arrowHead(lineWidth: number, unit: number): {
+    length: number;
+    halfWidth: number;
+};
+/** A box as left/top with non-negative sides, so negative widths from odd input still draw. */
+export declare function toRect(box: Box): Box;

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

@@ -0,0 +1,69 @@
+/**
+ * Markup drawn over an attached image before it is sent: pen, highlighter, arrows, boxes, ellipses, and text
+ * labels. Shapes live in the image's own pixel space, so the same list draws the on-screen overlay (scaled to
+ * the pane) and the flattened file (at full size). This file is the canvas renderer and flattening; the
+ * DOM-free shape model is `./markup-model.ts`, re-exported here. Everything takes its canvas as an argument, so
+ * it runs under unit tests without a real canvas.
+ */
+import { type Box, type MarkupMetrics, type MarkupShape, type MeasureText } from "./markup-model.js";
+export * from "./markup-model.js";
+/** Canvas area browsers reliably allocate (Safari's cap is 16 777 216 px); a bigger image is flattened smaller. */
+export declare const MAX_CANVAS_PIXELS = 16000000;
+/** The 2D context calls the renderer uses. A real CanvasRenderingContext2D satisfies it; tests pass a recorder. */
+export type MarkupContext = Pick<CanvasRenderingContext2D, "save" | "restore" | "beginPath" | "closePath" | "moveTo" | "lineTo" | "quadraticCurveTo" | "arcTo" | "ellipse" | "rect" | "stroke" | "fill" | "fillText" | "measureText" | "drawImage" | "scale" | "setLineDash"> & {
+    strokeStyle: CanvasRenderingContext2D["strokeStyle"];
+    fillStyle: CanvasRenderingContext2D["fillStyle"];
+    lineWidth: number;
+    lineCap: CanvasLineCap;
+    lineJoin: CanvasLineJoin;
+    globalAlpha: number;
+    globalCompositeOperation: GlobalCompositeOperation;
+    font: string;
+    textBaseline: CanvasTextBaseline;
+    textAlign: CanvasTextAlign;
+};
+export type FlattenCanvas = {
+    width: number;
+    height: number;
+    getContext(kind: "2d"): MarkupContext | null;
+    toBlob(callback: (blob: Blob | null) => void, type?: string, quality?: number): void;
+};
+export type FlattenInput = {
+    /** The original image, already decoded. */
+    image: CanvasImageSource;
+    /** The image's natural size; shapes are in this space. */
+    width: number;
+    height: number;
+    shapes: MarkupShape[];
+    /** File name of the original; the result keeps its base name with the new extension. */
+    name: string;
+    maxBytes: number;
+    /** Test seam; defaults to a detached `<canvas>`. */
+    createCanvas?: (width: number, height: number) => FlattenCanvas;
+};
+/** Measures with `ctx.measureText`, or estimates 0.6 em per character when there is no canvas (jsdom). */
+export declare function createMeasure(ctx: Pick<MarkupContext, "measureText" | "font"> | null): MeasureText;
+/**
+ * Draws shapes in order on a context already scaled to image px. Pen strokes are smoothed through quadratic
+ * midpoints with round caps and joins; a one-point stroke draws a dot. Highlighter strokes draw the same way at
+ * `HIGHLIGHT_ALPHA` with normal ("source-over") compositing, so the overlay on screen matches the file. Arrows
+ * draw a shaft and a filled head sized from the stroke width (head length 4x width, min 10u), with the shaft
+ * stopping at the head's base.
+ * Rectangles have rounded corners (radius 1.5x width, clamped to half the short side). Text draws a filled
+ * rounded label (radius 0.3 em) in the shape colour with `contrastText` lines. Each shape restores the context.
+ */
+export declare function drawShapes(ctx: MarkupContext, shapes: MarkupShape[], metrics: MarkupMetrics): void;
+/** A dashed outline around `box` (padded by 4 screen px / `scale`), for the selected shape on screen. */
+export declare function drawSelection(ctx: MarkupContext, box: Box, scale: number): void;
+/**
+ * Draws the image and its shapes into one file. Tries PNG at full size (scaled down to fit
+ * `MAX_CANVAS_PIXELS`); if that is over `maxBytes`, JPEG at quality 0.92, 0.85, 0.75 on a white background;
+ * then halves the size and tries again, up to three times. Rejects with a readable Error when the canvas has no
+ * 2D context, `toBlob` gives null, or nothing fits.
+ */
+export declare function flattenMarkup(input: FlattenInput): Promise<{
+    blob: Blob;
+    name: string;
+}>;
+/** Decodes an image URL. Rejects with a readable Error when it does not load. */
+export declare function loadImage(url: string): Promise<HTMLImageElement>;

package/dist/types/runtime/mention-parse.d.ts

@@ -0,0 +1,18 @@
+/** Mention parsing for the composer and message text. DOM-free, so native clients share it. */
+import type { Member, Mentioned } from "./api.js";
+/** The `@query` being typed just before `caret`, and where its `@` is, or null. */
+export declare function mentionQueryAt(text: string, caret: number): {
+    query: string;
+    start: number;
+} | null;
+/** Members whose name contains, or whose email starts with, `query` (any case); never the writer. */
+export declare function mentionMatches(members: readonly Member[], query: string, selfEmail: string | null | undefined): Member[];
+/** `text` with the `@query` at `start` (up to `caret`) replaced by `@Name `, and the caret after it. */
+export declare function insertMention(text: string, start: number, caret: number, member: Member): {
+    text: string;
+    caret: number;
+};
+/** Members picked while writing whose `@Name` is still in the text. */
+export declare function mentionsIn(text: string, picked: Map<string, Member>): Member[];
+/** Splits a message body around its mentions: odd entries are the `@Name` parts. */
+export declare function mentionParts(body: string, mentions: readonly Mentioned[] | undefined): string[];

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

@@ -1,17 +1,17 @@
 import { type TextareaHTMLAttributes } from "react";
 import type { Member, Mentioned } from "./client.js";
+export { mentionParts, mentionQueryAt, mentionsIn } from "./mention-parse.js";
 type Props = Omit<TextareaHTMLAttributes<HTMLTextAreaElement>, "value" | "onChange"> & {
     value: string;
     onValueChange: (next: string) => void;
     members: Member[];
     selfEmail?: string;
     onMention: (member: Member) => void;
+    /** Grow the field to its text. The composer uses this so a long draft stays visible. */
+    grow?: boolean;
 };
-/** Members picked while writing whose `@Name` is still in the text. */
-export declare function mentionsIn(text: string, picked: Map<string, Member>): Member[];
 export declare function MessageText({ body, mentions }: {
     body: string;
     mentions?: Mentioned[];
 }): import("react/jsx-runtime").JSX.Element;
-export declare function MentionTextarea({ value, onValueChange, members, selfEmail, onMention, onKeyDown, ...rest }: Props): import("react/jsx-runtime").JSX.Element;
-export {};
+export declare function MentionTextarea({ value, onValueChange, members, selfEmail, onMention, onKeyDown, grow, ...rest }: Props): import("react/jsx-runtime").JSX.Element;

package/dist/types/runtime/page-background.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The colour behind the page, as the browser paints it: the root element's background, else the body's (which
+ * the browser carries out to the whole window), else the window's own colour for the page's colour scheme
+ * (white, or dark under `color-scheme: dark`). A partly transparent one is laid over the window's colour.
+ *
+ * Never transparent. Snapshots and recording frames are JPEG and video, which have no transparency: a
+ * transparent background comes out black, with the page's black text on it.
+ */
+export declare function pageBackground(): string;

package/dist/types/runtime/page-image.d.ts

@@ -0,0 +1,123 @@
+/**
+ * Draws the visible page onto a canvas without reading a computed style per element.
+ *
+ * The page is cloned natively (`cloneNode(true)`, a few milliseconds for thousands of nodes), the page's own
+ * stylesheets are inlined once (cached per page, with fonts and `url()` assets embedded as data URLs), and the
+ * result is rasterized through an SVG `<foreignObject>`. The previous renderer (modern-screenshot) copied the
+ * diff of ~400 computed properties for every element and its pseudo-elements, which cost about a second of
+ * main-thread time per capture on an ordinary page and grew with the page. This one spends the main thread on
+ * the clone walk and on the browser's own SVG layout, and nothing on the network once warmed.
+ *
+ * The copy is built to land every element exactly where the person sees it, whatever is scrolled:
+ *
+ * - A scrolled element's children are shifted by its scroll offset, the window's included, so the root is never
+ *   transformed and never clips the part of the page that scrolled into view.
+ * - `position: fixed` and `position: sticky` elements are pinned at their on-screen box, since neither survives a
+ *   scroll offset expressed as a translation (a transform re-anchors fixed descendants; a static image has nothing
+ *   to stick to). Every box is measured while the page is copied, never when it is drawn: drawing waits for
+ *   fonts and pictures, and a page that scrolled on in the meantime would put its header wherever it had got to.
+ * - What is in the browser's top layer (a modal dialog with its backdrop, an open popover) is drawn open, over
+ *   everything else.
+ * - What is moving (a CSS animation or transition, a script animation, one driven by scrolling) is drawn at the
+ *   frame it was on.
+ * - Replaced elements (images, video, canvas, iframes, plugins) keep their on-screen box and their own look
+ *   (border, margin, fit) whatever happens to their pixels, so a slow or refused asset never reflows what
+ *   follows it.
+ * - A classic (non-overlay) scrollbar's gutter is kept as padding, so content beside one is not laid out wider.
+ *
+ * What is not carried over: what the page itself may not read (a frame's or plugin's content, a closed shadow
+ * tree, a picture or video from another origin that sends no CORS header, a WebGL canvas that does not keep
+ * its drawing buffer): a blank box of the same size. And styles that depend on `:hover`/`:focus` (dropped,
+ * which is what a screenshot should show anyway).
+ */
+export type PageImageOptions = {
+    /** Device pixels per CSS pixel in the output. */
+    scale: number;
+    /** Upper bound on the whole capture. */
+    timeout?: number;
+    /** Subtrees to leave out (the toolbar). */
+    exclude?: (element: Element) => boolean;
+    /** Painted behind the page. */
+    backgroundColor?: string;
+    /** CSS width/height of the captured area; defaults to the viewport. */
+    width?: number;
+    height?: number;
+    /** Window scroll offsets the page is shifted by. */
+    scrollX?: number;
+    scrollY?: number;
+};
+type Viewport = {
+    width: number;
+    height: number;
+};
+type Scroll = {
+    left: number;
+    top: number;
+};
+/** A data URL for `url`, or null when it can't be fetched in time. Never rejects. */
+export declare function assetDataUrl(url: string, timeout?: number): Promise<string | null>;
+/** Replaces every `url()` in `cssText` with a data URL. Unfetchable ones are left as they are. */
+export declare function inlineCssUrls(cssText: string, baseHref: string): Promise<string>;
+type StyleSource = {
+    key: string;
+    ownHref: string;
+    text: string | null;
+    href: string | null;
+};
+/** The sheets that style the page, read in document order. */
+export declare function collectStyleSources(doc: Document): StyleSource[];
+/** Every page style as one block of CSS with assets embedded. Cached; refreshed when a sheet is added or grows. */
+export declare function pageStyleText(doc?: Document): Promise<string>;
+/** Fetches fonts and CSS assets now, so the first capture pays nothing on the network. */
+export declare function prewarmPageImage(doc?: Document): void;
+/**
+ * The elements that paint inside the viewport, plus every ancestor of one. Elements without a box
+ * (`display: none`, `<option>`, SVG `<defs>`, `display: contents` wrappers) are not listed.
+ */
+export declare function visibleSet(root: Element, viewport: Viewport, exclude?: (element: Element) => boolean): Set<Element>;
+export type ClonedPage = {
+    root: Element;
+    waits: Promise<unknown>[];
+    elements: number;
+    /** Rules that belong after the page's own styles (see `renderSnapshot`). Empty for most pages. */
+    css: string;
+    /** Pins fixed and sticky elements where they are on screen. Call once `waits` have settled; runs once. */
+    finish: () => void;
+};
+/**
+ * A copy of `root` ready to serialize: `display: none` subtrees removed, offscreen images held by same-size
+ * placeholders, live form values, scroll offsets, canvases and visible images carried over. `waits` resolve
+ * when every visible image has its pixels. `scroll` is the window's offset, applied to the root's children.
+ *
+ * Everything the copy needs from the live page is read here, in one go. `finish` only rearranges the copy.
+ */
+export declare function clonePage(root: Element, viewport: Viewport, exclude: (element: Element) => boolean, view?: Window, scroll?: Scroll): ClonedPage;
+/**
+ * The SVG document that draws `clone` with `css` applied, `width`×`height` CSS pixels.
+ *
+ * Inside the image the `<svg>` is the root element, not the cloned `<html>`, so `rem` resolves against the
+ * svg's font size. `rootFontSize` (the live root's computed size) is set on it: a page that scales itself by
+ * a root font size set from an attribute or class on `<html>` would otherwise lay out at the browser default
+ * while fixed and sticky boxes stay pinned at their live, differently scaled coordinates.
+ */
+export declare function pageSvg(clone: Element, css: string, width: number, height: number, rootFontSize?: string): string;
+/** The page copied at one instant, with everything a later render needs. */
+export type PageSnapshot = {
+    page: ClonedPage;
+    css: Promise<string>;
+    width: number;
+    height: number;
+    /** The live root's computed font size, which `rem` resolves against inside the image too. */
+    rootFontSize: string;
+    backgroundColor?: string | undefined;
+};
+/**
+ * Copies the visible page now, synchronously, so the picture shows the page exactly as it was at this moment
+ * however long drawing it then takes. Rendering is `renderSnapshot`.
+ */
+export declare function snapshotPage(options: Omit<PageImageOptions, "scale" | "timeout">): PageSnapshot;
+/** Draws a snapshot onto a canvas at `scale` device pixels per CSS pixel. Throws when it can't be done in time. */
+export declare function renderSnapshot(snapshot: PageSnapshot, scale: number, timeout?: number): Promise<HTMLCanvasElement>;
+/** The visible page as a canvas. Throws when the page can't be drawn in time. */
+export declare function drawPage(options: PageImageOptions): Promise<HTMLCanvasElement>;
+export {};

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

@@ -1,16 +1,19 @@
 import type { Thread } from "./client.js";
 import type { PlacedStatus } from "./format.js";
+import type { Here } from "./screen.js";
 export type Box = {
     top: number;
     left: number;
     width: number;
     height: number;
 };
+/** `box` is the anchored element's box, set while the thread is placed. */
 export type Placed = {
     thread: Thread;
     status: PlacedStatus;
     top?: number;
     left?: number;
+    box?: Box;
 };
 export declare function overlayBounds(host: HTMLElement): {
     width: number;
@@ -26,13 +29,13 @@ export declare function placeAgainst(element: Element, host: HTMLElement): Box |
 export declare function useOverlayHost(enabled: boolean): HTMLElement | null;
 /**
  * Where each thread's anchor is on this page. Anchors are resolved only while `active` (the panel is open or this
- * page's pins are shown) and the tab is visible, only for open threads on this route, in idle-time slices. The page
+ * page's pins are shown) and the tab is visible, only for open threads on this screen, in idle-time slices. The page
  * is watched with a MutationObserver only while the panel is open or the page is small; otherwise clicks, keys,
  * focus and a slow re-check trigger re-resolves. Scrolling and resizing only re-measure elements already found.
  */
-export declare function usePlacement({ threads, route, host, active, panelOpen, visible, }: {
+export declare function usePlacement({ threads, here, host, active, panelOpen, visible, }: {
     threads: Thread[];
-    route: string;
+    here: Here;
     host: HTMLElement;
     active: boolean;
     panelOpen: boolean;

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

@@ -1,6 +1,8 @@
+/** A recording stops itself after this long. */
+export declare const RECORD_MAX_MS = 75000;
 export declare const FRAME_WIDTH = 1920;
 export declare const FRAME_HEIGHT = 1080;
-export declare function recordingMime(): string | null;
+export declare function recordingMime(sound?: boolean): string | null;
 export declare function formatClock(ms: number): string;
 type FeaturePolicy = {
     allowsFeature(feature: string): boolean;
@@ -24,10 +26,24 @@ export type TabTake = {
     stop: () => void;
     cancel: () => void;
     finished: Promise<Blob | null>;
+    /** The mic in the take; mute it with `enabled`. Null when sound was off or the mic was refused. */
+    microphone: MediaStreamTrack | null;
+};
+/** Mute or unmute the mic in this take. Returns whether it is now on. */
+export declare function toggleMicrophone(microphone: MediaStreamTrack): boolean;
+export type RecordOptions = {
+    /** Record the mic too. */
+    sound: boolean;
+    /**
+     * Every second of the recording as it lands, in order; the first chunk carries the file's header, so the
+     * chunks so far always make a playable file. Lets a take be kept somewhere safe while it runs.
+     */
+    onChunk?: (chunk: Blob, index: number, mime: string) => void;
 };
 /**
  * Films this tab. When the page allows screen capture, the browser asks first.
  * When the page forbids it, the visible page is filmed instead, so the record button still works.
+ * With `sound`, the mic is asked for after the screen (the screen prompt needs the click's activation).
  */
-export declare function startTabRecording(onReady?: (take: TabTake) => void): Promise<TabTake>;
+export declare function startTabRecording(options: RecordOptions, onReady?: (take: TabTake) => void): Promise<TabTake>;
 export {};

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

@@ -1,4 +1,4 @@
-import type { Thread } from "./client.js";
+import type { Thread } from "./api.js";
 export type Related = {
     thread: Thread;
     because: string;

package/dist/types/runtime/replay-model.d.ts

@@ -0,0 +1,80 @@
+export type ReplayDraft = {
+    type: "navigate";
+    path: string;
+} | {
+    type: "click";
+    label: string;
+} | {
+    type: "input";
+    label: string;
+    redacted: boolean;
+    value?: string;
+} | {
+    type: "console";
+    level: "error" | "warn";
+    message: string;
+}
+/** A request the page made that failed: `status` 0 means it never got an answer. */
+ | {
+    type: "network";
+    method: string;
+    path: string;
+    status: number;
+}
+/** Words the commenter said while a clip was recording, placed when that piece was spoken. */
+ | {
+    type: "say";
+    text: string;
+};
+export type ReplayEvent = ReplayDraft & {
+    t: number;
+};
+/** When the file goes with a recording: the clip's name and clock, so events sit on its timeline. */
+export type ReplayClip = {
+    name: string;
+    startedAt: number;
+    durationMs: number;
+};
+export type ReplayFile = {
+    v: 1;
+    kind: "instant-replay";
+    url: string;
+    events: ReplayEvent[];
+    clip?: ReplayClip;
+};
+export type ReplayBufferOptions = {
+    now?: () => number;
+    /** How far back events are kept. */
+    windowMs?: number;
+    maxEvents?: number;
+};
+/**
+ * What the commenter did, as a rolling window. The default minute backs the instant replay; a recording keeps a
+ * wider one for the clip's whole length. Stays in memory until it is attached.
+ */
+export declare class ReplayBuffer {
+    private items;
+    private readonly now;
+    private readonly windowMs;
+    private readonly maxEvents;
+    constructor(options?: ReplayBufferOptions | (() => number));
+    push(event: ReplayDraft): void;
+    /** An event that happened at `t`, not now: narration lands when it was spoken, not when it was written. */
+    pushAt(event: ReplayDraft, t: number): void;
+    /** `windowMs` keeps only the events of that last stretch. */
+    snapshot(url: string, clip?: ReplayClip, windowMs?: number): ReplayFile | null;
+    /** Every event still in the window, oldest first. */
+    events(): ReplayEvent[];
+    clear(): void;
+    get size(): number;
+}
+/** Accepts only the replay shape the toolbar writes. Anything else is dropped. */
+export declare function parseReplay(value: unknown): ReplayFile | null;
+/** The clip name a replay file goes with, by the stamp both carry: `recording-<stamp>.webm` ↔ `replay-<stamp>.json`. */
+export declare function replayStamp(name: string): string | null;
+/** One line of a replay event, as the viewers show it. */
+export declare function replayLine(event: ReplayEvent): string;
+/** Replaces secret query values in place. The page URL stored with a comment uses this too. */
+export declare function redactSecretSearchParams(url: URL): void;
+/** A console call's arguments as one redacted line. */
+export declare function consoleText(args: unknown[]): string;

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

@@ -1,42 +1,9 @@
-export type ReplayDraft = {
-    type: "navigate";
-    path: string;
-} | {
-    type: "click";
-    label: string;
-} | {
-    type: "input";
-    label: string;
-    redacted: boolean;
-    value?: string;
-} | {
-    type: "console";
-    level: "error" | "warn";
-    message: string;
-};
-export type ReplayEvent = ReplayDraft & {
-    t: number;
-};
-export type ReplayFile = {
-    v: 1;
-    kind: "instant-replay";
-    url: string;
-    events: ReplayEvent[];
-};
-/** Rolling minute of what the commenter did. Stays in memory until they attach it. */
-export declare class ReplayBuffer {
-    private now;
-    private events;
-    constructor(now?: () => number);
-    push(event: ReplayDraft): void;
-    snapshot(url: string): ReplayFile | null;
-    clear(): void;
-    get size(): number;
-}
-/** Accepts only the replay shape the toolbar writes. Anything else is dropped. */
-export declare function parseReplay(value: unknown): ReplayFile | null;
+import { type ReplayBuffer } from "./replay-model.js";
+export * from "./replay-model.js";
 /**
  * Records clicks, field changes, navigations, and console errors on this page.
  * Ignores the toolbar. Does not read network traffic. Call the return to stop and drop the buffer.
  */
-export declare function watchActivity(buffer: ReplayBuffer): () => void;
+export declare function watchActivity(buffer: ReplayBuffer, 
+/** Requests that are the toolbar's own (the comment service): never part of what the person did. */
+ignoreUrl?: (url: string) => boolean): () => void;

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

@@ -1,8 +1,14 @@
 import { type RuntimeProps } from "./toolbar.js";
+export { runtimeBuild } from "./build-id.js";
 export { runtimeVersion } from "./runtime-version.js";
 export type { RuntimeProps } from "./toolbar.js";
 export type ToolbarHandle = {
     update(props: RuntimeProps): void;
     unmount(): void;
 };
+/**
+ * Mounts the toolbar. The handle stays valid across a live update: when the worker starts serving a newer build,
+ * the toolbar loads it, unmounts this one and mounts the new one in the same container with the same props, and
+ * the handle the host holds forwards to it.
+ */
 export declare function mount(container: HTMLElement, props: RuntimeProps): ToolbarHandle;