@sentientui/core 0.33.0 → 0.34.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/dist/chunk-DGRAS5VP.mjs +2 -0
- package/dist/chunk-DGRAS5VP.mjs.map +1 -0
- package/dist/chunk-G6VP7HGJ.mjs +2 -0
- package/dist/chunk-G6VP7HGJ.mjs.map +1 -0
- package/dist/chunk-NCLBL5V3.mjs +2 -0
- package/dist/chunk-NCLBL5V3.mjs.map +1 -0
- package/dist/{index-COl_pfNm.d.cts → index-DX-MuX8O.d.ts} +43 -4
- package/dist/{index-CgkImSaM.d.ts → index-DnQbmMkx.d.cts} +43 -4
- package/dist/index-engagement.js +1 -1
- package/dist/index-engagement.js.map +1 -1
- package/dist/index-engagement.mjs +1 -1
- package/dist/index-engagement.mjs.map +1 -1
- package/dist/index-graph.d.cts +6 -4
- package/dist/index-graph.d.ts +6 -4
- package/dist/index-graph.js +1 -1
- package/dist/index-graph.js.map +1 -1
- package/dist/index-graph.mjs +1 -1
- package/dist/index-graph.mjs.map +1 -1
- package/dist/index-local.d.cts +4 -2
- package/dist/index-local.d.ts +4 -2
- package/dist/index-region.d.cts +40 -0
- package/dist/index-region.d.ts +40 -0
- package/dist/index-region.js +2 -0
- package/dist/index-region.js.map +1 -0
- package/dist/index-region.mjs +2 -0
- package/dist/index-region.mjs.map +1 -0
- package/dist/index-server.d.cts +15 -2
- package/dist/index-server.d.ts +15 -2
- package/dist/index-server.js +1 -1
- package/dist/index-server.js.map +1 -1
- package/dist/index-server.mjs +1 -1
- package/dist/index-server.mjs.map +1 -1
- package/dist/index-style-sample.d.cts +12 -0
- package/dist/index-style-sample.d.ts +12 -0
- package/dist/index-style-sample.js +2 -0
- package/dist/index-style-sample.js.map +1 -0
- package/dist/index-style-sample.mjs +2 -0
- package/dist/index-style-sample.mjs.map +1 -0
- package/dist/index.d.cts +4 -2
- package/dist/index.d.ts +4 -2
- package/dist/index.js +1 -1
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +1 -1
- package/dist/region-skeleton-D2ahkcbe.d.cts +61 -0
- package/dist/region-skeleton-D2ahkcbe.d.ts +61 -0
- package/dist/session-meta-B0sXgtFN.d.ts +226 -0
- package/dist/session-meta-Dk8ivs-l.d.cts +226 -0
- package/dist/style-vocabulary-BqviEw9O.d.cts +285 -0
- package/dist/style-vocabulary-BqviEw9O.d.ts +285 -0
- package/package.json +11 -1
- package/dist/chunk-EVYMV2C6.mjs +0 -2
- package/dist/chunk-EVYMV2C6.mjs.map +0 -1
- package/dist/session-meta-DydKfQiR.d.cts +0 -416
- 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
|
|
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-NCLBL5V3.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,61 @@
|
|
|
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
|
+
/** false = the page can't address these elements for per-element edits
|
|
32
|
+
* (React: the region wraps a component whose text the element tree can't
|
|
33
|
+
* see). The capture still describes the region — enough to REDESIGN it,
|
|
34
|
+
* which replaces the whole region — but no Rewrite arm may target it. */
|
|
35
|
+
editable?: false;
|
|
36
|
+
};
|
|
37
|
+
type ArmEdits = {
|
|
38
|
+
nodes: Record<string, {
|
|
39
|
+
text?: string;
|
|
40
|
+
hidden?: true;
|
|
41
|
+
like?: number;
|
|
42
|
+
}>;
|
|
43
|
+
order?: Record<string, number[]>;
|
|
44
|
+
};
|
|
45
|
+
/** What the requesting page can render for one slot (decide `render` field). */
|
|
46
|
+
type RenderCaps = {
|
|
47
|
+
fp?: string;
|
|
48
|
+
forms: boolean;
|
|
49
|
+
compose: boolean;
|
|
50
|
+
authored?: string[];
|
|
51
|
+
content?: boolean;
|
|
52
|
+
children?: boolean;
|
|
53
|
+
};
|
|
54
|
+
/** How the server serves an `edits` arm (SlotConfigEntry.edits). */
|
|
55
|
+
type ServedEdits = {
|
|
56
|
+
edits: ArmEdits;
|
|
57
|
+
fp: string;
|
|
58
|
+
leafToNode: number[];
|
|
59
|
+
};
|
|
60
|
+
|
|
61
|
+
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,61 @@
|
|
|
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
|
+
/** false = the page can't address these elements for per-element edits
|
|
32
|
+
* (React: the region wraps a component whose text the element tree can't
|
|
33
|
+
* see). The capture still describes the region — enough to REDESIGN it,
|
|
34
|
+
* which replaces the whole region — but no Rewrite arm may target it. */
|
|
35
|
+
editable?: false;
|
|
36
|
+
};
|
|
37
|
+
type ArmEdits = {
|
|
38
|
+
nodes: Record<string, {
|
|
39
|
+
text?: string;
|
|
40
|
+
hidden?: true;
|
|
41
|
+
like?: number;
|
|
42
|
+
}>;
|
|
43
|
+
order?: Record<string, number[]>;
|
|
44
|
+
};
|
|
45
|
+
/** What the requesting page can render for one slot (decide `render` field). */
|
|
46
|
+
type RenderCaps = {
|
|
47
|
+
fp?: string;
|
|
48
|
+
forms: boolean;
|
|
49
|
+
compose: boolean;
|
|
50
|
+
authored?: string[];
|
|
51
|
+
content?: boolean;
|
|
52
|
+
children?: boolean;
|
|
53
|
+
};
|
|
54
|
+
/** How the server serves an `edits` arm (SlotConfigEntry.edits). */
|
|
55
|
+
type ServedEdits = {
|
|
56
|
+
edits: ArmEdits;
|
|
57
|
+
fp: string;
|
|
58
|
+
leafToNode: number[];
|
|
59
|
+
};
|
|
60
|
+
|
|
61
|
+
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-D2ahkcbe.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-D2ahkcbe.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 };
|