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

package/dist/types/context.d.ts

@@ -0,0 +1,6 @@
+/** The tflo id grammar (ADR 0009): an analytics contract name, never user content. */
+export declare const TFLOW_ID: RegExp;
+/** The nearest `data-tflow-id` at or above `el`, if it is a valid contract name. */
+export declare function tflowIdAt(el: Element | null): string | undefined;
+/** Path only: query strings and fragments can carry tokens and PII, so they never leave the page. */
+export declare function pagePath(href: string): string;

package/dist/types/contract.d.ts

@@ -0,0 +1,13 @@
+export { SITE_KEY_PATTERN, USER_ID_PATTERN } from "./loader";
+/** `apiPath`: one or more `/segment`s of URL-safe characters; no trailing `/`, query or fragment. */
+export declare const API_PATH_PATTERN: RegExp;
+/** A context value the collector accepts: 1..=128 printable characters (no control characters). */
+export declare const CONTEXT_VALUE_MAX_LEN = 128;
+/**
+ * The recommended context-id grammar (the tflo id grammar, ADR 0009): an id, never user content.
+ * The SDK warns once per field when a value does not match it, and still sends it if it is valid
+ * for the collector ({@link CONTEXT_VALUE_MAX_LEN}).
+ */
+export declare const CONTEXT_ID_PATTERN: RegExp;
+/** The context fields, in wire order. `setContext` merges; `undefined` clears one field. */
+export declare const CONTEXT_FIELDS: readonly ["persona", "journeyId", "journeyStep", "device", "businessType", "state"];

package/dist/types/help/core/client.d.ts

@@ -0,0 +1,26 @@
+import type { GetGuideResponse, GetHelpIndexResponse } from "../../types";
+export interface HelpClientOptions {
+    endpoint: string;
+    siteKey: string;
+    /** Sent on help reads when set: reviewers sites require it, public sites validate it (ADR 0013 §1). */
+    reviewerToken?: string | undefined;
+    fetchImpl?: typeof fetch;
+    now?: () => number;
+    /** How long a value is used without asking the collector again. */
+    freshMs?: number;
+}
+/** Refetch a guide this long before its asset links stop working. */
+export declare const LINK_MARGIN_MS = 60000;
+export declare class HelpClient {
+    private readonly opts;
+    private indexEntry;
+    private readonly guides;
+    private readonly inflight;
+    private readonly now;
+    private readonly freshMs;
+    constructor(opts: HelpClientOptions);
+    index(): Promise<GetHelpIndexResponse>;
+    guide(journeyId: string): Promise<GetGuideResponse>;
+    private body;
+    private read;
+}

package/dist/types/help/core/controller.d.ts

@@ -0,0 +1,175 @@
+import type { GetGuideResponse, HelpIndexEntry } from "../../types";
+import type { AnchorResult, StepTarget } from "./highlight";
+export type CheckinAnswer = "understood" | "confused";
+export type CheckinPhase = "idle" | "asking" | "needs-consent" | "sending";
+export type SendOutcome = "sent" | "queued" | "dropped";
+export interface GuideStepView {
+    index: number;
+    title: string;
+    instruction: string;
+    tflowId?: string | undefined;
+    /** Ways to find the step's element, most stable first (a lone tflo anchor when none were stored). */
+    targets?: StepTarget[] | undefined;
+    /** The host's `journeyStep` id for this step, when known (contract C0c v1.1-r2). */
+    stepRef?: string | undefined;
+    /** Absolute, short-lived URL (same origin as the collector). */
+    screenshotUrl?: string | undefined;
+    videoStartMs?: number | undefined;
+    videoEndMs?: number | undefined;
+}
+export interface GuideView {
+    journeyId: string;
+    /** The journey's id within its project (`r1-j09`); check-ins are recorded against it. */
+    slug: string;
+    title: string;
+    goal: string;
+    steps: GuideStepView[];
+    videoUrl?: string | undefined;
+    captionsUrl?: string | undefined;
+    /** The guide content shown (`GetGuide.contentVersion`); help events quote it. */
+    version?: string | undefined;
+}
+export type HelpState = {
+    view: "closed";
+}
+/** The site has help switched off (collector `failed_precondition`). Render nothing; final. */
+ | {
+    view: "disabled";
+} | {
+    view: "index";
+    status: "loading" | "ready" | "error";
+    query: string;
+    results: HelpIndexEntry[];
+    total: number;
+    /** A request in progress (absent: idle). */
+    signal?: SignalPhase | undefined;
+    /** Result of the last callout/request send. */
+    signalNotice?: SendOutcome | undefined;
+} | {
+    view: "guide";
+    status: "loading" | "ready" | "error";
+    journeyId: string;
+    guide?: GuideView | undefined;
+    /** Position in `guide.steps`. */
+    step: number;
+    /** Whether the current step's element was found and highlighted. */
+    anchor: AnchorResult;
+    checkin: CheckinPhase;
+    /** Result of the last check-in send, for a short confirmation. */
+    notice?: SendOutcome | undefined;
+    /** A callout or request in progress (absent: idle). */
+    signal?: SignalPhase | undefined;
+    /** Result of the last callout/request send. */
+    signalNotice?: SendOutcome | undefined;
+} | {
+    view: "finished";
+    guide: GuideView;
+    notice?: SendOutcome | undefined;
+};
+export interface CheckinRequest {
+    guide: GuideView;
+    step: GuideStepView;
+    answer: CheckinAnswer;
+}
+/**
+ * A help signal the reader chose to send (north-star N4): a one-tap "This is confusing" on a
+ * guide step, or an "I couldn't find how to …" request in their own words. Never automatic:
+ * only an explicit command creates one, and nothing is sent before consent.
+ */
+export type HelpSignal = {
+    kind: "callout";
+    guide: GuideView;
+    step: GuideStepView;
+} | {
+    kind: "request";
+    text: string;
+    guide?: GuideView | undefined;
+    step?: GuideStepView | undefined;
+};
+/** A signal's progress: consent first (nothing leaves the page before), then sending. */
+export type SignalPhase = "idle" | "needs-consent" | "sending";
+/** Longest request text, in characters (the collector's comment limit). */
+export declare const MAX_REQUEST_CHARS = 4000;
+export interface HelpControllerDeps {
+    /** Collector endpoint, to make asset paths absolute. */
+    endpoint: string;
+    loadIndex(): Promise<{
+        guides?: HelpIndexEntry[];
+    }>;
+    loadGuide(journeyId: string): Promise<GetGuideResponse>;
+    /** Highlights the step's element by its targets (`undefined` or empty: the step names none). */
+    highlight(targets: readonly StepTarget[] | undefined): AnchorResult | Promise<AnchorResult>;
+    clearHighlight(): void;
+    hasConsent(): boolean;
+    giveConsent(): void;
+    /** Queues the check-in through the feedback outbox. Called only after consent. */
+    sendCheckin(request: CheckinRequest): Promise<SendOutcome>;
+    /** Queues a callout or request through the feedback outbox. Called only after consent. */
+    sendSignal(signal: HelpSignal): Promise<SendOutcome>;
+    /**
+     * Whether this reader may send callouts and requests (default: yes). An anonymous reader on a
+     * site that refuses anonymous feedback may not (ADR 0013 §4): the view hides those entry
+     * points (`HelpController.canSignal`) and the controller drops the commands.
+     */
+    signalsAllowed?(): boolean;
+}
+export type HelpListener = (state: HelpState) => void;
+/** The collector's answer when the site's help is switched off (board settings, lane N6a). */
+export declare function isHelpDisabled(err: unknown): boolean;
+export declare class HelpController {
+    private readonly deps;
+    private current;
+    private readonly listeners;
+    private entries;
+    /** Invalidates async results after a later command (open another guide, close). */
+    private generation;
+    private readonly asked;
+    private pending;
+    private pendingSignal;
+    constructor(deps: HelpControllerDeps);
+    get state(): HelpState;
+    subscribe(listener: HelpListener): () => void;
+    /** Whether the site serves help (the cached index read). A disabled site goes `disabled`. */
+    probe(): Promise<void>;
+    /** Opens the panel on the guide list (loads the index). */
+    open(): void;
+    close(): void;
+    /** Filters the loaded index locally; the query is never sent. */
+    search(query: string): void;
+    openGuide(journeyId: string): void;
+    /** Help is off for this site: no panel, no launcher, no retries. */
+    private disable;
+    /** Back one step; from the first step, back to the list. */
+    back(): void;
+    /** Ends the current step: asks "Did this step make sense?" once per step, then moves on. */
+    next(): void;
+    /** Answers the check-in. Without consent, asks for it first (nothing is sent before). */
+    answer(answer: CheckinAnswer): void;
+    /** Skips the check-in for this step. */
+    skipCheckin(): void;
+    giveConsent(): void;
+    /** "Not now": nothing is sent (a pending callout/request is dropped; the guide continues). */
+    declineConsent(): void;
+    canSignal(): boolean;
+    /** "This is confusing" on step `index`: guide, step and element only. After consent. */
+    sendCallout(stepIndex: number): void;
+    /** "I couldn't find how to …" in the reader's words, after consent; never the raw query. */
+    sendRequest(text: string): void;
+    private signal;
+    private patchSignal;
+    private sendSignalNow;
+    private send;
+    /** Re-finds the current step's element (the host's route or layout changed). */
+    refreshHighlight(): void;
+    private markAsked;
+    private advance;
+    private showStep;
+    /**
+     * Highlights the step's element. A result that arrives later (the fallback resolver loads
+     * lazily) is applied only while the same guide is still on the same step.
+     */
+    private anchorFor;
+    private set;
+}
+/** Wire guide → view model: defaults filled, steps ordered, asset paths made absolute. */
+export declare function toView(g: GetGuideResponse, journeyId: string, endpoint: string): GuideView;

package/dist/types/help/core/events.d.ts

@@ -0,0 +1,8 @@
+import type { CheckinRequest, HelpController } from "./controller";
+export interface TelemetryHook {
+    start(): void;
+    checkin(req: CheckinRequest): void;
+    /** `discard` (a logout): drop queued events instead of sending them. */
+    stop(discard?: boolean): void;
+}
+export declare function telemetryHook(endpoint: string, siteKey: string, controller: HelpController): TelemetryHook;

package/dist/types/help/core/help.d.ts

@@ -0,0 +1,24 @@
+import type { MountedWidget, MountOptions, WidgetModule } from "../../loader";
+import { type JourneezeContext, type SubmitFeedbackRequest, type WireFeedbackContext } from "../../types";
+import { type CheckinRequest, type GuideStepView, type GuideView, type HelpSignal } from "./controller";
+import { type HelpView } from "./panel";
+export { HelpController, isHelpDisabled, toView } from "./controller";
+export type { CheckinAnswer, CheckinPhase, CheckinRequest, GuideStepView, GuideView, HelpControllerDeps, HelpListener, HelpSignal, HelpState, SendOutcome, SignalPhase } from "./controller";
+export { MAX_REQUEST_CHARS } from "./controller";
+export { HelpClient } from "./client";
+export { searchGuides } from "./search";
+export { findAnchor, Highlighter, type AnchorResult, type StepTarget } from "./highlight";
+export { PANEL_CSS, placeholderView, type HelpView, type HelpViewOptions } from "./panel";
+/** Feedback context of a guide step: the host's ids, with the guide's journey and step. */
+export declare function guideStepContext(host: Readonly<JourneezeContext>, guide: GuideView, step: GuideStepView, href: string, width: number): WireFeedbackContext;
+/** Feedback context of a check-in: the host's ids, with the guide's journey and step. */
+export declare function checkinContext(host: Readonly<JourneezeContext>, req: CheckinRequest, href: string, width: number): WireFeedbackContext;
+/** Feedback context outside a guide: the host's ids and the page path only. */
+export declare function pageContext(host: Readonly<JourneezeContext>, href: string, width: number): WireFeedbackContext;
+/**
+ * The collector request for a help signal. A callout carries the guide step (and its element id)
+ * with no comment and no reaction; a request carries the reader's own text as its comment.
+ */
+export declare function signalRequest(siteKey: string, host: Readonly<JourneezeContext>, sig: HelpSignal, href: string, width: number): SubmitFeedbackRequest;
+export declare function mountHelp(options: MountOptions, getContext: () => Readonly<JourneezeContext>, view?: HelpView): MountedWidget;
+export declare const mount: WidgetModule["mount"];

package/dist/types/help/core/highlight.d.ts

@@ -0,0 +1,38 @@
+export type AnchorResult = "found" | "missing" | "none";
+/** One way to find a step's element (contract C0c v1.1 § Targets), most stable first. */
+export interface StepTarget {
+    by: "tflow" | "testId" | "role" | "css";
+    value: string;
+    /** For `role`: the accessible name. */
+    name?: string | undefined;
+}
+/** The lazily loaded fallback resolver (its own chunk: `src/resolve/resolve.ts`). */
+export type ResolverLoader = () => Promise<{
+    resolveTarget(targets: readonly StepTarget[], doc: Document): Element | undefined;
+}>;
+/**
+ * The visible element named `tflowId`, or `undefined`. The id is checked against the tflo
+ * grammar first, so it can never inject into the selector.
+ */
+export declare function findAnchor(tflowId: string, doc?: Document): Element | undefined;
+export declare function prefersReducedMotion(win?: Window): boolean;
+export declare class Highlighter {
+    private readonly win;
+    private readonly load;
+    private target;
+    private readonly box;
+    private readonly onMove;
+    /** Bumped on every show/hide, so a late resolver result never outlines a step left behind. */
+    private seq;
+    constructor(layer: HTMLElement | ShadowRoot, win?: Window, load?: ResolverLoader);
+    /**
+     * Outlines the step's element: `"none"` when the step names none, `"missing"` when no target
+     * resolves. A lone tflo anchor resolves at once; other targets load the fallback resolver
+     * first (a failed load is `"missing"`: the step's text still guides).
+     */
+    show(targets: readonly StepTarget[] | undefined): AnchorResult | Promise<AnchorResult>;
+    private outline;
+    hide(): void;
+    dispose(): void;
+    private place;
+}

package/dist/types/help/core/panel.d.ts

@@ -0,0 +1,11 @@
+import type { HelpController } from "./controller";
+export interface HelpViewOptions {
+    /** The consent copy to show before the first check-in is sent (the site's or the default). */
+    consentText(): Promise<string>;
+}
+/** A view renders the controller's state into the help's closed shadow root. */
+export type HelpView = (root: ShadowRoot, controller: HelpController, options: HelpViewOptions) => {
+    destroy(): void;
+};
+export declare const PANEL_CSS = "\n:host { all: initial; }\n.launcher { position:fixed; left:24px; bottom:24px; z-index:2147483646; width:44px; height:44px; border-radius:22px;\n  border:1px solid #1D2024; background:#1D2024; color:#FFFFFF; font:600 18px/1 system-ui,sans-serif; cursor:pointer; }\n.panel { position:fixed; left:24px; bottom:80px; z-index:2147483646; width:min(340px, calc(100vw - 48px));\n  max-height:min(70vh, 560px); overflow:auto; box-sizing:border-box; padding:16px; border:1px solid rgb(29 32 36/12%);\n  border-radius:10px; background:#FFFFFF; color:#1D2024; font:14px/1.45 system-ui,sans-serif; box-shadow:0 8px 24px rgb(0 0 0/12%); }\n.panel h2 { font-size:15px; margin:0 0 8px; }\n.panel p { margin:0 0 8px; }\n.panel ul { list-style:none; padding:0; margin:8px 0 0; }\n.panel li button { display:block; width:100%; text-align:left; padding:8px; margin:0 0 4px; border:1px solid rgb(29 32 36/12%);\n  border-radius:6px; background:#FFFFFF; color:inherit; font:inherit; cursor:pointer; }\n.panel input { width:100%; box-sizing:border-box; padding:8px; border:1px solid rgb(29 32 36/24%); border-radius:6px; font:inherit; }\n.panel .row { display:flex; gap:8px; flex-wrap:wrap; margin-top:12px; }\n.panel .row button { padding:6px 12px; border:1px solid #1D2024; border-radius:6px; background:#FFFFFF; color:#1D2024; font:inherit; cursor:pointer; }\n.panel .muted { color:#5D636B; font-size:13px; }\n.panel img { max-width:100%; border:1px solid rgb(29 32 36/12%); border-radius:6px; }\n:focus-visible { outline:2px solid #3D63C9; outline-offset:2px; }\n.jz-help-highlight { position:fixed; z-index:2147483645; pointer-events:none; box-sizing:border-box;\n  border:2px solid #3D63C9; border-radius:6px; box-shadow:0 0 0 4px rgb(61 99 201/20%); }\n";
+export declare const placeholderView: HelpView;

package/dist/types/help/core/search.d.ts

@@ -0,0 +1,7 @@
+import type { HelpIndexEntry } from "../../types";
+/**
+ * Guides matching every word of `query`, best first: a word in the title counts most, then the
+ * goal, then a step title. A blank query returns the index unchanged. No match returns `[]` (the
+ * UI offers "I couldn't find how to …" there).
+ */
+export declare function searchGuides(entries: readonly HelpIndexEntry[], query: string): HelpIndexEntry[];

package/dist/types/help/ui/callout.d.ts

@@ -0,0 +1,2 @@
+import type { HelpController } from "../core/controller";
+export declare function calloutButton(controller: HelpController, stepIndex: number): HTMLButtonElement;

package/dist/types/help/ui/panel.d.ts

@@ -0,0 +1,3 @@
+import type { HelpView } from "../core/panel";
+export type { HelpView, HelpViewOptions } from "../core/panel";
+export declare const helpPanelView: HelpView;

package/dist/types/help/ui/request.d.ts

@@ -0,0 +1,2 @@
+import type { HelpController } from "../core/controller";
+export declare function requestForm(controller: HelpController, query: string): HTMLFormElement;

package/dist/types/help/ui/styles.d.ts

@@ -0,0 +1 @@
+export declare const HELP_UI_CSS = "\n:host {\n  all: initial;\n  --jz-canvas:#F7F7F5; --jz-surface:#FFFFFF; --jz-raised:#F0F0EC; --jz-ink:#1D2024; --jz-muted:#5D636B;\n  --jz-faint:#6C727B; --jz-rule:rgb(29 32 36 / 12%); --jz-accent:#3D63C9; --jz-accent-ink:#FFFFFF;\n  --jz-accent-soft:rgb(61 99 201 / 10%); --jz-polished:#2F7D4F; --jz-confused:#6E4FC2;\n  --jz-shadow:0 1px 3px rgb(0 0 0 / 12%);\n  font: 400 13px/1.45 system-ui, -apple-system, \"Segoe UI\", sans-serif;\n  color: var(--jz-ink); -webkit-font-smoothing: antialiased;\n}\n@media (prefers-color-scheme: dark) {\n  :host {\n    --jz-canvas:#111316; --jz-surface:#181B1F; --jz-raised:#20242A; --jz-ink:#E8EAED; --jz-muted:#A3A9B2;\n    --jz-faint:#8A919B; --jz-rule:rgb(232 234 237 / 12%); --jz-accent:#7F9CF0; --jz-accent-ink:#111316;\n    --jz-accent-soft:rgb(127 156 240 / 14%); --jz-polished:#5DBB84; --jz-confused:#A48BEA;\n  }\n}\n*, *::before, *::after { box-sizing: border-box; }\nbutton { font: inherit; color: inherit; cursor: pointer; }\n:focus-visible { outline: 2px solid var(--jz-accent); outline-offset: 2px; }\nbutton:disabled { opacity: .45; cursor: not-allowed; }\n[hidden] { display: none !important; }\n\n.launcher { position:fixed; left:24px; bottom:24px; z-index:2147483646; width:44px; height:44px; min-width:44px; min-height:44px;\n  display:flex; align-items:center; justify-content:center; padding:0; border:1px solid var(--jz-accent); border-radius:999px;\n  background:var(--jz-accent); color:var(--jz-accent-ink); font-size:18px; font-weight:600; box-shadow:var(--jz-shadow);\n  transition: background 180ms ease-out, transform 180ms ease-out; }\n.launcher:hover, .launcher[aria-expanded=\"true\"] { background:var(--jz-ink); border-color:var(--jz-ink); }\n\n.panel { position:fixed; left:24px; bottom:80px; z-index:2147483646; width:min(360px, calc(100vw - 48px));\n  max-height:min(75vh, 580px); overflow:auto; padding:16px; border:1px solid var(--jz-rule); border-radius:10px;\n  background:var(--jz-surface); color:var(--jz-ink); box-shadow:var(--jz-shadow);\n  transition: opacity 180ms ease-out, transform 180ms ease-out; }\n.panel-head { display:flex; align-items:center; justify-content:space-between; gap:8px; margin-bottom:12px; }\n.panel-head h2 { margin:0; font-size:14px; font-weight:600; }\n.icon-btn { width:44px; height:44px; min-width:44px; display:flex; align-items:center; justify-content:center; padding:0;\n  border:0; border-radius:6px; background:transparent; color:var(--jz-faint); transition: color 180ms ease-out, background 180ms ease-out; }\n.icon-btn:hover { color:var(--jz-ink); background:var(--jz-raised); }\n\n.panel input { width:100%; min-height:44px; padding:8px 12px; border:1px solid var(--jz-rule); border-radius:6px;\n  background:var(--jz-canvas); color:var(--jz-ink); font:inherit; }\n.panel input::placeholder { color:var(--jz-faint); }\n.panel ul { list-style:none; padding:0; margin:12px 0 0; }\n.panel li { margin:0 0 8px; }\n.panel li button { display:block; width:100%; min-height:44px; text-align:left; padding:8px 12px; border:1px solid var(--jz-rule);\n  border-radius:6px; background:var(--jz-surface); color:inherit; font:inherit; transition: background 180ms ease-out, border-color 180ms ease-out; }\n.panel li button:hover { background:var(--jz-raised); border-color:var(--jz-accent); }\n.muted { color:var(--jz-muted); font-size:12px; margin:4px 0 0; }\n.row { display:flex; gap:8px; flex-wrap:wrap; margin-top:12px; }\n.row button { min-height:44px; padding:0 16px; border:1px solid var(--jz-rule); border-radius:6px; background:var(--jz-surface);\n  color:var(--jz-muted); transition: background 180ms ease-out, color 180ms ease-out; }\n.row button:hover { color:var(--jz-ink); background:var(--jz-raised); }\n.row .primary { border-color:var(--jz-accent); background:var(--jz-accent); color:var(--jz-accent-ink); }\n\n.card { border:1px solid var(--jz-rule); border-radius:10px; padding:16px; }\n.card h2 { margin:0 0 8px; font-size:14px; font-weight:600; }\n.progress { height:4px; margin:8px 0 12px; border-radius:999px; background:var(--jz-raised); overflow:hidden; }\n.progress-fill { height:100%; border-radius:999px; background:var(--jz-accent); transition: width 180ms ease-out; }\n.step-title { margin:0 0 8px; font-weight:600; }\n.panel img, .panel video { max-width:100%; margin-top:12px; border:1px solid var(--jz-rule); border-radius:6px; }\n\n.checkin { margin-top:12px; padding-top:12px; border-top:1px solid var(--jz-rule); }\n.checkin p { margin:0 0 8px; }\n.callout-btn { display:inline-flex; align-items:center; gap:6px; margin-top:12px; min-height:44px; padding:0 16px;\n  border:1px solid var(--jz-confused); border-radius:6px; background:var(--jz-surface); color:var(--jz-confused);\n  transition: background 180ms ease-out, color 180ms ease-out; }\n.callout-btn:hover { background:var(--jz-raised); }\n.callout-btn svg { flex:none; }\n.request { margin-top:12px; }\n.request p { margin:0 0 8px; color:var(--jz-muted); font-size:12px; }\n.request textarea { display:block; width:100%; padding:8px 12px; border:1px solid var(--jz-rule); border-radius:6px;\n  background:var(--jz-canvas); color:var(--jz-ink); font:inherit; resize:vertical; }\n.request button { margin-top:8px; min-height:44px; padding:0 16px; border:1px solid var(--jz-accent);\n  border-radius:6px; background:var(--jz-accent); color:var(--jz-accent-ink); }\n.checkin-btn { display:inline-flex; align-items:center; gap:6px; }\n.checkin-btn.understood { color:var(--jz-polished); border-color:var(--jz-polished); }\n.checkin-btn.confused { color:var(--jz-confused); border-color:var(--jz-confused); }\n.checkin-btn svg { flex:none; }\n\n@media (prefers-reduced-motion: reduce) {\n  :host *, :host *::before, :host *::after { animation-duration:1ms !important; transition-duration:1ms !important; }\n}\n.jz-help-highlight { position:fixed; z-index:2147483645; pointer-events:none; box-sizing:border-box;\n  border:2px solid var(--jz-accent); border-radius:6px; box-shadow:0 0 0 4px var(--jz-accent-soft); }\n";

package/dist/types/index.d.ts

@@ -0,0 +1,7 @@
+export { createJourneeze } from "./loader";
+export { tflowIdAt, pagePath } from "./context";
+export { isMasked } from "./mask";
+export { takeReviewerToken } from "./invite";
+export type { HelpModule, JourneezeHelpHandle, MountedWidget, WidgetModule } from "./loader";
+export type { MountOptions } from "./loader";
+export type { JourneezeConfigV1, JourneezeContext, JourneezeHandle, JourneezeHandleV1, JourneezeMaskingConfig, JourneezeOptions, JourneezeTransportConfig, HelpStatus, Reaction } from "./types";

package/dist/types/invite.d.ts

@@ -0,0 +1,4 @@
+/** Takes `jz_invite` from the URL (removing it) or from this tab's session. */
+export declare function takeReviewerToken(siteKey: string): string | undefined;
+/** Forgets this tab's reviewer token (`reset()`, a logout). */
+export declare function clearReviewerToken(siteKey: string): void;

package/dist/types/loader.d.ts

@@ -0,0 +1,57 @@
+import type { JourneezeConfigV1, JourneezeContext, JourneezeHandle, JourneezeHandleV1, JourneezeOptions, JourneezeSignalsConfigV1, JourneezeUserIdSignature } from "./types";
+/**
+ * An opaque, host-computed user id (§4 of the contract): the host's server computes
+ * `HMAC-SHA256(server_secret, immutable_internal_user_id)` and passes the digest as 64 lowercase
+ * hex characters or 43 unpadded base64url characters. Nothing else passes: an email, a name, a raw
+ * UUID, a ULID or a numeric id is refused. The SDK never hashes. Deliver it only in an
+ * authenticated, per-user, `Cache-Control: no-store` response, never in public config.
+ */
+export declare const USER_ID_PATTERN: RegExp;
+/** A site's public key: `pk_` + 32 lowercase hex (the collector's `SiteKey`). Not a secret. */
+export declare const SITE_KEY_PATTERN: RegExp;
+export interface MountedWidget {
+    /** `discard` (on `reset()`, a logout): drop queued telemetry instead of sending it. */
+    unmount(discard?: boolean): void;
+    /** Called after the host changed the context (route or journey step changes). */
+    contextChanged?(): void;
+}
+/**
+ * What a lazy chunk is mounted with: the host's options. The chunk resolves the collector base
+ * (`collectorBase`) and validates context (`checkContext`). `userId` is read live (it can change
+ * while a chunk is mounted; consent uses the current one) and is already validated.
+ */
+export interface MountOptions extends JourneezeOptions {
+    apiHost?: string;
+    apiPath?: string;
+    readonly userId?: string | undefined;
+    /** Signed host identity (contract §4, v1.3) from the config; checked and sent by the widget. */
+    userIdSig?: string | undefined;
+    userIdExp?: number | undefined;
+    /** The signature last given to `setUser` (it wins over the config's). */
+    signature?: JourneezeUserIdSignature | "" | undefined;
+    maskSelectors?: readonly string[];
+    maskAllText?: boolean;
+    nonce?: string;
+    /** Global Privacy Control is on and honoured: no help telemetry and no signals (§7). */
+    noTelemetry?: boolean;
+    pagePath?: "redacted" | "none";
+    /** Signals (signals-v1.md §3.2); run only by the lazy chunks, after consent. */
+    signals?: JourneezeSignalsConfigV1;
+}
+export interface WidgetModule {
+    /** `exit` switches the mode off from inside the widget (Esc, the toggle's Exit, "Not now"). */
+    mount(options: MountOptions, getContext: () => Readonly<JourneezeContext>, exit: () => void): MountedWidget;
+}
+/** The lazy `help` chunk (north-star N3): a launcher and guides built from the site's journeys. */
+export type HelpModule = WidgetModule;
+export type WidgetImporter = () => Promise<WidgetModule>;
+export type HelpImporter = () => Promise<HelpModule>;
+/** Kept for compatibility: `JourneezeHandle` itself now declares the help methods (#68). */
+export type JourneezeHelpHandle = JourneezeHandle;
+/** One `[journeeze]` warning per message per page. */
+export declare function warnOnce(message: string): void;
+/** Test helper: forget which warnings were shown. */
+export declare function resetWarnings(): void;
+/** A user id the contract accepts (§4), else `undefined` with a warning. Never hashed here. */
+export declare function checkUserId(id: string | undefined): string | undefined;
+export declare function createJourneeze(config: JourneezeConfigV1, importWidget?: WidgetImporter, importHelp?: HelpImporter): JourneezeHandleV1;

package/dist/types/mask.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Editable by state, not by attribute spelling: `contenteditable` is an enumerated attribute with
+ * case-insensitive keywords (`TRUE`, `Plaintext-Only` are editable), so any value other than a
+ * case-insensitive "false" counts, as does `isContentEditable` (inherited editability).
+ */
+export declare function isEditable(el: Element): boolean;
+/** This element itself must be masked (used by the screenshot clone filter). */
+export declare function isMaskedElement(el: Element): boolean;
+/** This element or an ancestor is masked. */
+export declare function isMasked(el: Element): boolean;

package/dist/types/react.d.ts

@@ -0,0 +1,9 @@
+import { type ReactNode } from "react";
+import { type JourneezeHelpHandle } from "./loader";
+import { type JourneezeConfigV1, type JourneezeContext, type JourneezeHandle, type JourneezeHandleV1, type JourneezeOptions, type JourneezeProviderPropsV1 } from "./types";
+export type JourneezeProviderProps = JourneezeProviderPropsV1 & {
+    children: ReactNode;
+};
+export declare function JourneezeProvider(props: JourneezeProviderProps): import("react").JSX.Element;
+export declare function useJourneeze(): JourneezeHandleV1;
+export type { JourneezeConfigV1, JourneezeContext, JourneezeHandle, JourneezeHandleV1, JourneezeHelpHandle, JourneezeOptions };

package/dist/types/resolve/resolve.d.ts

@@ -0,0 +1,12 @@
+import type { StepTarget } from "../help/core/highlight";
+/**
+ * The element's accessible name, following the accname order closely enough for guides:
+ * aria-labelledby, aria-label, native labels (`<label>`, `alt`), content for roles named from
+ * content, then `title` / `placeholder`.
+ */
+export declare function accessibleName(el: Element, role: string): string;
+/**
+ * The step's element: the first target, in the stored order, that resolves to exactly one
+ * visible element; `undefined` when none does.
+ */
+export declare function resolveTarget(targets: readonly StepTarget[], doc?: Document): Element | undefined;

package/dist/types/script.d.ts

@@ -0,0 +1,6 @@
+import { type JourneezeHelpHandle } from "./loader";
+declare global {
+    interface Window {
+        Journeeze?: JourneezeHelpHandle;
+    }
+}

package/dist/types/signals/cel.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Compile a site-rule string in the SDK's CEL subset into a single-event predicate, or return
+ * `undefined` for anything outside the subset. Never throws and never uses `eval`/`Function`.
+ */
+export declare function compileRule(src: string): ((event: {
+    kind: string;
+    fields: Readonly<Record<string, unknown>>;
+}) => boolean) | undefined;

package/dist/types/signals/hook.d.ts

@@ -0,0 +1,10 @@
+import type { MountOptions } from "../loader";
+import type { GetWidgetConfigResponse, JourneezeContext } from "../types";
+export interface SignalsHook {
+    /** `site`: the widget config the chunk read (or is reading); its `signalsEnabled` gates loading. */
+    start(site: Promise<GetWidgetConfigResponse | undefined> | GetWidgetConfigResponse | undefined): void;
+    /** `discard` (a logout, `reset()`): drop queued signals instead of sending them. */
+    stop(discard?: boolean): void;
+    contextChanged(): void;
+}
+export declare function signalsHook(options: MountOptions, endpoint: string, getContext: () => Readonly<JourneezeContext>): SignalsHook;

package/dist/types/signals/signals.conformance.d.ts

@@ -0,0 +1,2 @@
+/** Runs the whole conformance suite against one installed tflo package (`pkg` is its node_modules name). */
+export declare function signalsConformance(pkg: string, tflo: typeof import("tflo-browser-events")): void;

package/dist/types/signals/signals.d.ts

@@ -0,0 +1,145 @@
+import { CONTEXT_FIELDS } from "../contract";
+import type { MountOptions } from "../loader";
+import type { GetWidgetConfigResponse, JourneezeContext, JourneezeTfloModule } from "../types";
+export type ParamValue = {
+    intValue: string;
+} | {
+    doubleValue: number;
+} | {
+    boolValue: boolean;
+} | {
+    stringValue: string;
+};
+export interface SignalEnvelope {
+    eventId: string;
+    seq: number;
+    name: string;
+    source: "SIGNAL_SOURCE_PLATFORM" | "SIGNAL_SOURCE_SITE";
+    context: Partial<Record<(typeof CONTEXT_FIELDS)[number], string>>;
+    target?: string;
+    params?: Record<string, ParamValue>;
+}
+export interface RecordSignalsRequest {
+    siteKey: string;
+    consentGiven: true;
+    ruleSet: string;
+    signals: SignalEnvelope[];
+    /** Signals that didn't fit the page-end send and were dropped (C0d §6, field 5). */
+    droppedAtUnload?: number;
+}
+/** The platform rule set this chunk runs (C0d §4.1). Thresholds are part of the version. */
+export declare const RULE_SET = "jz-platform@1";
+export declare const RAGE_WINDOW_MS = 700;
+export declare const RAGE_CLICKS = 3;
+export declare const HESITATION_MS = 3000;
+export declare const DEAD_CLICK_MS = 1000;
+export declare const ABANDON_MS = 120000;
+export declare const CLOCK_MS = 1000;
+export declare const THROTTLE_MS = 10000;
+export declare const PAGE_CAP = 300;
+export declare const MAX_TARGETS = 64;
+export declare const MAX_BATCH = 50;
+export declare const MAX_BATCH_BYTES: number;
+export declare const FLUSH_MS = 5000;
+export declare const MAX_QUEUED = 200;
+export declare const MAX_QUEUED_BYTES: number;
+interface RawEvent {
+    kind: string;
+    ts: number;
+    fields: Record<string, unknown>;
+}
+interface DerivedSignal {
+    name: string;
+    ts: number;
+    payload: Record<string, unknown>;
+}
+interface Match {
+    first(): RawEvent;
+    last(): RawEvent;
+    readonly length: number;
+}
+interface PatternBuilder {
+    when(p: (e: RawEvent) => boolean): PatternBuilder;
+    then(p: (e: RawEvent) => boolean): PatternBuilder;
+    notThen(p: (e: RawEvent) => boolean): PatternBuilder;
+    within(ms: number): PatternBuilder;
+    emit(fn: (m: Match) => {
+        name?: string;
+        payload?: Record<string, unknown>;
+    }): unknown;
+}
+interface TfloInstance {
+    init(): Promise<void>;
+    addPattern(compiled: unknown): unknown;
+    removePattern(name: string): void;
+    ingest(e: RawEvent): unknown;
+    flush(): Promise<void>;
+    destroy(): void;
+}
+interface TfloCtors {
+    TFloBrowser: new (opts: {
+        sinks: {
+            name: string;
+            send(s: DerivedSignal): void;
+        }[];
+        onSinkError?: (sink: string, err: unknown) => void;
+    }) => TfloInstance;
+    Pattern: new (name: string) => PatternBuilder;
+}
+/** Whether `m` offers the capability floor the SDK relies on (C0d §3.3). */
+export declare function hasFloor(m: unknown): m is TfloCtors;
+/**
+ * The tflo module to attach to: the host's (injected, or its lazy loader, called only now, after
+ * consent), else the SDK's own. An injected module below the floor is ignored with one warning.
+ */
+export declare function resolveTflo(injected: JourneezeSignalsTflo | undefined, loadOwn?: () => Promise<unknown>): Promise<TfloCtors | undefined>;
+type JourneezeSignalsTflo = JourneezeTfloModule | (() => Promise<JourneezeTfloModule>);
+/** The tracked element's `data-tflow-id` for an event target, or undefined (masked or untracked). */
+export declare function trackedId(node: EventTarget | null | undefined, extraMask?: readonly string[]): string | undefined;
+export interface SignalsOptions {
+    options: MountOptions;
+    endpoint: string;
+    getContext: () => Readonly<JourneezeContext>;
+    /** The site's widget config (the chunk that started signals already read it, §4.4). */
+    site: GetWidgetConfigResponse;
+    /** Tests: time, timers, transport and the own-copy loader. */
+    now?: () => number;
+    fetchImpl?: typeof fetch;
+    loadOwn?: () => Promise<unknown>;
+    newId?: () => string;
+}
+export interface Signals {
+    contextChanged(): void;
+    /** Detaches every capture; `discard` (consent withdrawn, logout) drops queued signals unsent. */
+    stop(discard?: boolean): void;
+    /** Tests: settles pending sends. */
+    idle(): Promise<void>;
+}
+/** At most this many windows open at once; the oldest is dropped without firing. */
+export declare const MAX_WINDOWS = 128;
+/**
+ * Starts signals for one handle, or resolves undefined (the site's switch is off, or tflo is
+ * unavailable). Never throws into the host.
+ *
+ * Windows (`notThen(...).within(ms)`) on tflo 0.1.0: a negative step completes only when its
+ * runtime is flushed, and `TFloBrowser.flush()` drains every runtime at once (so it is never
+ * called, C0d §6 N1). Each window is therefore its own pattern, keyed to its own start event, and
+ * at its deadline the SDK flushes that one runtime (`addPattern`'s return value): a window that a
+ * settling event negated flushes empty. At page end windows are removed unflushed.
+ */
+export declare function startSignals(o: SignalsOptions): Promise<Signals | undefined>;
+/** Where the host is in a published journey's checkpoints (C0d §4.1, C0c § Step ids). */
+export interface Checkpoint {
+    journey: string;
+    /** 0-based position in the journey's checkpoints. */
+    index: number;
+    last: boolean;
+}
+/**
+ * The one place that knows how `journeyId`/`journeyStep` match `GetWidgetConfig.publishedJourneys`
+ * (C0c § Step ids): the journey by its slug; the step by exact string equality against the
+ * checkpoints; a repeated checkpoint matches its first occurrence after the current one, else
+ * its first occurrence.
+ */
+export declare function matchCheckpoint(site: GetWidgetConfigResponse, c: Readonly<JourneezeContext>, current?: Checkpoint): Checkpoint | undefined;
+export {};