@journeeze/sdk 0.1.0-rc.2 → 0.1.0-rc.3

package/AGENTS.md

@@ -10,9 +10,13 @@ The public types in this package (`dist/types`) follow them.
 
 ## Configuration
 - `siteKey` (`pk_` + 32 hex, `SITE_KEY_PATTERN`) is **public** runtime config per site. It is not a secret.
-- Direct mode is the default (browser → `app.journeeze.dev`, CORS for the site's allowlisted
-  origins). Set `apiHost`/`apiPath` **only** when the host runs a same-origin proxy
-  (docs/collector-proxy.md); `http:` is accepted only for `localhost`/`127.0.0.1`.
+- Direct mode is the default: the browser calls `https://app.journeeze.dev` with CORS for the
+  site's allowlisted origins. Set `apiHost` (script tag: `data-journeeze-api-host`) in every
+  environment except production: `https://app.staging.journeeze.dev` for a staging site key,
+  `http://localhost:8080` for the local stack, or the host's own origin when it runs a same-origin
+  proxy (then `apiPath` for a sub-path). Keep it in the same runtime config as the site key. The
+  SDK never infers it from where the script was loaded. `http:` is accepted only for
+  `localhost`/`127.0.0.1`.
 - CSP, if the host sends one: `script-src 'self' https://app.journeeze.dev` (+ `'wasm-unsafe-eval'`
   only with signals), `connect-src 'self' https://app.journeeze.dev`, `img-src 'self' blob:
   https://app.journeeze.dev`, `media-src 'self' https://app.journeeze.dev`, and pass your `nonce`.
@@ -60,6 +64,15 @@ The public types in this package (`dist/types`) follow them.
   one tflo runtime; otherwise the SDK lazy-loads its own copy after consent.
 - Signals start only after the same consent as feedback, and stop when the site's kill switch is off.
 
+## Script tag
+- `window.Journeeze` exists only after the module script runs, which is after inline scripts. Use
+  it from a user event or after `DOMContentLoaded`, never during page load.
+
+## GitHub
+- Issues and the `.jevitate/` catalog go through the Journeeze GitHub App
+  (`https://github.com/apps/journeeze/installations/new`), installed by the product owner on the
+  repository named at setup. Never use a personal access token.
+
 ## Never
 - Put a secret in the bundle (the HMAC secret, tokens, gateway keys).
 - Send raw user ids, emails, names, URLs or record ids anywhere (context, steps, rules, params).

package/CHANGELOG.md

@@ -1,6 +1,17 @@
 # Changelog
 
-## Unreleased
+## 0.1.0-rc.3 (not yet published)
+
+- **Setup documentation:** the README is a self-contained setup guide: what the Journeeze team sends you, install with a pinned version, `apiHost` per environment, CSP, signed identity with a test vector, privacy and masking, help, feedback, signals, the Journeeze GitHub App and its permissions, a checklist and troubleshooting. Examples use `window.Journeeze` only after `DOMContentLoaded`. The license line matches `LICENSE.md`.
+- **Help chat on the live `Converse` (HC8c):** each turn carries the reviewer token (when the host has one), and on consented turns the signed user id (`userId`, `userIdExp`, `userIdSig`) and the detector's over-masking counts (`overMasked`, counts per rule only). Closing the chat (✕ or Esc) ends a started conversation with a `cancel` turn; opening it again starts a new one.
+- **Chat copy as data (ADR 0020 §5):** the help chat ships no words of its own. Its chrome comes from the site's `widget.ui.*` copy (new `GetWidgetConfig.copy`, by full key, `{name}` placeholders filled by the widget), and its buttons, chips and "+" menu use the labels the server sends on each `Converse` action (`label`, `menu[].label/hint`). The chat reads `GetWidgetConfig` once (copy and mask selectors). If that call fails, only the launcher keeps a last-resort accessible name.
+- **Help chat shell (SDK 2.x, HC8a), behind `chat: true`:** `enableHelp()` (or `data-journeeze-chat` on the script tag) shows one "?" launcher that opens a conversation instead of the v1 help panel: job chips filtered as you type ("Other — none of these" last), inline guide cards, a composer with a "+" menu, a one-time consent line before anything is stored, a removable "Sent with this report" row and, for reviewers, "Team details". Turns go to the collector's `Converse` (direct-mode contract v2 §2). New `feedback()` on the handle opens the chat at "Report a problem" (without `chat: true` it switches feedback mode on). The chat is its own lazy chunk (≤ 11.5 KB gz).
+- **Intent routing in help (P6d):** when a reader who has already consented sends "Something else", help first asks the collector (`RouteIntent`) which of the site's jobs their words mean. A confident match with a guide shows "Did you mean: <job>?" with "Show me how" (its guide) and "No, send my request"; otherwise the request is sent as before. The answer is only a job id and its guide, never generated text; the words are not stored by routing. Without consent nothing is routed.
+- **Jobs in help (P4e2):** when the site's help index lists jobs, help opens on "What are you trying to do?": the jobs common for the host's `persona` under "Common for you", the rest under "More", a local filter, and "Something else". A job opens its guide (the persona's own when it has one) and ends with "Got it done?" (yes / partly / no, plus "Harder than it should be"); a job without a guide offers "Not possible here". `job_picked` / `job_not_possible` / `job_outcome` are aggregate engagement events (job id and entry version only), sent only after consent, with help on and never under Global Privacy Control. "Something else" is the reader's own words as a consented feedback request (with the optional "so you can…"), never telemetry. The jobs view is a separate lazy chunk (≤ 5 KB gz), loaded only for sites with jobs.
+
+## 0.1.0-rc.2 (2026-10-09)
+
+First version published to the public npm registry.
 
 - **Public on npm:** published to the npm registry as `@journeeze/sdk` (no registry config or token), starting with 0.1.0-rc.2. GitHub Packages (`@matt-cochran-products/journeeze-sdk`) is no longer published. The package is licensed for use with the Journeeze service (`LICENSE.md`); it is not open source.
 - **Signed host identity (contract C0a §4, v1.3):** `userIdSig` / `userIdExp` config fields and provider props, and `setUser(userId, { sig, exp })`. The signature is sent with feedback and end-user screenshot uploads while it is unexpired; the same id with a new signature only refreshes it. Sites that require signed identity treat an unsigned id as anonymous.

package/README.md

@@ -1,165 +1,344 @@
 # @journeeze/sdk
 
-Opt-in "suggest an improvement" mode for any website or app. A tiny loader (≤ 2 KB gz) holds
-your options and context; the widget is lazy-loaded only when the mode is switched on.
-Nothing observes the page while the mode is off. Inputs and editable regions are always masked,
-and the widget asks for consent before anything is captured.
+Journeeze adds in-app help and an opt-in feedback mode to any website or app. Visitors read
+step-by-step guides built from your documented user journeys, and invited reviewers (or signed-in
+users) point at what is unclear. Journeeze groups that feedback and files it as GitHub issues in
+your repository.
 
-## Install and transport
+The SDK is a small loader (about 2 KB gzipped). Nothing observes the page until help or the
+feedback mode is switched on, and nothing is captured before the visitor consents.
 
-Install from npm, or use the script tag served by Journeeze at `/sdk/`. The Journeeze
-integration guide covers the full path (provisioning, CSP block, identity, help, signals,
-checklist).
+**Contents:** [Before you start](#before-you-start) · [Install](#install) ·
+[Environments](#environments-and-apihost) · [Content Security Policy](#content-security-policy) ·
+[Signed-in users](#signed-in-users) · [Privacy and masking](#privacy-and-masking) ·
+[Help](#in-app-help) · [Feedback mode](#feedback-mode) · [Signals](#signals-optional) ·
+[GitHub](#connect-github) · [Checklist](#setup-checklist) ·
+[Troubleshooting](#troubleshooting) · [Versions](#versions-and-license)
 
-```sh
-npm install @journeeze/sdk@<version>
-```
+## Before you start
 
-**Direct mode (default since v1):** the SDK calls the Journeeze collector that issued your site
-key (`https://app.journeeze.dev`) with CORS for your site's allowlisted origins
-(`docs/contract/direct-mode-v1.md`). Requests never carry cookies or other credentials and are
-never cached.
+Journeeze is in early access. The Journeeze team sets up your account. Send them:
 
-**Proxy mode (optional):** set `apiHost` to your own origin (`data-journeeze-api-host` on the
-script tag; `apiPath` / `data-journeeze-api-path` for a sub-path) and proxy the collector paths
-per `docs/collector-proxy.md`. A v0 host that relied on the old same-origin default must set
-`apiHost: location.origin` before upgrading. `endpoint` / `data-journeeze-endpoint` still work
-and are deprecated.
+1. Your organisation and product name.
+2. Every origin the SDK will run on, with scheme, host and port. Example:
+   `https://app.example.com`, `https://*.preview.example.com`. Staging and production are separate.
+3. Whether visitors can be anonymous, or every user is signed in.
+4. The GitHub repository issues should go to (`owner/repo`).
+5. Who should be the project owner on the review board.
 
-```html
-<script type="module" src="https://app.journeeze.dev/sdk/script.js" data-journeeze-site-key="pk_..."></script>
-<script>/* later, from your own control: */ window.Journeeze?.enable();</script>
+You get back:
+
+| You receive | What it is | Where it goes |
+|---|---|---|
+| A **site key** per site (`pk_` + 32 hex) | Public identifier. Not a secret. | Your page or app runtime config |
+| An **identity secret** per site (64 hex) | Server secret for [signing user ids](#signed-in-users). Sent as a one-time 1Password link, never by email or chat. | Your server's secret store only |
+| An **owner invite link** | Opens the review board as project owner. Single use. | Open it once, in your browser |
+
+## Install
+
+Pick one way. Both load the same code.
+
+### npm (bundled apps)
+
+```sh
+npm install @journeeze/sdk@0.1.0-rc.3 --save-exact
 ```
 
+Pin an exact version. Release candidates (`-rc.N`) are on the `rc` tag; stable releases on
+`latest`.
+
+**React:**
+
 ```tsx
 import { JourneezeProvider, useJourneeze } from "@journeeze/sdk/react";
 
-<JourneezeProvider siteKey="pk_..." context={{ persona: "owner", journeyId: "r1-j09", journeyStep: "pay" }}>
-  <App />
-</JourneezeProvider>;
+export function Root() {
+  return (
+    <JourneezeProvider
+      siteKey={config.journeezeSiteKey}      // public, from runtime config
+      apiHost={config.journeezeApiHost}      // staging and local only; see "Environments"
+      context={{ persona: "owner", journeyId: "billing", journeyStep: "route.billing.pay" }}
+      pagePath="none"                        // you pass route ids as journeyStep
+    >
+      <App />
+    </JourneezeProvider>
+  );
+}
 
-const jz = useJourneeze(); jz.enable(); jz.setContext({ journeyStep: "confirm" });
+function HelpButton() {
+  const jz = useJourneeze();
+  return <button onClick={() => jz.enableHelp()}>Help</button>;
+}
 ```
 
-- Keep `context` in sync with your router: the provider sets it on every change and clears values
-  a route no longer provides. The widget asks "Did this step make sense?" about the step the
-  reviewer just finished when `journeyStep` changes.
-- Invited reviewers arrive with `?jz_invite=<token>`: the script tag and the provider read it once,
-  remove it from the URL and keep it for the tab's session (`takeReviewerToken`), unless you pass
-  `reviewerToken` yourself.
-- `onModeChange(enabled)` tells you when the mode switches on or off, including from inside the
-  widget (Esc, Exit, "Not now").
+- While `siteKey` is `undefined` (config still loading) the provider renders with an inert handle:
+  every method does nothing and nothing is sent. The real handle starts with the first key.
+- Keep `context` in sync with your router. The provider applies every change.
+- With TypeScript's `exactOptionalPropertyTypes`, optional props do not accept `undefined`. Pass
+  them only when set: `{...(config.journeezeApiHost ? { apiHost: config.journeezeApiHost } : {})}`.
 
-## Signed-in users, logout and privacy options (contract v1.1)
+**Without React:**
 
-The full contract is `docs/contract/sdk-v1.md`. The parts a host touches most:
+```ts
+import { createJourneeze } from "@journeeze/sdk";
 
-```tsx
-<JourneezeProvider
-  siteKey="pk_..."
-  apiHost="https://www.example.com" // proxy mode only; omit for direct mode (the default)
-  userId={user ? user.journeezeHash : undefined} // HMAC from YOUR server, never an email or raw id
-  pagePath="none" // you pass route ids (e.g. route.projects.hub) as journeyStep
-  maskSelectors={[".customer-name"]}
-  context={{ persona, journeyId, journeyStep: routeTemplate }}
->
+const jz = createJourneeze({ siteKey: "pk_...", apiHost: "https://app.staging.journeeze.dev" });
+document.querySelector("#help")?.addEventListener("click", () => jz.enableHelp());
 ```
 
-- **`userId`** is `HMAC-SHA256(server_secret, internal_user_id)` as 64 hex or 43 base64url
-  characters, delivered in an authenticated `no-store` response. Anything else is ignored with a
-  warning; the SDK never hashes. `USER_ID_PATTERN` and the other patterns are exported from
-  `@journeeze/sdk/contract` for your server's tests.
-- **Logout:** the provider handles it. `userId` changing away from an id, or the provider
-  unmounting, calls `reset()`. Script-tag hosts call `window.Journeeze.reset()` on every logout
-  path. `setUser(otherId)` resets first. `reset()` sends the user's unsent feedback once and
-  removes it from the device, clears context, consent and the reviewer token, and keeps help
-  available (empty) if it was on.
-- **Masking:** inputs, editable regions, `[data-jz-mask]`, media and frames are always masked.
-  `maskSelectors` and `maskAllText` widen it; an invalid selector switches screenshots off (fails
-  closed). `[data-jz-block]` leaves an empty box and cannot be picked. Users can always send
-  without the screenshot, after seeing it full size.
-- **Who sends a screenshot:** reviewers, and signed-in end users the host attributes with
-  `userId` on a site that accepts non-reviewer feedback; the upload is bound to that user. A fully
-  anonymous visitor never captures or sends one, and the consent copy says so (ADR 0013 §4).
-- **`pagePath`:** `"redacted"` (default) replaces id-like path segments with `:id`; `"none"` sends
-  no path.
-- **`nonce`** is set on the SDK's `<style>` elements for strict CSPs; Global Privacy Control turns
-  help telemetry off (`respectGlobalPrivacyControl`, default `true`).
+### Script tag (no bundler)
 
-## In-app help
+```html
+<script type="module"
+  src="https://app.journeeze.dev/sdk/script.js"
+  data-journeeze-site-key="pk_..."
+  data-journeeze-help></script>
+```
 
-Help is independent of the feedback mode. It shows a launcher that opens guides built from the
-site's published journeys, with search, step-by-step guidance that outlines each step's element,
-and an optional "Did this step make sense?" check-in. Reading guides needs no consent; nothing
-of the help chunk loads or listens on the page until you switch it on.
+The tag creates `window.Journeeze`. It is a module script, so it runs after your inline scripts.
+Use it from a click, or after `DOMContentLoaded`, never while the page is still loading:
 
 ```html
-<script type="module" src="https://<cdn>/journeeze/script.js" data-journeeze-site-key="pk_..." data-journeeze-help></script>
+<button id="suggest">Suggest an improvement</button>
+<script>
+  document.addEventListener("DOMContentLoaded", () => {
+    document.getElementById("suggest").addEventListener("click", () => window.Journeeze?.enable());
+  });
+</script>
 ```
 
-```tsx
-const jz = useJourneeze();
-await jz.enableHelp();   // lazy-loads the help chunk and shows the launcher
+| Attribute | Effect |
+|---|---|
+| `data-journeeze-site-key` | Required. Your site key. |
+| `data-journeeze-api-host` | The collector origin. Required outside production; see below. |
+| `data-journeeze-api-path` | Path prefix, only for a same-origin proxy. |
+| `data-journeeze-help` | Shows the help launcher at once. |
+| `data-journeeze-chat` | Help opens as a conversation instead of the guide panel. |
+
+`/sdk/script.js` is always the SDK version the Journeeze service currently runs. To control the
+version yourself, install from npm and pin it.
+
+## Environments and `apiHost`
+
+The SDK sends to production (`https://app.journeeze.dev`) unless you set `apiHost`. It does not
+follow where the script was loaded from. A staging or local site key sent to production is
+refused, so set `apiHost` next to the site key in each environment's config:
+
+| Environment | `apiHost` / `data-journeeze-api-host` |
+|---|---|
+| Production | leave it out |
+| Staging | `https://app.staging.journeeze.dev` |
+| Local Journeeze stack | `http://localhost:8080` |
+| Your own same-origin proxy | your origin, for example `https://www.example.com` |
+
+The browser calls the collector directly with CORS, only from the origins you registered. Requests
+carry no cookies and are not cached. A proxy is optional. It suits offices or CI where many users
+share one IP address, or a policy that allows no third-party requests. The Journeeze team sends the
+proxy guide (gateway key, the paths to forward, reference Worker and server code) on request.
+
+## Content Security Policy
+
+If your site sends a CSP, add these. Use `https://app.staging.journeeze.dev` on staging.
+
+```
+script-src   'self' https://app.journeeze.dev;
+connect-src  'self' https://app.journeeze.dev;
+img-src      'self' blob: https://app.journeeze.dev;
+media-src    'self' https://app.journeeze.dev;
+style-src    'self' 'nonce-<your nonce>';
+```
+
+- Add `'wasm-unsafe-eval'` to `script-src` only if you turn on [signals](#signals-optional).
+- Pass your nonce as the `nonce` option. The SDK puts it on the styles it injects.
+- With npm and a proxy, `script-src` and `connect-src` need only `'self'`.
+
+## Signed-in users
+
+Attributing feedback to a user is optional. When you do, your server makes the user id and signs
+it. The browser never sees either secret.
+
+1. **User id.** `HMAC-SHA256(your own secret, your internal user id)`, as 64 lowercase hex or
+   43 base64url characters. Never an email, name or raw id. The SDK ignores anything else with a
+   console warning. Keep this secret stable: changing it splits every user's history.
+2. **Signature.** With the identity secret you received for the site:
+
+   ```ts
+   import { createHmac } from "node:crypto";
+
+   export function signUserId(identitySecretHex: string, siteKey: string, userId: string) {
+     const userIdExp = Math.floor(Date.now() / 1000) + 3600; // at most 24 h ahead
+     const userIdSig = createHmac("sha256", Buffer.from(identitySecretHex, "hex"))
+       .update(`jz-id-v1\n${siteKey}\n${userId}\n${userIdExp}`)
+       .digest("base64url");
+     return { userId, userIdExp, userIdSig };
+   }
+   ```
+
+   Check your code against this vector. Secret: the bytes `0x00` to `0x1f` (hex
+   `000102…1e1f`). Site key `pk_0123456789abcdef0123456789abcdef`. User id: `a` × 64.
+   `userIdExp` `1800000000`. Expected `userIdSig`: `IluU_qUHY6OdSzqKu0Y_wS0sDB53qVOOnobfdHuCnjI`.
+3. **Deliver** `{ userId, userIdExp, userIdSig }` from an authenticated endpoint with
+   `Cache-Control: no-store`. Never put them in public config.
+4. **Pass them to the SDK:** provider props `userId`, `userIdSig`, `userIdExp`, or
+   `jz.setUser(userId, { sig, exp })`. Re-issue the signature before it expires. The SDK never
+   refreshes it.
+5. **Logout.** The React provider calls `reset()` when `userId` goes away or the provider
+   unmounts. Without React, call `jz.reset()` (or `window.Journeeze.reset()`) on every logout path.
+   `reset()` sends that user's unsent feedback once, then clears it, the context, consent and the
+   reviewer token from the device.
+
+Sites require the signature by default. With a missing, expired or wrong signature, that feedback
+is anonymous and has no screenshot.
+
+## Privacy and masking
+
+- Nothing is captured until the visitor turns the feedback mode on and consents. Reading help
+  needs no consent.
+- Screenshots are masked in the browser before encoding, and the visitor sees the masked image
+  before sending. They can always send without it.
+- Always masked: inputs, textareas, selects, editable regions, video, audio, canvas, frames and
+  `[data-jz-mask]`. The SDK also masks elements that look sensitive (password and card fields, API
+  keys, IBANs, email-shaped text). Mark such elements yourself rather than relying on detection.
+- `[data-jz-block]` leaves an empty box that cannot be picked.
+- `maskSelectors: [".customer-name"]` and `maskAllText: true` widen masking. One invalid selector
+  turns screenshots off (fails closed).
+- Anonymous visitors never capture or send a screenshot.
+- `pagePath`: `"redacted"` (default) replaces id-like path segments with `:id`; `"none"` sends no
+  path.
+- Global Privacy Control turns help telemetry and signals off (`respectGlobalPrivacyControl`,
+  default `true`).
+- The collector accepts a closed list of fields. Raw ids, emails, URLs and page text are not on it.
+
+Put `data-jz-mask` on every element that shows customer content.
+
+## In-app help
+
+Help shows a launcher that opens guides built from your published journeys: search, step-by-step
+guidance that outlines each step's element, and an optional "Did this step make sense?" check-in.
+
+```ts
+await jz.enableHelp();   // loads the help code and shows the launcher
 jz.isHelpEnabled();      // true
-jz.disableHelp();        // removes the launcher and panel
+jz.disableHelp();        // removes it
 ```
 
-To hide your own Help control when help isn't for this user, pass `onHelpStatus` (or the React
-provider's `onHelpStatus` prop). After `enableHelp()` checks the site it is called with
-`{ available: true }`, or `{ available: false, reason: "disabled" }` (the site has help off) or
-`{ available: false, reason: "audience" }` (reviewers-only help and no reviewer token), and again
-if that changes.
+- `onHelpStatus(status)` tells you whether help is available here: `{ available: true }`, or
+  `{ available: false, reason: "disabled" }` (help is off for the site) or `"audience"` (help is
+  for reviewers only and this visitor is not one). Hide your own Help button on `false`.
+- Steps point at elements by `data-tflow-id="area.element"` (lowercase letters, digits and `._:-`,
+  up to 96 characters). Give every element a guide points at a stable `data-tflow-id`. A step whose
+  element is not on the page shows its text without an outline.
+- Set `journeyStep` in `context` to a stable id for where the user is (a route id such as
+  `route.projects.hub`), never a URL or record id. Guides and signals match on it.
+- Help is switched on per site on the review board: **Settings → the site → In-app help**. Choose
+  **Reviewers** (default) or **Public visitors**.
 
-- `data-journeeze-help` on the script tag calls `enableHelp()` for you; a failed chunk load never
-  surfaces as an unhandled rejection.
-- Help reads guides with the collector RPCs `GetHelpIndex` and `GetGuide`, and loads step
-  screenshots, the guide video and its captions from `GET /journeeze.collector.v1/guide-assets/*`
-  (short-lived signed links). Your proxy must forward that prefix and `GET /sdk/*` (the chunks)
-  in addition to the feedback paths; see `docs/collector-proxy.md`.
-- Steps are anchored to `data-tflow-id` names. A step whose element isn't on the current page
-  shows its text without an outline.
-- If help is switched off for the site (the site's help settings on the board's **Settings** screen), the launcher renders nothing.
+Where guides come from: see [Connect GitHub](#connect-github).
 
-**Publishing guides.** Guides come from Jevitate journeys. An operator imports them into the
-project with `journeeze import-journeys --project <id> <.jevitate/journeys dir>`; each journey
-arrives as a draft. A triager reviews it on the board's **Journeys** screen (light edits to step
-text are allowed) and publishes it. Only published guides appear in help; a guide whose source
-journey changed goes stale until the new import is adopted.
+## Feedback mode
 
-Mark elements with `data-tflow-id="area.element"` to anchor feedback to stable names, and
-`data-jz-mask` to mask extra regions (form fields and `contenteditable` regions are always masked).
+```ts
+await jz.enable();       // turns the feedback mode on (asks for consent first)
+jz.disable();
+jz.isEnabled();
+```
 
-License: undecided (`UNLICENSED`); packaged so it can be open-sourced later.
+- Invited reviewers arrive with `?jz_invite=<token>`. The SDK reads it once, removes it from the
+  URL and keeps it for the tab.
+- `onModeChange(enabled)` reports every switch, including Esc and Exit inside the widget.
+- When `journeyStep` changes, the widget can ask about the step the reviewer just finished.
 
-## Signals (signal contract C0d)
+## Signals (optional)
 
-Aggregate-only behaviour signals (`docs/contract/signals-v1.md`): rage clicks, dead clicks,
-hesitation, abandoned journey steps, and your own registered site signals. Raw events never
-leave the page; only derived signals are sent, through a closed allowlist, with no URL, text,
-user id or session id.
+Aggregate behaviour signals: rage clicks, dead clicks, hesitation, abandoned journey steps and your
+own registered signals. They are computed in the browser. Only the derived signal is sent, with no
+URL, text, user id or session id.
 
 ```ts
 createJourneeze({
   siteKey,
   signals: {
     enabled: true,
-    // Pass your own tflo module so the page runs one tflo runtime (recommended if you use tflo):
-    tflo: () => import("tflo-browser-events"),
-    // Optional site rules; each name must be registered for the site in Journeeze first.
-    rules: [{ name: "export_clicked", when: 'event.kind == "click" && event.fields.target == "export.button"' }],
+    tflo: () => import("tflo-browser-events"), // pass your copy if your app already uses it
   },
 });
 ```
 
-- **When they run:** only after the visitor's consent, while help or feedback mode is on, with
-  `signals.enabled: true` and the site's signals switch on in Journeeze. Global Privacy Control
-  turns them off. Before that, no signals or tflo code is loaded.
-- **What is tracked:** elements with a `data-tflow-id` (`[a-z0-9._:-]`, up to 96 characters)
-  outside `data-jz-mask` / `data-jz-block` regions and form fields. The SDK listens to `click`,
-  `pointerover`/`pointerout`, `focusin`/`focusout` and `change` only: never keys, input or pointer
-  moves, and it never patches `fetch` or XHR.
-- **tflo:** without `signals.tflo` the SDK loads its own copy as a separate lazy chunk with the
-  WASM inlined. Under a Content-Security-Policy that needs `script-src 'wasm-unsafe-eval'` and
-  `connect-src data:`; injecting your own module avoids the second.
-- **Journeys:** set `journeyId` and `journeyStep` with `setContext`; `journeyStep` must equal the
-  published journey's step ids (its `stepRef`s) for `abandoned_step` to apply.
+- They run only after consent, while help or feedback is on, and while the site's signals switch on
+  the board is on. Turning that switch off stops them without a deploy.
+- Only elements with a `data-tflow-id` outside masked regions are tracked. The SDK listens to
+  clicks, hover, focus and change events. It never reads keystrokes, input values or pointer
+  movement.
+- Without your own `tflo-browser-events` (`>=0.1.0 <1`, optional peer dependency) the SDK loads its
+  own copy. That needs `'wasm-unsafe-eval'` in `script-src` and `data:` in `connect-src`.
+
+## Connect GitHub
+
+Journeeze files issues and reads your journey catalog through the **Journeeze GitHub App**.
+Install it on the repository you named during setup:
+
+**<https://github.com/apps/journeeze/installations/new>** → choose your account → **Only select
+repositories** → your repository → **Install**.
+
+| Permission | Why Journeeze needs it |
+|---|---|
+| Issues: read and write | File a cluster of feedback as one issue, and follow it until it is closed. |
+| Contents: read and write | Read your `.jevitate/` journey catalog. Writes go only to a Journeeze branch, as a pull request you review. |
+| Pull requests: read and write | Open those catalog pull requests and read their status. |
+| Metadata: read | Basic repository information GitHub requires for every App. |
+
+Each call uses a one-hour token limited to that repository. You can remove the App at any time
+(GitHub → Settings → Applications → Installed GitHub Apps). Journeeze then stops reading and
+filing.
+
+**After installing, tell the Journeeze team.** They link the repository to your project. This is
+one step on their side until the board does it for you.
+
+**Your journey catalog.** Journeeze reads the Jevitate catalog in your repository's `.jevitate/`
+folder (personas, jobs and journeys) on each push. Guides with screenshots and video are imported
+from your approved journeys as drafts. A triager reviews each one on the board (**Journeys**), may
+lightly edit the step text, and publishes it. Only published guides appear in help.
+
+**Without the App: upload from CI.** Your CI can upload the catalog as a bundle instead:
+`POST https://app.journeeze.dev/api/upload/v1/bundles` with `Authorization: Bearer jzu_…`. The
+Journeeze team creates upload keys for now and sends them as a one-time 1Password link. Ask them
+for the bundle format and a CI example. Never put an upload key in a URL or a log.
+
+## Setup checklist
+
+- [ ] Site key (and `apiHost` outside production) in each environment's runtime config.
+- [ ] SDK installed with a pinned version, or the script tag on every page.
+- [ ] CSP updated, if you send one.
+- [ ] `data-jz-mask` on every element with customer content; masked screenshot checked on each
+      screen that shows data.
+- [ ] `data-tflow-id` on every element a guide points at; `journeyStep` set per route.
+- [ ] Signed-in users: user id and signature made on your server and delivered `no-store`;
+      `reset()` on every logout path.
+- [ ] Journeeze GitHub App installed on your repository, and the Journeeze team told.
+- [ ] Help switched on for the site on the board, audience chosen, guides published.
+- [ ] One test feedback item sent from each site and seen on the board.
+
+## Troubleshooting
+
+| Symptom | Cause and fix |
+|---|---|
+| Requests go to `app.journeeze.dev` from staging or local, or the site key is refused | `apiHost` is not set. Set it for that environment. |
+| CORS error | The page origin is not registered for the site (scheme, host and port must match exactly). Ask the Journeeze team to add it. |
+| `window.Journeeze` is undefined | It was used during page load. Use it from a click or after `DOMContentLoaded`. |
+| Help launcher never appears | Help is off for the site, or the audience is Reviewers and this visitor has no invite. Check `onHelpStatus`. |
+| A guide step has no outline | The element's `data-tflow-id` is missing or changed. |
+| No screenshot offered | An invalid `maskSelectors` entry (fails closed), or the visitor is anonymous. |
+| Feedback is anonymous although `userId` is set | The signature is missing, wrong, expired, or made for another site key. |
+| `userId` ignored with a console warning | It is not a 64-hex or 43-base64url hash (for example a raw UUID or an email). |
+| `429` responses from an office or CI | Many users share one IP address. Use a proxy, or ask for a higher quota. |
+| Issues are never filed | The Journeeze GitHub App is not installed on the repository, or the Journeeze team has not linked it yet. |
+
+## Versions and license
+
+Changes are listed in `CHANGELOG.md` in this package. Public types ship in `dist/types`.
+`@journeeze/sdk/contract` exports `SITE_KEY_PATTERN` and `USER_ID_PATTERN` for your server's
+tests.
+
+Proprietary: see `LICENSE.md`. You may install this package and include it, unmodified, in
+websites and applications solely to connect them to the Journeeze service, under your agreement for
+that service. It is not open source.

package/dist/anchor-cPvFFTOS.js

@@ -0,0 +1 @@
+import{t as f}from"./context-UnG6_X61.js";const g=512,p=12;function b(t){const n=[];let o=t,e=false;for(let i=0;o&&i<p;i++){const r=o.hasAttribute("data-tflow-id")?f(o):void 0;if(r!==void 0&&o.getAttribute("data-tflow-id")===r){n.unshift(`[data-tflow-id="${r}"]`),e=true;break}const s=o.tagName.toLowerCase();if(s==="body"||s==="html"){n.unshift(s),e=true;break}const c=o,l=c.parentElement;let d=s;if(l){const u=Array.from(l.children).filter(m=>m.tagName===c.tagName);u.length>1&&(d+=`:nth-of-type(${u.indexOf(c)+1})`)}n.unshift(d),o=l}const a=n.join(" > ");return e&&a.length<=g?a:void 0}const h=t=>Number.isFinite(t)?Math.min(1,Math.max(0,t)):.5;function v(t,n,o){const e=t.getBoundingClientRect(),a={xRatio:h(e.width>0?(n-e.left)/e.width:.5),yRatio:h(e.height>0?(o-e.top)/e.height:.5)},i=f(t);i!==void 0&&(a.tflowId=i);const r=b(t);return r!==void 0&&(a.cssSelector=r),a}function A(t){return f(t)??t.tagName.toLowerCase()}function k(t){return t.closest("[data-jz-block]")!==null}function C(t){return t<768?"mobile":t<1024?"tablet":"desktop"}export{v as a,C as d,A as e,k as i};

package/dist/attach-DpioALxW.js

@@ -0,0 +1,21 @@
+import{t as K}from"./context-UnG6_X61.js";import{i as q}from"./anchor-cPvFFTOS.js";import{a as V,p as G}from"./upload-Fu2qvSJV.js";import{m as Se}from"./upload-Fu2qvSJV.js";import{M as I,u as J}from"./chat-BgmB0rnW.js";const R=10,j=.02,z=.01,h=(e,n,t)=>Number.isFinite(e)?Math.min(t,Math.max(n,e)):n,p=e=>Math.round(e*1e4)/1e4;function Q(e,n,t){return{x:h(t.width>0?(e-t.left)/t.width:0,0,1),y:h(t.height>0?(n-t.top)/t.height:0,0,1)}}function $(e,n,t){const i=h(n.x,0,1),a=h(n.y,0,1),r=h(t.x,0,1),s=h(t.y,0,1);return e==="arrow"?{type:e,x:p(i),y:p(a),w:p(r-i),h:p(s-a)}:{type:e,x:p(Math.min(i,r)),y:p(Math.min(a,s)),w:p(Math.abs(r-i)),h:p(Math.abs(s-a))}}function Z(e){return Math.abs(e.w)<z&&Math.abs(e.h)<z}function ee(e){return e==="arrow"?{type:e,x:.35,y:.35,w:.15,h:.15}:{type:e,x:.35,y:.4,w:.3,h:.2}}function te(e,n,t,i){const a=e.type==="arrow";if(i){const c=a?h(e.w+n,-e.x,1-e.x):h(e.w+n,z,1-e.x),u=a?h(e.h+t,-e.y,1-e.y):h(e.h+t,z,1-e.y);return{...e,w:p(c),h:p(u)}}const r=h(e.x+n,Math.max(0,-e.w),Math.min(1,1-e.w)),s=h(e.y+t,Math.max(0,-e.h),Math.min(1,1-e.h));return{...e,x:p(r),y:p(s)}}function U(e,n,t,i,a){const r=Math.atan2(i-n,t-e),s=c=>`${p(t-a*Math.cos(r+c))},${p(i-a*Math.sin(r+c))}`;return`${p(t)},${p(i)} ${s(Math.PI/7)} ${s(-Math.PI/7)}`}function ne(e,n,t,i){e.strokeStyle=e.fillStyle="#B42318",e.lineWidth=Math.max(2,Math.round(Math.max(t,i)/160));for(const a of n)if(e.beginPath(),a.type==="box"?e.rect(a.x*t,a.y*i,a.w*t,a.h*i):a.type==="circle"?e.ellipse((a.x+a.w/2)*t,(a.y+a.h/2)*i,a.w/2*t,a.h/2*i,0,0,Math.PI*2):(e.moveTo(a.x*t,a.y*i),e.lineTo((a.x+a.w)*t,(a.y+a.h)*i)),e.stroke(),a.type==="arrow"){const r=U(a.x*t,a.y*i,(a.x+a.w)*t,(a.y+a.h)*i,e.lineWidth*4).split(" ").map(s=>s.split(",").map(Number));e.beginPath(),r.forEach(([s,c],u)=>u?e.lineTo(s,c):e.moveTo(s,c)),e.fill()}}const ae="http://www.w3.org/2000/svg",B=["box","circle","arrow"];function m(e,n={},...t){const i=document.createElement(e);for(const[a,r]of Object.entries(n))i.setAttribute(a,r);return i.append(...t),i}function M(e,n){const t=document.createElementNS(ae,e);for(const[i,a]of Object.entries(n))t.setAttribute(i,String(a));return t}function ie(e,n,t){const i={fill:"none",stroke:"#B42318","stroke-width":3,"vector-effect":"non-scaling-stroke"};if(e.type==="box")return M("rect",{x:e.x*n,y:e.y*t,width:e.w*n,height:e.h*t,...i});if(e.type==="circle")return M("ellipse",{cx:(e.x+e.w/2)*n,cy:(e.y+e.h/2)*t,rx:e.w/2*n,ry:e.h/2*t,...i});const[a,r,s,c]=[e.x*n,e.y*t,(e.x+e.w)*n,(e.y+e.h)*t],u=M("g",{});return u.append(M("line",{x1:a,y1:r,x2:s,y2:c,...i}),M("polygon",{points:U(a,r,s,c,Math.max(n,t)/50),fill:"#B42318"})),u}function oe(e,n,t,i){return new Promise(a=>{let r="box",s=[],c,u;const v=B.map(o=>{const d=m("button",{type:"button",class:"tool","aria-pressed":String(o===r)},i(`draw.${o}`));return d.addEventListener("click",()=>{r=o,v.forEach((g,b)=>g.setAttribute("aria-pressed",String(B[b]===o)))}),d}),l=(o,d,g)=>{const b=m("button",{type:"button",class:d},o);return b.addEventListener("click",g),b},w=l(i("draw.undo"),"tool",()=>A(s.slice(0,-1),i("draw.removed_last"))),y=l(i("draw.clear"),"tool",()=>A([],i("draw.cleared"))),N=l(i("cancel"),"btn",()=>P(void 0)),X=l(i("draw.done"),"btn pri",()=>P(s)),T=M("svg",{viewBox:`0 0 ${t.w} ${t.h}`,preserveAspectRatio:"none","aria-hidden":"true"}),H=m("img",{src:n,alt:i("draw.image"),draggable:"false"}),W=m("span",{id:"jzd-k",class:"sr"},i("draw.keys")),f=m("div",{class:"stage",tabindex:"0",role:"group","aria-label":i("draw.stage"),"aria-describedby":"jzd-k"},H,T,W),L=m("p",{class:"msg",role:"status"}),E=m("div",{class:"jzd",role:"dialog","aria-modal":"true","aria-labelledby":"jzd-t","aria-describedby":"jzd-h"},m("header",{},m("h2",{id:"jzd-t"},i("draw.title")),m("p",{id:"jzd-h"},i("draw.hint"))),m("div",{class:"bar",role:"toolbar","aria-label":i("draw.tools")},...v,m("span",{class:"sep","aria-hidden":"true"}),w,y,m("span",{class:"end"},N,X)),m("div",{class:"wrap"},f),L);function k(){T.replaceChildren(...[...s,...u?[u]:[]].map(o=>ie(o,t.w,t.h))),w.disabled=y.disabled=s.length===0}function A(o,d){s=o,L.textContent=d,k()}function O(o){if(s.length>=R){L.textContent=i("draw.shape_limit",{max:R});return}A([...s,o],i(`draw.added.${o.type}`,{n:s.length+1,max:R}))}function S(){const o=f.parentElement,d=getComputedStyle(o),g=Math.max(1,o.clientWidth-parseFloat(d.paddingLeft||"0")-parseFloat(d.paddingRight||"0")),b=Math.max(1,o.clientHeight-parseFloat(d.paddingTop||"0")-parseFloat(d.paddingBottom||"0")),C=Math.min(g/t.w,b/t.h);f.style.width=`${Math.floor(t.w*C)}px`,f.style.height=`${Math.floor(t.h*C)}px`}const _=o=>Q(o.clientX,o.clientY,f.getBoundingClientRect());f.addEventListener("pointerdown",o=>{o.button===0&&(o.preventDefault(),f.setPointerCapture?.(o.pointerId),c=_(o))}),f.addEventListener("pointermove",o=>{c&&(u=$(r,c,_(o)),k())});const Y=o=>{if(!c)return;const d=$(r,c,_(o));c=u=void 0,Z(d)?k():O(d)};f.addEventListener("pointerup",Y),f.addEventListener("pointercancel",()=>{c=u=void 0,k()}),f.addEventListener("keydown",o=>{const d={ArrowLeft:[-j,0],ArrowRight:[j,0],ArrowUp:[0,-j],ArrowDown:[0,j]};if(o.key==="Enter"||o.key===" ")o.preventDefault(),O(ee(r));else if(d[o.key]&&s.length>0){o.preventDefault();const[g,b]=d[o.key];s=[...s.slice(0,-1),te(s[s.length-1],g,b,o.shiftKey)],k()}}),E.addEventListener("keydown",o=>{if(o.stopPropagation(),o.key==="Escape")o.preventDefault(),P(void 0);else if(o.key==="Tab"){const d=[...E.querySelectorAll("button:not([disabled]), [tabindex='0']")],g=d.indexOf(e.activeElement);(o.shiftKey?g<=0:g===d.length-1)&&(o.preventDefault(),d[o.shiftKey?d.length-1:0]?.focus())}}),window.addEventListener("resize",S);function P(o){window.removeEventListener("resize",S),E.remove(),a(o)}e.append(E),k(),S(),v[0].focus()})}const re=`
+.jzd{position:fixed;inset:0;z-index:2147483647;display:flex;flex-direction:column;background:var(--c);color:var(--i)}
+.jzd header{display:flex;flex-wrap:wrap;align-items:baseline;gap:4px 12px;padding:12px 16px;border-bottom:1px solid var(--l);background:var(--s)}
+.jzd h2{margin:0;font-size:14px;font-weight:600}
+.jzd header p{margin:0;font-size:12px;color:var(--m)}
+.jzd .bar{display:flex;flex-wrap:wrap;align-items:center;gap:6px;padding:8px 16px;border-bottom:1px solid var(--l);background:var(--s)}
+.jzd .bar .sep{width:1px;height:28px;background:var(--l);margin:0 4px}
+.jzd .bar .end{margin-left:auto;display:flex;gap:6px}
+.jzd .tool{min-width:44px;min-height:44px;padding:0 12px;border:1px solid var(--l);border-radius:6px;background:var(--s)}
+.jzd .tool[aria-pressed=true]{background:var(--as);border-color:var(--a);color:var(--a);font-weight:600}
+.jzd .wrap{flex:1;min-height:0;display:grid;place-items:center;padding:16px}
+.jzd .stage{position:relative;border:1px solid var(--l);border-radius:6px;overflow:hidden;background:var(--r);touch-action:none;cursor:crosshair;user-select:none;-webkit-user-select:none}
+.jzd .stage img,.jzd .stage svg{position:absolute;inset:0;width:100%;height:100%;display:block}
+.jzd .stage svg{overflow:visible}
+.jzd .stage *{pointer-events:none}
+.jzd .msg{min-height:20px;margin:0;padding:0 16px 8px;font-size:12px;color:var(--m)}
+.pick{position:fixed;inset:0;z-index:2147483647;cursor:crosshair;touch-action:none}
+.pick .hl{position:fixed;border:2px solid var(--a);border-radius:4px;background:var(--as);pointer-events:none}
+.pick .hint{position:fixed;left:50%;bottom:24px;transform:translateX(-50%);display:flex;align-items:center;gap:8px;max-width:calc(100vw - 32px);padding:4px 4px 4px 16px;border:1px solid var(--l);border-radius:10px;background:var(--s);box-shadow:var(--sh);font-size:13px}
+@media (max-width:640px){.jzd .bar .end{margin-left:0;width:100%}.jzd .bar .end .btn{flex:1}.jzd .wrap{padding:8px}}
+`,D=["image/png","image/jpeg","image/webp","image/gif"],se=10*1024*1024,ce=2*1024*1024,de=1600,le="[data-journeeze], [data-journeeze-chat]",x=(e,n)=>e.session.note(e.session.t(n,{max:I}));async function ze(e,n){return pe(n),e==="point_at_it"?ge(n):n.options.reviewerToken||n.options.userId?n.session.attachments.length>=I?x(n,"note.attachment_limit"):e==="show_us_where"?he(n):xe(n):x(n,"note.signed_out")}function pe(e){if(e.root.querySelector("style[data-jz-capture]"))return;const n=document.createElement("style");n.setAttribute("data-jz-capture",""),n.textContent=re,e.options.nonce&&(n.nonce=e.options.nonce),e.root.append(n)}async function ue(e){const n=await e.config(),t=Array.isArray(n.maskSelectors)?n.maskSelectors:[],{maskSelectors:i,maskAllText:a}=e.options;return{...i?{maskSelectors:i}:{},...t.length?{configMaskSelectors:t}:{},...a?{maskAllText:a}:{}}}async function me(e){try{const n=await V(document.body,await ue(e));if(n.blob)for(const[t,i]of Object.entries(n.detectorCounts))i&&e.session.overMask.set(t,(e.session.overMask.get(t)??0)+i);return n.blob}catch{return}}async function he(e){const n=e.suspend(),t=await me(e);if(!t)return n(),x(e,"note.masking_failed");const i={w:Math.max(1,window.innerWidth),h:Math.max(1,window.innerHeight)},a=URL.createObjectURL(t),r=await oe(e.root,a,i,e.session.t);URL.revokeObjectURL(a),n(),r&&await F(e,t,i,r,"attachment.screenshot")}async function F(e,n,t,i,a){const r=await fe(n,t,i);e.session.addAttachment({id:J(),thumbnail:r,label:e.session.t(a,{n:e.session.attachments.length+1}),...i.length?{shapes:i}:{},upload:()=>G(e.endpoint,e.options,n),release:()=>URL.revokeObjectURL(r)})||(URL.revokeObjectURL(r),x(e,"note.attachment_limit"))}async function fe(e,n,t){try{const i=await createImageBitmap(e),a=document.createElement("canvas");a.width=256,a.height=Math.max(1,Math.round(256*n.h/n.w));const r=a.getContext("2d");r.drawImage(i,0,0,a.width,a.height),ne(r,t,a.width,a.height);const s=await new Promise(c=>a.toBlob(c,"image/webp",.8));if(s)return URL.createObjectURL(s)}catch{}return URL.createObjectURL(e)}async function ge(e){const n=e.suspend(),t=await be(e.root,e.session.t);if(n(),!t)return;const i=q(t)?void 0:K(t);i?e.session.setAnchor({tflowId:i}):x(e,"note.no_name")}function we(e,n){return document.elementsFromPoint(e,n).find(t=>!t.closest(le)&&t!==document.documentElement)}function be(e,n){return new Promise(t=>{const i=document.createElement("div");i.className="hl",i.hidden=true;const a=document.createElement("button");a.type="button",a.className="btn",a.textContent=n("cancel");const r=document.createElement("div");r.className="hint",r.setAttribute("role","dialog"),r.setAttribute("aria-label",n("point.label")),r.append(n("point.hint"),a);const s=document.createElement("div");s.className="pick",s.append(i,r);const c=l=>{const w=we(l.clientX,l.clientY);return w?.closest("[data-tflow-id]")??w};s.addEventListener("pointermove",l=>{const w=c(l);if(i.hidden=!w,!w)return;const y=w.getBoundingClientRect();Object.assign(i.style,{left:`${y.left}px`,top:`${y.top}px`,width:`${y.width}px`,height:`${y.height}px`})}),s.addEventListener("pointerup",l=>{r.contains(l.target)||v(c(l))}),a.addEventListener("click",()=>v(void 0));const u=l=>{l.key==="Escape"&&(l.preventDefault(),l.stopPropagation(),v(void 0))};document.addEventListener("keydown",u,true);function v(l){document.removeEventListener("keydown",u,true),s.remove(),t(l)}e.append(s),a.focus()})}function xe(e){return new Promise(n=>{const t=document.createElement("input");t.type="file",t.accept=D.join(","),t.hidden=true,e.root.append(t),t.addEventListener("change",()=>{const i=t.files?.[0];t.remove(),i?ve(e,i).then(n):n()}),t.addEventListener("cancel",()=>{t.remove(),n()}),t.click()})}async function ve(e,n){if(!D.includes(n.type)||n.size>se)return x(e,"note.file_type");if(e.session.attachments.length>=I)return x(e,"note.attachment_limit");const t=await ye(n).catch(()=>{});if(!t)return x(e,"note.file_read");await F(e,t.blob,t.size,[],"attachment.image")}async function ye(e){const n=await createImageBitmap(e,{imageOrientation:"from-image"});let t=Math.min(1,de/Math.max(n.width,n.height));for(const i of[.85,.7,.5]){const a=document.createElement("canvas");a.width=Math.max(1,Math.round(n.width*t)),a.height=Math.max(1,Math.round(n.height*t)),a.getContext("2d").drawImage(n,0,0,a.width,a.height);const r=await new Promise(s=>a.toBlob(s,"image/webp",i));if(!r||r.type!=="image/webp"&&r.type!=="image/png")return;if(r.size<=ce)return{blob:r,size:{w:a.width,h:a.height}};t*=.75}}export{D as IMAGE_TYPES,se as MAX_FILE_BYTES,ve as addFile,ue as maskOptions,me as maskedCapture,Se as maskedSnapshotSvg,we as pageElementAt,be as pick,ze as plusItem,ye as reencode};