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

package/dist/types/help/ui/jobs/model.d.ts

@@ -0,0 +1,33 @@
+import type { HelpJobEntry } from "../../../types";
+import type { JobEvent } from "../../core/events";
+/** A job with an id and a title (the controller drops entries without either). */
+export type Job = HelpJobEntry & {
+    jobId: string;
+    title: string;
+};
+/**
+ * `HelpJobEntry.common_for`: the jobs common for `persona` first ("Common for you"), the rest
+ * after ("More"), each in index order. Without a persona every job is under "More".
+ */
+export declare function jobsForPersona(jobs: readonly Job[], persona: string | undefined): {
+    common: Job[];
+    more: Job[];
+};
+/** The guide that answers `job` for `persona`: its persona guide, else the job's own; none: no guide yet. */
+export declare function guideFor(job: Job, persona: string | undefined): {
+    journeyId: string;
+    stepCount: number;
+} | undefined;
+/** Local filter on the job titles (every word must appear); the query is never sent. */
+export declare function matchJobs(jobs: readonly Job[], query: string): Job[];
+/** A host `persona` context id the collector accepts on job events (`^[a-z0-9._:-]{1,96}$`). */
+export declare const JOB_PERSONA: RegExp;
+/**
+ * The job event with the host's persona (engagement.proto `persona`, follow-up 21), so answers
+ * can be read per job × persona. Only a context id is added: anything else is left off, so an
+ * out-of-shape persona never refuses the whole batch. The collector keeps it only when it names
+ * one of the project's catalog personas; it is never a user, session or device id.
+ */
+export declare function withPersona(e: JobEvent, persona: string | undefined): JobEvent;
+/** "1 step", "3 steps"; nothing without steps. */
+export declare function stepsLabel(n: number): string;

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

@@ -0,0 +1 @@
+export declare const JOBS_CSS = "\n:host { --jz-polish:#9A6412; --jz-broken:#B42318; }\n@media (prefers-color-scheme: dark) { :host { --jz-polish:#E0A54A; --jz-broken:#F07B70; } }\n.head-title { flex:1; display:flex; align-items:baseline; gap:8px; min-width:0; }\n.mono { font:11px/1.4 ui-monospace, \"JetBrains Mono\", monospace; color:var(--jz-faint); white-space:nowrap; }\n.panel h3 { margin:12px 0 4px; padding:0 12px; font-size:11px; font-weight:600; letter-spacing:.06em; text-transform:uppercase; color:var(--jz-faint); }\n.panel .jobs ul { margin:0; }\n.panel .jobs li { margin:0 0 2px; }\n.panel button.job { display:flex; align-items:center; justify-content:space-between; gap:8px; width:100%; min-height:48px;\n  padding:10px 12px; border:1px solid transparent; border-radius:6px; background:transparent; text-align:left; font-weight:500;\n  transition: background 180ms ease-out, border-color 180ms ease-out; }\n.panel button.job:hover { background:var(--jz-raised); border-color:var(--jz-rule); }\n.job .dim { color:var(--jz-faint); }\n.chip { flex:none; padding:2px 6px; border-radius:4px; background:var(--jz-accent-soft); color:var(--jz-accent); font-size:10px; font-weight:600; }\n.chip.none { background:var(--jz-raised); color:var(--jz-muted); }\n.jobs-foot { margin-top:8px; padding-top:8px; border-top:1px solid var(--jz-rule); }\n.row .not-possible { border-color:var(--jz-confused); color:var(--jz-confused); }\n.else label { display:block; margin:12px 0 6px; font-size:11px; font-weight:500; color:var(--jz-faint); }\n.else textarea { display:block; width:100%; min-height:88px; 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.note { margin:12px 0; padding:8px 12px; border-radius:6px; background:var(--jz-raised); color:var(--jz-muted); font-size:11px; }\n.panel .wide { width:100%; min-height:44px; padding:0 16px; border:1px solid var(--jz-accent); border-radius:6px;\n  background:var(--jz-accent); color:var(--jz-accent-ink); font-weight:500; }\n.route { margin:12px 0; padding:12px; border:1px solid var(--jz-accent); border-radius:6px; background:var(--jz-accent-soft); }\n.route p { margin:0 0 4px; }\n.done .progress-fill { width:100%; background:var(--jz-polished); }\n.answers { display:grid; grid-template-columns:repeat(3, 1fr); gap:8px; margin:12px 0 16px; }\n.answers button { display:flex; flex-direction:column; align-items:center; justify-content:center; gap:4px; min-height:64px;\n  border:1px solid var(--jz-rule); border-radius:6px; background:var(--jz-surface); font-size:12px; font-weight:500;\n  transition: background 180ms ease-out, border-color 180ms ease-out; }\n.answers button:hover { background:var(--jz-raised); }\n.answers button[aria-pressed=\"true\"] { border-color:var(--jz-accent); background:var(--jz-accent-soft); box-shadow:inset 0 0 0 1px var(--jz-accent); }\n.answers svg { width:18px; height:18px; }\n.a-YES svg { color:var(--jz-polished); }\n.a-PARTLY svg { color:var(--jz-polish); }\n.a-NO svg { color:var(--jz-broken); }\n.harder { padding-top:12px; border-top:1px solid var(--jz-rule); }\n.harder label { display:flex; align-items:center; gap:8px; min-height:44px; color:var(--jz-muted); font-weight:500; cursor:pointer; }\n.panel .harder input { width:16px; height:16px; min-height:0; margin:0; padding:0; accent-color:var(--jz-accent); }\n.harder p { margin:0; }\n@media (max-width: 480px) {\n  .panel { left:0; right:0; bottom:0; width:100%; max-height:85vh; border-radius:10px 10px 0 0;\n    padding-bottom:calc(16px + env(safe-area-inset-bottom, 0px)); }\n}\n";

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,59 @@
+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;
+    /** The chat (SDK 2.x): open at "Report a problem" (`feedback()`). */
+    report?(): 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-detector.d.ts

@@ -0,0 +1,22 @@
+/** The detector's rule ids (a closed set: later lanes count and report these, nothing else). */
+export declare const DETECTOR_RULES: readonly ["autocomplete_cc", "autocomplete_otp", "autocomplete_password", "input_password", "label_sensitive", "name_sensitive", "value_key_shaped", "value_card_shaped", "value_email_shaped"];
+export type DetectorRule = (typeof DETECTOR_RULES)[number];
+/** One flagged element: the rule that matched and where it is. Never the value. */
+export interface DetectorHit {
+    rule: DetectorRule;
+    selector: string;
+}
+/** Hits per rule, for one capture or one scan. */
+export type DetectorCounts = Partial<Record<DetectorRule, number>>;
+/**
+ * The first rule this element matches, or `undefined`. Pure and value-free in its result: it
+ * reads attributes, labels and the element's own text only to decide, and returns only the rule.
+ */
+export declare function detectSensitive(el: Element): DetectorRule | undefined;
+/** A value-free anchor for a hit: the nearest stable hook, else a short structural path. */
+export declare function anchorSelector(el: Element): string;
+/**
+ * Every flagged element under `root` that `isAlreadyMasked` does not already cover (subtrees of
+ * masked elements are skipped). For integration aids; captures use {@link detectSensitive}.
+ */
+export declare function scanSensitive(root: Element, isAlreadyMasked?: (el: Element) => boolean): DetectorHit[];

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

@@ -0,0 +1,2 @@
+/** Whether the mask audit was asked for in this tab. */
+export declare function takePreviewFlag(): boolean;

package/dist/types/preview/mask-audit.d.ts

@@ -0,0 +1,29 @@
+import type { DetectorHit } from "../mask-detector";
+/** One `journeeze.finding/v1` payload (docs/contract/schemas/finding-v1.schema.json). */
+export interface MaskFindingWire {
+    anchor?: string;
+    selector?: string;
+    pagePath: string;
+    rule: string;
+    detectedAt: string;
+}
+/** The detector's scan (`scanSensitive` from `../mask-detector`), passed in by the caller: the
+ *  widget already holds it, so this chunk never imports the widget chunk. */
+export type Scan = (root: Element, isAlreadyMasked: (el: Element) => boolean) => DetectorHit[];
+export interface MaskAuditOptions {
+    scan: Scan;
+    endpoint: string;
+    siteKey: string;
+    /** The implementer's widget token (an owner's or triager's). */
+    reviewerToken: string;
+    /** Host and journey-configuration selectors: elements they cover are already masked. */
+    maskSelectors?: readonly string[];
+    fetchImpl?: typeof fetch;
+    now?: () => Date;
+}
+/** The page's findings, value-free. Pure apart from reading the DOM. */
+export declare function auditPage(scan: Scan, root: Element, href: string, selectors: readonly string[], now: Date): MaskFindingWire[];
+/** Audits the current page and submits what is new for this tab. Never throws into the host. */
+export declare function runMaskAudit(opts: MaskAuditOptions): Promise<number>;
+/** Test helper: forget what this tab sent. */
+export declare function resetMaskAudit(): void;

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

@@ -0,0 +1,76 @@
+/** Wire id of the `journeeze.feedback/v2` schema. */
+export declare const FEEDBACK_SCHEMA_ID = "journeeze.feedback/v2";
+/** `kind` — why the feedback was filed. */
+export type FeedbackKind = "problem" | "unmet_need" | "suggestion" | "praise";
+/** `reaction` — a one-tap mood on the reply that prompted the feedback. */
+export type FeedbackReaction = "like" | "dislike" | "understood" | "confused";
+/** `context.device`. */
+export type FeedbackDevice = "desktop" | "tablet" | "mobile";
+/** `context.removed[]` — context chips the user removed before sending. */
+export type FeedbackRemovedChip = "page" | "persona" | "browser" | "device" | "viewport" | "build";
+/** `team.verdict` — reviewer-only. */
+export type FeedbackVerdict = "unreviewed" | "polished" | "needs_polish" | "broken";
+/** `team.severity` — reviewer-only. */
+export type FeedbackSeverity = "low" | "medium" | "high" | "critical";
+/** `attachments[].shapes[].type`. */
+export type FeedbackShapeType = "box" | "circle" | "arrow";
+/** `job` — the journey job the feedback is about. */
+export interface FeedbackJob {
+    jobId: string;
+    stepReached?: number;
+}
+/** `unmetNeed` — what the user could not do with the product. */
+export interface FeedbackUnmetNeed {
+    need: string;
+    soYouCan?: string;
+    typedQuery?: string;
+}
+/** `context.viewport` — both sides optional. */
+export interface FeedbackViewport {
+    w?: number;
+    h?: number;
+}
+/** `attachments[].shapes[]` — a normalised annotation over the screenshot. */
+export interface FeedbackShape {
+    type: FeedbackShapeType;
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+/** `attachments[]` — one masked screenshot upload. */
+export interface FeedbackAttachment {
+    screenshotId: string;
+    shapes?: FeedbackShape[];
+}
+/** One message in a feedback payload (also `$defs.message` reused by `journeeze.turn/v1`). */
+export interface FeedbackMessage {
+    text?: string;
+    anchor?: string;
+    attachments?: FeedbackAttachment[];
+}
+/** `context` — the closed context allowlist. */
+export interface FeedbackContext {
+    pagePath: string;
+    persona?: string;
+    browser?: string;
+    device?: FeedbackDevice;
+    viewport?: FeedbackViewport;
+    build?: string;
+    removed?: FeedbackRemovedChip[];
+}
+/** `team` — reviewer-only fields. */
+export interface FeedbackTeam {
+    verdict?: FeedbackVerdict;
+    severity?: FeedbackSeverity;
+}
+/** A `journeeze.feedback/v2` payload. */
+export interface Feedback {
+    kind: FeedbackKind;
+    job?: FeedbackJob;
+    unmetNeed?: FeedbackUnmetNeed;
+    reaction?: FeedbackReaction;
+    messages: FeedbackMessage[];
+    context: FeedbackContext;
+    team?: FeedbackTeam;
+}

package/dist/types/schemas/finding.d.ts

@@ -0,0 +1,22 @@
+/** Wire id of the `journeeze.finding/v1` schema. */
+export declare const FINDING_SCHEMA_ID = "journeeze.finding/v1";
+/** `rule` — which secret-detector rule matched. */
+export type FindingRule = "autocomplete_cc" | "autocomplete_otp" | "autocomplete_password" | "input_password" | "label_sensitive" | "name_sensitive" | "value_key_shaped" | "value_card_shaped" | "value_email_shaped";
+/** Fields shared by both branches of the `oneOf`. */
+export interface FindingBase {
+    pagePath: string;
+    rule: FindingRule;
+    detectedAt: string;
+}
+/** Branch for a flagged element that has a tflo id. */
+export interface FindingWithAnchor extends FindingBase {
+    anchor: string;
+    selector?: never;
+}
+/** Branch for a flagged element addressed by CSS selector. */
+export interface FindingWithSelector extends FindingBase {
+    selector: string;
+    anchor?: never;
+}
+/** A `journeeze.finding/v1` payload: exactly one of `anchor` or `selector`. */
+export type Finding = FindingWithAnchor | FindingWithSelector;

package/dist/types/schemas/index.d.ts

@@ -0,0 +1,6 @@
+export { FEEDBACK_SCHEMA_ID } from "./feedback";
+export type { Feedback, FeedbackAttachment, FeedbackContext, FeedbackDevice, FeedbackJob, FeedbackKind, FeedbackMessage, FeedbackReaction, FeedbackRemovedChip, FeedbackSeverity, FeedbackShape, FeedbackShapeType, FeedbackTeam, FeedbackUnmetNeed, FeedbackViewport, FeedbackVerdict, } from "./feedback";
+export { TURN_SCHEMA_ID } from "./turn";
+export type { Turn, TurnAction, TurnActionInput, TurnInput, TurnTextInput } from "./turn";
+export { FINDING_SCHEMA_ID } from "./finding";
+export type { Finding, FindingBase, FindingRule, FindingWithAnchor, FindingWithSelector } from "./finding";

package/dist/types/schemas/turn.d.ts

@@ -0,0 +1,26 @@
+import type { FeedbackMessage, FeedbackTeam } from "./feedback";
+/** Wire id of the `journeeze.turn/v1` schema. */
+export declare const TURN_SCHEMA_ID = "journeeze.turn/v1";
+/** `input.action` — the stable chat intents (ADR 0018). */
+export type TurnAction = "pick_job" | "other_need" | "guide_next" | "guide_back" | "didnt_work" | "report_problem" | "send" | "cancel" | "affirm" | "deny" | "talk_to_assistant";
+/** `input` branch where the user typed text. */
+export interface TurnTextInput {
+    kind: "text";
+    text: string;
+}
+/** `input` branch where the user chose an action. */
+export interface TurnActionInput {
+    kind: "action";
+    action: TurnAction;
+    jobId?: string;
+    step?: number;
+}
+/** `input` — the `oneOf` text|action as a discriminated union on `kind`. */
+export type TurnInput = TurnTextInput | TurnActionInput;
+/** A `journeeze.turn/v1` payload. */
+export interface Turn {
+    input: TurnInput;
+    draft?: FeedbackMessage;
+    /** Reviewer-only (verdict, severity); the collector rejects it from non-reviewer sessions. */
+    team?: FeedbackTeam;
+}

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

@@ -0,0 +1,149 @@
+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";
+    /** The host's context ids, plus its release id (`appVersion`, ADR 0014 addendum) when set. */
+    context: Partial<Record<(typeof CONTEXT_FIELDS)[number] | "appVersion", 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.
+ * `jz-platform@2` adds `step_completed` (ADR 0014 addendum); the collector still accepts `@1`.
+ */
+export declare const RULE_SET = "jz-platform@2";
+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 {};

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

@@ -0,0 +1,33 @@
+/** The platform rule's name. */
+export declare const STEP_COMPLETED = "step_completed";
+/** The closed duration buckets, fastest first (proto `StepDurationBucket`). */
+export declare const DURATION_BUCKETS: readonly ["lt5s", "lt15s", "lt60s", "lt5m", "ge5m"];
+export type DurationBucket = (typeof DURATION_BUCKETS)[number];
+/** The bucket a measured duration falls in. */
+export declare function durationBucket(ms: number): DurationBucket;
+/** `step_completed`'s params: ids and a bucket, nothing else. */
+export interface StepCompleted {
+    journey: string;
+    step: string;
+    duration_bucket: DurationBucket;
+}
+/** Where the page is in a published journey's checkpoints (as matched by `matchCheckpoint`). */
+export interface ReachedAnchor {
+    journey: string;
+    /** 0-based checkpoint position. */
+    index: number;
+    /** The anchor's name: the checkpoint's step id. */
+    step: string;
+}
+export interface StepTimer {
+    /**
+     * Called on every context sync with the journey the host is in and the anchor matched (if any).
+     * Returns the params of the completion to send, once per anchor going forward.
+     */
+    sync(journeyId: string | undefined, at: ReachedAnchor | undefined): StepCompleted | undefined;
+}
+/**
+ * One handle's step clock. It outlives tflo instances (a back/forward-cache restore re-arms the
+ * checkpoints but does not complete the current anchor twice); a journey change restarts it.
+ */
+export declare function stepTimer(now: () => number): StepTimer;