@sentientui/core 0.32.0 → 0.34.0

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.
Files changed (52) hide show
  1. package/dist/chunk-3FKD44SF.mjs +2 -0
  2. package/dist/chunk-3FKD44SF.mjs.map +1 -0
  3. package/dist/chunk-DGRAS5VP.mjs +2 -0
  4. package/dist/chunk-DGRAS5VP.mjs.map +1 -0
  5. package/dist/{index-CgkImSaM.d.ts → index-C2EOL-_c.d.cts} +43 -4
  6. package/dist/{index-COl_pfNm.d.cts → index-DrMXbLKP.d.ts} +43 -4
  7. package/dist/index-engagement.js +1 -1
  8. package/dist/index-engagement.js.map +1 -1
  9. package/dist/index-engagement.mjs +1 -1
  10. package/dist/index-engagement.mjs.map +1 -1
  11. package/dist/index-graph.d.cts +6 -4
  12. package/dist/index-graph.d.ts +6 -4
  13. package/dist/index-graph.js +1 -1
  14. package/dist/index-graph.js.map +1 -1
  15. package/dist/index-graph.mjs +1 -1
  16. package/dist/index-graph.mjs.map +1 -1
  17. package/dist/index-local.d.cts +4 -2
  18. package/dist/index-local.d.ts +4 -2
  19. package/dist/index-region.d.cts +40 -0
  20. package/dist/index-region.d.ts +40 -0
  21. package/dist/index-region.js +2 -0
  22. package/dist/index-region.js.map +1 -0
  23. package/dist/index-region.mjs +2 -0
  24. package/dist/index-region.mjs.map +1 -0
  25. package/dist/index-server.d.cts +74 -3
  26. package/dist/index-server.d.ts +74 -3
  27. package/dist/index-server.js +1 -1
  28. package/dist/index-server.js.map +1 -1
  29. package/dist/index-server.mjs +1 -1
  30. package/dist/index-server.mjs.map +1 -1
  31. package/dist/index-style-sample.d.cts +12 -0
  32. package/dist/index-style-sample.d.ts +12 -0
  33. package/dist/index-style-sample.js +2 -0
  34. package/dist/index-style-sample.js.map +1 -0
  35. package/dist/index-style-sample.mjs +2 -0
  36. package/dist/index-style-sample.mjs.map +1 -0
  37. package/dist/index.d.cts +4 -2
  38. package/dist/index.d.ts +4 -2
  39. package/dist/index.js +1 -1
  40. package/dist/index.js.map +1 -1
  41. package/dist/index.mjs +1 -1
  42. package/dist/region-skeleton-CQ4yhVw1.d.cts +56 -0
  43. package/dist/region-skeleton-CQ4yhVw1.d.ts +56 -0
  44. package/dist/session-meta-CWGtzFOQ.d.ts +226 -0
  45. package/dist/session-meta-KwDqU9a8.d.cts +226 -0
  46. package/dist/style-vocabulary-BqviEw9O.d.cts +285 -0
  47. package/dist/style-vocabulary-BqviEw9O.d.ts +285 -0
  48. package/package.json +11 -1
  49. package/dist/chunk-EVYMV2C6.mjs +0 -2
  50. package/dist/chunk-EVYMV2C6.mjs.map +0 -1
  51. package/dist/session-meta-DydKfQiR.d.cts +0 -416
  52. package/dist/session-meta-DydKfQiR.d.ts +0 -416
package/dist/index.mjs CHANGED
@@ -1,2 +1,2 @@
1
- import{A as T,B as U,C as V,D as W,E as X,F as Y,G as Z,H as _,I as $,J as aa,K as ba,L as ca,M as da,N as ea,O as fa,a as t,b as u,c as v,d as w,e as x,f as y,g as z,h as A,i as B,j as C,k as D,l as E,m as F,n as G,o as H,p as I,q as J,r as K,s as L,t as M,u as N,v as O,w as P,x as Q,y as R,z as S}from"./chunk-EVYMV2C6.mjs";import{b as a,c as b,d as c,e as d,f as e,g as f,h as g,i as h,j as i,k as j,l as k,m as l,n as m,o as n,p as o,r as p,s as q,t as r,u as s}from"./chunk-2NVSFI4V.mjs";import"./chunk-TMCGHANO.mjs";export{f as AGENT_INTENTS,C as BLOCK_ALIGNS,H as BLOCK_EMPHASES,K as BLOCK_FITS,B as BLOCK_GAPS,L as BLOCK_GRID_COLUMNS,M as BLOCK_HEADING_LEVELS,D as BLOCK_JUSTIFIES,P as BLOCK_MAX_WIDTHS,O as BLOCK_PADS,J as BLOCK_RATIOS,E as BLOCK_SIZES,N as BLOCK_SURFACES,I as BLOCK_TEXT_ALIGNS,G as BLOCK_TONES,F as BLOCK_WEIGHTS,l as CLICK_ID_KEYS,Q as FORM_FIELD_KINDS,R as FORM_INPUT_TYPES,a as LEGACY_SESSION_COOKIE_NAME,y as LOCAL_MODE_BANNER,X as MAX_BLOCK_ARMS,W as MAX_BLOCK_CHILDREN,V as MAX_BLOCK_DEPTH,U as MAX_BLOCK_NODES,Y as MAX_BLOCK_TEXT_LEN,S as MAX_FORM_FIELDS,T as MAX_FORM_SELECT_OPTIONS,z as PAGE_SCOPE_RE,x as PROD_KEYLESS_ERROR,_ as REVEAL_MS,t as SNAPSHOT_STORAGE_KEY_PREFIX,ca as _registerConsentUpgradeInit,g as agentIntent,c as agentUaList,s as armOfResult,ba as attachMicroSignalDetectors,q as baselineResultFor,r as baselineSlots,h as classifiedAgents,Z as containsFormBlock,o as deriveSessionSegment,i as detectDeviceClass,n as detectTimeOfDay,j as detectTrafficSource,m as extractTrackedParams,ea as grantConsent,fa as init,da as isDoNotTrackEnabled,e as matchedAgentToken,A as pageScopeMatches,u as readSnapshot,k as referrerDomainFromReferer,w as renderPrePaintScript,$ as resetRevealStyles,aa as reveal,b as sessionCookieName,p as toWireSlot,d as uaTokenMatch,v as writeSnapshot};
1
+ import{A as T,B as U,C as V,D as W,E as X,F as Y,G as Z,H as ba,I as ca,J as da,K as ea,L as fa,M as ga,N as ha,O as ia,a as t,b as u,c as v,d as w,e as x,f as y,g as z,h as A,i as B,j as C,k as D,l as E,m as F,n as G,o as H,p as I,q as J,r as K,s as L,t as M,u as N,v as O,w as P,x as Q,y as R,z as S}from"./chunk-DGRAS5VP.mjs";import{a as _,b as $,c as aa}from"./chunk-3FKD44SF.mjs";import{b as a,c as b,d as c,e as d,f as e,g as f,h as g,i as h,j as i,k as j,l as k,m as l,n as m,o as n,p as o,r as p,s as q,t as r,u as s}from"./chunk-2NVSFI4V.mjs";import"./chunk-TMCGHANO.mjs";export{f as AGENT_INTENTS,C as BLOCK_ALIGNS,H as BLOCK_EMPHASES,K as BLOCK_FITS,B as BLOCK_GAPS,L as BLOCK_GRID_COLUMNS,M as BLOCK_HEADING_LEVELS,D as BLOCK_JUSTIFIES,P as BLOCK_MAX_WIDTHS,O as BLOCK_PADS,J as BLOCK_RATIOS,E as BLOCK_SIZES,N as BLOCK_SURFACES,I as BLOCK_TEXT_ALIGNS,G as BLOCK_TONES,F as BLOCK_WEIGHTS,l as CLICK_ID_KEYS,Q as FORM_FIELD_KINDS,R as FORM_INPUT_TYPES,a as LEGACY_SESSION_COOKIE_NAME,y as LOCAL_MODE_BANNER,X as MAX_BLOCK_ARMS,W as MAX_BLOCK_CHILDREN,V as MAX_BLOCK_DEPTH,U as MAX_BLOCK_NODES,Y as MAX_BLOCK_TEXT_LEN,S as MAX_FORM_FIELDS,T as MAX_FORM_SELECT_OPTIONS,$ as MAX_SKELETON_LEAVES,_ as MAX_SKELETON_NODES,aa as MAX_SKELETON_TEXT,z as PAGE_SCOPE_RE,x as PROD_KEYLESS_ERROR,ba as REVEAL_MS,t as SNAPSHOT_STORAGE_KEY_PREFIX,fa as _registerConsentUpgradeInit,g as agentIntent,c as agentUaList,s as armOfResult,ea as attachMicroSignalDetectors,q as baselineResultFor,r as baselineSlots,h as classifiedAgents,Z as containsFormBlock,o as deriveSessionSegment,i as detectDeviceClass,n as detectTimeOfDay,j as detectTrafficSource,m as extractTrackedParams,ha as grantConsent,ia as init,ga as isDoNotTrackEnabled,e as matchedAgentToken,A as pageScopeMatches,u as readSnapshot,k as referrerDomainFromReferer,w as renderPrePaintScript,ca as resetRevealStyles,da as reveal,b as sessionCookieName,p as toWireSlot,d as uaTokenMatch,v as writeSnapshot};
2
2
  //# sourceMappingURL=index.mjs.map
@@ -0,0 +1,56 @@
1
+ declare const MAX_SKELETON_NODES = 40;
2
+ declare const MAX_SKELETON_LEAVES = 120;
3
+ declare const MAX_SKELETON_TEXT = 300;
4
+ type SkeletonRole = 'action' | 'heading' | 'text' | 'label' | 'image';
5
+ type SkeletonNode = {
6
+ tag: string;
7
+ role: SkeletonRole;
8
+ level?: 1 | 2 | 3 | 4 | 5 | 6;
9
+ text: string;
10
+ classes: string;
11
+ filled?: boolean;
12
+ href?: string;
13
+ src?: string;
14
+ color: string;
15
+ group: number;
16
+ restylable: boolean;
17
+ };
18
+ type RegionSkeleton = {
19
+ v: 1;
20
+ root: {
21
+ tag: string;
22
+ classes: string;
23
+ ambientBg: string | null;
24
+ ambientBgAlt?: string;
25
+ ambientText: string;
26
+ };
27
+ nodes: SkeletonNode[];
28
+ leaves: string[];
29
+ leafToNode: number[];
30
+ fp: string;
31
+ };
32
+ type ArmEdits = {
33
+ nodes: Record<string, {
34
+ text?: string;
35
+ hidden?: true;
36
+ like?: number;
37
+ }>;
38
+ order?: Record<string, number[]>;
39
+ };
40
+ /** What the requesting page can render for one slot (decide `render` field). */
41
+ type RenderCaps = {
42
+ fp?: string;
43
+ forms: boolean;
44
+ compose: boolean;
45
+ authored?: string[];
46
+ content?: boolean;
47
+ children?: boolean;
48
+ };
49
+ /** How the server serves an `edits` arm (SlotConfigEntry.edits). */
50
+ type ServedEdits = {
51
+ edits: ArmEdits;
52
+ fp: string;
53
+ leafToNode: number[];
54
+ };
55
+
56
+ export { type ArmEdits as A, MAX_SKELETON_LEAVES as M, type RegionSkeleton as R, type ServedEdits as S, MAX_SKELETON_NODES as a, MAX_SKELETON_TEXT as b, type RenderCaps as c, type SkeletonNode as d, type SkeletonRole as e };
@@ -0,0 +1,56 @@
1
+ declare const MAX_SKELETON_NODES = 40;
2
+ declare const MAX_SKELETON_LEAVES = 120;
3
+ declare const MAX_SKELETON_TEXT = 300;
4
+ type SkeletonRole = 'action' | 'heading' | 'text' | 'label' | 'image';
5
+ type SkeletonNode = {
6
+ tag: string;
7
+ role: SkeletonRole;
8
+ level?: 1 | 2 | 3 | 4 | 5 | 6;
9
+ text: string;
10
+ classes: string;
11
+ filled?: boolean;
12
+ href?: string;
13
+ src?: string;
14
+ color: string;
15
+ group: number;
16
+ restylable: boolean;
17
+ };
18
+ type RegionSkeleton = {
19
+ v: 1;
20
+ root: {
21
+ tag: string;
22
+ classes: string;
23
+ ambientBg: string | null;
24
+ ambientBgAlt?: string;
25
+ ambientText: string;
26
+ };
27
+ nodes: SkeletonNode[];
28
+ leaves: string[];
29
+ leafToNode: number[];
30
+ fp: string;
31
+ };
32
+ type ArmEdits = {
33
+ nodes: Record<string, {
34
+ text?: string;
35
+ hidden?: true;
36
+ like?: number;
37
+ }>;
38
+ order?: Record<string, number[]>;
39
+ };
40
+ /** What the requesting page can render for one slot (decide `render` field). */
41
+ type RenderCaps = {
42
+ fp?: string;
43
+ forms: boolean;
44
+ compose: boolean;
45
+ authored?: string[];
46
+ content?: boolean;
47
+ children?: boolean;
48
+ };
49
+ /** How the server serves an `edits` arm (SlotConfigEntry.edits). */
50
+ type ServedEdits = {
51
+ edits: ArmEdits;
52
+ fp: string;
53
+ leafToNode: number[];
54
+ };
55
+
56
+ export { type ArmEdits as A, MAX_SKELETON_LEAVES as M, type RegionSkeleton as R, type ServedEdits as S, MAX_SKELETON_NODES as a, MAX_SKELETON_TEXT as b, type RenderCaps as c, type SkeletonNode as d, type SkeletonRole as e };
@@ -0,0 +1,226 @@
1
+ import { SlotResult, SlotDecl } from '@sentientui/policy';
2
+ import { v as BlockNode, F as ComposeArm, $ as SitePalette, a4 as StyleVocabulary } from './style-vocabulary-BqviEw9O.js';
3
+ import { S as ServedEdits } from './region-skeleton-CQ4yhVw1.js';
4
+
5
+ /**
6
+ * Slot declaration helpers shared by the browser client (decide) and the
7
+ * server preload path. Pure wrappers over @sentientui/policy.
8
+ */
9
+
10
+ /** SDK-facing slot declaration. `dims` accepts readonly arrays (`as const`). */
11
+ type SlotDeclInput = {
12
+ id: string;
13
+ arms?: string[];
14
+ dims?: Record<string, readonly string[]>;
15
+ baseline?: string | Record<string, string>;
16
+ };
17
+
18
+ /**
19
+ * Whitelists the wire fields of a slot declaration. Anything an SDK layer
20
+ * attached (goal configs, refs, …) is stripped so it never reaches the zod
21
+ * schema on the API. Also normalizes readonly arrays to mutable ones.
22
+ */
23
+ declare function toWireSlot(d: SlotDeclInput): SlotDecl;
24
+ /** The declared (or default first-declared) baseline result for a slot. */
25
+ declare function baselineResultFor(d: SlotDeclInput): SlotResult;
26
+ /** Baseline results for a whole declaration list, keyed by slot id. */
27
+ declare function baselineSlots(decls: SlotDeclInput[]): Record<string, SlotResult>;
28
+ /**
29
+ * Canonical arm string of a slot result: dims results encode as sorted
30
+ * `dim=value` pairs joined with '|'; arms results are the arm id verbatim.
31
+ */
32
+ declare function armOfResult(result: SlotResult): string;
33
+
34
+ declare const SNAPSHOT_STORAGE_KEY_PREFIX = "_snt_snap:";
35
+ /** Versioned compound locator: resolve id → dataAttr → selector, then verify
36
+ * against fingerprint. Lets a slot survive DOM/markup drift. */
37
+ type CompoundLocator = {
38
+ v?: number;
39
+ id?: string;
40
+ dataAttr?: {
41
+ name: string;
42
+ value: string;
43
+ };
44
+ selector?: string;
45
+ urlMatch?: string;
46
+ /** Where the element is expected to exist — see page-scope.ts. Health only, never serving. */
47
+ page?: string;
48
+ fingerprint?: {
49
+ tag?: string;
50
+ text?: string;
51
+ };
52
+ semanticId?: string;
53
+ };
54
+ /** Bounded, declarative operations a registry arm may apply to its element.
55
+ * The style set is a fixed whitelist (validated server-side); no arbitrary CSS,
56
+ * HTML, or JS ever. `text` is applied via textContent; https-only URLs.
57
+ * moveBefore/moveAfter (exactly one) reposition the element relative to a
58
+ * uniquely-resolving sibling anchor — post-decide only, never pre-paint. */
59
+ type SlotOps = {
60
+ text?: string;
61
+ style?: Record<string, string>;
62
+ hidden?: boolean;
63
+ href?: string;
64
+ imageSrc?: string;
65
+ imageAlt?: string;
66
+ moveBefore?: CompoundLocator;
67
+ moveAfter?: CompoundLocator;
68
+ };
69
+ /** Registry-mode apply info per slot: where to apply and what to set. Stored so
70
+ * a returning visitor's pre-paint can reapply it. `target` is the Phase-2 bare
71
+ * selector; `locator` (Phase 3) is the compound locator, preferred when present. */
72
+ type SlotConfigEntry = {
73
+ kind: 'tokens' | 'arms';
74
+ target?: string;
75
+ locator?: CompoundLocator;
76
+ content?: string;
77
+ ops?: SlotOps;
78
+ /** Composition Blocks per arm — ALL arms, not just the served one, because
79
+ * Option-B rendering pre-paints every arm hidden and reveals the served one
80
+ * (spec §6). Holdout sessions receive the baseline arm's tree only, so the
81
+ * control group's DOM stays meaningful. Absent for non-composition slots. */
82
+ blocks?: Record<string, BlockNode>;
83
+ /** The served Rewrite arm (spec 2026-09-23 §4.3): per-node edits plus the
84
+ * skeleton fingerprint and leaf map they were written against. */
85
+ edits?: ServedEdits;
86
+ /** The server has no skeleton for this region — capture and report one. */
87
+ needsSkeleton?: true;
88
+ /** Redesign arms per arm id — ALL arms, same Option-B reason as `blocks`.
89
+ * Served only to pages that declared RenderCaps.compose. */
90
+ compose?: Record<string, ComposeArm>;
91
+ /** A hybrid <Adaptive> held back: its id still has un-migrated variant
92
+ * history, so the page renders its original until the operator migrates. */
93
+ blocked?: 'variant_history';
94
+ };
95
+ type DecisionSnapshot = {
96
+ v: 1;
97
+ persona: string;
98
+ band: 'low' | 'medium' | 'high';
99
+ slots: Record<string, SlotResult>;
100
+ layoutOrder: string[] | null;
101
+ savedAt: number;
102
+ slotConfig?: Record<string, SlotConfigEntry>;
103
+ /** Derived site palette for Composition Block rendering — cached so the
104
+ * pre-paint render already looks native (a palette that pops in post-decide
105
+ * would be its own flash). */
106
+ palette?: SitePalette;
107
+ /** The site-style entries the served compose arms reference — cached so the
108
+ * pre-paint render already borrows the site's classes. Additive (v stays 1). */
109
+ vocabulary?: StyleVocabulary;
110
+ };
111
+ /** Returns null on missing, corrupt, or wrong-version data — never throws. */
112
+ declare function readSnapshot(apiKey: string): DecisionSnapshot | null;
113
+ /** Best-effort persist — storage failures are swallowed. */
114
+ declare function writeSnapshot(apiKey: string, snap: DecisionSnapshot): void;
115
+ /**
116
+ * Inline pre-paint script (Rung 1a): reads the snapshot and sets
117
+ * `data-sentient-persona` / `data-sentient-confidence` on <html> before
118
+ * first paint. Single-writer: it never overwrites attributes already set.
119
+ *
120
+ * Safety properties (pinned by tests):
121
+ * - apiKey goes through JSON.stringify, then '<' is escaped to <, so a
122
+ * hostile key can neither break the JS string nor terminate the <script>.
123
+ * - Built by string concatenation and contains no backticks, so the output
124
+ * survives being embedded in template-literal-based renderers.
125
+ */
126
+ declare function renderPrePaintScript(apiKey: string): string;
127
+
128
+ /** Session metadata helpers (browser + Node). No DOM APIs. */
129
+ /**
130
+ * Known AI-agent / crawler user-agent tokens. Matched case-insensitively as
131
+ * substrings. This is maintained data — bot lists move monthly. Used both to
132
+ * flag automation on sessions (agentic browsers that leak a token) and by the
133
+ * server middleware / agent-feed route to identify crawler HTTP reads.
134
+ */
135
+ declare const agentUaList: readonly string[];
136
+ /** True when the user-agent contains a known AI-agent / crawler token. */
137
+ declare function uaTokenMatch(userAgent: string): boolean;
138
+ /** The first known agent token found in the user-agent, or null. */
139
+ declare function matchedAgentToken(userAgent: string): string | null;
140
+ /**
141
+ * Purpose category for an agent fetch, inferred from its published user-agent:
142
+ * - `user` — a person asked an assistant to read the page, live (…-User UAs)
143
+ * - `search` — indexing for an AI answer engine (…-SearchBot / SearchBot)
144
+ * - `training` — model-training crawl (GPTBot, ClaudeBot, CCBot, …)
145
+ * - `other` — not clearly AI, or an unknown/new token
146
+ */
147
+ type AgentIntent = 'user' | 'search' | 'training' | 'other';
148
+ /** Intent per agent token. Maintained beside `agentUaList` — when you add or
149
+ * rename a token above, set its intent here (a unit test enforces coverage). */
150
+ declare const AGENT_INTENTS: Record<string, AgentIntent>;
151
+ /** Intent for a matched bot token (case-insensitive); `other` for null/unknown. */
152
+ declare function agentIntent(botName: string | null): AgentIntent;
153
+ /** `agentUaList` grouped by intent — the "which crawlers do you classify?" reference. */
154
+ declare function classifiedAgents(): Record<AgentIntent, string[]>;
155
+ declare function detectDeviceClass(userAgent: string): string;
156
+ declare function detectTrafficSource(referrer: string, appOrigin?: string): string;
157
+ declare function referrerDomainFromReferer(referrer: string): string | null;
158
+ /**
159
+ * Ad-platform click-ID query params worth keeping. An ALLOWLIST, unlike the
160
+ * `utm_` prefix match: unknown query keys here are unbounded-cardinality junk
161
+ * (session tokens, cache busters) that would bloat the sessions table, so only
162
+ * the IDs the major ad platforms actually append survive.
163
+ *
164
+ * gclid / gbraid / wbraid — Google Ads auto-tagging (search, YouTube, Display;
165
+ * gbraid/wbraid are the iOS-14 privacy variants)
166
+ * fbclid — Meta (Facebook + Instagram). Appended to EVERY outbound Meta
167
+ * click, paid and organic alike — it identifies the platform, never spend.
168
+ * ttclid — TikTok Ads
169
+ * msclkid — Microsoft Ads (Bing)
170
+ * twclid — X/Twitter Ads
171
+ * li_fat_id — LinkedIn Ads
172
+ */
173
+ declare const CLICK_ID_KEYS: readonly string[];
174
+ /**
175
+ * Splits a URL query into the attribution params the session upsert carries:
176
+ * every `utm_`-prefixed key, plus allowlisted ad click IDs (CLICK_ID_KEYS).
177
+ * Accepts a raw search string ("?a=b" or "a=b"), a URLSearchParams, or a
178
+ * Next.js `searchParams` object (whose values may be string arrays — the
179
+ * first occurrence wins, matching URLSearchParams iteration order).
180
+ * Node-safe: no DOM APIs.
181
+ */
182
+ declare function extractTrackedParams(search: string | URLSearchParams | Record<string, string | string[] | undefined>): {
183
+ utmParams: Record<string, string>;
184
+ clickIds: Record<string, string>;
185
+ };
186
+ declare function detectTimeOfDay(d: Date): string;
187
+ type SessionUpsertPayload = {
188
+ sessionId: string;
189
+ ephemeral: boolean;
190
+ utmParams: Record<string, string>;
191
+ /** Allowlisted ad-platform click IDs from the landing URL (CLICK_ID_KEYS). */
192
+ clickIds: Record<string, string>;
193
+ deviceClass: string;
194
+ trafficSource: string;
195
+ referrerDomain: string | null;
196
+ timeOfDay: string;
197
+ dayOfWeek: string;
198
+ /**
199
+ * True when this session is likely driven by automation — either
200
+ * `navigator.webdriver` was set, or the user-agent carried a known agent
201
+ * token. Probabilistic: a flag for metrics + bandit exclusion, never a gate.
202
+ */
203
+ automation: boolean;
204
+ };
205
+ /** Bandit segment key: `<device_class>:<traffic_source>`. */
206
+ declare function deriveSessionSegment(opts?: {
207
+ userAgent?: string;
208
+ referer?: string;
209
+ appOrigin?: string;
210
+ }): string;
211
+ /**
212
+ * Builds a session upsert body aligned with the browser SDK so SSR assign uses
213
+ * the same segment key (`device:source`) as the client after hydration.
214
+ */
215
+ declare function buildSessionUpsertPayload(sessionId: string, opts?: {
216
+ userAgent?: string;
217
+ referer?: string;
218
+ appOrigin?: string;
219
+ utmParams?: Record<string, string>;
220
+ clickIds?: Record<string, string>;
221
+ now?: Date;
222
+ /** `navigator.webdriver` value from the browser, when available. */
223
+ webdriver?: boolean;
224
+ }): SessionUpsertPayload;
225
+
226
+ export { AGENT_INTENTS as A, CLICK_ID_KEYS as C, type DecisionSnapshot as D, SNAPSHOT_STORAGE_KEY_PREFIX as S, type AgentIntent as a, type CompoundLocator as b, type SessionUpsertPayload as c, type SlotConfigEntry as d, type SlotDeclInput as e, type SlotOps as f, agentIntent as g, agentUaList as h, armOfResult as i, baselineResultFor as j, baselineSlots as k, buildSessionUpsertPayload as l, classifiedAgents as m, deriveSessionSegment as n, detectDeviceClass as o, detectTimeOfDay as p, detectTrafficSource as q, extractTrackedParams as r, matchedAgentToken as s, readSnapshot as t, referrerDomainFromReferer as u, renderPrePaintScript as v, toWireSlot as w, uaTokenMatch as x, writeSnapshot as y };
@@ -0,0 +1,226 @@
1
+ import { SlotResult, SlotDecl } from '@sentientui/policy';
2
+ import { v as BlockNode, F as ComposeArm, $ as SitePalette, a4 as StyleVocabulary } from './style-vocabulary-BqviEw9O.cjs';
3
+ import { S as ServedEdits } from './region-skeleton-CQ4yhVw1.cjs';
4
+
5
+ /**
6
+ * Slot declaration helpers shared by the browser client (decide) and the
7
+ * server preload path. Pure wrappers over @sentientui/policy.
8
+ */
9
+
10
+ /** SDK-facing slot declaration. `dims` accepts readonly arrays (`as const`). */
11
+ type SlotDeclInput = {
12
+ id: string;
13
+ arms?: string[];
14
+ dims?: Record<string, readonly string[]>;
15
+ baseline?: string | Record<string, string>;
16
+ };
17
+
18
+ /**
19
+ * Whitelists the wire fields of a slot declaration. Anything an SDK layer
20
+ * attached (goal configs, refs, …) is stripped so it never reaches the zod
21
+ * schema on the API. Also normalizes readonly arrays to mutable ones.
22
+ */
23
+ declare function toWireSlot(d: SlotDeclInput): SlotDecl;
24
+ /** The declared (or default first-declared) baseline result for a slot. */
25
+ declare function baselineResultFor(d: SlotDeclInput): SlotResult;
26
+ /** Baseline results for a whole declaration list, keyed by slot id. */
27
+ declare function baselineSlots(decls: SlotDeclInput[]): Record<string, SlotResult>;
28
+ /**
29
+ * Canonical arm string of a slot result: dims results encode as sorted
30
+ * `dim=value` pairs joined with '|'; arms results are the arm id verbatim.
31
+ */
32
+ declare function armOfResult(result: SlotResult): string;
33
+
34
+ declare const SNAPSHOT_STORAGE_KEY_PREFIX = "_snt_snap:";
35
+ /** Versioned compound locator: resolve id → dataAttr → selector, then verify
36
+ * against fingerprint. Lets a slot survive DOM/markup drift. */
37
+ type CompoundLocator = {
38
+ v?: number;
39
+ id?: string;
40
+ dataAttr?: {
41
+ name: string;
42
+ value: string;
43
+ };
44
+ selector?: string;
45
+ urlMatch?: string;
46
+ /** Where the element is expected to exist — see page-scope.ts. Health only, never serving. */
47
+ page?: string;
48
+ fingerprint?: {
49
+ tag?: string;
50
+ text?: string;
51
+ };
52
+ semanticId?: string;
53
+ };
54
+ /** Bounded, declarative operations a registry arm may apply to its element.
55
+ * The style set is a fixed whitelist (validated server-side); no arbitrary CSS,
56
+ * HTML, or JS ever. `text` is applied via textContent; https-only URLs.
57
+ * moveBefore/moveAfter (exactly one) reposition the element relative to a
58
+ * uniquely-resolving sibling anchor — post-decide only, never pre-paint. */
59
+ type SlotOps = {
60
+ text?: string;
61
+ style?: Record<string, string>;
62
+ hidden?: boolean;
63
+ href?: string;
64
+ imageSrc?: string;
65
+ imageAlt?: string;
66
+ moveBefore?: CompoundLocator;
67
+ moveAfter?: CompoundLocator;
68
+ };
69
+ /** Registry-mode apply info per slot: where to apply and what to set. Stored so
70
+ * a returning visitor's pre-paint can reapply it. `target` is the Phase-2 bare
71
+ * selector; `locator` (Phase 3) is the compound locator, preferred when present. */
72
+ type SlotConfigEntry = {
73
+ kind: 'tokens' | 'arms';
74
+ target?: string;
75
+ locator?: CompoundLocator;
76
+ content?: string;
77
+ ops?: SlotOps;
78
+ /** Composition Blocks per arm — ALL arms, not just the served one, because
79
+ * Option-B rendering pre-paints every arm hidden and reveals the served one
80
+ * (spec §6). Holdout sessions receive the baseline arm's tree only, so the
81
+ * control group's DOM stays meaningful. Absent for non-composition slots. */
82
+ blocks?: Record<string, BlockNode>;
83
+ /** The served Rewrite arm (spec 2026-09-23 §4.3): per-node edits plus the
84
+ * skeleton fingerprint and leaf map they were written against. */
85
+ edits?: ServedEdits;
86
+ /** The server has no skeleton for this region — capture and report one. */
87
+ needsSkeleton?: true;
88
+ /** Redesign arms per arm id — ALL arms, same Option-B reason as `blocks`.
89
+ * Served only to pages that declared RenderCaps.compose. */
90
+ compose?: Record<string, ComposeArm>;
91
+ /** A hybrid <Adaptive> held back: its id still has un-migrated variant
92
+ * history, so the page renders its original until the operator migrates. */
93
+ blocked?: 'variant_history';
94
+ };
95
+ type DecisionSnapshot = {
96
+ v: 1;
97
+ persona: string;
98
+ band: 'low' | 'medium' | 'high';
99
+ slots: Record<string, SlotResult>;
100
+ layoutOrder: string[] | null;
101
+ savedAt: number;
102
+ slotConfig?: Record<string, SlotConfigEntry>;
103
+ /** Derived site palette for Composition Block rendering — cached so the
104
+ * pre-paint render already looks native (a palette that pops in post-decide
105
+ * would be its own flash). */
106
+ palette?: SitePalette;
107
+ /** The site-style entries the served compose arms reference — cached so the
108
+ * pre-paint render already borrows the site's classes. Additive (v stays 1). */
109
+ vocabulary?: StyleVocabulary;
110
+ };
111
+ /** Returns null on missing, corrupt, or wrong-version data — never throws. */
112
+ declare function readSnapshot(apiKey: string): DecisionSnapshot | null;
113
+ /** Best-effort persist — storage failures are swallowed. */
114
+ declare function writeSnapshot(apiKey: string, snap: DecisionSnapshot): void;
115
+ /**
116
+ * Inline pre-paint script (Rung 1a): reads the snapshot and sets
117
+ * `data-sentient-persona` / `data-sentient-confidence` on <html> before
118
+ * first paint. Single-writer: it never overwrites attributes already set.
119
+ *
120
+ * Safety properties (pinned by tests):
121
+ * - apiKey goes through JSON.stringify, then '<' is escaped to <, so a
122
+ * hostile key can neither break the JS string nor terminate the <script>.
123
+ * - Built by string concatenation and contains no backticks, so the output
124
+ * survives being embedded in template-literal-based renderers.
125
+ */
126
+ declare function renderPrePaintScript(apiKey: string): string;
127
+
128
+ /** Session metadata helpers (browser + Node). No DOM APIs. */
129
+ /**
130
+ * Known AI-agent / crawler user-agent tokens. Matched case-insensitively as
131
+ * substrings. This is maintained data — bot lists move monthly. Used both to
132
+ * flag automation on sessions (agentic browsers that leak a token) and by the
133
+ * server middleware / agent-feed route to identify crawler HTTP reads.
134
+ */
135
+ declare const agentUaList: readonly string[];
136
+ /** True when the user-agent contains a known AI-agent / crawler token. */
137
+ declare function uaTokenMatch(userAgent: string): boolean;
138
+ /** The first known agent token found in the user-agent, or null. */
139
+ declare function matchedAgentToken(userAgent: string): string | null;
140
+ /**
141
+ * Purpose category for an agent fetch, inferred from its published user-agent:
142
+ * - `user` — a person asked an assistant to read the page, live (…-User UAs)
143
+ * - `search` — indexing for an AI answer engine (…-SearchBot / SearchBot)
144
+ * - `training` — model-training crawl (GPTBot, ClaudeBot, CCBot, …)
145
+ * - `other` — not clearly AI, or an unknown/new token
146
+ */
147
+ type AgentIntent = 'user' | 'search' | 'training' | 'other';
148
+ /** Intent per agent token. Maintained beside `agentUaList` — when you add or
149
+ * rename a token above, set its intent here (a unit test enforces coverage). */
150
+ declare const AGENT_INTENTS: Record<string, AgentIntent>;
151
+ /** Intent for a matched bot token (case-insensitive); `other` for null/unknown. */
152
+ declare function agentIntent(botName: string | null): AgentIntent;
153
+ /** `agentUaList` grouped by intent — the "which crawlers do you classify?" reference. */
154
+ declare function classifiedAgents(): Record<AgentIntent, string[]>;
155
+ declare function detectDeviceClass(userAgent: string): string;
156
+ declare function detectTrafficSource(referrer: string, appOrigin?: string): string;
157
+ declare function referrerDomainFromReferer(referrer: string): string | null;
158
+ /**
159
+ * Ad-platform click-ID query params worth keeping. An ALLOWLIST, unlike the
160
+ * `utm_` prefix match: unknown query keys here are unbounded-cardinality junk
161
+ * (session tokens, cache busters) that would bloat the sessions table, so only
162
+ * the IDs the major ad platforms actually append survive.
163
+ *
164
+ * gclid / gbraid / wbraid — Google Ads auto-tagging (search, YouTube, Display;
165
+ * gbraid/wbraid are the iOS-14 privacy variants)
166
+ * fbclid — Meta (Facebook + Instagram). Appended to EVERY outbound Meta
167
+ * click, paid and organic alike — it identifies the platform, never spend.
168
+ * ttclid — TikTok Ads
169
+ * msclkid — Microsoft Ads (Bing)
170
+ * twclid — X/Twitter Ads
171
+ * li_fat_id — LinkedIn Ads
172
+ */
173
+ declare const CLICK_ID_KEYS: readonly string[];
174
+ /**
175
+ * Splits a URL query into the attribution params the session upsert carries:
176
+ * every `utm_`-prefixed key, plus allowlisted ad click IDs (CLICK_ID_KEYS).
177
+ * Accepts a raw search string ("?a=b" or "a=b"), a URLSearchParams, or a
178
+ * Next.js `searchParams` object (whose values may be string arrays — the
179
+ * first occurrence wins, matching URLSearchParams iteration order).
180
+ * Node-safe: no DOM APIs.
181
+ */
182
+ declare function extractTrackedParams(search: string | URLSearchParams | Record<string, string | string[] | undefined>): {
183
+ utmParams: Record<string, string>;
184
+ clickIds: Record<string, string>;
185
+ };
186
+ declare function detectTimeOfDay(d: Date): string;
187
+ type SessionUpsertPayload = {
188
+ sessionId: string;
189
+ ephemeral: boolean;
190
+ utmParams: Record<string, string>;
191
+ /** Allowlisted ad-platform click IDs from the landing URL (CLICK_ID_KEYS). */
192
+ clickIds: Record<string, string>;
193
+ deviceClass: string;
194
+ trafficSource: string;
195
+ referrerDomain: string | null;
196
+ timeOfDay: string;
197
+ dayOfWeek: string;
198
+ /**
199
+ * True when this session is likely driven by automation — either
200
+ * `navigator.webdriver` was set, or the user-agent carried a known agent
201
+ * token. Probabilistic: a flag for metrics + bandit exclusion, never a gate.
202
+ */
203
+ automation: boolean;
204
+ };
205
+ /** Bandit segment key: `<device_class>:<traffic_source>`. */
206
+ declare function deriveSessionSegment(opts?: {
207
+ userAgent?: string;
208
+ referer?: string;
209
+ appOrigin?: string;
210
+ }): string;
211
+ /**
212
+ * Builds a session upsert body aligned with the browser SDK so SSR assign uses
213
+ * the same segment key (`device:source`) as the client after hydration.
214
+ */
215
+ declare function buildSessionUpsertPayload(sessionId: string, opts?: {
216
+ userAgent?: string;
217
+ referer?: string;
218
+ appOrigin?: string;
219
+ utmParams?: Record<string, string>;
220
+ clickIds?: Record<string, string>;
221
+ now?: Date;
222
+ /** `navigator.webdriver` value from the browser, when available. */
223
+ webdriver?: boolean;
224
+ }): SessionUpsertPayload;
225
+
226
+ export { AGENT_INTENTS as A, CLICK_ID_KEYS as C, type DecisionSnapshot as D, SNAPSHOT_STORAGE_KEY_PREFIX as S, type AgentIntent as a, type CompoundLocator as b, type SessionUpsertPayload as c, type SlotConfigEntry as d, type SlotDeclInput as e, type SlotOps as f, agentIntent as g, agentUaList as h, armOfResult as i, baselineResultFor as j, baselineSlots as k, buildSessionUpsertPayload as l, classifiedAgents as m, deriveSessionSegment as n, detectDeviceClass as o, detectTimeOfDay as p, detectTrafficSource as q, extractTrackedParams as r, matchedAgentToken as s, readSnapshot as t, referrerDomainFromReferer as u, renderPrePaintScript as v, toWireSlot as w, uaTokenMatch as x, writeSnapshot as y };