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

package/dist/types/chat/shell/session.d.ts

@@ -0,0 +1,148 @@
+import type { FeedbackSeverity, FeedbackShape, FeedbackVerdict } from "../../schemas/feedback";
+import { type ConverseAction, type ConverseMenuItem, type ConverseTransport, type FailureKind } from "./converse";
+import type { Copy } from "./copy";
+import { type Chip, type ContextChip, type ReportFacts } from "./model";
+export type Entry = {
+    kind: "assistant";
+    text: string;
+    copyId: string;
+} | {
+    kind: "user";
+    text: string;
+} | {
+    kind: "card";
+    job: string;
+    step: number;
+    of?: number | undefined;
+    title?: string | undefined;
+    instruction?: string | undefined;
+    live: boolean;
+} | {
+    kind: "note";
+    text: string;
+};
+/** A draft screenshot or file ("Show us where", "Attach a file"). */
+export interface Attachment {
+    id: string;
+    /** An image URL for the thumbnail (a `blob:` URL of the masked capture). */
+    thumbnail: string;
+    label?: string;
+    /** Set once uploaded: only uploaded attachments travel with a turn. */
+    screenshotId?: string;
+    /** Shapes drawn over the image, normalised (feedback/v2 `attachments[].shapes`). */
+    shapes?: FeedbackShape[];
+    /** Uploads the masked image; called only after consent. Resolves its `screenshotId`. */
+    upload?: () => Promise<string | undefined>;
+    /** Frees the thumbnail when the attachment leaves the draft. */
+    release?: () => void;
+}
+/** "Point at it": the element's tflo id (feedback/v2 message `anchor`), never its values. */
+export interface DraftAnchor {
+    tflowId: string;
+}
+/** Screenshots per message (feedback/v2 `attachments` maxItems). */
+export declare const MAX_ATTACHMENTS = 5;
+export interface TeamDetails {
+    verdict?: FeedbackVerdict;
+    severity?: FeedbackSeverity;
+}
+export interface SessionDeps {
+    siteKey: string;
+    /** A reviewer session: Team details travel with each turn as turn/v1 `team`. */
+    reviewer?: boolean;
+    transport: ConverseTransport;
+    /** The site's widget copy (`widget.ui.*`, ADR 0020 §5). */
+    t: Copy;
+    /** Page facts for the report's context, read at each turn. */
+    facts(): ReportFacts;
+    hasConsent(): boolean;
+    giveConsent(): void;
+}
+export declare class ChatSession {
+    private readonly deps;
+    /** New when a closed conversation is reopened. */
+    conversationId: string;
+    entries: Entry[];
+    state: string;
+    actions: ConverseAction[];
+    requiresConsent: boolean;
+    pending: boolean;
+    error: FailureKind | undefined;
+    /** Free text is off: Jev is down (a 503, or the server's tap-only clarify). Chips still work. */
+    tapOnly: boolean;
+    /** Set when a send was held back for consent: the view moves focus to Allow. */
+    consentAsked: boolean;
+    filed: string | undefined;
+    attachments: Attachment[];
+    anchor: DraftAnchor | undefined;
+    readonly removed: Set<string>;
+    team: TeamDetails;
+    private job;
+    private step;
+    private last;
+    /** Closed by the user: the next open starts a new conversation. */
+    private ended;
+    private opening;
+    /** Runtime over-masking since the last consented turn, per detector rule (counts only; the
+     *  capture chunk adds to it). They travel with the next consented turn as `overMasked`. */
+    readonly overMask: Map<string, number>;
+    private readonly listeners;
+    private consent;
+    /** The site's widget copy. */
+    readonly t: Copy;
+    constructor(deps: SessionDeps);
+    subscribe(fn: () => void): () => void;
+    private emit;
+    /** The opening question with the site's known jobs (no turn is sent to show it). */
+    start(chips: Chip[]): void;
+    /** The user closed the chat (✕, Esc). A conversation the server knows ends with a `cancel`
+     *  turn (state `closed`; nothing is filed). Fire and forget: its failure shows nothing. */
+    close(): void;
+    /** Opening the chat again after a close starts a new conversation (consent is kept). */
+    reopen(): void;
+    offers(type: ConverseAction["type"]): boolean;
+    /** The server's label of an action on offer ("" when it is not offered or has none). */
+    label(type: ConverseAction["type"]): string;
+    chips(): Chip[];
+    /** The "+" menu with the server's labels and hints, in `items` order. */
+    plusItems(): ConverseMenuItem[];
+    /** The consent line shows: the server offers consent or needs it, and the user has not allowed. */
+    needsConsent(): boolean;
+    allow(): void;
+    contextChips(): ContextChip[];
+    removeContext(key: string): void;
+    setTeam(team: TeamDetails): void;
+    /** Team details without unset fields (turn/v1 `team` is a closed object). */
+    private teamOnWire;
+    /** Adds (or replaces) a draft attachment; false when the message already has five. */
+    addAttachment(a: Attachment): boolean;
+    removeAttachment(id: string): void;
+    setAnchor(anchor: DraftAnchor | undefined): void;
+    /** A calm line in the conversation (never sent). */
+    note(text: string): void;
+    /** Uploads draft images not yet uploaded, after consent only; a failed one leaves the draft. */
+    private uploadPending;
+    /** The draft message a turn carries (after consent only): uploaded images with their shapes,
+     *  and the anchor. */
+    private draft;
+    pickJob(chip: Chip): void;
+    other(): void;
+    next(): void;
+    back(): void;
+    didntWork(): void;
+    talk(): void;
+    /** `Journeeze.feedback()`: the conversation opens at "Report a problem". */
+    reportProblem(): void;
+    /** A typed message. Held back (false) while consent is needed, or while typing is off. */
+    sendText(text: string): boolean;
+    /** "Send report" (the server's `send` action). */
+    sendReport(): boolean;
+    /** Sends the failed turn again with the same `turnId` (the collector de-duplicates it). */
+    retry(): void;
+    private askConsent;
+    private facts;
+    private run;
+    private exec;
+    private send;
+    private apply;
+}

package/dist/types/chat/shell/styles.d.ts

@@ -0,0 +1 @@
+export declare const CHAT_CSS = "\n:host{all:initial;--c:#F7F7F5;--s:#FFF;--r:#F0F0EC;--i:#1D2024;--m:#5D636B;--f:#6C727B;--l:rgb(29 32 36/12%);--a:#3D63C9;--ai:#FFF;--as:rgb(61 99 201/10%);--sh:0 1px 3px rgb(0 0 0/12%),0 4px 12px rgb(0 0 0/8%);\nfont:400 13px/1.45 Inter,system-ui,-apple-system,\"Segoe UI\",sans-serif;color:var(--i);-webkit-font-smoothing:antialiased}\n@media (prefers-color-scheme:dark){:host{--c:#111316;--s:#181B1F;--r:#20242A;--i:#E8EAED;--m:#A3A9B2;--f:#8A919B;--l:rgb(232 234 237/12%);--a:#7F9CF0;--ai:#111316;--as:rgb(127 156 240/14%)}}\n*,*::before,*::after{box-sizing:border-box}\nbutton,input,select{font:inherit;color:inherit}\nbutton{cursor:pointer}\nbutton:disabled,input:disabled{cursor:not-allowed;opacity:.55}\n:focus-visible{outline:2px solid var(--a);outline-offset:2px}\n[hidden]{display:none!important}\n.sr{position:absolute;width:1px;height:1px;overflow:hidden;clip:rect(0 0 0 0);white-space:nowrap}\n.launcher{position:fixed;right:24px;bottom:24px;z-index:2147483646;width:56px;height:56px;border-radius:999px;border:0;background:var(--a);color:var(--ai);font-size:24px;font-weight:600;box-shadow:var(--sh)}\n.panel{position:fixed;right:24px;bottom:92px;z-index:2147483646;width:min(360px,calc(100vw - 48px));height:min(600px,calc(100vh - 116px));display:flex;flex-direction:column;background:var(--s);border:1px solid var(--l);border-radius:10px;box-shadow:var(--sh);overflow:hidden}\n.head{display:flex;justify-content:space-between;align-items:center;gap:8px;padding:8px 8px 8px 16px;border-bottom:1px solid var(--l);background:var(--c)}\n.head h2{margin:0;font-size:13px;font-weight:600}\n.head p{margin:0;font-size:12px;color:var(--f)}\n.x{width:44px;height:44px;border:0;border-radius:6px;background:transparent;color:var(--m);font-size:20px}\n.log{flex:1;overflow-y:auto;padding:16px;display:flex;flex-direction:column;gap:12px}\n.msg{max-width:85%;padding:8px 12px;border:1px solid var(--l);border-radius:12px;white-space:pre-wrap;overflow-wrap:anywhere}\n.as{align-self:flex-start;background:var(--s);border-bottom-left-radius:2px}\n.us{align-self:flex-end;background:var(--as);border-bottom-right-radius:2px}\n.note{align-self:flex-start;margin:0;font-size:12px;color:var(--m)}\n.card{align-self:flex-start;width:90%;padding:12px;border:1px solid var(--l);border-radius:10px;background:var(--c)}\n.card h3{margin:0 0 4px;font-size:12px;font-weight:600;color:var(--a)}\n.card p{margin:0 0 8px;color:var(--m)}\n.row{display:flex;gap:8px;flex-wrap:wrap}\n.btn{min-height:44px;padding:0 16px;border:1px solid var(--l);border-radius:6px;background:var(--s)}\n.pri{background:var(--a);border-color:var(--a);color:var(--ai);font-weight:600}\n.link{min-height:44px;padding:0 4px;border:0;background:none;color:var(--a);text-decoration:underline}\n.foot{border-top:1px solid var(--l);padding:12px;display:flex;flex-direction:column;gap:8px;background:var(--s)}\n.dyn{display:flex;flex-direction:column;gap:8px}.dyn:empty{display:none}\n.chips{display:flex;flex-wrap:wrap;gap:6px}\n.chip{min-height:44px;padding:0 12px;border:1px solid var(--l);border-radius:999px;background:var(--s);color:var(--m)}\n.chip.job{border-color:var(--a);color:var(--a)}\n.err{margin:0;padding:8px;border-radius:6px;background:var(--r);color:var(--i)}\n.consent{margin:0;font-size:12px;color:var(--m)}\n.consent.ask{color:var(--i);font-weight:600}\ndetails{font-size:12px;color:var(--m)}\nsummary{cursor:pointer;min-height:24px}\n.ctx{display:flex;flex-wrap:wrap;gap:6px;margin-top:6px;padding:0;list-style:none}\n.ctx li{display:flex;align-items:center;gap:2px;padding-left:8px;border:1px solid var(--l);border-radius:6px;background:var(--r);color:var(--i)}\n.ctx li.fixed{padding-right:8px;min-height:32px}\n.ctx button,.att button{width:32px;height:32px;border:0;background:none;color:var(--m)}\n.team{display:flex;gap:8px;margin-top:6px}\n.team label{display:flex;flex-direction:column;gap:2px;color:var(--i)}\n.team select{min-height:32px;border:1px solid var(--l);border-radius:6px;background:var(--s)}\n.atts{display:flex;flex-wrap:wrap;gap:8px;margin:0;padding:0;list-style:none}\n.att{position:relative;width:64px;height:48px;border:1px solid var(--l);border-radius:6px;overflow:hidden;background:var(--r)}\n.att img{width:100%;height:100%;object-fit:cover}\n.pt{display:flex;align-items:center;gap:2px;padding-left:8px;border:1px solid var(--l);border-radius:6px;background:var(--r);font-size:12px;max-width:100%;overflow-wrap:anywhere}\n.pt button{width:32px;height:32px;border:0;background:none;color:var(--m)}\n.att button{position:absolute;top:0;right:0;background:var(--i);color:var(--s);border-radius:0 0 0 6px}\n.comp{position:relative;display:flex;gap:6px;align-items:center}\n.comp input{flex:1;min-width:0;min-height:44px;padding:0 12px;border:1px solid var(--l);border-radius:6px;background:var(--c)}\n.ico{width:44px;height:44px;flex:none;border:1px solid var(--l);border-radius:6px;background:var(--s);font-size:18px}\n.send{background:var(--a);border-color:var(--a);color:var(--ai)}\n.menu{position:absolute;left:0;right:0;bottom:52px;z-index:1;padding:4px;margin:0;list-style:none;background:var(--s);border:1px solid var(--l);border-radius:10px;box-shadow:var(--sh)}\n.menu button{display:block;width:100%;min-height:44px;padding:4px 12px;border:0;border-radius:6px;background:none;text-align:left}\n.menu button:hover,.menu button:focus-visible{background:var(--c)}\n.menu small{display:block;color:var(--f)}\n.dots{align-self:flex-start;color:var(--f)}\n@media (max-width:640px){.panel{inset:0;width:auto;height:auto;border-radius:0;border:0}.launcher[aria-expanded=true]{display:none}}\n@media (prefers-reduced-motion:reduce){*{transition-duration:1ms!important}}\n";

package/dist/types/chat/shell/view.d.ts

@@ -0,0 +1,18 @@
+import type { PlusItem } from "./converse";
+import type { ChatSession } from "./session";
+export interface ChatViewOptions {
+    /** A reviewer session (the host passed a reviewer token): shows "Team details". */
+    reviewer: boolean;
+    /** A "+" menu item was chosen (HC8b wires "Show us where" and friends here). */
+    onPlusItem(item: PlusItem): void;
+}
+export interface ChatView {
+    open(): void;
+    close(): void;
+    isOpen(): boolean;
+    /** Hides the chat while the user captures or points at the page; the returned function brings
+     *  it back with focus on the composer's "+" (or the input). */
+    suspend(): () => void;
+    destroy(): void;
+}
+export declare function chatView(root: ShadowRoot, session: ChatSession, opts: ChatViewOptions): ChatView;

package/dist/types/chat/transport.d.ts

@@ -0,0 +1,5 @@
+import type { MountOptions } from "../loader";
+import { type ConverseTransport } from "./shell/converse";
+/** {@link converseTransport} with the caller's identity on each turn, read live from the mount
+ *  options (`setUser` can change the id). */
+export declare function liveTransport(endpoint: string, options: MountOptions, fetchImpl?: typeof fetch): ConverseTransport;

package/dist/types/config.d.ts

@@ -0,0 +1,34 @@
+import type { JourneezeConfigV1, JourneezeContext } from "./types";
+/**
+ * The collector base URL (contract §5): `endpoint` (deprecated, wins), else `apiHost` + `apiPath`,
+ * else the Journeeze collector itself (direct mode, the v1 default: C0a §5 "Change [J3c]", C0b §1).
+ * A v0 host that relied on its own same-origin proxy without `endpoint` must set
+ * `apiHost: location.origin`. `apiHost` is an https origin (http only for localhost/127.0.0.1)
+ * without path, query or fragment.
+ */
+export declare function collectorBase(config: Pick<JourneezeConfigV1, "endpoint" | "apiHost" | "apiPath">, page?: string): string;
+/** The context fields the collector accepts (§3): an invalid value is dropped, never sent. */
+export declare function checkContext(next: Readonly<JourneezeContext>): JourneezeContext;
+/**
+ * The page path feedback carries (contract §3): {@link pagePath} with identifier-like segments
+ * replaced by `:id`, since they can name a person or a record. `pagePath: "none"` (Allumata review
+ * B7) drops it entirely, in the feedback channel.
+ */
+export declare function sentPath(href: string): string;
+/**
+ * The host's signature over the user id (contract §4, v1.3; the widget's uploads and feedback,
+ * the chat's Converse turns), only while it is well formed and
+ * unexpired; otherwise the id travels unsigned (sites that require signed identity then treat
+ * the request as anonymous). Fixed into the request when it is written, like the id.
+ */
+export declare function signedIdentity(o: {
+    userIdSig?: string | undefined;
+    userIdExp?: number | undefined;
+    signature?: {
+        sig: string;
+        exp: number;
+    } | "" | undefined;
+}): {
+    userIdSig?: string;
+    userIdExp?: number;
+};

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,184 @@
+import type { GetGuideResponse, HelpIndexEntry, HelpJobEntry, WireJobRequest } 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;
+    /** The site's jobs ("What are you trying to do?", P4e1), in index order; absent or empty: none. */
+    jobs?: HelpJobEntry[] | undefined;
+    /** 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;
+    jobRequest?: WireJobRequest | 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[];
+        jobs?: HelpJobEntry[];
+    }>;
+    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;
+    /** Whether the site's consent is given (views send nothing about the reader before it). */
+    hasConsent(): boolean;
+    /** "This is confusing" on step `index`: guide, step and element only. After consent. */
+    sendCallout(stepIndex: number): void;
+    /**
+     * "I couldn't find how to …" (or help's "Something else") in the reader's words, after
+     * consent; never the raw query. `jobRequest` (index only): the "so you can…" answer and job.
+     */
+    sendRequest(text: string, jobRequest?: WireJobRequest): 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,32 @@
+import type { CheckinRequest, HelpController } from "./controller";
+/** The answer to "Got it done?" (engagement.proto `JobAnswer`). */
+export type JobAnswer = "YES" | "PARTLY" | "NO";
+/**
+ * A job engagement event (P4e1, ADR 0014 addendum): the job's id and the entry version the reader
+ * saw, plus the answer for an outcome. Never text: "Something else" is feedback, not an event.
+ * `persona` (engagement.proto field 13, follow-up 21) is the host's `persona` context id, which
+ * the jobs view adds when it has the context-id shape (`withPersona`), so answers can be read per
+ * job × persona.
+ */
+export type JobEvent = {
+    event: "PICKED" | "NOT_POSSIBLE";
+    jobId: string;
+    jobVersion?: string | undefined;
+    persona?: string | undefined;
+} | {
+    event: "OUTCOME";
+    jobId: string;
+    jobVersion?: string | undefined;
+    persona?: string | undefined;
+    answer: JobAnswer;
+    harder?: boolean | undefined;
+};
+export interface TelemetryHook {
+    start(): void;
+    checkin(req: CheckinRequest): void;
+    /** A job event; dropped when telemetry was never started (no consent yet). */
+    job(e: JobEvent): 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,25 @@
+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 { JobAnswer, JobEvent } from "./events";
+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,27 @@
+import type { HelpController } from "./controller";
+import type { JobEvent } from "./events";
+import type { Routed } from "./routing";
+export interface HelpViewOptions {
+    /** The consent copy to show before the first check-in is sent (the site's or the default). */
+    consentText(): Promise<string>;
+    /** The host's `persona` context id, read live (orders "Common for you"). */
+    persona?(): string | undefined;
+    /**
+     * A job event (P4e1). Help forwards it to telemetry only after consent, with help on and
+     * without Global Privacy Control; otherwise it is dropped. Never carries text.
+     */
+    jobEvent?(e: JobEvent): void;
+    /** Adds a stylesheet to help's shadow root (with the host's CSP nonce): lazily loaded parts. */
+    addStyle?(css: string): void;
+    /**
+     * Intent routing (P6d): the reader's "Something else" words → a job and its guide, or
+     * `undefined`. Sends only after consent, to a reader allowed to send requests; never rejects.
+     */
+    routeIntent?(text: string): Promise<Routed | undefined>;
+}
+/** 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/routing.d.ts

@@ -0,0 +1,21 @@
+/** Longest text routed, in characters (the collector's limit). */
+export declare const MAX_ROUTE_CHARS = 500;
+/** How long the reader waits for a route before their request path is offered as is. */
+export declare const ROUTE_TIMEOUT_MS = 6000;
+export interface RouteDeps {
+    endpoint: string;
+    siteKey: string;
+    reviewerToken?: string | undefined;
+    /** The site's consent, read on every call. */
+    hasConsent(): boolean;
+    /** Whether this reader may send requests at all. */
+    canSignal(): boolean;
+    fetchImpl?: typeof fetch;
+}
+/** A routed job: its id and its guide for any persona (the view prefers the persona's guide). */
+export interface Routed {
+    jobId: string;
+    journeyId?: string | undefined;
+}
+/** Routes `text` to a job, or resolves `undefined` (never rejects). */
+export declare function routeIntent(deps: RouteDeps, text: string): Promise<Routed | undefined>;

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/jobs/jobs.d.ts

@@ -0,0 +1,24 @@
+import type { HelpController, HelpState } from "../../core/controller";
+import type { HelpViewOptions } from "../../core/panel";
+type Child = Node | string | false | undefined;
+/** What the styled panel lends the jobs view (so the jobs chunk does not repeat it). */
+export interface JobsKit {
+    controller: HelpController;
+    options: HelpViewOptions;
+    el<K extends keyof HTMLElementTagNameMap>(tag: K, attrs?: Record<string, string>, ...children: Child[]): HTMLElementTagNameMap[K];
+    button(label: string, onClick: () => void, attrs?: Record<string, string>): HTMLButtonElement;
+    /** The shared consent group ("Allow and send" / "Not now"). */
+    consentGroup(): HTMLElement;
+    /** Re-renders the panel after a change local to the jobs view. */
+    rerender(): void;
+    /** The guide view's wording of a check-in send outcome. */
+    checkinNotice: Record<string, string>;
+}
+export interface JobsUi {
+    /** Whether the jobs view renders this state (the index with jobs, or the end of a job's guide). */
+    owns(s: HelpState): boolean;
+    content(s: HelpState): Child[];
+    destroy(): void;
+}
+export declare function jobsUi(kit: JobsKit): JobsUi;
+export {};