@journeeze/sdk 0.0.0-stage → 0.1.0-rc.2

package/dist/types/telemetry/telemetry.d.ts

@@ -0,0 +1,63 @@
+import type { CheckinRequest, HelpState } from "../help/core/controller";
+/** One event of the closed plan, as the collector's `HelpEngagementEvent` (Connect JSON names). */
+export interface WireHelpEvent {
+    event: string;
+    journeyId?: string;
+    stepIndex?: number;
+    entry?: string;
+    answer?: string;
+    guideVersion?: string;
+    /** C0b §7: random, unchanged across retries; the collector counts it once per site per hour. */
+    eventId?: string;
+    /** C0b §7: 1, 2, 3… within this page load; never stored, never linked across loads. */
+    seq?: number;
+}
+export interface RecordHelpEventsRequest {
+    siteKey: string;
+    consentGiven: true;
+    events: WireHelpEvent[];
+    /** C0b v1.1 §4: events this page load dropped at an earlier page end (aggregate, no ids). */
+    droppedAtUnload?: number;
+}
+export interface TelemetryOptions {
+    endpoint: string;
+    siteKey: string;
+    /** The help controller: events are derived from its state changes. */
+    subscribe(listener: (state: HelpState) => void): () => void;
+    fetchImpl?: typeof fetch;
+    /** Wait before sending a partial batch (1–10 s; default {@link FLUSH_MS}). */
+    flushMs?: number;
+    /** Randomness for the retry jitter (tests). */
+    random?: () => number;
+    /** A new event id (tests); default `crypto.randomUUID()` (UUIDv4). */
+    newId?: () => string;
+    /**
+     * Honour Global Privacy Control (default: yes). With GPC on, telemetry is off without asking
+     * (C0a §7, ADR 0013 §3); reading help and explicit callouts are not telemetry and still work.
+     * Do Not Track is ignored (C0a §7).
+     */
+    respectGlobalPrivacyControl?: boolean;
+}
+/** Whether Global Privacy Control turns telemetry off for these options. */
+export declare function gpcRefusesTelemetry(opts: Pick<TelemetryOptions, "respectGlobalPrivacyControl">, nav?: object | undefined): boolean;
+export interface Telemetry {
+    /** A check-in answer the reader sent (help calls this after consent). */
+    checkin(req: CheckinRequest): void;
+    /**
+     * Sends what is queued (page-end transport) and stops; nothing is sent afterwards. With
+     * `discard` (a logout, `reset()`) the queue is dropped instead: nothing more about this reader
+     * leaves.
+     */
+    stop(discard?: boolean): void;
+}
+/** The collector's batch limit, and the per-request byte cap (C0b §4). */
+export declare const MAX_BATCH = 50;
+export declare const MAX_BATCH_BYTES: number;
+/** A partial batch waits at most this long (C0b §4: 5 s, configurable 1–10 s). */
+export declare const FLUSH_MS = 5000;
+export declare const MIN_FLUSH_MS = 1000;
+export declare const MAX_FLUSH_MS = 10000;
+/** The in-memory queue cap (C0b §6): this many events or bytes; the oldest are dropped first. */
+export declare const MAX_QUEUED = 200;
+export declare const MAX_QUEUED_BYTES: number;
+export declare function startTelemetry(opts: TelemetryOptions): Telemetry;

package/dist/types/transport.d.ts

@@ -0,0 +1,30 @@
+/** First retry after 1 s, doubling. */
+export declare const RETRY_BASE_MS = 1000;
+/** Retries after the first attempt; 3 for a request that got no response at all (status 0). */
+export declare const MAX_RETRIES = 5;
+export declare const MAX_RETRIES_NO_RESPONSE = 3;
+/** A batch first sent longer ago than this is dropped, so a retry never outlives the 1 h de-duplication window. */
+export declare const MAX_BATCH_AGE_MS: number;
+/** Statuses worth retrying (0 = no response). Every other `4xx` is final. */
+export declare function isRetryable(status: number): boolean;
+/** Whether attempt `retries + 1` may still happen after a failure with `status`. */
+export declare function mayRetry(retries: number, status: number): boolean;
+/**
+ * The wait before retry number `retry` (1-based): `1 s × 2^(retry−1)`, capped at 60 s, ±50 %
+ * jitter, and never shorter than the server's `Retry-After` (itself capped at 60 s).
+ */
+export declare function retryDelayMs(retry: number, retryAfter?: number, random?: () => number): number;
+/** The page-end budget shared by every Journeeze batched stream on the page (C0b v1.1 §4). */
+export declare const PAGE_END_BUDGET_BYTES: number;
+/** Bytes left in this page end's shared budget. Streams fill it in priority order (C0b §4). */
+export declare function pageEndRemaining(): number;
+/**
+ * Sends one batch at page end (C0b v1.1 §4): a `keepalive` fetch (`text/plain`, no credentials,
+ * no other header), or one `sendBeacon` where keepalive is unsupported, never both. The body
+ * must fit {@link pageEndRemaining}; it is charged to the shared budget. Returns whether the
+ * browser accepted it; on `false` the caller keeps the batch for when the page returns and MUST
+ * NOT try another keepalive request.
+ */
+export declare function sendAtPageEnd(endpoint: string, method: string, body: unknown, fetchImpl?: typeof fetch): boolean;
+/** Byte length of `value` as JSON (UTF-8). */
+export declare function jsonBytes(value: unknown): number;

package/dist/types/types.d.ts

@@ -0,0 +1,391 @@
+/** Host-declared context: who is reviewing and where they are in a journey. Ids, never user data. */
+export interface JourneezeContext {
+    persona?: string | undefined;
+    journeyId?: string | undefined;
+    journeyStep?: string | undefined;
+    /** desktop / tablet / mobile. The widget derives it from the viewport when unset. */
+    device?: string | undefined;
+    /** Review-item coordinate, e.g. `plumber` (wire field lands with collector lane L3). */
+    businessType?: string | undefined;
+    /** Review-item coordinate, e.g. `empty` (wire field lands with collector lane L3). */
+    state?: string | undefined;
+}
+export interface JourneezeOptions {
+    /** Public site key from the Journeeze project settings. Not a secret. */
+    siteKey: string;
+    /**
+     * Where the collector paths are served. Defaults to the host page's own origin: the site proxies
+     * `/journeeze.collector.v1.*` to Journeeze (docs/collector-proxy.md), so there is no CORS. A
+     * relative (`/jz`) or absolute override is allowed.
+     */
+    endpoint?: string;
+    context?: JourneezeContext;
+    /** Reviewer token from the board's review link (`?jz_invite=`), when the reviewer was invited. */
+    reviewerToken?: string;
+    /** Told when the mode switches on or off, including from inside the widget (Esc, Exit, "Not now"). */
+    onModeChange?: (enabled: boolean) => void;
+    /**
+     * Told whether in-app help is available to the current user once `enableHelp()` has checked
+     * the site, and again if that changes (#142), so a host can hide its own Help control.
+     */
+    onHelpStatus?: (status: HelpStatus) => void;
+}
+/**
+ * Whether in-app help is available to the current user (#142). `disabled`: the site has help
+ * switched off. `audience`: the site's help is for reviewers only and this user isn't one.
+ */
+export type HelpStatus = {
+    available: true;
+} | {
+    available: false;
+    reason: "disabled" | "audience";
+};
+export type Reaction = "like" | "dislike" | "understood" | "confused";
+export interface JourneezeHandle {
+    /** Switch the feedback mode on: lazy-loads the widget, which asks for consent first. */
+    enable(): Promise<void>;
+    /** Switch the mode off and unmount the widget. Nothing is captured while off. */
+    disable(): void;
+    isEnabled(): boolean;
+    /** Show the help launcher: lazy-loads the help chunk. Reading guides needs no consent. */
+    enableHelp(): Promise<void>;
+    /** Remove the launcher and panel; nothing of the help chunk keeps running. */
+    disableHelp(): void;
+    isHelpEnabled(): boolean;
+    /** Update persona / journey step as the reviewer moves through the host app. */
+    setContext(context: JourneezeContext): void;
+    getContext(): Readonly<JourneezeContext>;
+}
+export { API_PATH_PATTERN, CONTEXT_FIELDS, CONTEXT_ID_PATTERN, CONTEXT_VALUE_MAX_LEN, SITE_KEY_PATTERN, USER_ID_PATTERN } from "./contract";
+/** Where the collector is reached (§5 of the contract; transport in direct-mode-v1.md). */
+export interface JourneezeTransportConfig {
+    /**
+     * The collector origin, e.g. `https://app.journeeze.dev` (direct mode, CORS for the site's
+     * allowlisted origins) or `https://www.example.com` (the site's same-origin proxy). An absolute
+     * `https:` origin; `http:` only for `localhost`/`127.0.0.1`. No path, query or fragment.
+     */
+    apiHost?: string;
+    /**
+     * A path prefix under `apiHost` where the site mounts the collector paths, e.g. `/jz`
+     * (neutral words only: blockers drop paths containing `track`, `analytics` and similar).
+     * Starts with `/`, no trailing `/`, no query or fragment. Default: none.
+     */
+    apiPath?: string;
+}
+/** Screenshot masking options (§6). They can only widen masking, never narrow it. */
+export interface JourneezeMaskingConfig {
+    /**
+     * Extra CSS selectors masked in screenshots, on top of the fixed defaults (form fields,
+     * editable regions, `[data-jz-mask]`, media and frames). Masking misconfiguration fails closed:
+     * if any entry is not a valid selector, or matching it throws, the handle takes no screenshots
+     * at all (feedback is still sent without one) and the SDK warns once (contract §6, v1.1).
+     */
+    maskSelectors?: readonly string[];
+    /** Replace every text run in screenshots with a box of the same size. Default `false`. */
+    maskAllText?: boolean;
+}
+/** What feedback sends as the page path (contract §2/§3, v1.1). */
+export type JourneezePagePathMode = "redacted" | "none";
+/**
+ * A raw event as the SDK's signal patterns see it (signals-v1.md). It never leaves the browser.
+ * `ts` is `performance.now()` time.
+ */
+export interface JourneezeSignalEvent {
+    kind: string;
+    ts: number;
+    fields: Readonly<Record<string, unknown>>;
+}
+/**
+ * The tflo module surface the SDK uses when the host injects its own (signals-v1.md §3.3,
+ * "capability floor"): the `tflo-browser-events@0.1.0` surface. Typed structurally so the SDK
+ * has no build-time dependency on the package.
+ */
+export interface JourneezeTfloModule {
+    TFloBrowser: unknown;
+    Pattern: unknown;
+}
+/** A site rule (signals-v1.md §4.2). The name must be registered for the site. */
+export interface JourneezeSiteRule {
+    /** `^[a-z][a-z0-9_]{0,63}$`, registered for the site; never a platform name or `jz_*`. */
+    name: string;
+    /** A rule in the SDK's own CEL subset (signals-v1.md §4.2), or a predicate over raw events. */
+    when: string | ((event: JourneezeSignalEvent) => boolean);
+    /** Param mapping (`"event.<path>"`); keys must be in the registration's allowlist (≤ 8). */
+    params?: Readonly<Record<string, string>>;
+}
+/**
+ * Signals configuration. signals-v1.md (C0d) §3.2 is the normative definition. Signals run only
+ * with consent, help or feedback mode on and `enabled: true`; before that no tflo code is loaded.
+ */
+export interface JourneezeSignalsConfigV1 {
+    /** Signals are off unless `true`. Default `false`: the signals chunk never loads. */
+    enabled?: boolean;
+    /** Optional site rules. */
+    rules?: readonly JourneezeSiteRule[];
+    /** The host's own tflo module, or a lazy loader for it (`() => import("tflo-browser-events")`). */
+    tflo?: JourneezeTfloModule | (() => Promise<JourneezeTfloModule>);
+}
+/** SDK configuration, contract v1: today's options plus the v1 fields, all optional. */
+export interface JourneezeConfigV1 extends Omit<JourneezeOptions, "endpoint">, JourneezeTransportConfig, JourneezeMaskingConfig {
+    /**
+     * Kept for v0 hosts: a full collector base URL (relative or absolute). When set it wins over
+     * `apiHost`/`apiPath`, and the SDK warns once.
+     * @deprecated Use `apiHost` (and `apiPath`).
+     */
+    endpoint?: string;
+    /**
+     * The signed-in user's opaque id ({@link USER_ID_PATTERN}). Without it feedback is anonymous.
+     * An invalid value is dropped with a console warning and never sent.
+     */
+    userId?: string;
+    /**
+     * Signed host identity (contract §4, v1.3): the host server's signature over `userId`, from
+     * the same authenticated `no-store` response. Unpadded base64url
+     * HMAC-SHA256(site identity secret, `"jz-id-v1\n" + siteKey + "\n" + userId + "\n" + userIdExp`).
+     * Sites that require signed identity ignore an unsigned or expired `userId` (the feedback is
+     * anonymous and carries no screenshot). The SDK never computes or refreshes it: re-supply it
+     * with {@link JourneezeHandleV1.setUser} before `userIdExp`.
+     */
+    userIdSig?: string;
+    /** Expiry of {@link userIdSig}, Unix seconds (at most 24 h ahead). */
+    userIdExp?: number;
+    /**
+     * A CSP nonce set on every `<style>` the SDK injects (in its shadow roots), so hosts with
+     * `style-src 'nonce-…'` need no `'unsafe-inline'`.
+     */
+    nonce?: string;
+    /**
+     * Honour Global Privacy Control (`navigator.globalPrivacyControl === true`): no help telemetry
+     * and no signals are sent. Feedback the user explicitly submits is not affected. Default `true`.
+     */
+    respectGlobalPrivacyControl?: boolean;
+    /**
+     * `"redacted"` (default): send the page path with id-like segments replaced. `"none"`: send no
+     * page path; reviewers group by `journeyStep`. Hosts with route templates should use `"none"`.
+     */
+    pagePath?: JourneezePagePathMode;
+    /** Signals (signals-v1.md §3.2): derived, aggregate-only signals; off unless `enabled`. */
+    signals?: JourneezeSignalsConfigV1;
+}
+/**
+ * The host's signature over a user id (contract §4, v1.3). Passing it again for the same id
+ * only refreshes the signature (no logout).
+ */
+export interface JourneezeUserIdSignature {
+    /** {@link JourneezeConfigV1.userIdSig}. */
+    sig: string;
+    /** {@link JourneezeConfigV1.userIdExp}, Unix seconds. */
+    exp: number;
+}
+/** The handle, contract v1: today's handle plus identity and logout. */
+export interface JourneezeHandleV1 extends JourneezeHandle {
+    /**
+     * Set (or, with `undefined`, clear) the signed-in user's opaque id ({@link USER_ID_PATTERN}).
+     * Applies to feedback created from now on. Switching user is a logout, enforced here: a
+     * different id while one is set calls {@link reset} first; `undefined` while one is set is
+     * {@link reset}; the same id does nothing. An invalid id is treated as `undefined` and warns.
+     */
+    setUser(userId: string | undefined, signature?: JourneezeUserIdSignature): void;
+    /**
+     * Call on logout (contract §8, v1.1). Sends this user's queued and stored feedback once (the
+     * reset-send rule), still attributed to them, then removes it from storage whatever the
+     * outcome; switches feedback mode off; clears the user id, the context, the reviewer token and
+     * the anonymous consent entry; drops queued help telemetry and signals and resets the signals'
+     * per-page-load counters and windows (v1 has no session id); and, if help was on, remounts it
+     * with empty state. Idempotent, safe on a handle that was never enabled, never
+     * throws. The React provider calls it itself when `userId` changes away from an id and on
+     * unmount.
+     */
+    reset(): void;
+}
+/**
+ * Props of `<JourneezeProvider>` (contract §8, "Asynchronous configuration", v1.1-r2): the v1
+ * config with `siteKey` possibly `undefined` while the host's public config loads. While it is
+ * undefined the provider gives its children an inert handle (every method a no-op, nothing sent,
+ * nothing loaded) and `useJourneeze()` never throws; the first defined `siteKey` creates the real
+ * handle.
+ */
+export type JourneezeProviderPropsV1 = Omit<JourneezeConfigV1, "siteKey"> & {
+    siteKey: string | undefined;
+    /** The provider's children; typed structurally so this file needs no React types. */
+    children?: unknown;
+};
+/** Proto3 JSON enum names of `journeeze.collector.v1.Reaction`. */
+export declare const REACTION_WIRE: Readonly<Record<Reaction, string>>;
+/** Proto3 JSON enum names of `journeeze.collector.v1.FeedbackKind` (unspecified is omitted). */
+export declare const FEEDBACK_KIND_WIRE: {
+    readonly request: "FEEDBACK_KIND_REQUEST";
+    readonly callout: "FEEDBACK_KIND_CALLOUT";
+};
+/**
+ * A help-originated feedback kind (north-star N4). Plain feedback has no kind: it omits the
+ * field (proto3 unspecified).
+ */
+export type FeedbackKind = "request" | "callout";
+/** The wire name of a feedback kind. */
+export type WireFeedbackKind = (typeof FEEDBACK_KIND_WIRE)[FeedbackKind];
+export interface WireFeedbackContext {
+    persona?: string | undefined;
+    journeyId?: string | undefined;
+    journeyStep?: string | undefined;
+    tflowId?: string;
+    pagePath?: string;
+    device?: string | undefined;
+    businessType?: string | undefined;
+    state?: string | undefined;
+}
+export interface WireElementAnchor {
+    tflowId?: string;
+    cssSelector?: string;
+    xRatio: number;
+    yRatio: number;
+}
+export interface SubmitFeedbackRequest {
+    siteKey: string;
+    consentGiven: true;
+    context: WireFeedbackContext;
+    anchor?: WireElementAnchor;
+    reaction?: string;
+    comment?: string;
+    screenshotId?: string;
+    reviewerToken?: string;
+    /**
+     * Omitted = plain feedback. A request needs a comment; a callout needs an element anchor or a
+     * step of a guide shown on the site. Neither carries a reaction.
+     */
+    kind?: WireFeedbackKind;
+    /**
+     * Direct-mode contract C0b v1.1 §7: a random UUIDv4 the outbox stamps once per submission and
+     * reuses on every retry; the collector answers a repeat with the original feedback id.
+     */
+    submissionId?: string;
+    /**
+     * Contract C0a §4 (collector.proto `user_id = 10`): the host's opaque user id, fixed when the
+     * submission is written so a queued item replays under the id it was written with.
+     */
+    userId?: string;
+    /** Signed host identity (C0a §4 v1.3, collector.proto `user_id_exp = 12`). */
+    userIdExp?: number;
+    /** Signed host identity (C0a §4 v1.3, collector.proto `user_id_sig = 13`). */
+    userIdSig?: string;
+}
+export interface SubmitFeedbackResponse {
+    feedbackId?: string;
+}
+export interface GetWidgetConfigResponse {
+    enabled?: boolean;
+    consentText?: string;
+    personas?: string[];
+    /** Feedback (help callouts and requests included) from a visitor with no reviewer token and no user id (ADR 0013 §4). */
+    anonymousAllowed?: boolean;
+    /** Who may read the site's help: "reviewers" or "public" (ADR 0013 §1). */
+    helpAudience?: string;
+    /** The site's published journeys and their checkpoints in order (signals-v1.md §4.1, §4.4; C0c § Step ids). */
+    publishedJourneys?: {
+        journeyId: string;
+        stepIds: string[];
+    }[];
+    /** Site signals registered for the site (signals-v1.md §4.2); site rules may emit only these. */
+    siteSignals?: {
+        name: string;
+        meaning?: string;
+        params?: {
+            name: string;
+            type: "int" | "double" | "bool" | "string";
+        }[];
+    }[];
+    /** The site's signals switch (signals-v1.md §4.4): when not true no signals chunk loads. */
+    signalsEnabled?: boolean;
+}
+/** `CreateScreenshotUpload` (collector.proto): reserve a masked PNG/WebP upload, at most 2 MiB. */
+export interface CreateScreenshotUploadRequest {
+    siteKey: string;
+    contentType: "image/webp" | "image/png";
+    /** Exact size of the bytes that will be PUT. */
+    byteLength: number;
+    reviewerToken?: string;
+    /** Opaque host user id (C0a §4) for an attributed end user's upload (#141). */
+    userId?: string;
+    /** Required with `userId` and no `reviewerToken`. */
+    consentGiven?: boolean;
+    /** Signed host identity (C0a §4 v1.3, collector.proto `user_id_exp = 7`). */
+    userIdExp?: number;
+    /** Signed host identity (C0a §4 v1.3, collector.proto `user_id_sig = 8`). */
+    userIdSig?: string;
+}
+/** `GetHelpIndex` (collector.proto): the site's published guides. Read-only, no consent needed. */
+export interface GetHelpIndexRequest {
+    siteKey: string;
+}
+export interface HelpIndexEntry {
+    journeyId?: string;
+    /** The journey's stable id within its project (e.g. `r1-j09`). */
+    slug?: string;
+    title?: string;
+    goal?: string;
+    stepTitles?: string[];
+    /** Changes whenever the guide changes. */
+    version?: string;
+}
+export interface GetHelpIndexResponse {
+    guides?: HelpIndexEntry[];
+    /** Changes whenever any guide changes (also the ETag). */
+    version?: string;
+}
+/** `GetGuide` (collector.proto): one published guide with short-lived same-origin asset links. */
+export interface GetGuideRequest {
+    siteKey: string;
+    journeyId: string;
+}
+export interface GuideStep {
+    index?: number;
+    title?: string;
+    instruction?: string;
+    /** The element the step acts on (`data-tflow-id`), if the app names it. */
+    tflowId?: string;
+    /** Path relative to the collector endpoint; expires. */
+    screenshotUrl?: string;
+    videoStartMs?: number;
+    videoEndMs?: number;
+    /** Every way to find the element, most stable first (contract C0c v1.1 § Targets). */
+    targets?: GuideTarget[];
+    /** The host's `journeyStep` id for this step (C0c v1.1-r2), when known. */
+    stepRef?: string;
+}
+/** One way to find a guide step's element. */
+export interface GuideTarget {
+    /** tflow, testId, role or css. */
+    strategy?: string;
+    /** The tflo id, test id, ARIA role or CSS selector. */
+    value?: string;
+    /** For role: the accessible name. */
+    name?: string;
+}
+export interface GetGuideResponse {
+    journeyId?: string;
+    slug?: string;
+    title?: string;
+    goal?: string;
+    steps?: GuideStep[];
+    /** Paths relative to the collector endpoint; they expire (fetch the guide again). */
+    videoUrl?: string;
+    captionsUrl?: string;
+    /** The guide revision (C0c v1.1-r2): 1 when created, +1 when its content is replaced. */
+    rev?: number;
+    /** Changes when the guide or its asset links change (also the ETag). */
+    version?: string;
+    /** The guide content the steps show (16 hex); help events quote it (ADR 0011). */
+    contentVersion?: string;
+    /** RFC 3339 time the asset links stop working; fetch the guide again before then. */
+    linksExpireAt?: string;
+}
+export interface CreateScreenshotUploadResponse {
+    /** Pass as `SubmitFeedbackRequest.screenshotId` once the upload succeeded. */
+    screenshotId: string;
+    /** Path relative to the collector endpoint to PUT the bytes to. */
+    uploadUrl: string;
+    /** Headers to send with the PUT (content type and a single-use upload token). */
+    headers?: Record<string, string>;
+    /** RFC 3339 time after which the upload is refused. */
+    expiresAt?: string;
+}

package/dist/types/widget/anchor.d.ts

@@ -0,0 +1,11 @@
+import type { WireElementAnchor } from "../types";
+/** `main > section:nth-of-type(2) > button`, relative to the nearest tflo element (or `body`). */
+export declare function structuralSelector(el: Element): string | undefined;
+/** The anchor for a click at (`x`, `y`) viewport coordinates on `el`. */
+export declare function anchorFor(el: Element, x: number, y: number): WireElementAnchor;
+/** Short label for the pointing tag: the tflo id, else the tag name. */
+export declare function elementLabel(el: Element): string;
+/** `[data-jz-block]` regions (contract §10) are left out of screenshots and cannot be anchored. */
+export declare function isBlocked(el: Element): boolean;
+/** Device class from the viewport width, when the host did not declare one. */
+export declare function deviceClass(width: number): "mobile" | "tablet" | "desktop";

package/dist/types/widget/capture.d.ts

@@ -0,0 +1,28 @@
+/** Screenshot masking options (contract §6): they can only widen masking, never narrow it. */
+export interface MaskOptions {
+    /** Extra selectors replaced by a placeholder, exactly like form fields. Invalid entries warn once. */
+    maskSelectors?: readonly string[];
+    /** Replace every text run with a same-size box. Default `false`. */
+    maskAllText?: boolean;
+}
+export declare class MaskingError extends Error {
+}
+/**
+ * Clone hooks for modern-screenshot. `filter` runs on every child before it is cloned (pre-order);
+ * `onCloneEachNode` runs when a node's clone is complete (post-order), so a stack pairs each clone
+ * with its source. Text nodes are filtered but get no clone callback, so they are not stacked.
+ */
+export declare function maskingHooks(root: Node, opts?: MaskOptions): {
+    filter: (node: Node) => boolean;
+    onCloneEachNode: (clone: Node) => void;
+    onCloneNode: (clone: Node) => void;
+    failure: () => string | undefined;
+};
+/** A hatched box with the masked element's geometry. Reads layout only, never content. */
+export declare function placeholderFor(el: Element, doc: Document): HTMLElement;
+/** A transparent box with a blocked element's geometry: it holds the space, with no content. */
+export declare function emptyBoxFor(el: Element, doc: Document): HTMLElement;
+/** The visible viewport as a masked WebP (PNG where WebP encoding is unsupported), ≤ 2 MB. */
+export declare function captureViewport(root?: Element, opts?: MaskOptions): Promise<Blob | undefined>;
+/** The masked clone as SVG markup (what gets rasterised). Used by the e2e privacy checks. */
+export declare function maskedSnapshotSvg(root?: Element): Promise<string>;

package/dist/types/widget/consent.d.ts

@@ -0,0 +1,25 @@
+export declare const CONSENT_VERSION = 1;
+/**
+ * Default consent copy (the site's `GetWidgetConfig.consentText` replaces it). One consent per
+ * site covers both the feedback mode and in-app help check-ins, so both show this same text.
+ */
+export declare const DEFAULT_CONSENT = "Feedback mode captures the element you point at, a screenshot of this page with form fields hidden, your comment, and your persona and journey step. It never records keystrokes, form contents or query strings. Your feedback is visible to the project's review team.";
+/** Default copy for a fully anonymous visitor, who never sends a screenshot (ADR 0013 §4). */
+export declare const DEFAULT_CONSENT_NO_SCREENSHOT = "Feedback mode captures the element you point at, your comment, and your persona and journey step. No screenshot is sent. It never records keystrokes, form contents or query strings. Your feedback is visible to the project's review team.";
+/**
+ * Whose consent (contract §7, §9): per user when the host passes a `userId` (so on a shared device
+ * the next user is asked again), otherwise the site's anonymous entry.
+ */
+export declare const consentScope: (o: {
+    siteKey: string;
+    userId?: string | undefined;
+}) => string;
+/** Forgets the site's anonymous consent (`reset()`, a logout). Users' own entries stay. */
+export declare function clearConsent(siteKey: string, storage?: Storage | undefined): void;
+export declare function safeLocalStorage(): Storage | undefined;
+/** `storage` null: memory only (an anonymous reader of public help, ADR 0013 §3). */
+export declare function hasConsent(scope: string, storage?: Storage | null | undefined): boolean;
+/** `storage` null: remembered for this page only (ADR 0013 §3). */
+export declare function storeConsent(scope: string, storage?: Storage | null | undefined): void;
+/** Test helper: forget in-memory consent. */
+export declare function resetConsentMemory(): void;

package/dist/types/widget/feedback.d.ts

@@ -0,0 +1,36 @@
+import type { MountOptions } from "../loader";
+import type { GetWidgetConfigResponse, JourneezeOptions } from "../types";
+import { CollectorError } from "../wire";
+import { Outbox } from "./outbox";
+export interface FeedbackChannel {
+    readonly outbox: Outbox;
+    /** Removes the page listeners and stores what is unsent for a later widget or help. */
+    dispose(): void;
+}
+export interface FeedbackChannelHooks {
+    /** Runs on pagehide before the outbox is persisted (the widget stashes pending uploads). */
+    beforePersist?: () => void;
+    onDropped?: (error: CollectorError) => void;
+    /**
+     * Keep unsent items in memory only, never in browser storage: an anonymous reader of public
+     * help (ADR 0013 §3). Unsent items are then lost when the page goes away.
+     */
+    memoryOnly?: boolean;
+}
+type ChannelOptions = JourneezeOptions & Partial<Pick<MountOptions, "userId" | "pagePath" | "apiHost" | "apiPath">>;
+/**
+ * Whose outbox items these are (contract §9, v1.1): the reviewer token on reviewer sites, else the
+ * signed-in user, else anonymous. A page claims only its own owner's items.
+ */
+export declare const ownerOf: (o: ChannelOptions) => string;
+/**
+ * The storage half of `reset()` (contract §8, v1.1), loaded only at logout: this owner's stored
+ * feedback is removed from the device now and sent once (keepalive within the page-end budget,
+ * else plain fetch); a send that fails is lost, by design, so no comment text of the user stays at
+ * rest on a shared device. The anonymous consent is forgotten (the loader clears the reviewer token).
+ */
+export declare function logout(options: ChannelOptions): Promise<void>;
+export declare function feedbackChannel(options: ChannelOptions, endpoint: string, hooks?: FeedbackChannelHooks): FeedbackChannel;
+/** The site's public widget configuration (consent copy, personas). */
+export declare function widgetConfig(endpoint: string, siteKey: string): Promise<GetWidgetConfigResponse>;
+export {};

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

@@ -0,0 +1,14 @@
+declare const PATHS: {
+    readonly like: "<circle cx=\"12\" cy=\"12\" r=\"10\"/><path d=\"M8 14s1.5 2 4 2 4-2 4-2\"/><path d=\"M9 9h.01\"/><path d=\"M15 9h.01\"/>";
+    readonly dislike: "<circle cx=\"12\" cy=\"12\" r=\"10\"/><path d=\"M16 16s-1.5-2-4-2-4 2-4 2\"/><path d=\"M9 9h.01\"/><path d=\"M15 9h.01\"/>";
+    readonly understood: "<circle cx=\"12\" cy=\"12\" r=\"10\"/><path d=\"m9 12 2 2 4-4\"/>";
+    readonly confused: "<circle cx=\"12\" cy=\"12\" r=\"10\"/><path d=\"M9.09 9a3 3 0 0 1 5.83 1c0 2-3 3-3 3\"/><path d=\"M12 17h.01\"/>";
+    readonly close: "<path d=\"M18 6 6 18\"/><path d=\"m6 6 12 12\"/>";
+    readonly persona: "<path d=\"M19 21v-2a4 4 0 0 0-4-4H9a4 4 0 0 0-4 4v2\"/><circle cx=\"12\" cy=\"7\" r=\"4\"/>";
+    readonly step: "<path d=\"M5 12h14\"/><path d=\"m12 5 7 7-7 7\"/>";
+    readonly info: "<circle cx=\"12\" cy=\"12\" r=\"10\"/><path d=\"M12 16v-4\"/><path d=\"M12 8h.01\"/>";
+};
+export type IconName = keyof typeof PATHS;
+/** A decorative (aria-hidden) inline SVG icon. Static markup only. */
+export declare function icon(name: IconName, size?: number): SVGSVGElement;
+export {};