​

✍️ Attribute write operations

​

🎲 Random bucketing attributes

​

🔌 The SDK reconnects on its own

​

🐞 usertour.setDebug(true)

​

🌐 Localization: destinations, alt text, and the API

​

🗑️ Soft delete for themes, attributes, segments and events

​

🐛 Fixes

• A brand-new flow started right after another was dismissed even with a quiet period (“at least N minutes after any flow”) configured: the quiet period never held for a content the user had no event on yet.
• A start rule combining an event with a browser condition never fired when the event alone satisfied its group: the browser leaf was never tracked.
• Content gated on a condition that had toggled could not start after a reconnect, because the reconnect carried the condition’s stale state.
• Text-input “has any value” was true whenever the input existed, empty or not; it now requires a non-empty value.
• A hover launcher’s tooltip closes when the pointer leaves it; the banner frame no longer shows the browser’s default iframe border on hosts without a CSS reset.
• Two OAuth handshakes in the same second could no longer collide on their state value.
• The self-hosted installation snippet’s ASSETS_URI no longer carries a trailing slash, as the docs say, and the snippet queues a setDebug call placed before the script loads.
• identifyAnonymous()’s opts parameter is documented as having no effect: anonymous ids are minted client-side, so a backend can never sign one.

​

Behaviour changes to check

• Text-input “has any value” now requires a value. A rule that meant “the input is on the page” should use an element “present” condition on the same selector.
• The quiet period now holds for content the user has never seen.
• Segments using is empty / has any value on a List attribute never matched anyone before; they match now, so their membership changes after upgrade.
• Attribute acceptance is wider (numeric strings into Numbers, numbers into Strings, any ISO 8601 date-time into a DateTime). Inference on first creation stays strict.
• Deletes can be refused. An attribute, segment, theme or event still used by live content answers 409 (E1042 / E1043 / E1030 / E1031); E1030 now means “used by live content” rather than “has recorded events”, so fired events can be deleted. Publishing a version that references a deleted definition answers E1044.
• identify() / group() resolve to { rejected } instead of a boolean; truthiness is unchanged, and an older SDK reads the new acknowledgement as truthy.

​

Upgrade notes

• One migration, additive (Localization.deleted, default false, no backfill), and one seed backfill that runs on start: translation rows below schema version 2 get their navigate / alt / chip-fallback clones blanked so the new rows start as real untranslated copy. Expect a Localized unit stores backfill completed log line.
• A new BullMQ queue, attribute-backfill, runs in the server process on your existing Redis; a job is enqueued when a bucketing attribute is created or restored.
• SDK 0.8.1 ships in the image. The server is backward compatible with pages still running 0.8.0, and the handshake log line now names each connection’s SDK version (… authenticated for user u1 (sdk 0.8.0)), so the pages that have not reloaded since the deploy can be counted from the logs.
• usertour.js 0.0.26 on npm carries the operation typings, the setDebug stub and the write-result type; it is safe with every bundle version, including ones older than this release.
• Nest log contexts that used the old class names change (for example SharedModule → CommonModule); update any log filters that key on them.
• No new environment variable. Rollback is a plain revert: bucketing values already written are inert under the previous server, and SDK 0.8.1 accepts the previous server’s acknowledgements.

​

🛠️ Under the hood

• Server modules layout (ADR 0015). Every directory under apps/server/src moved into src/modules/<name>/; src/ holds only the entry points (api/, openapi/, mcp/, web-socket/). A test enforces the import direction. Queue, cron, Redis key, cookie and event names are unchanged. The GraphQL schema and the v2 OpenAPI document are byte-identical before and after.
• One rule point for attribute writes (ADR 0017). resolveAttributeWrites → judgeAttributeWrite → applyAttributeWrites, shared by the socket, v2 and MCP paths; user, company and membership rows are locked with FOR NO KEY UPDATE (so foreign-key inserts never deadlock against them), in the order user → companies by id → memberships; a write that changes nothing takes no lock. Prisma transactions wait up to 10 s and may run 15 s, so the socket queue’s 10 s timeout is always the first limit to fire.
• Connection recovery (ADR 0018) is an explicit state machine in the SDK; failed writes are kept in a replay registry with one record per target, keyed by the latest send, replayed once within ten minutes. The server disconnects a socket whose data is gone instead of rebuilding it from a stale handshake, and the throttler marks a refused message rather than throwing.
• Debug logging (ADR 0019) reclassified every SDK message into debug / info / warn / error / critical with a scope per component.
• Bucketing (ADR 0020) values are a hash of attribute and entity id, materialised at birth and by the backfill, derived at read time when missing.
• Tests and CI. 65 real-browser widget render checks, a 71-scenario SDK runtime suite against a protocol server the test controls, 26 server rules-conformance scenarios including composite start-rule trees, and a GitHub Actions workflow that lints, type-checks and runs the unit, server e2e and browser suites on every pull request and on pushes to staging and main.
• Authorization registry. The endpoint-to-capability test now covers every endpoint, including the identity-verification signing secrets and the audit log, which had drifted out of it.
• Validation. v2 bodies skip class-transformer in the global pipe (zod DTOs carry no metadata for it); __proto__ is refused as an attribute name on every path.

​

🔗 HubSpot: two-way property sync

​

📌 Onboarding milestones on the HubSpot timeline

​

👥 Four roles, and a publish whitelist for editors

• Ownership transfer is its own action, available only to the Owner; the previous owner becomes an Admin. An Admin can invite, re-role and remove anyone except the Owner, and the Owner’s row can no longer be changed through the team endpoints at all.
• Webhook and integration auto-disable emails go to every Admin as well as the Owner.
• SSO auto-provisioning assigns Editor or Viewer only, Editor by default; a just-in-time editor starts with an empty whitelist.
• Personal API keys inherit their owner’s whitelist as a publish ceiling: REST and MCP publish calls outside it are refused with E1039, and over MCP the refusal names the environments the key may publish to, so an assistant can recover on its own. The key’s own environment scope still governs everything else.

​

✉️ Redesigned transactional emails

​

🤖 In the official MCP registry

​

🐳 Self-hosting notes

• Seven migrations run on upgrade, including the role migration described above. It is not a no-op: memberships, pending invites and SSO default roles are rewritten. After deploying, open Settings → Team and promote whoever should be an Admin.
• HubSpot needs your own HubSpot app. Redirect URLs and secrets are bound to an app, so upload your copy of integrations/hubspot to your HubSpot developer account (the directory README has the procedure) and set HUBSPOT_CLIENT_ID / HUBSPOT_CLIENT_SECRET. The callback defaults to ${API_URL}/api/integrations/hubspot/oauth/callback, overridable with HUBSPOT_CALLBACK_URL. It must be registered on the app and served by the host the dashboard sends API requests to. Without credentials the HubSpot page shows a pointer to this setup instead of Connect. No traffic is relayed through Usertour Cloud.
• Redis_DB selects a logical Redis database (0–15) for the cache, the queues and the socket adapter. Unset, it stays 0.
• The default email sender reads Usertour <support@usertour.io> (it was spelled UserTour). Setting EMAIL_SENDER overrides it as before.

​

🐛 Fixes

• Any signed-in user could read another project’s plan and usage, or open a checkout or billing-portal session against it, by project id. The subscription endpoints were never attached to the permission guard. Reads now require project membership, and checkout and portal require the Owner.
• Switching a flow’s frequency from Once to Multiple crashed the builder when the flow’s start rules had been written through the API or MCP; the page showed “Something went wrong” and reloading did not help. The missing repeat window is now filled in on read. Delivery to end users was never affected.
• A project could be left with no owner. The role-change endpoint accepted Owner as a target and would re-role the Owner’s own row; the dashboard hid both, the API did not.
• Auto-disable notifications could silently fail to send when a project had many recipients. Each message opened its own SMTP session, and a provider refusing a dozen parallel logins dropped them. Mail now goes through one pooled connection set, and a send during shutdown fails fast instead of hanging the process.
• The activity feed on a company’s page was slow on large workspaces. Its query scanned every event in the table — 660 ms on a million rows — and now resolves through indexes in under a millisecond.
• An integration’s page flashed “not connected” on load before settling on its real state. It holds a skeleton until the environment is known.
• The plan comparison left excluded features blank, which read as missing data. They show a cross, and integrations are listed by name in their own section, next to webhooks.

​

🛠️ Under the hood

• The sync engine is provider-agnostic below the adapter: mappings, links and sync runs are three tables with no HubSpot assumptions, and the engine is named for object sync rather than for its first provider. The HubSpot app project lives in integrations/hubspot, outside the pnpm workspace because HubSpot’s CLI builds and deploys it.
• Write-backs and timeline events are messages on the outbound ledger, under topics that name the message rather than the recipient — sync.object.update and event.tracked.<codeName>. A write-back carries the field set, not values; values are read at delivery, so retries send current data. The timeline occurrence id is the ledger message id, which is what makes a retry idempotent.
• Loops are impossible by construction, through three gates that each suffice alone: inbound applies only listed properties (our own usertour_* write-backs never re-enter), outbound skips changes whose origin is the provider, and a field cannot sit in both lists of one mapping.
• The OAuth handshake binds the callback to the browser that started it: a signed ten-minute state plus an httpOnly SameSite=Lax transaction cookie set on the authenticated response, so a forwarded authorize link cannot attach a victim’s HubSpot account to an attacker’s environment. A Marketplace-initiated install finishes inside HubSpot’s frame where that cookie never arrives, so its state is verified by being spent once instead; returnUrl is honoured only for HubSpot app hosts.
• Tokens are AES-256-GCM encrypted and refreshed under a single-flight lock with compare-and-set, so a disconnect mid-refresh is never overwritten. A rejected access token is refreshed once, then treated as a revoked grant. Provider errors are stripped of their request before they propagate — the token form carries the app secret.
• Errors are one of four kinds, each with one handling: transient (retry ladder, feeds the breaker), rate limit (wait for Retry-After, never the breaker), revoked (off at once), refused (a 4xx closes the round immediately with HubSpot’s reason, instead of walking a 25-hour ladder). A round is alive while its heartbeat is fresh, and the stale window outlasts any single wait a job can take; one journal poller runs under a renewed Redis lease so ticks never overlap across instances.
• Every dated HubSpot path — OAuth, CRM objects and properties, the webhooks journal — hangs off one HUBSPOT_API_VERSION constant (2026-09). Timeline events stay on /integrators/timeline/v4 until HubSpot publishes a dated replacement.
• Behaviour is decided only by capability — roleCan(role, capability) on the server, can(capability) in the web app — and role names are compared only where roles are assigned. The USER → EDITOR enum change is a hand-written ALTER TYPE … RENAME VALUE, metadata-only, instead of the drop-and-recreate Prisma generates.
• The permission test suite now fails on any unguarded resolver: every resolver class must register the guard, and every query and mutation must be in the capability map or in an explicit, reasoned exemption list. The e2e endpoint matrix moved to four tiers.
• Emails render from typed props in a new @usertour/emails package (React templates replacing mjml + handlebars). The SMTP pool closes in the application-shutdown phase, after the queue workers drain.
• The MCP registry entry is published by CI on release tags over OIDC, taking its version from the tag, so a release cannot ship a stale listing. The e2e suite runs on its own Redis database so it no longer consumes a local dev server’s jobs.

​

📡 Event streaming to analytics providers

​

🔁 Cohort sync from Mixpanel and Amplitude

​

⚡ Zapier

​

🧾 Track events from your own servers

​

🌐 Localized link destinations

​

🐳 Self-hosting notes

• RUN_SEED=false skips the startup seed on an instance. Multi-instance deployments set it on all but one instance (or run the seed from a one-off job) so the idempotent backfills execute once instead of once per replica. Unset, behaviour is unchanged.
• If you front the server with your own reverse proxy, route /inbound to the API (cohort-sync receive URLs live there) and allow request bodies up to 5 MB on the API location; the bundled nginx already does both.
• The legacy integration tables are dropped, not migrated. That module was never reachable — hidden menu entry, dead call site — so any rows in them never took effect. jsforce leaves the dependency tree.

​

🐛 Fixes

• A page holding only the public environment token could record built-in events such as flow_completed. The SDK’s socket channel kept its own event registration and accepted any name, polluting analytics and firing every webhook or Zap on that topic. It now rides the same core as the REST endpoint and refuses built-in names.
• Reload buttons on user and company detail pages misbehaved. The activity feed’s reload crashed with a circular-structure error because the click event was passed as query variables; the sessions list emptied itself on refresh and never repopulated. Both keep their rows on screen, and the buttons now show an in-flight spinner.
• A long URL blew the link popover open in the editor, pushing the attribute and delete buttons outside the card. The URL wraps inside the editable instead. Same fix for the image link panel and the page-navigate action input.
• Un-entitled projects flashed all provider cards before the upsell on the integrations page. Skeleton cards hold the layout while entitlement settles.
• An integration running only cohort sync read as “Disabled”. The status badge now considers both capabilities.

​

🛠️ Under the hood

• Integrations are a second transport over the outbound ledger: BIZ_EVENT_TRACKED → listener → ledger → one delivery queue → pure per-provider adapters. The ledger stores the canonical envelope and the wire body is derived at delivery time, which is what lets a key or region fix apply to in-flight retries and keeps the message log uniform across webhooks and integrations. The retry ladder and reconcile parameters moved to outbound/delivery-backoff.ts, shared by both transports.
• Cohort sync is one provider-agnostic engine behind per-provider entry adapters that normalise payloads into a single batch contract. Writes are set-based and idempotent (createMany … skipDuplicates, bulk deletes), so a retried or out-of-order batch cannot corrupt state; full-roster rounds carry their state on the mapping row and only reap members their own environment bridged. Processing is synchronous in the request — a failure returns 5xx and the provider retries. Tokens are utin_-prefixed, encrypted at rest with a sha256 lookup column; a bad token 404s, a disabled switch or lapsed plan 503s so the provider keeps retrying rather than pausing permanently.
• Custom event registration is one idempotent step outside the event transaction (registerCustomEvent: definition upsert, reserved-name guard, attribute registration, one retry absorbing concurrent first use), shared by the v2 REST endpoint, the SDK socket channel and the Zapier action.
• Localization replaces the “stored value equals live source, so not an override” heuristic with an explicit format stamp on every localized write, plus an idempotent seed-time backfill for rows saved before link units existed.
• The integration catalog moved to @usertour/constants and provider types split into analytics and automation unions; the Zapier app lives in integrations/zapier, deliberately outside the pnpm workspace because the Zapier Platform CLI builds and deploys it.
• Test coverage: end-to-end suites for cohort sync (materialisation, idempotent increments, paged replace, cross-environment convergence, read-only enforcement, token rotation, release-on-delete), the Amplitude entry, the track-event route, and built-in-name refusal on the socket channel.

​

🪝 Outbound webhooks

​

🛡️ Delivery that survives an outage

​

🧾 A message log you can re-send from

​

🔌 Endpoints as an API resource

​

🚀 A starting point after signup

​

🐛 Fixes

• docker stop always burned the full grace period and then killed the container. A shell held PID 1 with no signal handler, so the SIGTERM never reached Node. The image now runs Node as PID 1 and shuts down cleanly — HTTP server, Redis and Prisma closed in order.
• Detail dialogs could grow past the screen and jump while closing. They are now bounded by the viewport and scroll inside, and the closing animation no longer collapses their content.
• Long values broke the webhook screens’ layout. Status badges and table headers no longer wrap inside their columns, long topics and URLs truncate with the full value on hover, and an over-long URL or an oversized topic list is caught inline in the form instead of coming back as a raw server error.

​

🛠️ Under the hood

• Domain events are emitted after commit, so a rolled-back transaction can never produce a webhook. Delete events are sourced from DELETE … RETURNING, which gives per-row attribution: concurrent duplicate deletes emit exactly one message instead of two with different ids.
• Signing secrets are AES-256-GCM encrypted at rest, the treatment the SDK signing secrets and 2FA secrets already had. The plaintext boundary is the domain service; the delivery worker decrypts its own read.
• User-controlled URLs run behind the shared SSRF egress guard — HTTPS-only fail-fast at save time, DNS-rebinding-pinned resolution and IP-literal vetting at send time, and proxy environment variables are disabled on guarded deliveries, since dialing a proxy would leave the guard inspecting the wrong host. ALLOW_PRIVATE_NETWORK_EGRESS opts self-hosted deployments out.
• Retries live in Redis for a day, so an hourly reconcile sweep re-queues messages whose job was lost with the queue — resuming from the highest logged attempt, never from a row count.
• Concurrent writes to breaker and message state are compare-and-swap guarded end to end; the rules that came out of it are now a written convention (docs/conventions/concurrent-state-writes.md) rather than tribal knowledge.

​

🔗 Zero-config self-hosting tells the truth about its address

​

🛡️ A forwarded-header chain that can’t be spoofed

​

🐛 Fixes

• Settings → MCP showed an empty Server URL on a zero-config self-host. The /mcp endpoint itself self-described fine; the display read raw config. Both now share one derivation — along with the installation page’s API URL.
• Behind a TLS-terminating edge, OAuth metadata advertised http:// and MCP clients refused to connect. nginx overwrote the edge’s X-Forwarded-Proto with its own scheme. It now passes the header through — including when duplicate headers arrive merged as https, https.
• The port vanished from derived URLs. nginx’s $host strips it, so the stock 8011:80 setup derived dead http://localhost/… links. The client’s own Host header is forwarded intact.
• A bad TRUST_PROXY value — or any startup error — left a zombie container. Bootstrap exceptions died in a log-only handler: the process neither listened nor exited, and restart policies never fired. Input is now sanitized ("", wrapping quotes and True all parse), anything still invalid throws naming the variable, and startup fails fast with exit code 1.
• globalConfig threw over the legacy websocket transport when API_URL was unset (no HTTP request to derive from). It returns empty values instead.

​

🛠️ Under the hood

• The URL-derivation contract is pinned by e2e: scheme from X-Forwarded-Proto, host and port from Host, resolved per request, config always winning — and the derived MCP URL must equal the oauth-protected-resource metadata byte-for-byte (RFC 9728).
• Rate-limit regression tests cover the spoofing paths: rotating fake X-Forwarded-For prefixes over one real client — public or private-range — land in a single bucket and hit 429.
• The Docker-image workflow actions moved to their Node 24 majors, clearing the runner deprecation warnings.
• The README now opens with Build Your Onboarding with AI: three real prompts with their unedited results, and the self-host pointer for the Claude Code plugin (USERTOUR_MCP_URL).

​

🔌 Public v2 REST API

​

🤖 MCP server for AI assistants

​

🔑 Personal API keys and Connected apps

​

🧾 Audit log

​

✋ Authoring that refuses to fail silently

​

📊 Analytics that says what it counts

​

👥 Environment-scoped members, version history

​

🐛 Fixes

• waitMs was always seconds. The trigger and start-rule field is renamed waitSeconds; the runtime never read it as milliseconds, so the old name mis-taught everyone who saw it.
• A version that ever shipped is now frozen. Unpublishing used to unlock a live version for editing, silently rewriting what users had already seen; fork it instead.
• Banners had no start priority. Two banners competing for the single banner slot resolved arbitrarily; banner now takes a priority like resource center.
• Attribute conditions were not scoped by entity. A condition on a company attribute could be built against a user, and vice versa.
• Launcher fringe on dark hosts. A backdrop behind icon launchers leaked a light seam on dark pages; removed.
• Banner remount on SPA navigation, live-chat provider guard, choice-label ids and watcher idempotency in the SDK (0.7.9).
• Social login dropped the flow it interrupted. Signing in with Google or GitHub from a page that required a login (the MCP consent screen) landed on the homepage instead of returning; the target now rides the OAuth state round-trip, validated same-origin on the way back.

​

🛠️ Under the hood

• The v2 surface is a self-contained module: zod contracts generate both validation and the OpenAPI document, mappers are pure functions testable without DI, and a response-contract check runs on every e2e request so a mapper can’t quietly return a shape the spec doesn’t declare.
• Content authoring rides a codec pair — a decompiler that presents stored steps/rules as an intent-level representation, and a compiler that turns that representation back into internal structures (markdown→slate, blocks and rules→storage). A permanent round-trip corpus pins it against real content.
• Condition validators live in @usertour/helpers as a single source of truth, shared by the builder and by the v2 publish/dry-run gate.
• The MCP server is scope-gated by construction: a token only sees the tools its capabilities allow, and every handler re-authorizes on call.
• OAuth issues short-lived access tokens with rotating refresh tokens (60s grace so a lost response can’t brick a grant), and MCP_SERVER_URL is the single truth for the advertised MCP resource — set it to serve /mcp on its own domain.
• Test coverage: every MCP tool ships with an e2e case, the v2 capability matrix is asserted route-by-route against the OpenAPI document, and theme settings round-trip per field across 158 paths.

​

🧬 Segments can filter across entities

​

🎛️ Faster segment filter editing

​

📡 Trackers follow company switches

​

🐛 Fixes

• Company segments with grouped conditions matched every company at runtime. Runtime evaluation didn’t recurse into condition groups, so a segment whose conditions were wrapped in a group silently compiled to “no filter” — auto-start rules fired (and hide rules stayed off) for companies far outside the segment, while the segment’s company list, which compiled correctly, looked right.
• Mixed-entity OR conditions were evaluated as AND at runtime. Company segment evaluation partitioned conditions into per-entity buckets that all had to match, dropping the OR semantics between them.
• Company lists dropped membership conditions. Offline company queries ignored membership-attribute conditions entirely; they now filter with the same semantics as runtime.
• Search no longer clobbers filters. On list pages, the search box’s OR clause could overwrite a condition filter’s own top-level OR; the two now combine as independent AND members.

​

🛠️ Under the hood

• common/attribute/filter.ts gains a three-projection builder — createBizUserConditionsFilter (with all / current / none company-scan modes) and createBizCompanyConditionsFilter — sharing a membership-anchored condition tree with boolean-simplified fallback branches for rows without memberships. Runtime segment evaluation, offline user/company queries, and list search all ride it.
• Tracker ingest validates the report’s (content, version) pair against the socket’s distributed session and resolves the event id from that snapshot rather than the live Version row, with the publish-state check moved inside the ingest transaction. Batch diffs identify tracker sessions by composite key — they carry no biz session id — and compare tracker payloads so condition changes re-emit.
• The v2 WebSocket gateway gains an e2e harness with coverage batches across flow auto-start, checklists, launchers, banners, announcements, resource center, timers, frequency rules, session recovery, identity verification, and runtime segment evaluation.

​

🔐 Prove user identities with a signed token

​

🎛️ A new Identity Verification settings page

​

📊 Coverage-first, opt-in enforcement

​

🔑 What identity verification does and doesn’t cover

​

🛠️ Under the hood

• One checkToken classifier is the single source of truth for both the runtime handshake and the console validator, so they can never disagree. Claim comparison is string-coerced (numeric IDs), exp/nbf carry a 30-second clock tolerance, tokens are length-bounded before any decode on the unauthenticated handshake path, and a handshake with a company claim verifies its token exactly once.
• Signing secrets live in a dedicated EnvironmentSigningSecret table — utv_-prefixed, AES-256-GCM encrypted at rest (HMAC needs the original value, so hashing is impossible by construction), at most two active per environment for the rotation window, with lastUsedAt observability. The lifecycle mutations run in serializable transactions that retry on serialization failure.
• The SDK keeps a single identity token as the source of truth for reconnect credentials: a refreshed token revives a handshake that was rejected while a token was expiring, and a server-rejected group() claim rolls back with concurrency-safe compare-and-restore so it can never poison a later reconnect.
• Verification runs only on the v2 WebSocket surface; the REST API already authenticates with secret, server-side keys, and the v1 socket path is out of scope as it winds down.

​

🌍 A translation editor for every content type

​

🤖 AI machine translation

​

🚚 Delivery keyed on the user’s locale

​

🔁 Versioned, publish-gated, preview-ready

​

🐛 Fixes

• Widgets now apply mid-session updates fully. A session update refreshed only part of the widget state, so changes like a plan’s branding flag — and now the interface language — didn’t take effect until reload.
• Checklists re-deliver when their delivered content changes. The change detector compared only task lists, so updates to the launcher button or checklist body were dropped as “no change”.
• Viewers see announcement content read-only instead of an editable-looking editor, and the announcement list’s guide link now points at the announcements guide.
• Settings row-action icons align on a shared icon box across all settings tables.

​

🛠️ Under the hood

• Translations live in VersionOnLocalization rows — a structural clone of the source per (version, locale), where empty string means untranslated. Delivery merges structurally: the source tree owns structure and behavior, the translation donates non-empty text. Rows are keyed by step cvid, so forks and restores copy them verbatim with zero remapping.
• Locale resolution is a pure function of the locale_code user attribute (seeded and backfilled as a default attribute), shared by content delivery, widget chrome, and the delivered-locale stamp on analytics events.
• Machine translation is served by a new instance-level ai module (Vercel AI SDK; Anthropic / OpenAI-compatible / Bedrock with a three-tier AWS credential chain). Structured outputs are enforced end to end, and responses that split one translation across entries are dropped for retry instead of saving fragments.
• The translation editor saves through read-write-symmetric payload builders: a session may only overwrite what it could read, so drifted or unreadable fragments of the stored row survive every save. Published versions fork lazily on the first actual write, and the editor pins its version so its own fork never remounts it mid-edit.

​

📣 Announcements in the Resource Center

​

🔔 Notification levels: silent, badge, popup

• Silent — it simply appears in the feed.
• Badge — an unread count appears on the launcher, the announcement tab, and the Resource Center home row; opening the feed marks everything seen and clears the badges immediately.
• Popup — the newest unseen announcement additionally presents itself once, either as a centered modal or as a speech bubble anchored to the launcher, following all four launcher placements.

​

🎯 Targeting, scheduling, and analytics

​

🐛 Fixes

• The content editor no longer loses edits under concurrent saves. Editing a published version’s content and settings at the same time could fork two drafts and drop one side’s changes, republishing could ship a stale config, and targeting edits could silently revert to the pre-edit rules after republish. Forks are now serialized and each save path applies its own changes.
• The save indicator tells the truth — it stays on while a debounced save is still pending and survives edits made mid-write, so leaving the page no longer discards work that looked saved.
• Previews no longer crash on empty versions — the launcher list and content-detail previews guard against versions that have no data yet.
• Resource Center home header background defaults to none, so themes without an explicit header color render as designed.
• SDK: a failed Resource Center data load is no longer mistaken for an empty one — failures are now retried, and widget socket round-trips are bounded by a timeout so a dropped acknowledgment can’t hang the panel.

​

🛠️ Under the hood

• AnnouncementService owns one visibility gate — published, not deleted, announcement time reached, targeting passed — shared by the feed scan and the direct by-id fetch, so a deep link can never expose what the feed would hide. Websocket payloads for the announcement APIs are validated at the boundary.
• Read state lives in a dedicated BizAnnouncementSeen table; marking is batched, and the insert-returning first-seen path emits each analytics event exactly once.
• Default events/attributes backfill for existing projects moved from app boot into prisma/seed, running idempotently on every deploy; the seed now connects over DATABASE_DIRECT_URL so a saturated connection pooler can’t silently skip it.
• @usertour/types now holds only types and enums — all instantiated constants moved to @usertour/constants.

​

🔐 Project-level single sign-on (OIDC)

• Works with any standard OIDC provider — Okta, Microsoft Entra, Auth0, OneLogin, Authentik, Google Workspace — through issuer discovery, with optional explicit endpoint overrides.
• Force SSO: require everyone in a project to sign in through the IdP; password and social logins are routed to the SSO entry instead.
• Invite-first provisioning by default: a user must hold a pending invite to join through SSO, with optional auto-provisioning (just-in-time account creation) when you’d rather let the IdP vouch for new members. An existing account is never silently linked into a project it isn’t already a member of.
• Branded sign-in: upload a project logo in Settings and it appears on the SSO sign-in page.
• Graceful edges: pending invites can be accepted through SSO, callback failures show friendly messages, and members aren’t locked out if the project’s SSO entitlement lapses.

​

🧩 SDK installation page

​

🛡️ Stability & error reporting

• Automatic recovery from stale assets after a deploy — a missing code chunk now triggers a clean reload instead of a broken screen.
• Browser auto-translation no longer crashes the app, and unexpected errors are now reported to PostHog so they surface earlier.

​

🐛 Fixes

• Bulk selection in the users / companies tables tracks the right rows — after deleting a couple of entries the selection no longer jumps to unrelated rows (it’s now keyed by entity ID rather than row position).
• Double-escaped text in translated strings is fixed — apostrophes and quotes no longer render as HTML entities.
• Builder polish: the exit-button icon points outward, and the bubble notch matches the bubble’s background color.
• Dark mode and additional languages are still being completed — this release defaults the workspace to light / English until that coverage lands.

​

🏗️ A rebuilt content builder

​

🌙 Dark mode

​

🎨 Design-system polish

​

🐛 Fixes

• Launcher tooltips now render inside an iframe like flows and checklists, so the host page’s CSS can no longer corrupt their styling.
• Embedding a YouTube URL works in resource centers, banners, checklists, and launchers — they now resolve oembed instead of trying to iframe the raw watch URL.
• Modal placements apply both offsets on edge-centered positions, and icon-launcher theme opacity takes effect in the SDK.
• A step’s “Same as flow” theme persists instead of silently reverting to a specific theme.
• The element-picker button now shows a real tooltip so its purpose is clear.

​

What’s Changed

​

🔄 Live, consistent data across the workspace

​

✨ Content detail and theme builder stop flashing

​

📜 Unified, sturdier list pagination

​

🚧 Explicit not-found pages

​

🐛 Fixes

• Mutations that reuse a cached record no longer fail. Outgoing variables now strip the cache’s __typename tag, which the server’s input types had been rejecting.
• The segment-filter “Save” button hides correctly after saving, and no-op edits stop re-running queries. Condition comparison now matches the server’s JSON-equivalent form instead of in-memory key differences.

​

🛠️ Under the hood

• Apollo InMemoryCache switched to normalized mode with per-mutation update(cache) callbacks. The app-wide default is no-cache, with an explicit SHARED_CACHE_QUERY_OPTIONS (cache-and-network) opt-in for shared lists and facade hooks. Recorded as ADR 0005 / 0006.
• The server-state-in-Context anti-pattern is retired: ~20 Context providers deleted in favour of focused hooks, AppContext is now a thin facade over identity hooks, and the remaining raw useQuery / useMutation calls are wrapped in @usertour/hooks.
• List pagination unified into three documented primitives — useCursorPagination (page buttons), useLoadMoreAccumulator (load-more), and a shared useCursorFetchMore request-side helper — with cache-level merge owned by typePolicy accumulators.
• Users and companies UI deduplicated into shared components/segments/entity/* components.
• apollo3-cache-persist dropped (in-memory cache only); the analytics session table’s row-shared queries hoisted from per-row to per-table (~80 → 3 observers); a lighter useShouldShowMadeWith reader replaces a three-query useSubscription on theme previews.

• Viewer-role members get a clean read-only list. Row checkboxes and bulk-action buttons (add to manual segment, remove, delete) no longer appear on the users / companies tables for viewer-role accounts — no more grey buttons or fake affordances they can’t act on.
• Segment dialogs settle down. The rename dialog no longer refetches the segment list on Cancel / Escape (used to flash the table); selecting a row on a MANUAL segment on the companies page no longer hits the error boundary; double-submit and view-only guards aligned across the user / company filter-save dialogs.
• Soft-deleted content surfaces correctly. The content detail page renders a “404 / This content has been deleted” placeholder instead of going blank for deleted flows / checklists / etc. Sessions tied to deleted content now carry a “Deleted” badge on the user-detail Sessions tab and the session-detail page so historical analytics stay legible.
• @usertour/ui consolidation (ADR 0004). The 38 per-component packages under packages/components/<atom>/ (button, dialog, popover, …) collapse into a single @usertour/ui aligned with shadcn’s single-directory convention. @usertour/frame is kept standalone so the embedded SDK / widget bundles stay unaffected — SDK usertour.js is byte-identical to the v0.8.2 build. See docs/adr/0004 for the full migration story.

• Non-English users no longer see hardcoded English literals from shared UI primitives — date-range picker presets, locale selector placeholders, and content-loading spinner messages now flow through i18n.
• Two DateRangePicker instances on the content analytics page (header + tooltip-target-missing dialog) no longer share a duplicate DOM id=“date” — axe / lighthouse no longer flag the a11y violation.
• SegmentEditDialog’s Save with a missing segment id now surfaces an error toast instead of silently dead-buttoning.
• Bulk delete / remove toasts no longer render “0 users deleted” on a successful action when the server’s count field comes back nullable — falls back to the confirmed selection count.
• useSaveCompanySegmentFilter no longer misattributes a post-save refetch failure as “save failed”.
• ENCRYPTION_KEY is wired through config and the in-service ‘development-key-not-secure’ fallback is removed — operators must set the env var explicitly (production deployments unaffected).

• Settings refactor wraps up. Shared primitives (NewItemButton, DestructiveConfirmDialog managed mode, useSettingsForm), consistent “New X” copy across create dialogs, and faster /settings/events (no per-row listAttributeOnEvents fetch on mount).
• Component-style conventions. Two new rules under docs/conventions/react-components.md — Radix-style named *Props + body destructure, and const over function for component declarations — applied across @usertour/ui, theme builder, and settings.
• Attribute & event picker overhaul. + New attribute defaults Object type to the active tab; the event dialogs’ attribute picker now scrolls inside the dialog, searches by display name (not UUID), and hides already-selected items.

• Profile name save no longer wipes the user’s avatar.
• Attribute delete handles the AttributeOnEvent foreign key instead of throwing a Prisma error.
• Salesforce-sandbox now writes to its own integration row (was silently aliasing production).
• Toggling an integration’s “Stream events” switch off no longer commits unsaved API key edits.
• Destructive dialogs stay locked while their mutation is in flight; 2FA Setup / Regenerate dialogs reset on Cancel; session delete / end dialogs no longer hang on soft-failure.
• Segment edit dialogs and theme variation rename no longer clobber the user’s typing on Apollo cache updates.
• PostHog “Personal API key” and HubSpot “Private App access token” labels restored (had regressed to generic “API Key”).

​

What’s Changed

​

🛡️ Settings nav and routes match real permissions

​

💬 Error toasts show the server’s actual reason

​

✅ Save dialogs confirm success and retain input on failure

​

🐛 Fixes

• Viewing a soft-deleted content no longer 500s. getContent returned a generic 500 when the underlying row was soft-deleted; it now returns a typed not-found response the UI can render.
• Viewing a soft-deleted session no longer 500s. Same shape for querySessionDetail.
• Duplicate event / attribute names return a typed error. Creating a row with a duplicate codeName previously leaked Prisma’s P2002 as a generic 500; it now returns E0048 (ResourceAlreadyExistsError).
• Deleting a localization with localized version data no longer 500s. The delete now cascades VersionOnLocalization rows in one transaction.
• Step / version-localization mutations stop bouncing on soft-deleted content. contentVersionIsEditable null-guards before reading editedVersionId.

​

🛠️ Under the hood

• A single ROLE_CAPABILITIES matrix in @usertour/constants is the source of truth for “what each role can do”. The previous pattern of 93 @Roles([VIEWER, ADMIN, OWNER]) decorators scattered across resolvers is replaced by @RequirePermission(Capability.X) plus one PermissionGuard that reads the matrix. Adding a new role is now one matrix row, not 93 decorator edits.
• 11 per-module guards (content / environments / biz / integration / localizations / attributes / themes / events / analytics / team / projects) collapse into one PermissionGuard with a scope-resolver registry. Each resolver registers how to derive projectId from its args (e.g. contentId → content.projectId), so the guard’s “is this user a member of the resource’s owning project” check is one code path.
• UserOnProject.capabilities: [String] is now part of the GraphQL schema. The web app’s useAppContext().can(capability) reads from this array instead of re-deriving from the role string, so frontend and backend gates can’t drift.
• A 93-endpoint × 5-role authorization test matrix lives in test/e2e/endpoints.ts and drives two surfaces: permission.e2e-spec.ts (jest, 312 deny-direction assertions + cross-project IDOR coverage) and test/smoke/spot-check.sh (env-driven bash tool, 558-row diagnostic against a seeded fixture). Adding a new role-gated endpoint is one row in the table; both surfaces pick it up.
• Test factories adopt the outline-style “recursive override” shape — buildX(prisma, overrides?) auto-builds missing parent FKs, so a new spec can do await buildStep(prisma) and get a fully-wired project → environment → content → version → step chain in one line.

• 📋 Banner button “Start a flow / checklist” was empty — it now lists your content.
• 📊 Analytics charts went stale after deleting or ending a session — they now refresh along with the table.
• ⏳ Detail pages no longer flash “not found” before the record loads; a session still loading its events shows a spinner instead.
• 💬 Cleaned up the delete-session dialog wording.

​

Highlights

• Reworked auth flows — invite rebuilt, reset-password folded into the login page, reset codes hardened, and the whole signup/login/invite path tightened.
• Self-serve project selection — a user with no active project now lands on a dedicated page to create or pick one, instead of a silent “Unnamed Project” bootstrap or a blank admin shell.

​

Security

• Login no longer runs invite/side effects before the password is verified, and invites are bound to the recipient’s email.
• Refresh tokens are single-use and deleted on rotation/logout (no more unbounded revoked rows); a daily job sweeps expired rows.
• Logout ends only the current session; “log out everywhere” stays reserved for password change / 2FA enrollment.
• Reset-by-code consumption + password update are atomic; OAuth email is lowercased at the boundary; invite races and seat-count edges tightened.

​

Fixes

• Logout / account-switch hard-loads a clean login page — no ?next flash and no leaking of the page you just left.
• Cross-tab auth sync: login/logout/register in one tab reloads the others onto the shared session; stale-tab drift on email-link flows self-recovers.
• Auth pages gate on globalConfig (no OAuth-button flash) and read it from a single source (no duplicate queries / double loading).
• Invite email now renders the project name correctly.

​

Performance

• Project initialization batched into far fewer queries.

​

What’s Changed

​

🌐 Localization on auth pages

​

🔗 Deep-link return after sign-in

​

🧭 Environment-aware landing

​

🪟 404 stays inside the admin shell

​

🎨 Sign-in visual refresh

​

🐛 Fixes

• Admin nav highlight restored. Users / Companies / Settings were no longer highlighted in the sidebar after navigating into them. Fixed by switching active-state detection from the (now wrong) inner-route id to URL pattern matching.
• OAuth failure lands on the sign-in page, not the API. Split-origin deploys (API and SPA on different hosts) used to dump OAuth-failure traffic onto a non-existent /auth/signin route on the API host. The redirect now prefixes the SPA host correctly.

​

🛠️ Under the hood

• The hand-rolled CustomRoute if-chain in routes/index.tsx is replaced by <AuthGuard mode='guest' | 'user' | 'setup'>, a single three-mode state machine that owns every auth-related redirect (setup-admin enforcement, sign-in bounce with ?next=, 2FA enrolment). routes/config.ts becomes a nested RouteObject tree with React.lazy per-page chunks; page-area providers (Environment / Attribute / Subscription) mount once at the user-area parent and stop remounting on every navigation.
• Seven hand-rolled <Card> + <CardHeader> blocks across the auth pages collapse into one <AuthCard> shell that owns the title chrome, description, footer slot, and loading skeleton. The three legacy React contexts that shadowed react-hook-form’s <Form> (SignInContext / RegistrationContext / InviteContext) are dropped — the same data flows through useFormContext() and props.
• The Auth.redirectUrl field on the GraphQL schema and the LOGIN_REDIRECT_URL env var that fed it are gone. The SPA now owns the post-login destination decision: ?next= (validated as same-origin) wins, otherwise LandingRedirect resolves the env. OAuth callbacks redirect to the SPA root through the same handler.
• packages/hooks/src/hooks/gql.ts had grown to 1306 lines; the auth domain (13 hooks + 3 new mutation wrappers) splits out to a new hooks/auth.ts module. The why, and the triggers that should pull more domains out in the future, are documented in docs/adr/0002-hook-domain-boundary.md. The package also gets a README with the decision tree for adding new hooks.

• “No conditions yet” empty state. When the auto-start toggle is on but no conditions are set, ContentDetailAutoStartRules now surfaces an inline “rule won’t activate until you add at least one condition” card. The runtime is never sent an enabled=true rule with an empty autoStartRules — coerceEnabledForPersist writes enabled=false on the wire even while the local toggle visually stays on, so the user can see what they’re configuring without producing an un-actionable server state.
• Sibling settings hide while incomplete. Wait / Frequency / “Only start if not complete” / Priority now render only when the rule is on AND has at least one condition. Off-state hides them along with the conditions list; empty-state hides them because their writes would never reach the wire anyway (and fully-controlled Priority would visibly snap back on click).
• No-op saves removed. Flipping the auto-start switch when the coerced enabled value already matches the server no longer queues a save. Previously, turning the toggle on or off with no conditions wrote (false, []) even though the server was already in that state — and on a published version, that no-op write silently forked a new draft.
• “Only start if not complete” responds instantly on Frequency change. Switching Frequency between Once / Multiple / Unlimited used to leave the IfCompleted control hidden for ~1s because its visibility gate read from the setting prop, which goes through the debounced save / mutation / refetch round-trip. A localSetting mirror in autostart-rules now reflects user edits synchronously; a lastObservedSettingRef with deep-equal compare ignores reference-only prop flips emitted during the save cycle (where setIsSaving(true) triggers a parent re-render carrying the still-stale version.config).
• No flicker on Frequency switch. Switching options no longer triggers a redundant setData re-render in ConditionFrequency that briefly flashed the picker’s children. The prop-sync useEffect uses value-equality bailout (isEqual(prev, next)) so the user’s own edit echoing back through defaultValue doesn’t cycle the children.

• Trigger conditions share the auto-start empty-state UX. Auto-start rules and tracker rules now behave identically when their conditions list is empty: both show “No conditions yet” with the same hint. The showEmptyState gate moved from showEnabledSwitch && enabled && … to effectiveEnabled && …, so switchless consumers (tracker passes showEnabledSwitch={false}) automatically participate.
• Same “don’t autosave empty” policy. Tracker’s handleAutoStartRulesDataChange now calls debouncedUpdateVersion.cancel() when conditions go empty, mirroring content-detail-settings.tsx. Without this, a rapid delete sequence in the tracker editor had the same lost-deletion race as the auto-start card.

• Flow publish requires at least one step. useContentPublishState now keeps the Publish button disabled when content.type === FLOW and version.steps is empty — an empty flow has nothing for the runtime to render. Mirrors the existing tracker-needs-event-and-conditions check.

• Rapid condition deletion no longer resurrects deleted conditions. A “delete A → delete B → delete C” burst previously left the debounce queue holding the second-to-last value (e.g. [C]), which fired ~500ms after the user emptied the list and re-synced the server back to that stale state on refetch. Both content-detail-settings.tsx and content-detail-tracker-editor.tsx now call debouncedUpdateVersion.cancel() when conditions become empty.
• Version history shows the new draft after publish-then-edit. Editing a just-published content silently forks a new draft version (because ensureEditableVersionId refuses to update a published version in place), but the Apollo listContentVersions cache wasn’t auto-refreshed — so the Version tab kept showing the pre-fork list until reload. processVersion / saveVersionData / saveVersionTheme / saveVersionScheduledAt now detect fork via editableVersionId !== version.id and add refetchVersionList to the post-mutation Promise.all.
• Frequency / Wait pickers sync on content or version switch. ConditionFrequency and ConditionWait previously only read defaultValue for the initial useState value; subsequent prop changes were ignored, so navigating between contents left both pickers stuck on the prior content’s values until the user re-interacted. Both now sync internal state via a prop-sync useEffect on defaultValue change.

• New TOTP-based 2FA flow using authenticator apps (Google Authenticator, Authy, 1Password, etc.). Secrets are stored AES-256-GCM encrypted; each user gets 10 one-time recovery codes (bcrypt-hashed) at setup, shown once with a Download / Copy / “I have saved” confirmation gate.
• Sign-in adds an /auth/2fa step when 2FA is on. The page accepts both an authenticator code and — via “Use a recovery code instead” — a one-time recovery code. The same flow applies to email/password and the Google/GitHub OAuth callbacks.
• Step-up auth on sensitive operations: disabling 2FA and regenerating recovery codes both require a fresh authenticator (or recovery) code. Recovery code consumption is an atomic CAS so a stolen list cannot be replayed concurrently.
• Settings → Account exposes the full lifecycle: enable, regenerate, disable, plus a recovery-codes sub-row that reflects current state.

• New Require 2FA for all users toggle on System Admin → Authentication. When on, non-enrolled users are redirected to a forced /auth/2fa/setup page on their next request and cannot bypass it via API clients.
• Server-side enforcement runs in two layers: turning the policy on revokes refresh tokens of every non-enrolled user, and a TwoFactorEnrollmentGuard rejects non-bootstrap GraphQL operations from non-enrolled users while the policy is active.
• The toggle is gated by the instance license. If the license stops covering 2FA, the policy goes dormant (not silently off): existing enrolled users keep verifying, new non-enrolled users stop being forced. Admins cannot turn the policy on until they have enabled 2FA on their own account, to avoid self-lockout.
• SaaS deployments don’t surface the instance-wide toggle — per-user 2FA only.

• Email/password login now locks out a given email after 10 failed attempts in a rolling 10-minute window, backed by a Redis Lua-script INCR

• EXPIRE helper. Lockout is per-email, not per-IP, and clears automatically on success.

• All 60 packages previously under @usertour-packages/* move to @usertour/: every packages/components/ and packages/radix/* leaf, plus business-components / builder / contexts / editor / finder / gql / hooks / i18n / icons / dom / tailwind / widget / ui. Apps and the four pre-unified packages (types, helpers, constants, license) keep their existing names.
• Roughly 791 import sites, every workspace package.json’s name and dependencies entries, the root build:deps script, the four dev* filter lists, turbo.json’s dev.dependsOn, and the SDK Vite bundler’s manual-chunk regex all switch over in one mechanical pass.
• docs/architecture/packages.md updates: the Namespace section now reads “every workspace package lives under @usertour/*”, and the P1 → P2 migration checklist drops the namespace-rewrite step that’s no longer needed. The types-vs-constants boundary still applies.

• @usertour/sdk bumps to 0.7.0 to signal the namespace rename, since every transitive @usertour-packages/* import path that SDK consumers reached through has shifted.

• New PlanFeatures type in @usertour/types and a shared PLAN_FEATURES matrix in @usertour-packages/constants/billing that covers every per-tier value the product gates on today: removeBranding, sessionsLimit, teamMemberLimit, environmentLimit, dataRetentionYears, apiRateLimit, plus placeholders for upcoming auditLogs / ssoSaml / ssoOidc gates.
• resolvePlanFeatures(planType, overridePlan), parseOverridePlan, and isWithinLimit helpers live in @usertour/helpers and run on both server and web — the same merged feature set drives runtime enforcement and UI rendering.
• Subscription.overridePlan (the JSONB column that was wired up but unread) is now the canonical layer for per-customer grants. Override fields replace base fields via spread, so a CS-granted seat bump or a legacy benefit ({“removeBranding”: true} for grandfathered Starter projects) lands in resolution without any code change.
• @usertour-packages/constants was promoted from P1 (source-direct) to P2 (pre-built dist) since the NestJS server now requires it at runtime. The P1 → P2 migration steps are codified in docs/architecture/packages.md.
• PlanType enum gains ENTERPRISE so the self-hosted license path stops using bare strings; the two existing Record<PlanType, …> maps on the web pick up the new key.

• ProjectsService gains resolveProjectFeatures, checkEnvironmentLimit, and checkTeamMemberLimit. The cloud / self-hosted bypass, subscription lookup, override merge, count query, and error throw all live in one place and accept a Prisma TransactionClient.
• EnvironmentsService.create was previously gated only by the client — useEnvironmentLimit disabled the form button but any consumer that bypassed the form (stale UI, direct mutation call) could create past the cap. The mutation now delegates to projectsService.checkEnvironmentLimit inside its own transaction. New EnvironmentLimitError (E0030) with en/zh messages.
• TeamService.inviteTeamMember’s hand-rolled hobby/starter/growth if-chain is gone; the gate now goes through projectsService.checkTeamMemberLimit, which honours overridePlan the same way the client does. The roughly 230-line dup between projects.service and web-socket.service for cloud / self-hosted config resolution also collapses — web-socket.service.getConfig delegates to projects.

• The same email used to accumulate multiple Invite pending rows on the team settings page because there was no dedup before prisma.invite.create. Each row counted against the seat quota, letting a project artificially fill its allotment by inviting one address twice. Two new errors register pre-create: TeamMemberAlreadyInvitedError (E0031) and TeamMemberAlreadyInProjectError (E0032).
• When the SMTP layer rejected the recipient (e.g. 550 / EENVELOPE for a bad mailbox), the freshly created invite row stayed in the DB while the client got a generic 500 and the new dedup check blocked the user from retrying. The mutation now wraps sendInviteEmail in a try / catch — failure soft-deletes the invite (matching the cancel / accept lifecycle) and surfaces InvitationDeliveryFailedError (E0033).

• Comparison table aligns with usertour.io: Support & service section becomes Community / Email / Priority with priority gated to Business only, the ghost Concierge support row is gone, and the Growth card’s redundant Live chat support line drops back to Email support.
• Every drift-prone row (Sessions / Data Retention / Environments / API rate / Team members / No-branding) is now matrix-driven via a typed matrixRow helper instead of a hardcoded values: [false, true, true, true] literal.
• Per-customer override surfaces only on the user’s current plan card and current plan column. Other cards stay base so a CS-granted sessions bump on Growth doesn’t make the Starter or Business columns claim the same number. The comparison table stays apples-to-apples for upgrade decisions while honouring the user’s actual entitlement on their own row.
• Pricing page icons switch from lucide-react + a custom BoxIcon to the project’s standard remix icons (@usertour-packages/icons).
• Unlimited sessions render as 123 / Unlimited instead of 123 / Infinity; the percent / threshold caption hides when the cap is unbounded.

• SubscriptionContext now exposes effective features: PlanFeatures so consumers stop re-resolving themselves.
• apps/web/src/hooks/use-plan-limits.ts adds useEnvironmentLimit, useTeamMemberLimit, and useSessionsLimit. Each hook composes the subscription features, the relevant resource list, and the self-hosted bypass into a single { limit, current, canUseMore } shape. Consumers like EnvironmentCreateForm and MemberInviteDialog shrink to one line and now honour override on the client side too — the server check the hook mirrors used to be the only place that saw the override.

• docs/architecture/packages.md gets a @usertour/types vs @usertour-packages/constants split (contracts vs values, with the “delete-the-line, what breaks?” heuristic), a P1 / P2 package-shape section with the 6-step migration checklist that this branch’s constants promotion follows, and a note that runtime values should share as soon as a second real consumer exists — including code that copies the same business contract values without importing them.

• Replaced the legacy ContentActions component with a schema-driven registry parallel to Conditions: each action type (Step goto / Flow dismiss / Flow start / Page navigate / JavaScript evaluate / Launcher / Banner / Checklist dismiss) is now a self-contained schema with its own Summary, Editor, validate and normalize.
• Save-time validation gates on every consumer with an explicit Save click — flow trigger, checklist item, launcher behavior, resource-center block, step builder — so incomplete chips can’t slip through.
• Outer red indicator on button / question elements now reflects the actual chip state inside, keeping the visible error consistent with what reaches storage.
• Restored the v1 mutex semantic: Dismiss flow + Start new flow can coexist again (encoded as two pairwise sets against Step goto instead of one transitive 3-set).
• Launcher behavior’s debounced auto-save now gates on the same validateActions check so partial chips never reach the DB, with the validator hoisted to LauncherBuilder so subpage switches (Target / Tooltip modes) don’t bypass it. The gate also respects actionType so a stale action list under SHOW_TOOLTIP no longer blocks tooltip saves.
• Dismiss-chip remove button rebuilt as a plain <button> matching the other chip variants (the <Button size=“compact-icon-sm”> previously pinned height to 24px and didn’t snap to the chip edge).

• Flattened packages/shared/* into packages/* and dropped the shared- prefix where it had stopped carrying meaning: shared-editor → editor, shared-hooks → hooks, shared-components → business-components; builder, contexts, finder, gql, i18n, assets move up to top level.
• Promoted generic UI primitives (SelectPopover, ColorPicker, DateTimePicker, LoadingContainer, LocateSelect, ScaledPreviewContainer, ErrorTooltip) from shared-components into @usertour-packages/ui. ColorPicker took a userId prop so it no longer drags useCurrentUserId() and the Apollo hook tree into L1 UI.
• Added a layering RFC at docs/architecture/packages.md that defines L0–L5, the dependency rules, the decision tree for new packages, and the known drift it accepts.

• Every predefined event (PAGE_VIEWED, FLOW_STARTED, FLOW_ENDED, FLOW_STEP_, LAUNCHER_, BANNER_, RESOURCE_CENTER_, CHECKLIST_*, QUESTION_ANSWERED, TOOLTIP_TARGET_MISSING) now ships with a one-line description written in agent-agnostic passive voice — meaning it stays accurate whether the event is fired by the SDK, by user code via usertour.track(), or by the server-side API. Events settings page surfaces them directly under each event name.
• Switched the project-init event seed from a one-shot createMany to a per-event upsert, mirroring the existing attribute init, so re-running init backfills displayName + description on existing predefined rows.
• Events list query gained a secondary id order key so the predefined block stops reshuffling on every page refresh (a quirk left over from the original createMany clustering every row at the same createdAt).

• Tailwind content globs in apps/web and apps/sdk collapsed to packages//src/ so package relocations don’t silently drop styles again.
• Actions chip’s isEqual now routes through @usertour/helpers’ existing re-export instead of pulling fast-deep-equal as an undeclared transitive.
• SDK bumped to 0.6.9.

• Rebuilt the theme builder as a three-column shell with variations on the left, schema-driven settings in the right inspector, and a live macOS-chrome preview in the middle.
• Added variations support with drag-to-reorder, inline rename, conditions, and Base pinning.
• Replaced the legacy v1 inspector with schema-driven field components (typed FieldDef schema, cascade rules, coverage-tested round-trip).
• Restored per-setting tooltips on every inspector field with full i18n in en-US and zh-Hans.
• Added preview-frame chrome (browser bar + widget switcher) so widgets keep their intended layout context.
• Added unsaved-changes warning on close and pre-publish readonly + validation guards.
• Theme detail now lives inside the shared sidebar shell, matching the rest of the admin’s detail-page architecture.
• New variations seed from the current Base settings rather than factory defaults.
• Polished active color swatch labels, font-color positioning, Auto fallback rendering, primary brand color seeding, banner alignment in chrome, and many smaller details.

• Replaced v1 Rules with a schema-driven Conditions system covering every condition type (user-attr, current-page, event, event-attribute, segment, content, element, text-input, text-fill, time, task-clicked, group).
• Migrated every Rules consumer in the admin and shared editor to the new component; deleted v1 Rules from shared-components.
• Added a Where-clause UI for event filters with errors that bubble up to the outer event chip and a [Where] badge that distinguishes it from [If].
• Added standalone exports for Frequency, IfCompleted, Wait, and Priority that reuse the same primitives.
• Validation now spans snapshot, property-based, and production-fixture tests.

• Date attributes now render in the chip as MMM d, yyyy, matching the picker trigger.
• Split absolute-date operator labels into separate dropdown vs chip forms so “Signed up on May 13, 2026” reads naturally.
• Inline the two range inputs for between on a single row.
• Keep “Add value” alive when list-attribute popovers reopen, and hide stale list values on valueless operators (is empty / has any value).
• Commit invalid edits on popover close so the save gate catches them; block save when checklist / resource center conditions are incomplete.
• Honor the consumer’s filterItems array order in the add-condition dropdown.
• The DateTimePicker calendar now sits above its parent popover (no more z-index clipping in builder chrome) and matches the conditions-popover trigger hover language.
• Say “Add filter” instead of “Add condition” when the same component is used to filter a list (segments, user/company tables).

• Replaced the instant data-state styling on Tabs with a shared motion.span that slides between triggers via framer-motion’s layoutId. Pill and underline variants both ride the same mechanism.
• Added a variant=“primary” cva variant for tinted active pills (replaces six call sites that hand-rolled data-[state=active]:bg-primary overrides).
• The content detail header’s underline now slides between Analytics / Content / Versions on route change.

• useContentBuilder and the rename / open-editor form now decide whether to fork using contentOnEnvironments (per-env source of truth) instead of the deprecated Content.publishedVersionId field. Resolves a class of bugs where a publish in one environment could send authors straight into a still-live version in another.
• Session status badges flip to terminal-first priority (Dismissed > Completed > Active) so a session that was completed and then dismissed reads as Dismissed, matching the underlying event log.
• “Finished in X” wording in session lists aligned to “Completed in X” to match the canonical FLOW_COMPLETED event name.
• Removed the “Published X ago” badge from the content detail header — per-env publish times don’t reduce to one number, and version history surfaces the detail when needed.

• Dropped the CreatedAt column from Attributes / Events / Environments settings tables. API keys keep it because creation time is a real security / rotation signal.
• Unified the eight “New X” buttons across settings and content lists onto a single RiAddLine + mr-2 h-4 w-4 pattern. Fixed New Events → New Event along the way.
• Segment headers now use horizontal dots (matching page-level overflow conventions elsewhere).

• Fixed analytics: NPS / Scale response-rate denominator now aligns with the rolling-window aggregate.
• Fixed resource center: active session resumes on refresh regardless of current page; attrCodes preloaded from action-block clickedActions.
• Fixed content loading spinner to center reliably inside detail pages’ min-h-full containers via a min-h-[60vh] floor.
• Extracted CompactPopoverTrigger to consolidate three identical inline trigger className chains (ConditionCombobox, ConditionSelect, DateTimePicker).
• Several i18n polishes across theme-builder option labels (“Dismiss the flow”, “Show a speech bubble instead”), DateTime operator phrasing, dead placement keys, etc.
• Build / typecheck: exported forwardRef prop interfaces so tsup —dts can emit valid declarations; aligned border.borderRadius type to number.

​

🧭 Resource Center

• Updated Resource Center to follow one-session-per-user behavior, matching Banner behavior.
• Prevented dismissed or completed Resource Centers from being reactivated for the same user.
• Added a Resource Center guide link to the Resource Centers list header.

​

📊 Analytics & Session Management

• Added support for ending Banner and Resource Center sessions from the analytics/session management flow.
• Added admin-ended tracking for server-side ended sessions.
• Added end-reason attributes for Banner and Resource Center dismissed events.
• Reused dismissed-event session ending logic across Checklist, Launcher, Banner, and Resource Center.

​

⚙️ SDK & Types

• Added ADMIN_ENDED as a content end reason.
• Added banner_end_reason and resource_center_end_reason event attributes.
• Bumped @usertour/sdk from 0.6.4 to 0.6.6.

​

🧭 Resource Center

• Added Resource Center as a new content type with full builder, preview, SDK, widget, and server support.
• Added tab-based Resource Center navigation with configurable tabs, icons, ordering, and filtered visibility.
• Added Resource Center blocks for rich text, action links, dividers, content lists, sub-pages, and live chat.
• Added search, detail views, and grouped display for Resource Center content lists.
• Added Resource Center launcher behavior, visibility controls, open/close lifecycle handling, and persisted navigation state.
• Added conditional block visibility and attribute preloading for more personalized Resource Center experiences.
• Added Resource Center theme settings for launcher styling, panel sizing, header background, logo upload, and layout controls.

​

💬 Live Chat & Actions

• Added live chat block support for multiple providers and custom JavaScript providers.
• Added SDK live chat management for loading, showing, hiding, and cleaning up provider widgets.
• Improved live chat behavior when Resource Center blocks are opened, closed, or destroyed.
• Added collapse-to-launcher behavior after Resource Center action and content-list item clicks.

​

📊 Analytics

• Added Resource Center analytics for views and clicks grouped by tab and block.
• Added Resource Center event attributes for tab ID and tab name.
• Added analytics support for announcement-style Resource Center content.
• Improved analytics charts, granularity controls, session columns, and status display.
• Improved analytics labels, tooltips, ranking indicators, and CSV export handling.
• Fixed Resource Center analytics ordering and array payload handling.

​

👥 Users, Companies & Sessions

• Redesigned user, company, and session detail pages with clearer layout and navigation.
• Added richer activity feeds with event categorization, icons, translations, and count labels.
• Improved session lists with clickable rows, status columns, and clearer session detail views.
• Improved company/member attribute display and membership layouts.
• Added externalId columns for user and company tables.
• Added collapsible search and improved filter toolbar behavior for user and company tables.
• Improved column customization with drag-and-drop, search, visibility management, and divider rows.

​

🎨 UI & Builder Improvements

• Added a shared icon picker with upload, URL, and built-in icon options.
• Replaced initials avatars with a curated default avatar icon set.
• Improved Resource Center builder layout, block settings, validation, loading states, and error tooltips.
• Added Resource Center preview support in theme settings.
• Improved admin layouts, subpage layouts, warning display, and navigation clarity.
• Rewrote tooltips and labels across auto-start, hide rules, attributes, events, announcements, and Resource Center settings.

​

⚙️ SDK, Server & Infrastructure

• Added SDK Resource Center APIs and global launcher visibility handling.
• Added Resource Center socket handling, reconnect restoration, session activation, and RESOURCE_CENTER_STARTED support.
• Improved server-side content orchestration, session building, condition evaluation, socket emitting, and event tracking.
• Added PostgreSQL backup script support and Dockerfile updates for backup tooling.
• Added Redis TLS support through environment configuration.
• Updated default initialization for missing attributes and clearer predefined attribute descriptions.

​

📡 Event Trackers

• Added Event Trackers for capturing and managing event-based tracking flows.
• Added event creation and tracker-related content management capabilities.
• Added event-based rule building with new event condition and filtering components.
• Expanded event tracking with richer client and business context.
• Improved websocket event tracking handling, validation, and response behavior.

​

🛠️ Self-Hosted Admin Panel

• Added a new Admin Panel for self-hosted deployments.
• Added a setup flow for system administrators.
• Added user and project management capabilities for self-hosted teams.
• Added instance settings management for general and authentication configuration.
• Added project-level subscription management controls.

​

🔐 Licensing & Instance Management

• Added license key upload, validation, and instance-level license management.
• Improved license limit handling and related error messages.
• Updated licensing-related validation behavior across instance and project flows.

​

📊 Analytics & Export

• Added CSV export support for analytics-related data.
• Improved analytics queries and filtering capabilities.
• Improved export handling for checklist, session reason, and flow question data.
• Added and expanded test coverage for export payload generation.

​

✨ UX & Platform Improvements

• Improved admin navigation, layouts, and search experience.
• Improved project member management and owner selection flows.
• Improved redirect URL handling through configuration.
• Updated terminology from company to project across multiple areas.
• Improved rule builder behavior, state handling, and styling.
• Fixed date-fns-tz type issues.
• Upgraded server dependencies to address related advisories.

​

🧩 Banner Content Type (Core)

• Added full Banner content type support across editor, preview, and runtime flows.
• Implemented banner embed placement controls with more consistent rendering behavior.
• Improved banner layout structure for better alignment, readability, and responsive presentation.
• Added configurable banner wrapper behavior, including theme padding and max-width handling.
• Standardized z-index behavior for banner-related components to reduce overlap issues.

​

🎛️ Content Configuration & Interaction

• Added button visibility and disabled-state conditions for more flexible interaction logic.
• Added banner dismiss action handling for better user-controlled behavior.
• Improved content detail settings and priority logic for content-type-specific behavior.
• Refined descriptions and guidance text in content settings to improve usability.

​

🔗 URL Targeting & Link Handling

• Added module-level URL filtering and improved URL change detection.
• Added link editing capabilities and URL decorator support for richer link control.
• Improved targeting consistency for condition matching and runtime content delivery.

​

📊 Analytics & Session Reliability

• Extended analytics data model and queries with content field support.
• Improved session creation flow with findOrCreateBizSession plus distributed locking.
• Reduced duplicate session creation risk in concurrent scenarios.

​

🖥️ Preview & UI Refinements

• Improved browser preview layout and visual structure.
• Enhanced badge placement and preview presentation for banner content.
• Cleaned up unused preview components and improved overall UI consistency.
• Updated default embed width behavior for better visual balance.

​

🧹 Refactors & Cleanup

• Consolidated parts of content create/detail flows for better maintainability.
• Removed legacy NPS/Survey references from content-related modules.
• Performed structural refactors in banner/theme settings for clearer logic and easier extension.

​

📦 v0.4.9

​

🧭 Popper Stability Improvements

• Improved reference element handling to prevent Popper flash during initialization and repositioning.
• Reduced visual flicker when tooltips or modals mount under dynamic layout changes.
• Enhanced positioning reliability in async rendering scenarios.

​

🎛 SDK Component Fixes

• Fixed incorrect button padding calculations in SDK components.
• Updated padding logic to derive height from font-size, ensuring correct button height when used with utilities like leading-none.
• Improved sizing consistency across different Tailwind setups.

​

🎨 Tailwind Integration Fixes

• Corrected SDK font-weight variable mappings in Tailwind configuration.
• Aligned font-weight variable names with Tailwind conventions.
• Improved typography customization reliability when overriding theme tokens.

​

🚀 v0.4.8 — Editor makeover, launcher icons & bug fixes

​

✨ What’s New

• Revamped editor toolbar with a sleek TipTap style
• Editor got a facelift: new color picker, smoother drag & drop, and more flexible layouts for easier editing
• Columns in the editor now support padding adjustments
• Usertour.js now has a handy disableEvalJs method
• Website UI is more responsive across devices
• Flow components now support Speech Bubbles
• Launcher icons can now be uploaded and we added more built-in options

​

🐛 Fixes

• Checklist preview now shows the header properly
• Star Rating no longer overflows when there are lots of stars
• Editor won’t reset button text when you select an action
• NPS can now set user properties even when selecting 0

​

🚀 v0.4.7 — UI polish, segment & checklist fixes, UX improvements

​

🧠 Segment & Filtering

• Set default column when initializing or creating a segment.
• Fixed a bug where column filters stopped working after selecting a filter in segments.

​

🎨 UI / UX Improvements

• Improved focus effect for Launcher checklist.
• Fixed preview flash issue by scaling preview components from 0 → 1.
• Optimized progress bar styles.
• Fixed theme list preview overflow issues.
• Fixed default theme button height calculation errors.
• System theme now properly disables buttons.
• Improved layout for theme and trigger components that were too narrow.
• Fixed SDK button height issue caused by default Tailwind line-height: 1.25rem.

​

✅ Checklist & Flow Fixes

• Fixed issue where completion animation reappeared after dismissing a checklist.
• Fixed inaccurate checklist list styles.
• Added title length limits to checklist task breakdown.
• Fixed browser history back behavior when switching between Draft and Published states.
• Improved launch rule auto-expand animation for smoother transitions.

​

🛠 Builder & Page Improvements

• Standardized page buttons to use <Button> components so they can receive focus.
• Removed globalSocketId to avoid stale or unnecessary socket identifiers.
• Session list now displays company information.

​

📊 Analytics & Data

• Improved handling of numeric stats with large arrays and overly long labels.
• Unified right alignment for step-level analytics data.