@sentientui/core 0.11.0 → 0.11.2

package/README.md

@@ -42,11 +42,15 @@ client.goal('trial_started', { plan: 'pro' });
 | Option | Type | Description |
 |--------|------|-------------|
 | `apiKey` | `string` | Public API key (`pk_…`) from the SentientUI dashboard. |
-| `context` | `'landing' \| 'ecommerce' \| 'saas' \| 'marketplace'` | Type of product. Used for segment weighting and analytics grouping. |
-| `consent` | `boolean` *(default `true`)* | When `false`, returns a no-op client (no cookies, no events). |
-| `initialAssignments` | `Record<string, string>` | SSR-preloaded assignments. Seeds the cache so `assign()` returns immediately for listed components. |
+| `context` | `'landing' \| 'ecommerce' \| 'saas' \| 'marketplace'` | Local label only — echoed in `debug` logs, never sent to the server. Analytics grouping comes from the project's context type configured in the dashboard. |
+| `consent` | `boolean` *(default `true`)* | When `false`, returns a no-op client (no cookies, no events). **The default is `true`** — for GDPR-style opt-in, pass `false` until your banner is accepted (see `preConsentBehavior`). |
+| `preConsentBehavior` | `'defaults' \| 'statistical_winner'` | What to render while `consent` is `false`: site defaults, or the read-only statistical winner via `/v1/winner` (no session, no events). |
+| `respectDoNotTrack` | `boolean` *(default `true`)* | Honors the browser DNT signal — overrides `consent: true` and blocks `grantConsent()`. |
+| `initialAssignments` | `Record<string, string>` | SSR-preloaded assignments. Seeds the cache so `assign()` returns without a network call for listed code variants. (Managed-text components still fetch once when the seed carries no content.) |
 | `sessionSegment` | `string` | Segment from SSR (`device:source`). Must match the value used in `preloadAssignments`. |
+| `ssrSessionId` | `string` | Session ID minted during SSR (from `readSessionCookie`) so server and client share one session. |
 | `userId` | `string` | Optional cross-session identity. Persists portraits across sessions for the same user. |
+| `country` | `string` | ISO 3166-1 alpha-2 country code, if you already know it server-side. |
 | `debug` | `boolean` | Logs events to the console and exposes `window.__sentient`. |
 | `localMode` | `'auto' \| boolean` | Keyless local engine. `'auto'` (default) enables it only under the `development` export condition; production builds without a key short-circuit to defaults with one `console.error`. |
 | `initialSlots` | `Record<string, string \| Record<string, string>>` | SSR-preloaded slot results (from `preloadDecisions`/`loadAdaptiveDecision`). |
@@ -72,7 +76,7 @@ Queues an event for batched ingest. Events flush every 5 s and on `visibilitycha
 
 Fires a named goal for the current session. Used for cross-component conversions (e.g. `'trial_started'`, `'purchase_completed'`) where you cannot scope the reward to a single `<Adaptive>`.
 
-- `weight` (0–1, default `1.0`) — partial reward value. Use values < 1 for funnel steps that precede the final conversion. The bandit learns from each step immediately.
+- `weight` (0–1, default `1.0`) — partial reward value. Use values < 1 for funnel steps that precede the final conversion. Step weights are summed (capped at 1.0 per session) and credited when the visit is finalized, about 30 minutes after the visitor goes inactive — not instantly.
 - `stepIndex` (default `0`) — position in the funnel for analytics grouping.
 
 > **Which goal method?** `goal()` is **session-level** — it POSTs to `/v1/goals` with no component/variant, so it appears in funnel charts but **not** the per-variant CVR breakdown. For variant experiments, prefer **`componentGoal()`** (below) or the declarative `<Adaptive goal={…}>` prop, both of which attribute the conversion to the served variant.
@@ -92,7 +96,7 @@ No-ops (with a `debug` warning) if the component has not been assigned yet — r
 
 ### `client.identify(userId)`
 
-Attaches a stable user ID to the session. Portraits and cluster assignment carry forward across future sessions for the same `userId`.
+Attaches a stable user ID to the session. On the link, the server copies the highest-reliability portrait from the user's other sessions onto this one, so portraits and cluster assignment carry forward across devices for the same `userId`.
 
 ### `client.getAssignment(componentId, segment)`
 
@@ -100,11 +104,11 @@ Synchronously returns the cached assignment, or `null` if not yet assigned. Use
 
 ### `client.getGraph()`
 
-Returns the current `GraphSnapshot` (page nodes captured by the optional graph scanner — see `@sentientui/core/graph`).
+Returns the current `GraphSnapshot` (page nodes captured by the optional graph scanner — see "Optional: graph mode" below). Permanently returns an empty snapshot on the lean client; graph mode must be enabled at `init` time.
 
 ### `client.destroy()`
 
-Flushes the event queue and clears session state. Call on page unload if you need a synchronous teardown (the SDK already handles `visibilitychange` automatically).
+Flushes the event queue and **deletes the visitor identity** — the 365-day `_snt_uid` cookie and all local storage. This is a consent-revocation/forget-me teardown, not a page-unload cleanup: calling it on every unload makes each visit a brand-new visitor and defeats "Visit 1 learns, Visit 2 converts". For unload, do nothing — the SDK already flushes on `visibilitychange`/`beforeunload` automatically.
 
 ## SSR helpers
 
@@ -192,20 +196,24 @@ physically contain none of it. Production without a key short-circuits to defaul
 
 ## Optional: graph mode
 
-`@sentientui/core/graph` is a separate, tree-shakable entry that activates the DOM scanner and graph sync (component-to-component edges + 2-hop reward propagation). Import it once, on the client, after `init()`:
+`@sentientui/core/graph` is a separate, tree-shakable entry containing the graph-capable client (DOM scanner + graph sync: component-to-component edges + 2-hop reward propagation). A bare `import('@sentientui/core/graph')` has **no effect** — the entry exports its own `init`, which you must call with `graph: true` **instead of** the lean `init`:
 
 ```ts
-import('@sentientui/core/graph');
+import { init } from '@sentientui/core/graph';
+
+const client = init({ apiKey: 'pk_…', context: 'saas', graph: true });
 ```
 
-The lean bundle stays under 8 KB gzip; graph adds roughly another 8 KB.
+A client created by the lean `init` can never activate graph mode later (`getGraph()` stays empty). The lean bundle is ~8 KB gzip (CI budget: 10 KB); graph adds roughly another 8 KB.
 
 > **Using `@sentientui/react`?** Don't import this entry yourself — pass the
 > `enableGraph` prop to `AdaptiveProvider` / `AdaptiveRoot` instead. The provider
 > wires the graph-capable `init()` into its single client for you; calling `init`
 > from this entry alongside the provider would create a second client.
 
-## Local overrides (development)
+## Local overrides (development — `@sentientui/react` only)
+
+Dev overrides are implemented by the **React SDK**, not this package — `client.assign()` here does not read them. With `@sentientui/react`:
 
 ```
 # URL parameter (stackable)
@@ -215,7 +223,7 @@ https://yourapp.com?sentient_variant=hero_cta:variant_a
 window.__sentient_overrides = { hero_cta: 'variant_a' };
 ```
 
-Overrides bypass the bandit entirely — no events recorded.
+While a variant is forced, the React components record nothing — no exposure, no goals, no micro-signals — so the bandit's weights are untouched.
 
 ## Docs
 

package/dist/index.d.cts

@@ -187,8 +187,10 @@ type SentientConfig = {
     debug?: boolean;
     /**
      * Pre-seeded assignments from `preloadAssignments()` (SSR).
-     * Seeds the local cache so `assign()` never makes a network call for listed components,
-     * guaranteeing server and client render the same variant on first paint.
+     * Seeds the local cache so `assign()` returns without a network call for
+     * listed code variants, guaranteeing server and client render the same
+     * variant on first paint. Managed-text components (assign with no
+     * variantIds) still fetch once when the seed carries no content.
      */
     initialAssignments?: Record<string, string>;
     /**

package/dist/index.d.ts

@@ -187,8 +187,10 @@ type SentientConfig = {
     debug?: boolean;
     /**
      * Pre-seeded assignments from `preloadAssignments()` (SSR).
-     * Seeds the local cache so `assign()` never makes a network call for listed components,
-     * guaranteeing server and client render the same variant on first paint.
+     * Seeds the local cache so `assign()` returns without a network call for
+     * listed code variants, guaranteeing server and client render the same
+     * variant on first paint. Managed-text components (assign with no
+     * variantIds) still fetch once when the seed carries no content.
      */
     initialAssignments?: Record<string, string>;
     /**

package/llms.txt

@@ -9,7 +9,7 @@
 
 ## Install (agent quickstart)
 
-- React app: `npx sentientui init` — detects the framework (Next App/Pages, Vite, Remix, CRA),
+- React app: `npx @sentientui/cli init` — detects the framework (Next App/Pages, Vite, Remix, CRA),
   installs @sentientui/react, wraps the app with the provider, writes .env.local, scaffolds an
   example. Works with NO API key (keyless local mode: deterministic simulated decisions).
   Verify by opening the app with `?sentient_persona=buyer` vs `?sentient_persona=deal_seeker`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sentientui/core",
-  "version": "0.11.0",
+  "version": "0.11.2",
   "private": false,
   "type": "module",
   "main": "./dist/index.js",