@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.
- package/dist/chunk-3FKD44SF.mjs +2 -0
- package/dist/chunk-3FKD44SF.mjs.map +1 -0
- package/dist/chunk-DGRAS5VP.mjs +2 -0
- package/dist/chunk-DGRAS5VP.mjs.map +1 -0
- package/dist/{index-CgkImSaM.d.ts → index-C2EOL-_c.d.cts} +43 -4
- package/dist/{index-COl_pfNm.d.cts → index-DrMXbLKP.d.ts} +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 +74 -3
- package/dist/index-server.d.ts +74 -3
- 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-CQ4yhVw1.d.cts +56 -0
- package/dist/region-skeleton-CQ4yhVw1.d.ts +56 -0
- package/dist/session-meta-CWGtzFOQ.d.ts +226 -0
- package/dist/session-meta-KwDqU9a8.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
|
@@ -1,416 +0,0 @@
|
|
|
1
|
-
import { SlotResult, SlotDecl } from '@sentientui/policy';
|
|
2
|
-
|
|
3
|
-
/**
|
|
4
|
-
* Composition Blocks (spec: 2026-08-20-nocode-composition-variants-design.md §4).
|
|
5
|
-
*
|
|
6
|
-
* A bounded, TYPED component tree — never HTML — that a registry arm may carry
|
|
7
|
-
* (`published_config.arms[].blocks`). The vocabulary is the whitelist: every
|
|
8
|
-
* prop value is an enumerated token, validated server-side before publish
|
|
9
|
-
* (apps/api/src/domain/composition-blocks.ts) and rendered client-side through
|
|
10
|
-
* document.createElement + property assignment only. No innerHTML/outerHTML/
|
|
11
|
-
* insertAdjacentHTML exists anywhere on this path — the security property is
|
|
12
|
-
* preserved by never accepting HTML, not by sanitizing it, which is why there
|
|
13
|
-
* is no sanitizer to keep honest.
|
|
14
|
-
*
|
|
15
|
-
* Token lists live here (not in the API domain like SlotOps' mirrors) because
|
|
16
|
-
* three parties must agree byte-for-byte: the server validator, the snippet
|
|
17
|
-
* renderer, and eventually the React renderer (§11) — a drifted copy would let
|
|
18
|
-
* a published arm fail to render, which the fail-safe turns into an invisibly
|
|
19
|
-
* missing section, not an error.
|
|
20
|
-
*/
|
|
21
|
-
declare const BLOCK_GAPS: readonly ["none", "sm", "md", "lg"];
|
|
22
|
-
declare const BLOCK_ALIGNS: readonly ["start", "center", "end", "stretch"];
|
|
23
|
-
declare const BLOCK_JUSTIFIES: readonly ["start", "center", "end", "between"];
|
|
24
|
-
declare const BLOCK_SIZES: readonly ["sm", "md", "lg"];
|
|
25
|
-
declare const BLOCK_WEIGHTS: readonly ["normal", "medium", "bold"];
|
|
26
|
-
declare const BLOCK_TONES: readonly ["default", "muted", "accent"];
|
|
27
|
-
declare const BLOCK_EMPHASES: readonly ["primary", "secondary", "ghost"];
|
|
28
|
-
declare const BLOCK_TEXT_ALIGNS: readonly ["left", "center", "right"];
|
|
29
|
-
declare const BLOCK_RATIOS: readonly ["auto", "square", "landscape", "wide"];
|
|
30
|
-
declare const BLOCK_FITS: readonly ["cover", "contain"];
|
|
31
|
-
declare const BLOCK_GRID_COLUMNS: readonly [2, 3, 4];
|
|
32
|
-
declare const BLOCK_HEADING_LEVELS: readonly [2, 3, 4];
|
|
33
|
-
declare const BLOCK_SURFACES: readonly ["default", "raised"];
|
|
34
|
-
declare const BLOCK_PADS: readonly ["none", "sm", "md", "lg"];
|
|
35
|
-
declare const BLOCK_MAX_WIDTHS: readonly ["measure"];
|
|
36
|
-
type BlockGap = (typeof BLOCK_GAPS)[number];
|
|
37
|
-
type BlockAlign = (typeof BLOCK_ALIGNS)[number];
|
|
38
|
-
type BlockJustify = (typeof BLOCK_JUSTIFIES)[number];
|
|
39
|
-
type BlockSize = (typeof BLOCK_SIZES)[number];
|
|
40
|
-
type BlockWeight = (typeof BLOCK_WEIGHTS)[number];
|
|
41
|
-
type BlockTone = (typeof BLOCK_TONES)[number];
|
|
42
|
-
type BlockEmphasis = (typeof BLOCK_EMPHASES)[number];
|
|
43
|
-
type BlockTextAlign = (typeof BLOCK_TEXT_ALIGNS)[number];
|
|
44
|
-
type BlockRatio = (typeof BLOCK_RATIOS)[number];
|
|
45
|
-
type BlockFit = (typeof BLOCK_FITS)[number];
|
|
46
|
-
type BlockSurface = (typeof BLOCK_SURFACES)[number];
|
|
47
|
-
type BlockPad = (typeof BLOCK_PADS)[number];
|
|
48
|
-
type BlockMaxWidth = (typeof BLOCK_MAX_WIDTHS)[number];
|
|
49
|
-
/** Flex row/column container. `surface: 'raised'` renders it as a card
|
|
50
|
-
* (palette surface bg + border hairline + radius + readable text pairing);
|
|
51
|
-
* a raised stack with no `pad` defaults to `md` — a zero-padding card is a
|
|
52
|
-
* design bug both renderers refuse to reproduce. */
|
|
53
|
-
type StackBlock = {
|
|
54
|
-
type: 'stack';
|
|
55
|
-
direction: 'row' | 'column';
|
|
56
|
-
children: BlockNode[];
|
|
57
|
-
gap?: BlockGap;
|
|
58
|
-
align?: BlockAlign;
|
|
59
|
-
justify?: BlockJustify;
|
|
60
|
-
wrap?: boolean;
|
|
61
|
-
surface?: BlockSurface;
|
|
62
|
-
pad?: BlockPad;
|
|
63
|
-
};
|
|
64
|
-
/** 2–4 equal-column grid container. */
|
|
65
|
-
type GridBlock = {
|
|
66
|
-
type: 'grid';
|
|
67
|
-
columns: (typeof BLOCK_GRID_COLUMNS)[number];
|
|
68
|
-
children: BlockNode[];
|
|
69
|
-
gap?: BlockGap;
|
|
70
|
-
align?: BlockAlign;
|
|
71
|
-
pad?: BlockPad;
|
|
72
|
-
};
|
|
73
|
-
/** Paragraph / label. `maxWidth: 'measure'` caps long copy at a readable 65ch. */
|
|
74
|
-
type TextBlock = {
|
|
75
|
-
type: 'text';
|
|
76
|
-
value: string;
|
|
77
|
-
size?: BlockSize;
|
|
78
|
-
weight?: BlockWeight;
|
|
79
|
-
tone?: BlockTone;
|
|
80
|
-
align?: BlockTextAlign;
|
|
81
|
-
maxWidth?: BlockMaxWidth;
|
|
82
|
-
};
|
|
83
|
-
/** h2–h4 — never h1 (the page owns its h1). */
|
|
84
|
-
type HeadingBlock = {
|
|
85
|
-
type: 'heading';
|
|
86
|
-
value: string;
|
|
87
|
-
level: (typeof BLOCK_HEADING_LEVELS)[number];
|
|
88
|
-
size?: BlockSize;
|
|
89
|
-
align?: BlockTextAlign;
|
|
90
|
-
maxWidth?: BlockMaxWidth;
|
|
91
|
-
};
|
|
92
|
-
/** Link styled as a button. `tag` feeds agent legibility (agentDataByVariant). */
|
|
93
|
-
type ButtonBlock = {
|
|
94
|
-
type: 'button';
|
|
95
|
-
label: string;
|
|
96
|
-
href: string;
|
|
97
|
-
emphasis?: BlockEmphasis;
|
|
98
|
-
size?: BlockSize;
|
|
99
|
-
tag?: string;
|
|
100
|
-
};
|
|
101
|
-
/** Inline text link. */
|
|
102
|
-
type LinkBlock = {
|
|
103
|
-
type: 'link';
|
|
104
|
-
label: string;
|
|
105
|
-
href: string;
|
|
106
|
-
tag?: string;
|
|
107
|
-
};
|
|
108
|
-
/** Image. `alt` is required; empty only with an explicit `decorative: true`. */
|
|
109
|
-
type ImageBlock = {
|
|
110
|
-
type: 'image';
|
|
111
|
-
src: string;
|
|
112
|
-
alt: string;
|
|
113
|
-
decorative?: boolean;
|
|
114
|
-
ratio?: BlockRatio;
|
|
115
|
-
fit?: BlockFit;
|
|
116
|
-
};
|
|
117
|
-
/** Eyebrow / pill. */
|
|
118
|
-
type BadgeBlock = {
|
|
119
|
-
type: 'badge';
|
|
120
|
-
value: string;
|
|
121
|
-
tone?: BlockTone;
|
|
122
|
-
};
|
|
123
|
-
/** Vertical rhythm. */
|
|
124
|
-
type SpacerBlock = {
|
|
125
|
-
type: 'spacer';
|
|
126
|
-
size: BlockSize;
|
|
127
|
-
};
|
|
128
|
-
/** Section separation — a 1px hairline in the palette border color. No props:
|
|
129
|
-
* anything a divider could be configured with is a styling decision, and
|
|
130
|
-
* styling decisions live in tokens, not on nodes. */
|
|
131
|
-
type DividerBlock = {
|
|
132
|
-
type: 'divider';
|
|
133
|
-
};
|
|
134
|
-
declare const FORM_FIELD_KINDS: readonly ["input", "textarea", "select"];
|
|
135
|
-
declare const FORM_INPUT_TYPES: readonly ["text", "email", "number", "tel"];
|
|
136
|
-
declare const MAX_FORM_FIELDS = 5;
|
|
137
|
-
declare const MAX_FORM_SELECT_OPTIONS = 8;
|
|
138
|
-
/** One field of a form block. Fields are props, not child blocks, so an input
|
|
139
|
-
* can never appear outside a form — the constraint is structural, no
|
|
140
|
-
* validator has to chase it. */
|
|
141
|
-
type FormField = {
|
|
142
|
-
kind: (typeof FORM_FIELD_KINDS)[number];
|
|
143
|
-
/** Slug key for the values object handed to onFormSubmit. */
|
|
144
|
-
name: string;
|
|
145
|
-
/** Visible label — required, a11y is not optional. */
|
|
146
|
-
label: string;
|
|
147
|
-
/** input fields only. Never password/file/hidden — the closed list is the guarantee. */
|
|
148
|
-
inputType?: (typeof FORM_INPUT_TYPES)[number];
|
|
149
|
-
required?: boolean;
|
|
150
|
-
placeholder?: string;
|
|
151
|
-
/** select fields only: 2–MAX_FORM_SELECT_OPTIONS plain-text options. */
|
|
152
|
-
options?: string[];
|
|
153
|
-
};
|
|
154
|
-
/** Lead/contact form. Submit fires `submitGoal` (a project goal) and hands the
|
|
155
|
-
* values to the developer's onFormSubmit — field values never reach Sentient.
|
|
156
|
-
* At most one form per tree; a form is a leaf (no children). */
|
|
157
|
-
type FormBlock = {
|
|
158
|
-
type: 'form';
|
|
159
|
-
submitGoal: string;
|
|
160
|
-
submitLabel: string;
|
|
161
|
-
fields: FormField[];
|
|
162
|
-
emphasis?: BlockEmphasis;
|
|
163
|
-
};
|
|
164
|
-
type BlockNode = StackBlock | GridBlock | TextBlock | HeadingBlock | ButtonBlock | LinkBlock | ImageBlock | BadgeBlock | SpacerBlock | DividerBlock | FormBlock;
|
|
165
|
-
/** The derived site palette (spec §4 "Colour and type: derived, not chosen").
|
|
166
|
-
* Sampled by the on-site editor from the live page's own buttons — computed
|
|
167
|
-
* styles, so values are plain colors (rgb/hex), never var()/url() — validated
|
|
168
|
-
* server-side, stored per project, and served with the decision so injected
|
|
169
|
-
* blocks render in the merchant's own primary color and corner radius.
|
|
170
|
-
* Absent → the renderer's neutral inherit-first defaults. */
|
|
171
|
-
type SitePalette = {
|
|
172
|
-
primaryBg: string;
|
|
173
|
-
primaryText: string;
|
|
174
|
-
radius: string;
|
|
175
|
-
/** Brand accent — resolves `tone: 'accent'` and secondary/ghost button color.
|
|
176
|
-
* Optional: sites tokenized before brand-token extraction shipped carry
|
|
177
|
-
* only the three fields above, and every renderer keeps its neutral
|
|
178
|
-
* fallback for them. */
|
|
179
|
-
accent?: string;
|
|
180
|
-
/** Readable text color on the accent (contrast-derived when not declared). */
|
|
181
|
-
accentText?: string;
|
|
182
|
-
/** Card/section background. */
|
|
183
|
-
surface?: string;
|
|
184
|
-
/** Readable text color on the surface (contrast-derived when not declared).
|
|
185
|
-
* Resolves the text pairing of `surface: 'raised'` stacks. */
|
|
186
|
-
surfaceText?: string;
|
|
187
|
-
/** Hairline border color (form fields, dividers). */
|
|
188
|
-
border?: string;
|
|
189
|
-
/** Muted text color — resolves `tone: 'muted'` (fallback: opacity 0.7). */
|
|
190
|
-
muted?: string;
|
|
191
|
-
};
|
|
192
|
-
declare const MAX_BLOCK_NODES = 64;
|
|
193
|
-
declare const MAX_BLOCK_DEPTH = 5;
|
|
194
|
-
declare const MAX_BLOCK_CHILDREN = 12;
|
|
195
|
-
declare const MAX_BLOCK_ARMS = 4;
|
|
196
|
-
declare const MAX_BLOCK_TEXT_LEN = 500;
|
|
197
|
-
/** True when the tree contains a form node at any depth. Surfaces that cannot
|
|
198
|
-
* render forms (snippet today, React without an onFormSubmit handler) must
|
|
199
|
-
* refuse the WHOLE tree — skipping just the form node would render a section
|
|
200
|
-
* minus its call-to-action, which looks live while converting nothing. */
|
|
201
|
-
declare function containsFormBlock(node: unknown): boolean;
|
|
202
|
-
|
|
203
|
-
/**
|
|
204
|
-
* Slot declaration helpers shared by the browser client (decide) and the
|
|
205
|
-
* server preload path. Pure wrappers over @sentientui/policy.
|
|
206
|
-
*/
|
|
207
|
-
|
|
208
|
-
/** SDK-facing slot declaration. `dims` accepts readonly arrays (`as const`). */
|
|
209
|
-
type SlotDeclInput = {
|
|
210
|
-
id: string;
|
|
211
|
-
arms?: string[];
|
|
212
|
-
dims?: Record<string, readonly string[]>;
|
|
213
|
-
baseline?: string | Record<string, string>;
|
|
214
|
-
};
|
|
215
|
-
|
|
216
|
-
/**
|
|
217
|
-
* Whitelists the wire fields of a slot declaration. Anything an SDK layer
|
|
218
|
-
* attached (goal configs, refs, …) is stripped so it never reaches the zod
|
|
219
|
-
* schema on the API. Also normalizes readonly arrays to mutable ones.
|
|
220
|
-
*/
|
|
221
|
-
declare function toWireSlot(d: SlotDeclInput): SlotDecl;
|
|
222
|
-
/** The declared (or default first-declared) baseline result for a slot. */
|
|
223
|
-
declare function baselineResultFor(d: SlotDeclInput): SlotResult;
|
|
224
|
-
/** Baseline results for a whole declaration list, keyed by slot id. */
|
|
225
|
-
declare function baselineSlots(decls: SlotDeclInput[]): Record<string, SlotResult>;
|
|
226
|
-
/**
|
|
227
|
-
* Canonical arm string of a slot result: dims results encode as sorted
|
|
228
|
-
* `dim=value` pairs joined with '|'; arms results are the arm id verbatim.
|
|
229
|
-
*/
|
|
230
|
-
declare function armOfResult(result: SlotResult): string;
|
|
231
|
-
|
|
232
|
-
/**
|
|
233
|
-
* Decision snapshot: the SPA / return-visit pre-paint source. Written after
|
|
234
|
-
* every successful decide; read by the inline pre-paint script (before any
|
|
235
|
-
* framework code runs) and by init() to seed slot/persona state.
|
|
236
|
-
*/
|
|
237
|
-
|
|
238
|
-
declare const SNAPSHOT_STORAGE_KEY_PREFIX = "_snt_snap:";
|
|
239
|
-
/** Versioned compound locator: resolve id → dataAttr → selector, then verify
|
|
240
|
-
* against fingerprint. Lets a slot survive DOM/markup drift. */
|
|
241
|
-
type CompoundLocator = {
|
|
242
|
-
v?: number;
|
|
243
|
-
id?: string;
|
|
244
|
-
dataAttr?: {
|
|
245
|
-
name: string;
|
|
246
|
-
value: string;
|
|
247
|
-
};
|
|
248
|
-
selector?: string;
|
|
249
|
-
urlMatch?: string;
|
|
250
|
-
/** Where the element is expected to exist — see page-scope.ts. Health only, never serving. */
|
|
251
|
-
page?: string;
|
|
252
|
-
fingerprint?: {
|
|
253
|
-
tag?: string;
|
|
254
|
-
text?: string;
|
|
255
|
-
};
|
|
256
|
-
semanticId?: string;
|
|
257
|
-
};
|
|
258
|
-
/** Bounded, declarative operations a registry arm may apply to its element.
|
|
259
|
-
* The style set is a fixed whitelist (validated server-side); no arbitrary CSS,
|
|
260
|
-
* HTML, or JS ever. `text` is applied via textContent; https-only URLs.
|
|
261
|
-
* moveBefore/moveAfter (exactly one) reposition the element relative to a
|
|
262
|
-
* uniquely-resolving sibling anchor — post-decide only, never pre-paint. */
|
|
263
|
-
type SlotOps = {
|
|
264
|
-
text?: string;
|
|
265
|
-
style?: Record<string, string>;
|
|
266
|
-
hidden?: boolean;
|
|
267
|
-
href?: string;
|
|
268
|
-
imageSrc?: string;
|
|
269
|
-
imageAlt?: string;
|
|
270
|
-
moveBefore?: CompoundLocator;
|
|
271
|
-
moveAfter?: CompoundLocator;
|
|
272
|
-
};
|
|
273
|
-
/** Registry-mode apply info per slot: where to apply and what to set. Stored so
|
|
274
|
-
* a returning visitor's pre-paint can reapply it. `target` is the Phase-2 bare
|
|
275
|
-
* selector; `locator` (Phase 3) is the compound locator, preferred when present. */
|
|
276
|
-
type SlotConfigEntry = {
|
|
277
|
-
kind: 'tokens' | 'arms';
|
|
278
|
-
target?: string;
|
|
279
|
-
locator?: CompoundLocator;
|
|
280
|
-
content?: string;
|
|
281
|
-
ops?: SlotOps;
|
|
282
|
-
/** Composition Blocks per arm — ALL arms, not just the served one, because
|
|
283
|
-
* Option-B rendering pre-paints every arm hidden and reveals the served one
|
|
284
|
-
* (spec §6). Holdout sessions receive the baseline arm's tree only, so the
|
|
285
|
-
* control group's DOM stays meaningful. Absent for non-composition slots. */
|
|
286
|
-
blocks?: Record<string, BlockNode>;
|
|
287
|
-
};
|
|
288
|
-
type DecisionSnapshot = {
|
|
289
|
-
v: 1;
|
|
290
|
-
persona: string;
|
|
291
|
-
band: 'low' | 'medium' | 'high';
|
|
292
|
-
slots: Record<string, SlotResult>;
|
|
293
|
-
layoutOrder: string[] | null;
|
|
294
|
-
savedAt: number;
|
|
295
|
-
slotConfig?: Record<string, SlotConfigEntry>;
|
|
296
|
-
/** Derived site palette for Composition Block rendering — cached so the
|
|
297
|
-
* pre-paint render already looks native (a palette that pops in post-decide
|
|
298
|
-
* would be its own flash). */
|
|
299
|
-
palette?: SitePalette;
|
|
300
|
-
};
|
|
301
|
-
/** Returns null on missing, corrupt, or wrong-version data — never throws. */
|
|
302
|
-
declare function readSnapshot(apiKey: string): DecisionSnapshot | null;
|
|
303
|
-
/** Best-effort persist — storage failures are swallowed. */
|
|
304
|
-
declare function writeSnapshot(apiKey: string, snap: DecisionSnapshot): void;
|
|
305
|
-
/**
|
|
306
|
-
* Inline pre-paint script (Rung 1a): reads the snapshot and sets
|
|
307
|
-
* `data-sentient-persona` / `data-sentient-confidence` on <html> before
|
|
308
|
-
* first paint. Single-writer: it never overwrites attributes already set.
|
|
309
|
-
*
|
|
310
|
-
* Safety properties (pinned by tests):
|
|
311
|
-
* - apiKey goes through JSON.stringify, then '<' is escaped to <, so a
|
|
312
|
-
* hostile key can neither break the JS string nor terminate the <script>.
|
|
313
|
-
* - Built by string concatenation and contains no backticks, so the output
|
|
314
|
-
* survives being embedded in template-literal-based renderers.
|
|
315
|
-
*/
|
|
316
|
-
declare function renderPrePaintScript(apiKey: string): string;
|
|
317
|
-
|
|
318
|
-
/** Session metadata helpers (browser + Node). No DOM APIs. */
|
|
319
|
-
/**
|
|
320
|
-
* Known AI-agent / crawler user-agent tokens. Matched case-insensitively as
|
|
321
|
-
* substrings. This is maintained data — bot lists move monthly. Used both to
|
|
322
|
-
* flag automation on sessions (agentic browsers that leak a token) and by the
|
|
323
|
-
* server middleware / agent-feed route to identify crawler HTTP reads.
|
|
324
|
-
*/
|
|
325
|
-
declare const agentUaList: readonly string[];
|
|
326
|
-
/** True when the user-agent contains a known AI-agent / crawler token. */
|
|
327
|
-
declare function uaTokenMatch(userAgent: string): boolean;
|
|
328
|
-
/** The first known agent token found in the user-agent, or null. */
|
|
329
|
-
declare function matchedAgentToken(userAgent: string): string | null;
|
|
330
|
-
/**
|
|
331
|
-
* Purpose category for an agent fetch, inferred from its published user-agent:
|
|
332
|
-
* - `user` — a person asked an assistant to read the page, live (…-User UAs)
|
|
333
|
-
* - `search` — indexing for an AI answer engine (…-SearchBot / SearchBot)
|
|
334
|
-
* - `training` — model-training crawl (GPTBot, ClaudeBot, CCBot, …)
|
|
335
|
-
* - `other` — not clearly AI, or an unknown/new token
|
|
336
|
-
*/
|
|
337
|
-
type AgentIntent = 'user' | 'search' | 'training' | 'other';
|
|
338
|
-
/** Intent per agent token. Maintained beside `agentUaList` — when you add or
|
|
339
|
-
* rename a token above, set its intent here (a unit test enforces coverage). */
|
|
340
|
-
declare const AGENT_INTENTS: Record<string, AgentIntent>;
|
|
341
|
-
/** Intent for a matched bot token (case-insensitive); `other` for null/unknown. */
|
|
342
|
-
declare function agentIntent(botName: string | null): AgentIntent;
|
|
343
|
-
/** `agentUaList` grouped by intent — the "which crawlers do you classify?" reference. */
|
|
344
|
-
declare function classifiedAgents(): Record<AgentIntent, string[]>;
|
|
345
|
-
declare function detectDeviceClass(userAgent: string): string;
|
|
346
|
-
declare function detectTrafficSource(referrer: string, appOrigin?: string): string;
|
|
347
|
-
declare function referrerDomainFromReferer(referrer: string): string | null;
|
|
348
|
-
/**
|
|
349
|
-
* Ad-platform click-ID query params worth keeping. An ALLOWLIST, unlike the
|
|
350
|
-
* `utm_` prefix match: unknown query keys here are unbounded-cardinality junk
|
|
351
|
-
* (session tokens, cache busters) that would bloat the sessions table, so only
|
|
352
|
-
* the IDs the major ad platforms actually append survive.
|
|
353
|
-
*
|
|
354
|
-
* gclid / gbraid / wbraid — Google Ads auto-tagging (search, YouTube, Display;
|
|
355
|
-
* gbraid/wbraid are the iOS-14 privacy variants)
|
|
356
|
-
* fbclid — Meta (Facebook + Instagram). Appended to EVERY outbound Meta
|
|
357
|
-
* click, paid and organic alike — it identifies the platform, never spend.
|
|
358
|
-
* ttclid — TikTok Ads
|
|
359
|
-
* msclkid — Microsoft Ads (Bing)
|
|
360
|
-
* twclid — X/Twitter Ads
|
|
361
|
-
* li_fat_id — LinkedIn Ads
|
|
362
|
-
*/
|
|
363
|
-
declare const CLICK_ID_KEYS: readonly string[];
|
|
364
|
-
/**
|
|
365
|
-
* Splits a URL query into the attribution params the session upsert carries:
|
|
366
|
-
* every `utm_`-prefixed key, plus allowlisted ad click IDs (CLICK_ID_KEYS).
|
|
367
|
-
* Accepts a raw search string ("?a=b" or "a=b"), a URLSearchParams, or a
|
|
368
|
-
* Next.js `searchParams` object (whose values may be string arrays — the
|
|
369
|
-
* first occurrence wins, matching URLSearchParams iteration order).
|
|
370
|
-
* Node-safe: no DOM APIs.
|
|
371
|
-
*/
|
|
372
|
-
declare function extractTrackedParams(search: string | URLSearchParams | Record<string, string | string[] | undefined>): {
|
|
373
|
-
utmParams: Record<string, string>;
|
|
374
|
-
clickIds: Record<string, string>;
|
|
375
|
-
};
|
|
376
|
-
declare function detectTimeOfDay(d: Date): string;
|
|
377
|
-
type SessionUpsertPayload = {
|
|
378
|
-
sessionId: string;
|
|
379
|
-
ephemeral: boolean;
|
|
380
|
-
utmParams: Record<string, string>;
|
|
381
|
-
/** Allowlisted ad-platform click IDs from the landing URL (CLICK_ID_KEYS). */
|
|
382
|
-
clickIds: Record<string, string>;
|
|
383
|
-
deviceClass: string;
|
|
384
|
-
trafficSource: string;
|
|
385
|
-
referrerDomain: string | null;
|
|
386
|
-
timeOfDay: string;
|
|
387
|
-
dayOfWeek: string;
|
|
388
|
-
/**
|
|
389
|
-
* True when this session is likely driven by automation — either
|
|
390
|
-
* `navigator.webdriver` was set, or the user-agent carried a known agent
|
|
391
|
-
* token. Probabilistic: a flag for metrics + bandit exclusion, never a gate.
|
|
392
|
-
*/
|
|
393
|
-
automation: boolean;
|
|
394
|
-
};
|
|
395
|
-
/** Bandit segment key: `<device_class>:<traffic_source>`. */
|
|
396
|
-
declare function deriveSessionSegment(opts?: {
|
|
397
|
-
userAgent?: string;
|
|
398
|
-
referer?: string;
|
|
399
|
-
appOrigin?: string;
|
|
400
|
-
}): string;
|
|
401
|
-
/**
|
|
402
|
-
* Builds a session upsert body aligned with the browser SDK so SSR assign uses
|
|
403
|
-
* the same segment key (`device:source`) as the client after hydration.
|
|
404
|
-
*/
|
|
405
|
-
declare function buildSessionUpsertPayload(sessionId: string, opts?: {
|
|
406
|
-
userAgent?: string;
|
|
407
|
-
referer?: string;
|
|
408
|
-
appOrigin?: string;
|
|
409
|
-
utmParams?: Record<string, string>;
|
|
410
|
-
clickIds?: Record<string, string>;
|
|
411
|
-
now?: Date;
|
|
412
|
-
/** `navigator.webdriver` value from the browser, when available. */
|
|
413
|
-
webdriver?: boolean;
|
|
414
|
-
}): SessionUpsertPayload;
|
|
415
|
-
|
|
416
|
-
export { type SessionUpsertPayload as $, AGENT_INTENTS as A, BLOCK_ALIGNS as B, type BlockSurface as C, type BlockTextAlign as D, type BlockTone as E, type BlockWeight as F, type ButtonBlock as G, CLICK_ID_KEYS as H, type CompoundLocator as I, type DecisionSnapshot as J, type DividerBlock as K, FORM_FIELD_KINDS as L, FORM_INPUT_TYPES as M, type FormBlock as N, type FormField as O, type GridBlock as P, type HeadingBlock as Q, type ImageBlock as R, type LinkBlock as S, MAX_BLOCK_ARMS as T, MAX_BLOCK_CHILDREN as U, MAX_BLOCK_DEPTH as V, MAX_BLOCK_NODES as W, MAX_BLOCK_TEXT_LEN as X, MAX_FORM_FIELDS as Y, MAX_FORM_SELECT_OPTIONS as Z, SNAPSHOT_STORAGE_KEY_PREFIX as _, type AgentIntent as a, type SitePalette as a0, type SlotConfigEntry as a1, type SlotDeclInput as a2, type SlotOps as a3, type SpacerBlock as a4, type StackBlock as a5, type TextBlock as a6, agentIntent as a7, agentUaList as a8, armOfResult as a9, baselineResultFor as aa, baselineSlots as ab, buildSessionUpsertPayload as ac, classifiedAgents as ad, containsFormBlock as ae, deriveSessionSegment as af, detectDeviceClass as ag, detectTimeOfDay as ah, detectTrafficSource as ai, extractTrackedParams as aj, matchedAgentToken as ak, readSnapshot as al, referrerDomainFromReferer as am, renderPrePaintScript as an, toWireSlot as ao, uaTokenMatch as ap, writeSnapshot as aq, BLOCK_EMPHASES as b, BLOCK_FITS as c, BLOCK_GAPS as d, BLOCK_GRID_COLUMNS as e, BLOCK_HEADING_LEVELS as f, BLOCK_JUSTIFIES as g, BLOCK_MAX_WIDTHS as h, BLOCK_PADS as i, BLOCK_RATIOS as j, BLOCK_SIZES as k, BLOCK_SURFACES as l, BLOCK_TEXT_ALIGNS as m, BLOCK_TONES as n, BLOCK_WEIGHTS as o, type BadgeBlock as p, type BlockAlign as q, type BlockEmphasis as r, type BlockFit as s, type BlockGap as t, type BlockJustify as u, type BlockMaxWidth as v, type BlockNode as w, type BlockPad as x, type BlockRatio as y, type BlockSize as z };
|