@guidelytech/guide-runtime 0.5.0 → 0.6.2

package/dist/capture.d.ts

@@ -0,0 +1,184 @@
+import { CapturedElement, NormalizedRect, CaptureStepInput } from '@guidelytech/shared';
+
+/**
+ * Pure DOM helpers for how-to capture: which element an interaction is about, how to name it for
+ * people, which fields and on-screen text are sensitive, and where things sit in a screenshot.
+ */
+/** Elements a click is "about" when it lands on them or inside them. */
+declare const CAPTURE_INTERACTIVE_SELECTOR = "a,button,input,select,textarea,label,summary,[role=button],[role=link],[role=tab],[role=menuitem],[role=menuitemcheckbox],[role=menuitemradio],[role=option],[role=checkbox],[role=radio],[role=switch],[role=combobox],[contenteditable]:not([contenteditable=false])";
+/** Always-redacted elements (on top of the project's mask selectors). */
+declare const REDACT_SELECTOR = "[data-guidely-redact]";
+/** Fields whose typed text becomes a `type` step (instead of a click). */
+declare function isTextEntry(el: Element): boolean;
+/** The element a pointer interaction is about: the closest interactive ancestor, else the target itself. */
+declare function actionTarget(target: Element): Element;
+/** The control a `<label>` is for (clicking the label acts on it), if any. */
+declare function labelControl(el: Element): Element | null;
+/** Is the element (or an ancestor) covered by the mask selectors or `[data-guidely-redact]`? */
+declare function isMaskedElement(el: Element, maskSelector: string): boolean;
+/** Fields whose value is never recorded and whose pixels are redacted from screenshots. */
+declare function isSensitiveField(el: Element, maskSelector?: string): boolean;
+type SensitiveNumberKind = "card" | "ssn" | "phone";
+/**
+ * Classifies a number run: card (13–19 digits in groups of 4+), US SSN (3-2-4) or phone
+ * (10–13 digits written with a country code, area-code parentheses or 3+ groups ending in 4 digits).
+ * Dates, times, prices, versions and IP addresses do not match.
+ */
+declare function classifyNumber(run: string): SensitiveNumberKind | null;
+/** Character ranges `[start, end)` of emails, card numbers, SSNs and phone numbers in `text`. */
+declare function findSensitiveText(text: string): Array<[number, number]>;
+/** Typed values are recorded verbatim unless they contain something like a card number or SSN. */
+declare function looksLikeSecretValue(value: string): boolean;
+/** Normalised role: button, link, tab, menuitem, checkbox, radio, switch, field, dropdown, option or element. */
+declare function captureRole(el: Element): string;
+/**
+ * Visible name of an element for people: aria-label, aria-labelledby, its `<label>`, its text
+ * (not for fields, whose value is user data), placeholder, alt, title or name. Max 80 characters.
+ */
+declare function captureLabel(el: Element): string;
+/** People-facing description of the element; masked elements get no label (never their text). */
+declare function describeCapturedElement(el: Element, maskSelector?: string): CapturedElement;
+/** The value a `type` step records: trimmed, at most 200 characters. */
+declare function fieldValue(el: Element): string;
+/** Text of the selected option(s) of a `<select>`. */
+declare function selectedOptionText(el: HTMLSelectElement): string;
+interface Box {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/**
+ * Maps a viewport rect (CSS px) to fractions of a screenshot of that viewport, padded by `pad`
+ * CSS px and clamped to the frame. Returns null when nothing of it is on screen.
+ */
+declare function normalizeRect(rect: Box, viewport: {
+    width: number;
+    height: number;
+}, pad?: number): NormalizedRect | null;
+/** Scales a viewport rect (CSS px) to frame pixels, clipped to the frame. */
+declare function toFrameRect(rect: Box, scaleX: number, scaleY: number, frame: {
+    width: number;
+    height: number;
+}, pad?: number): Box | null;
+interface RedactionOptions {
+    maskSelector?: string;
+    /** Stop after this many text nodes (keeps the synchronous scan cheap on huge pages). */
+    maxTextNodes?: number;
+}
+/**
+ * Viewport rects (CSS px) to blur in a screenshot: password and other sensitive fields, masked and
+ * `[data-guidely-redact]` elements, field values and visible text that look like emails, card
+ * numbers, SSNs or phone numbers. Runs synchronously so it matches the frame grabbed with it.
+ */
+declare function collectRedactions(doc: Document, options?: RedactionOptions): Box[];
+
+/**
+ * Screenshots for how-to capture: a tab-capture stream (`getDisplayMedia`) played into a hidden
+ * video, frames grabbed synchronously into a canvas, sensitive regions blurred into the pixels and
+ * the result encoded — all in the browser, so raw pixels of redacted regions never leave it.
+ */
+type ScreenResult = {
+    ok: true;
+    screen: ScreenSource;
+} | {
+    ok: false;
+    reason: "unsupported" | "denied" | "wrong-surface" | "error";
+};
+interface ScreenSource {
+    /** True while the stream delivers frames. */
+    live(): boolean;
+    /** Called once when the user stops sharing (or the stream ends otherwise). */
+    onEnded(cb: () => void): void;
+    /** Draws the current frame into a new canvas (synchronously). Null when no frame is available. */
+    grab(): HTMLCanvasElement | null;
+    /** Does the current frame show the page as it is after `changedAt` (a `performance.now()` time)? */
+    freshSince(changedAt: number): boolean;
+    /** Resolves when the next frame arrives (or after `timeoutMs`). */
+    nextFrame(timeoutMs?: number): Promise<void>;
+    stop(): void;
+}
+/** Can this browser capture the tab at all? */
+declare function canCaptureScreen(): boolean;
+/**
+ * Asks the user to share this tab (must run from a user gesture) and plays the stream into a
+ * hidden `<video>` appended to `container`. Rejects windows and screens: their frames do not
+ * match the page's viewport, so highlights and redactions would land in the wrong place.
+ */
+declare function requestTabCapture(container: Node, doc?: Document): Promise<ScreenResult>;
+/** Copies the video's current frame into a new canvas. */
+declare function grabFrame(video: HTMLVideoElement, doc?: Document): HTMLCanvasElement | null;
+/**
+ * Blurs viewport rects (CSS px) into the canvas by averaging each region down to a few samples per
+ * line of text and scaling it back up, which leaves nothing legible to recover. Returns the number
+ * of regions blurred.
+ */
+declare function redactCanvas(canvas: HTMLCanvasElement, rects: Box[], viewport: {
+    width: number;
+    height: number;
+}): number;
+/** Encodes as WebP (JPEG where WebP encoding is unsupported), at most `maxWidth` wide and `maxBytes` big. */
+declare function encodeScreenshot(canvas: HTMLCanvasElement, options?: {
+    maxWidth?: number;
+    maxBytes?: number;
+}): Promise<Blob | null>;
+/** Synchronous JPEG data URL (≤ 1600 px wide), for persisting an unsent screenshot while the page unloads. */
+declare function screenshotDataUrl(canvas: HTMLCanvasElement): string | null;
+
+/** A captured step before the SDK gives it a `clientId`. */
+type CaptureStepDraft = Omit<CaptureStepInput, "clientId">;
+interface CapturedStep {
+    step: CaptureStepDraft;
+    /**
+     * The screenshot, already redacted (encode it with `encodeScreenshot`); null without screenshots.
+     * A promise when the current frame predates a scroll or resize: it resolves with the next frame,
+     * after `step.highlight` and `step.redactions` were updated to match it.
+     */
+    frame: HTMLCanvasElement | Promise<HTMLCanvasElement | null> | null;
+}
+interface CaptureOptions {
+    /** How-to title shown in the toolbar before recording starts. */
+    title: string;
+    /** Steps already recorded (a recording continues across full page loads). */
+    stepCount?: number;
+    /** False when the server cannot store screenshots: record steps only. Default true. */
+    screenshots?: boolean;
+    /**
+     * Continue a recording after a full page load: start recording straight away. `navigate` adds a
+     * step for the new page; `screenshots` offers "Screenshots paused — Resume" (the stream is gone).
+     */
+    resume?: {
+        navigate: boolean;
+        screenshots: boolean;
+    };
+    /** Comma-joined CSS selectors whose text and pixels are never captured. */
+    maskSelector?: string;
+    onStep(step: CapturedStep): void;
+    /** Recording started; `screenshots` is whether the user chose to take screenshots. */
+    onStart?(info: {
+        screenshots: boolean;
+    }): void;
+    onFinish(): void;
+    onCancel(): void;
+    doc?: Document;
+}
+interface CaptureSession {
+    /** Shows "Saving…" (and stops recording) while queued uploads finish. */
+    setSaving(saving: boolean): void;
+    isRecording(): boolean;
+    stop(): void;
+}
+/** A repeat press on the same element within this window is a double click, not a new step. */
+declare const DOUBLE_CLICK_MS = 400;
+/** URL changes this soon after an interaction were caused by it (no separate navigate step). */
+declare const NAV_AFTER_ACTION_MS = 1500;
+/** Wait for the page to settle before capturing a navigate step. */
+declare const NAV_SETTLE_MS = 600;
+/**
+ * Starts how-to capture: a Shadow-DOM toolbar (bottom centre, a small pill while recording) and passive capture-phase
+ * listeners that turn clicks, typing, selections and navigations into steps. The app keeps
+ * receiving every event; nothing is prevented.
+ */
+declare function startCapture(options: CaptureOptions): CaptureSession;
+
+export { type Box, CAPTURE_INTERACTIVE_SELECTOR, type CaptureOptions, type CaptureSession, type CaptureStepDraft, type CapturedStep, DOUBLE_CLICK_MS, NAV_AFTER_ACTION_MS, NAV_SETTLE_MS, REDACT_SELECTOR, type RedactionOptions, type ScreenResult, type ScreenSource, type SensitiveNumberKind, actionTarget, canCaptureScreen, captureLabel, captureRole, classifyNumber, collectRedactions, describeCapturedElement, encodeScreenshot, fieldValue, findSensitiveText, grabFrame, isMaskedElement, isSensitiveField, isTextEntry, labelControl, looksLikeSecretValue, normalizeRect, redactCanvas, requestTabCapture, screenshotDataUrl, selectedOptionText, startCapture, toFrameRect };