@sentientui/react 0.36.1 → 0.37.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -2,7 +2,7 @@
2
2
 
3
3
  React SDK for [SentientUI](https://sentient-ui.com) — the adaptive ladder. Declare bounded
4
4
  variations (styles, content, arrangement order); a persona-keyed optimizer on the hosted API
5
- learns which one converts best for each visitor type. Visit 1 learns; Visit 2 converts.
5
+ learns which one converts best for each visitor type, and measures the lift against a held-out control group.
6
6
 
7
7
  ## Installation
8
8
 
@@ -67,6 +67,11 @@ attributes: only that inline script (which `AdaptiveRoot` includes for you) writ
67
67
  the attributes itself, so the demo works either way — don't let that mask a missing script when
68
68
  you add a real key.)
69
69
 
70
+ Give `<SentientPersonaScript>` the same consent gate as the provider
71
+ (`<SentientPersonaScript apiKey="pk_…" consentFrom="cookiebot" />`). With `consent={false}`, or a
72
+ `consentFrom` and no `consent={true}`, it renders nothing, because its fallback reads the decision
73
+ stored on the visitor's device, which has to wait for consent. `AdaptiveRoot` does this for you.
74
+
70
75
  ## The adaptive ladder
71
76
 
72
77
  ### Rung 0 — Observe
@@ -228,9 +233,27 @@ Imported from `@sentientui/react/next`.
228
233
  | `persona` | `string` *(optional)* | Declared persona — the role your app already knows for this visitor (e.g. from your auth context). Must be a key in the project's persona vocabulary (dashboard → Settings → Personas); unrecognized values are ignored server-side. Served at full confidence, overriding the inferred persona; forwarded through both SSR paths. Stable for the session — remount to apply a new value. Never a user id or email. |
229
234
  | `consent` | `boolean` *(default `true`)* | Set `false` to skip SDK init (no cookies, no events). Flip to `true` after the visitor accepts. |
230
235
  | `respectDoNotTrack` | `boolean` *(default `true`)* | Honor the browser's Do Not Track signal. When on and DNT is enabled, the SDK sets no cookies and sends no tracking data (overriding `consent: true`), and `grantConsent()` won't re-enable it. Set `false` to make your own consent gate authoritative. |
236
+ | `consentFrom` | preset or `{ cookie, value, event }` *(optional)* | Your consent platform — see [Consent management](#consent-management-gdpr). Cookie-based sources are also read on the server, so a consented visitor gets personalized HTML and a non-consented one gets none. |
231
237
  | `timeoutMs` | `number` *(default `1000`)* | Server-side fetch timeout before falling back to the first variant. Typical decide is well under 150 ms; the full budget is only reached on a cold start or an API distant from your SSR host. |
238
+ | `nonce` | `string` *(optional)* | CSP nonce for the inline pre-paint script and the `<style>` the client injects. |
232
239
  | `debug` | `boolean` | Log assignment and event activity to the console. |
233
240
 
241
+ #### What `<AdaptiveRoot>` costs your rendering
242
+
243
+ - **Every route under it renders dynamically.** It reads `headers()` and `cookies()` to decide per visitor, so
244
+ Next.js can't statically generate or ISR-cache those routes.
245
+ - **It adds one API round trip to time-to-first-byte**, usually well under 150 ms and capped by `timeoutMs`
246
+ (default 1000 ms). On timeout the page renders the originals and decides in the browser instead.
247
+ - **It skips the round trip entirely** for visitors it must not track (DNT/GPC, consent refused or not yet given).
248
+
249
+ Want static pages? Put `<AdaptiveProvider>` in a client component instead, only around the routes that adapt.
250
+ Decisions then happen in the browser after hydration: the server HTML shows the originals, a returning
251
+ visitor's last decision is restored from the SDK's local snapshot as soon as the client starts (no network
252
+ wait), and a first-time visitor's arrives after one round trip.
253
+
254
+ `@sentientui/react/next` is ESM-only (the App Router always loads it as ESM). The package root and
255
+ `/server` ship both ESM and CommonJS.
256
+
234
257
  ### `<AdaptiveProvider>` (any React app)
235
258
 
236
259
  Accepts the same `apiKey`, `persona`, `consent`, `debug` props as `<AdaptiveRoot>`, plus `onAssignment` (not available on `<AdaptiveRoot>` — function props can't cross the RSC boundary) and:
@@ -255,7 +278,8 @@ never both. `AdaptiveProps` is the union of the two exported prop types below.
255
278
  | `children` | `ReactNode` | The original. Renders for holdout/control traffic, unknown visitor types, visitor types with no version, and every error path. |
256
279
  | `goal` | `string \| GoalConfig` *(optional)* | Conversion goal credited to this region. |
257
280
  | `onFormSubmit` | `(values: Record<string, string>) => void` *(optional)* | Receives the values when a generated form version submits. Form versions are only offered when this is present; values never reach SentientUI. |
258
- | `className` | `string` *(optional)* | Class for the wrapper `<div>`. |
281
+ | `as` | `'div' \| 'section' \| 'li' \| 'span' \| …` *(optional, default `'div'`)* | Wrapper element — e.g. `'li'` inside a list. Always a real element, never `display: contents`: it is what exposure and goals observe. |
282
+ | `className` | `string` *(optional)* | Class for the wrapper element. |
259
283
  | `reportBaselineText` | `boolean` *(default `true`)* | At first registration, send this region's rendered text (capped at 400 chars) so generated versions are grounded in what they replace. Set `false` for a region wrapping personalized or account content. |
260
284
 
261
285
  **Code variants** — `AdaptiveVariantsProps`:
@@ -269,8 +293,24 @@ never both. `AdaptiveProps` is the union of the two exported prop types below.
269
293
  | `microSignalGoals` | `MicroSignalGoals` *(optional)* | When a passive micro-signal fires on this component, also record a named goal: micro-signal type → goal name (or `{ name, weight?, stepIndex? }`), e.g. `{ rage_click: 'confused_by_hero' }`. |
270
294
  | `agentDataByVariant` | `Record<string, unknown>` *(optional)* | Structured data keyed by variant ID that AI agents can consume via `GET /v1/agent/layout`. Only the assigned variant's entry is sent to the server. Preferred over `agentData`. |
271
295
  | `agentData` | `unknown` *(optional, deprecated)* | Deprecated in favour of `agentDataByVariant`. Single value stored once regardless of which variant is shown; kept for backward compatibility. |
296
+ | `as`, `className` | *(optional)* | Wrapper element and its class, as for generated versions. |
272
297
  | `clientOnly` | `boolean` | Render nothing on the server; resolve on the client only. Use for cookie-dependent components. Without it, a component with no preloaded assignment server-renders its first variant. (This replaces the deprecated provider-level `ssrFallback="none"`, which is still accepted.) |
273
298
 
299
+ #### Which goal API?
300
+
301
+ One canonical path per situation — the others are for the cases these can't reach:
302
+
303
+ | You want to record… | Use | Credits |
304
+ |---|---|---|
305
+ | a click, submit or scroll inside an adaptive region | the `goal` prop on `<Adaptive>` | the version that region showed |
306
+ | a visitor reaching a page or route (pricing, checkout) | `usePageGoal(name, { componentId? })` | that component's version, or the session |
307
+ | an event you fire yourself, tied to a region (a phone call, a custom widget) | `useAdaptiveGoal(componentId)` | the version that region showed |
308
+ | a conversion outside React (server, another framework) | `client.goal(name, { value, externalId })` from `@sentientui/core` | the session |
309
+
310
+ `useAssignment` records nothing (use `useAdaptive`), and the positional
311
+ `client.goal(name, metadata, weight, stepIndex)` form is deprecated in favour of
312
+ `client.goal(name, options)`; both leave in 1.0.
313
+
274
314
  #### Goal types
275
315
 
276
316
  **A string is the goal's NAME; an object config has none.** `goal="signup_click"` reports under
@@ -556,6 +596,8 @@ DOM graph scanning and behavioral engagement capture are **on by default** — n
556
596
 
557
597
  Both modules are loaded on demand after init, so the base bundle stays lean, and neither ever runs for a Do-Not-Track, Global Privacy Control, or consent-gated visitor (see Consent below).
558
598
 
599
+ What they cost, so you can decide: about 21 KB gzip on top of the ~16 KB core client, fetched after hydration (never on the critical path). One `MutationObserver` watches the page for sections added later, and it batches a burst of DOM changes into a single scan 200 ms after the burst starts, so a chat or a live list doesn't make it do work on every frame. Turn graph scanning off and the dashboard's page-structure view goes empty. Turn engagement off and audiences stop learning from on-page behaviour.
600
+
559
601
  Opt out per feature:
560
602
 
561
603
  ```tsx
@@ -568,85 +610,90 @@ Direct `@sentientui/core` users enable graph scanning by importing `init` from `
568
610
 
569
611
  ## Consent management (GDPR)
570
612
 
571
- By default the SDK initialises with `consent: true`, so tracking starts on first paint — opt-in consent is something you wire up, not the default. For GDPR-style opt-in, pass `consent={false}` until the visitor accepts your banner; no events are sent and no cookie is written while consent is false. To serve the best-performing variant while the cookie banner is pending (rather than freezing the UI), add `preConsentBehavior: 'statistical_winner'`:
572
-
573
- ```tsx
574
- <AdaptiveProvider
575
- apiKey={process.env.NEXT_PUBLIC_SENTIENT_API_KEY!}
576
- consent={hasConsent}
577
- preConsentBehavior="statistical_winner"
578
- >
579
- {children}
580
- </AdaptiveProvider>
581
- ```
582
-
583
- Set `hasConsent` to `false` until the user accepts your cookie banner, then flip it to `true`. The provider re-initialises automatically and begins full tracking.
584
-
585
- ### Without React
613
+ Tracking starts on first paint unless you gate it — opt-in consent is something you wire up,
614
+ not the default (in development the provider warns once when neither `consent` nor
615
+ `consentFrom` is set). While the SDK is gated no cookie is written and nothing about the
616
+ visitor is sent. The one exception is `preConsentBehavior="statistical_winner"`, which asks
617
+ `GET /v1/winner` for the best version, a read-only request that carries no identifier.
586
618
 
587
- ```ts
588
- import { init, grantConsent } from '@sentientui/core';
619
+ A refusal forgets the visitor: the cookie, the assignment cache and the decision snapshot.
620
+ That means `consent` flipping to `false`, or the platform recording a "no". A platform that is
621
+ still loading, or reopened by a visitor who already said yes, only pauses tracking. Once the
622
+ platform has answered in the page load, a return to "no answer" (a banner reset that deletes its
623
+ cookie) also pauses: `AdaptiveRoot`'s server-side read applies only until the browser answers.
589
624
 
590
- const client = init({
591
- apiKey: 'pk_...',
592
- consent: false,
593
- preConsentBehavior: 'statistical_winner',
594
- });
625
+ Conversions fired before consent is known: with `preConsentBehavior` they are held in memory
626
+ and sent, in order and ahead of later goals, if the visitor accepts on the same page (dropped on a refusal). Without it there is no
627
+ client yet, so `useSentient()` returns `null` and a conversion fired then is not recorded. Use
628
+ `usePageGoal`, which waits, or fire once `useSentient()` returns a client.
595
629
 
596
- // After the user accepts the cookie banner:
597
- grantConsent(); // upgrades client in place — no need to reassign
598
- ```
630
+ Every key the SDK stores is listed in
631
+ [SDK_COOKIE_DISCLOSURE.md](https://github.com/SentientUI/sdk/blob/main/SDK_COOKIE_DISCLOSURE.md).
599
632
 
600
- ### OneTrust and Cookiebot
633
+ ### Follow your consent platform (recommended)
601
634
 
602
- In React, don't wire a CMP callback to `grantConsent()`: with `consent={false}` and no
603
- `preConsentBehavior`, `<AdaptiveProvider>` never creates a client, so there is nothing to
604
- upgrade — `grantConsent()` just warns "called before init()" and tracking never starts. Point
605
- `consentFrom` at the CMP instead. The source is re-read every time the event fires, so a later
606
- withdrawal gates the SDK again too:
635
+ Point `consentFrom` at your CMP. The provider reads the platform's own API, events and cookie,
636
+ starts the moment it grants, and gates and forgets again on withdrawal — no reload, no callback
637
+ wiring:
607
638
 
608
639
  ```tsx
609
- // OneTrust — C0002 = Analytics/Performance category
610
- <AdaptiveProvider
611
- apiKey={process.env.NEXT_PUBLIC_SENTIENT_API_KEY!}
612
- consentFrom={{
613
- check: () => window.OnetrustActiveGroups?.includes('C0002') === true,
614
- event: 'OneTrustGroupsUpdated',
615
- }}
616
- >
617
- {children}
618
- </AdaptiveProvider>
619
-
620
- // Cookiebot — re-read on accept AND decline, so withdrawal is honoured
621
- <AdaptiveProvider
622
- apiKey={process.env.NEXT_PUBLIC_SENTIENT_API_KEY!}
623
- consentFrom={{
624
- check: () => window.Cookiebot?.consent?.statistics === true,
625
- event: 'CookiebotOnConsentReady',
626
- }}
627
- >
640
+ <AdaptiveProvider apiKey={process.env.NEXT_PUBLIC_SENTIENT_API_KEY!} consentFrom="onetrust">
628
641
  {children}
629
642
  </AdaptiveProvider>
630
643
  ```
631
644
 
632
- `<AdaptiveRoot>` is a Server Component and accepts only the cookie form — a `check` function
633
- cannot cross the server→client boundary. Point it at a cookie your CMP (or a one-line listener)
634
- writes, and it also resolves the cookie on the server for already-consented visitors:
645
+ | Preset | Reads | Default category |
646
+ |---|---|---|
647
+ | `'cookiebot'` | `Cookiebot.consent`, `CookieConsent` cookie | `statistics` — `{ cmp: 'cookiebot', category: 'marketing' }` to change |
648
+ | `'onetrust'` | `OnetrustActiveGroups` (exact group match), `OptanonConsent` cookie | `C0002` — `{ cmp: 'onetrust', group: 'C0004' }` |
649
+ | `'cookieyes'` | `getCkyConsent()`, `cookieyes-consent` cookie | `analytics` |
650
+ | `'tcf'` | IAB TCF v2.2 `__tcfapi`, `euconsent-v2` cookie | purposes 1, 5, 6, 8 (8 may rest on legitimate interest); `{ cmp: 'tcf', vendorId }` also requires vendor consent |
651
+ | `'google-consent-mode'` | the latest `consent default/update` in `dataLayer` | `analytics_storage`; pass `region: 'ES'` (e.g. from your CDN's country header) to resolve region-scoped defaults — without it a region-scoped denial reads as denied |
652
+ | `'shopify'` | Shopify Customer Privacy API | `analytics` |
653
+
654
+ Your own banner works too: `consentFrom={{ cookie: 'analytics_consent', value: 'granted', event: 'consent-decided' }}`,
655
+ or any JS API: `consentFrom={{ check: () => window.myCmp?.analytics === true, event: 'mycmp:changed' }}`.
656
+ A `check` returning false only pauses tracking; add `refused: () => window.myCmp?.answered === true`
657
+ so a refusal also deletes the visitor's data.
658
+ Hand-rolled checks are where CMP bugs live (`OnetrustActiveGroups.includes('C0002')` is also
659
+ true for `C00021`), so prefer a preset.
660
+
661
+ To show the best-performing version while the banner is pending, instead of the first one, add
662
+ `preConsentBehavior="statistical_winner"` — it calls only `GET /v1/winner`, a read-only endpoint
663
+ that stores nothing about the visitor.
664
+
665
+ ### `<AdaptiveRoot>` (Next.js)
666
+
667
+ `<AdaptiveRoot>` is a Server Component: it takes every preset and the cookie form (a `check`
668
+ function cannot cross the server→client boundary). For the cookie-based presets
669
+ (`cookiebot`, `onetrust`, `cookieyes`, `tcf`) and the cookie form it also reads the decision on
670
+ the server, so an already-consented visitor gets personalized server HTML:
635
671
 
636
672
  ```tsx
637
- <AdaptiveRoot
638
- apiKey={process.env.NEXT_PUBLIC_SENTIENT_API_KEY!}
639
- consentFrom={{ cookie: 'analytics_consent', value: 'granted', event: 'consent-decided' }}
640
- >
673
+ <AdaptiveRoot apiKey={process.env.NEXT_PUBLIC_SENTIENT_API_KEY!} consentFrom="cookiebot">
641
674
  {children}
642
675
  </AdaptiveRoot>
643
676
  ```
644
677
 
645
- For a `check()` predicate in the App Router, render `<AdaptiveProvider>` from a client component
646
- instead. `grantConsent()` remains correct for direct `@sentientui/core` users (above), whose
647
- `init({ consent: false })` does create an upgradeable client.
678
+ ### Your own flag
679
+
680
+ ```tsx
681
+ <AdaptiveProvider apiKey={process.env.NEXT_PUBLIC_SENTIENT_API_KEY!} consent={hasConsent}>
682
+ ```
683
+
684
+ Flip `hasConsent` to `true` on accept and back to `false` on withdrawal. Don't wire a CMP
685
+ callback to `grantConsent()` in React: with `consent={false}` and no `preConsentBehavior` the
686
+ provider has no client to upgrade.
648
687
 
649
- When `consent: false` without `preConsentBehavior`, the SDK is a complete no-op — no API calls, no cookies, nothing. The `preConsentBehavior: 'statistical_winner'` mode calls only `GET /v1/winner`, a read-only endpoint that returns the best variant without storing any visitor data.
688
+ ### Without React
689
+
690
+ ```ts
691
+ import { init, grantConsent } from '@sentientui/core';
692
+
693
+ const client = init({ apiKey: 'pk_...', consent: false });
694
+ grantConsent(); // on accept: upgrades the client in place
695
+ client.destroy(); // on withdrawal: forgets the visitor
696
+ ```
650
697
 
651
698
  ## Docs
652
699
 
package/dist/index.d.cts CHANGED
@@ -198,6 +198,12 @@ type AdaptiveProviderProps = {
198
198
  * Never runs for a DNT/GPC or consent-gated visitor (no client → no capture).
199
199
  */
200
200
  engagement?: boolean;
201
+ /**
202
+ * CSP nonce for the <style> the SDK injects (the adaptation reveal), so a
203
+ * nonce-based CSP needs no `style-src 'unsafe-inline'`. `AdaptiveRoot`
204
+ * forwards its own `nonce`. Defaults to the nonce of a script on the page.
205
+ */
206
+ nonce?: string;
201
207
  children: ReactNode;
202
208
  };
203
209
  /**
@@ -212,6 +218,9 @@ declare function AdaptiveProvider(props: AdaptiveProviderProps): JSX.Element;
212
218
  declare function useSentient(): SentientClient | null;
213
219
  /** Internal: SSR-preloaded assignments for hydration-safe first render. */
214
220
  declare function useInitialAssignments(): Record<string, string>;
221
+ /** The `device:source` segment this provider decides and caches under —
222
+ * the SSR value when one was passed, else derived once per mount. */
223
+ declare function useSessionSegment(): string;
215
224
  /**
216
225
  * Returns the persona-specific section order from SSR, or null when no
217
226
  * sections were declared on AdaptiveRoot or reliability is below threshold.
@@ -222,6 +231,14 @@ declare function useLayoutOrder(): string[] | null;
222
231
  /** Internal: configured API base URL (devtools fetches /v1/explain against this, never a relative URL). */
223
232
  declare function useAdaptiveApiBaseUrl(): string;
224
233
 
234
+ /**
235
+ * The element `<Adaptive>` renders around its content (audit S17: it was
236
+ * always a `<div>`, which is invalid inside a `<ul>`, a `<p>` or a table row
237
+ * and broke `display: grid` children). Intrinsic tags only: the wrapper is
238
+ * what exposure, goals and micro-signals observe, so it must be a real box —
239
+ * `display: contents` would give IntersectionObserver nothing to measure.
240
+ */
241
+ type AdaptiveElement = 'div' | 'section' | 'article' | 'aside' | 'header' | 'footer' | 'main' | 'nav' | 'span' | 'li' | 'figure' | 'form' | 'label' | 'td' | 'th';
225
242
  type ScrollDepthGoal = {
226
243
  type: 'scroll_depth';
227
244
  threshold: number;
@@ -274,13 +291,15 @@ type AdaptiveSlotProps = {
274
291
  * shape as AdaptiveGroup's. Form arms fire their own submitGoal regardless. */
275
292
  goal?: string | GoalConfig;
276
293
  className?: string;
294
+ /** Wrapper element. @default 'div' */
295
+ as?: AdaptiveElement;
277
296
  /** On first registration the SDK sends the region's rendered text (capped at
278
297
  * 400 chars) so dashboard-generated versions are grounded in what they
279
298
  * replace. Set false for a slot wrapping personalized or account content —
280
299
  * the text of THIS region is all that is ever read, never the page. */
281
300
  reportBaselineText?: boolean;
282
301
  };
283
- declare function AdaptiveSlot({ id, children, variants, onFormSubmit, goal, className, reportBaselineText, }: AdaptiveSlotProps): JSX.Element;
302
+ declare function AdaptiveSlot({ id, children, variants, onFormSubmit, goal, className, as: Tag, reportBaselineText, }: AdaptiveSlotProps): JSX.Element;
284
303
 
285
304
  /** `<Adaptive>` with variants written in code — each key an arm, first key the control. */
286
305
  type AdaptiveVariantsProps = {
@@ -306,6 +325,10 @@ type AdaptiveVariantsProps = {
306
325
  * Use for inferred goals surfaced in the dashboard (e.g. rage_click → 'confused_by_hero').
307
326
  */
308
327
  microSignalGoals?: MicroSignalGoals;
328
+ /** Wrapper element. @default 'div' */
329
+ as?: AdaptiveElement;
330
+ /** Class for the wrapper element. */
331
+ className?: string;
309
332
  /**
310
333
  * When true, renders nothing during SSR and before client hydration.
311
334
  * Use when you cannot pass `initialAssignments` and prefer a blank slot over
@@ -511,6 +534,14 @@ type SentientPersonaScriptProps = {
511
534
  persona: string;
512
535
  confidence: number;
513
536
  } | null;
537
+ /**
538
+ * The same consent gate you give the provider. With `consent={false}`, or a
539
+ * `consentFrom` source and no `consent={true}`, nothing is rendered: the
540
+ * fallback reads the stored decision from the visitor's device, and that
541
+ * must wait for consent (grader F3). `AdaptiveRoot` handles this for you.
542
+ */
543
+ consent?: boolean;
544
+ consentFrom?: unknown;
514
545
  };
515
546
  /**
516
547
  * Single writer of the Rung-1a `<html>` attributes
@@ -524,7 +555,7 @@ type SentientPersonaScriptProps = {
524
555
  * (the same pattern next-themes uses). The client SDK adopts the attributes
525
556
  * as truth and never rewrites them mid-session.
526
557
  */
527
- declare function SentientPersonaScript(props: SentientPersonaScriptProps): JSX.Element;
558
+ declare function SentientPersonaScript(props: SentientPersonaScriptProps): JSX.Element | null;
528
559
 
529
560
  type UseAdaptiveTokensOptions = {
530
561
  goal?: string | GoalConfig;
@@ -730,4 +761,4 @@ declare function renderBlocks(node: BlockNode, opts: RenderBlocksOptions): JSX.E
730
761
  */
731
762
  declare function renderCompose(compose: ComposeArm, opts: RenderBlocksOptions): JSX.Element | null;
732
763
 
733
- export { Adaptive, type AdaptiveGeneratedProps, AdaptiveGroup, type AdaptiveGroupProps, type AdaptivePersona, type AdaptiveProps, AdaptiveProvider, type AdaptiveProviderProps, AdaptiveSlot, type AdaptiveSlotProps, AdaptiveText, type AdaptiveTextProps, type AdaptiveVariantsProps, type AgentBlock, type AgentFeed, type AssignmentState, type ClickGoal, type ComponentWeights, type CompositeGoal, type FireGoal, type FormSubmitGoal, type GoalConfig, type MicroSignalGoalConfig, type MicroSignalGoals, type PageGoalOptions, type RenderBlocksOptions, type ScrollDepthGoal, SentientPersonaScript, type SentientPersonaScriptProps, type SsrFallback, type UseAdaptiveBind, type UseAdaptiveResult, type UseAdaptiveTokensOptions, type UseAdaptiveTokensResult, type VariantWeight, type WeightedCompositeGoal, type WeightedStep, buildAgentFeed, defineAgentContent, getAgentContent, renderAgentJsonLd, renderAgentJsonLdBody, renderAgentMarkdown, renderBlocks, renderCompose, useAdaptive, useAdaptiveApiBaseUrl, useAdaptiveGoal, useAdaptivePersona, useAdaptiveTokens, useAssignment, useInitialAssignments, useLayoutOrder, usePageGoal, useSentient };
764
+ export { Adaptive, type AdaptiveElement, type AdaptiveGeneratedProps, AdaptiveGroup, type AdaptiveGroupProps, type AdaptivePersona, type AdaptiveProps, AdaptiveProvider, type AdaptiveProviderProps, AdaptiveSlot, type AdaptiveSlotProps, AdaptiveText, type AdaptiveTextProps, type AdaptiveVariantsProps, type AgentBlock, type AgentFeed, type AssignmentState, type ClickGoal, type ComponentWeights, type CompositeGoal, type FireGoal, type FormSubmitGoal, type GoalConfig, type MicroSignalGoalConfig, type MicroSignalGoals, type PageGoalOptions, type RenderBlocksOptions, type ScrollDepthGoal, SentientPersonaScript, type SentientPersonaScriptProps, type SsrFallback, type UseAdaptiveBind, type UseAdaptiveResult, type UseAdaptiveTokensOptions, type UseAdaptiveTokensResult, type VariantWeight, type WeightedCompositeGoal, type WeightedStep, buildAgentFeed, defineAgentContent, getAgentContent, renderAgentJsonLd, renderAgentJsonLdBody, renderAgentMarkdown, renderBlocks, renderCompose, useAdaptive, useAdaptiveApiBaseUrl, useAdaptiveGoal, useAdaptivePersona, useAdaptiveTokens, useAssignment, useInitialAssignments, useLayoutOrder, usePageGoal, useSentient, useSessionSegment };
package/dist/index.d.ts CHANGED
@@ -198,6 +198,12 @@ type AdaptiveProviderProps = {
198
198
  * Never runs for a DNT/GPC or consent-gated visitor (no client → no capture).
199
199
  */
200
200
  engagement?: boolean;
201
+ /**
202
+ * CSP nonce for the <style> the SDK injects (the adaptation reveal), so a
203
+ * nonce-based CSP needs no `style-src 'unsafe-inline'`. `AdaptiveRoot`
204
+ * forwards its own `nonce`. Defaults to the nonce of a script on the page.
205
+ */
206
+ nonce?: string;
201
207
  children: ReactNode;
202
208
  };
203
209
  /**
@@ -212,6 +218,9 @@ declare function AdaptiveProvider(props: AdaptiveProviderProps): JSX.Element;
212
218
  declare function useSentient(): SentientClient | null;
213
219
  /** Internal: SSR-preloaded assignments for hydration-safe first render. */
214
220
  declare function useInitialAssignments(): Record<string, string>;
221
+ /** The `device:source` segment this provider decides and caches under —
222
+ * the SSR value when one was passed, else derived once per mount. */
223
+ declare function useSessionSegment(): string;
215
224
  /**
216
225
  * Returns the persona-specific section order from SSR, or null when no
217
226
  * sections were declared on AdaptiveRoot or reliability is below threshold.
@@ -222,6 +231,14 @@ declare function useLayoutOrder(): string[] | null;
222
231
  /** Internal: configured API base URL (devtools fetches /v1/explain against this, never a relative URL). */
223
232
  declare function useAdaptiveApiBaseUrl(): string;
224
233
 
234
+ /**
235
+ * The element `<Adaptive>` renders around its content (audit S17: it was
236
+ * always a `<div>`, which is invalid inside a `<ul>`, a `<p>` or a table row
237
+ * and broke `display: grid` children). Intrinsic tags only: the wrapper is
238
+ * what exposure, goals and micro-signals observe, so it must be a real box —
239
+ * `display: contents` would give IntersectionObserver nothing to measure.
240
+ */
241
+ type AdaptiveElement = 'div' | 'section' | 'article' | 'aside' | 'header' | 'footer' | 'main' | 'nav' | 'span' | 'li' | 'figure' | 'form' | 'label' | 'td' | 'th';
225
242
  type ScrollDepthGoal = {
226
243
  type: 'scroll_depth';
227
244
  threshold: number;
@@ -274,13 +291,15 @@ type AdaptiveSlotProps = {
274
291
  * shape as AdaptiveGroup's. Form arms fire their own submitGoal regardless. */
275
292
  goal?: string | GoalConfig;
276
293
  className?: string;
294
+ /** Wrapper element. @default 'div' */
295
+ as?: AdaptiveElement;
277
296
  /** On first registration the SDK sends the region's rendered text (capped at
278
297
  * 400 chars) so dashboard-generated versions are grounded in what they
279
298
  * replace. Set false for a slot wrapping personalized or account content —
280
299
  * the text of THIS region is all that is ever read, never the page. */
281
300
  reportBaselineText?: boolean;
282
301
  };
283
- declare function AdaptiveSlot({ id, children, variants, onFormSubmit, goal, className, reportBaselineText, }: AdaptiveSlotProps): JSX.Element;
302
+ declare function AdaptiveSlot({ id, children, variants, onFormSubmit, goal, className, as: Tag, reportBaselineText, }: AdaptiveSlotProps): JSX.Element;
284
303
 
285
304
  /** `<Adaptive>` with variants written in code — each key an arm, first key the control. */
286
305
  type AdaptiveVariantsProps = {
@@ -306,6 +325,10 @@ type AdaptiveVariantsProps = {
306
325
  * Use for inferred goals surfaced in the dashboard (e.g. rage_click → 'confused_by_hero').
307
326
  */
308
327
  microSignalGoals?: MicroSignalGoals;
328
+ /** Wrapper element. @default 'div' */
329
+ as?: AdaptiveElement;
330
+ /** Class for the wrapper element. */
331
+ className?: string;
309
332
  /**
310
333
  * When true, renders nothing during SSR and before client hydration.
311
334
  * Use when you cannot pass `initialAssignments` and prefer a blank slot over
@@ -511,6 +534,14 @@ type SentientPersonaScriptProps = {
511
534
  persona: string;
512
535
  confidence: number;
513
536
  } | null;
537
+ /**
538
+ * The same consent gate you give the provider. With `consent={false}`, or a
539
+ * `consentFrom` source and no `consent={true}`, nothing is rendered: the
540
+ * fallback reads the stored decision from the visitor's device, and that
541
+ * must wait for consent (grader F3). `AdaptiveRoot` handles this for you.
542
+ */
543
+ consent?: boolean;
544
+ consentFrom?: unknown;
514
545
  };
515
546
  /**
516
547
  * Single writer of the Rung-1a `<html>` attributes
@@ -524,7 +555,7 @@ type SentientPersonaScriptProps = {
524
555
  * (the same pattern next-themes uses). The client SDK adopts the attributes
525
556
  * as truth and never rewrites them mid-session.
526
557
  */
527
- declare function SentientPersonaScript(props: SentientPersonaScriptProps): JSX.Element;
558
+ declare function SentientPersonaScript(props: SentientPersonaScriptProps): JSX.Element | null;
528
559
 
529
560
  type UseAdaptiveTokensOptions = {
530
561
  goal?: string | GoalConfig;
@@ -730,4 +761,4 @@ declare function renderBlocks(node: BlockNode, opts: RenderBlocksOptions): JSX.E
730
761
  */
731
762
  declare function renderCompose(compose: ComposeArm, opts: RenderBlocksOptions): JSX.Element | null;
732
763
 
733
- export { Adaptive, type AdaptiveGeneratedProps, AdaptiveGroup, type AdaptiveGroupProps, type AdaptivePersona, type AdaptiveProps, AdaptiveProvider, type AdaptiveProviderProps, AdaptiveSlot, type AdaptiveSlotProps, AdaptiveText, type AdaptiveTextProps, type AdaptiveVariantsProps, type AgentBlock, type AgentFeed, type AssignmentState, type ClickGoal, type ComponentWeights, type CompositeGoal, type FireGoal, type FormSubmitGoal, type GoalConfig, type MicroSignalGoalConfig, type MicroSignalGoals, type PageGoalOptions, type RenderBlocksOptions, type ScrollDepthGoal, SentientPersonaScript, type SentientPersonaScriptProps, type SsrFallback, type UseAdaptiveBind, type UseAdaptiveResult, type UseAdaptiveTokensOptions, type UseAdaptiveTokensResult, type VariantWeight, type WeightedCompositeGoal, type WeightedStep, buildAgentFeed, defineAgentContent, getAgentContent, renderAgentJsonLd, renderAgentJsonLdBody, renderAgentMarkdown, renderBlocks, renderCompose, useAdaptive, useAdaptiveApiBaseUrl, useAdaptiveGoal, useAdaptivePersona, useAdaptiveTokens, useAssignment, useInitialAssignments, useLayoutOrder, usePageGoal, useSentient };
764
+ export { Adaptive, type AdaptiveElement, type AdaptiveGeneratedProps, AdaptiveGroup, type AdaptiveGroupProps, type AdaptivePersona, type AdaptiveProps, AdaptiveProvider, type AdaptiveProviderProps, AdaptiveSlot, type AdaptiveSlotProps, AdaptiveText, type AdaptiveTextProps, type AdaptiveVariantsProps, type AgentBlock, type AgentFeed, type AssignmentState, type ClickGoal, type ComponentWeights, type CompositeGoal, type FireGoal, type FormSubmitGoal, type GoalConfig, type MicroSignalGoalConfig, type MicroSignalGoals, type PageGoalOptions, type RenderBlocksOptions, type ScrollDepthGoal, SentientPersonaScript, type SentientPersonaScriptProps, type SsrFallback, type UseAdaptiveBind, type UseAdaptiveResult, type UseAdaptiveTokensOptions, type UseAdaptiveTokensResult, type VariantWeight, type WeightedCompositeGoal, type WeightedStep, buildAgentFeed, defineAgentContent, getAgentContent, renderAgentJsonLd, renderAgentJsonLdBody, renderAgentMarkdown, renderBlocks, renderCompose, useAdaptive, useAdaptiveApiBaseUrl, useAdaptiveGoal, useAdaptivePersona, useAdaptiveTokens, useAssignment, useInitialAssignments, useLayoutOrder, usePageGoal, useSentient, useSessionSegment };