@sentientui/core 0.25.0 → 0.27.0

package/dist/index.mjs

@@ -1,2 +1,2 @@
-import{A as T,B as U,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-RL5B6M4G.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,A as BLOCK_ALIGNS,F as BLOCK_EMPHASES,I as BLOCK_FITS,z as BLOCK_GAPS,J as BLOCK_GRID_COLUMNS,K as BLOCK_HEADING_LEVELS,B as BLOCK_JUSTIFIES,H as BLOCK_RATIOS,C as BLOCK_SIZES,G as BLOCK_TEXT_ALIGNS,E as BLOCK_TONES,D as BLOCK_WEIGHTS,l as CLICK_ID_KEYS,a as LEGACY_SESSION_COOKIE_NAME,y as LOCAL_MODE_BANNER,O as MAX_BLOCK_ARMS,N as MAX_BLOCK_CHILDREN,M as MAX_BLOCK_DEPTH,L as MAX_BLOCK_NODES,P as MAX_BLOCK_TEXT_LEN,x as PROD_KEYLESS_ERROR,t as SNAPSHOT_STORAGE_KEY_PREFIX,R as _registerConsentUpgradeInit,g as agentIntent,c as agentUaList,s as armOfResult,Q as attachMicroSignalDetectors,q as baselineResultFor,r as baselineSlots,h as classifiedAgents,o as deriveSessionSegment,i as detectDeviceClass,n as detectTimeOfDay,j as detectTrafficSource,m as extractTrackedParams,T as grantConsent,U as init,S as isDoNotTrackEnabled,e as matchedAgentToken,u as readSnapshot,k as referrerDomainFromReferer,w as renderPrePaintScript,b as sessionCookieName,p as toWireSlot,d as uaTokenMatch,v as writeSnapshot};
+import{A as T,B as U,C as V,D as W,E as X,F as Y,G as Z,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-TRBPPGFT.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,A as BLOCK_ALIGNS,F as BLOCK_EMPHASES,I as BLOCK_FITS,z as BLOCK_GAPS,J as BLOCK_GRID_COLUMNS,K as BLOCK_HEADING_LEVELS,B as BLOCK_JUSTIFIES,H as BLOCK_RATIOS,C as BLOCK_SIZES,G as BLOCK_TEXT_ALIGNS,E as BLOCK_TONES,D as BLOCK_WEIGHTS,l as CLICK_ID_KEYS,L as FORM_FIELD_KINDS,M as FORM_INPUT_TYPES,a as LEGACY_SESSION_COOKIE_NAME,y as LOCAL_MODE_BANNER,S as MAX_BLOCK_ARMS,R as MAX_BLOCK_CHILDREN,Q as MAX_BLOCK_DEPTH,P as MAX_BLOCK_NODES,T as MAX_BLOCK_TEXT_LEN,N as MAX_FORM_FIELDS,O as MAX_FORM_SELECT_OPTIONS,x as PROD_KEYLESS_ERROR,t as SNAPSHOT_STORAGE_KEY_PREFIX,W as _registerConsentUpgradeInit,g as agentIntent,c as agentUaList,s as armOfResult,V as attachMicroSignalDetectors,q as baselineResultFor,r as baselineSlots,h as classifiedAgents,U as containsFormBlock,o as deriveSessionSegment,i as detectDeviceClass,n as detectTimeOfDay,j as detectTrafficSource,m as extractTrackedParams,Y as grantConsent,Z as init,X as isDoNotTrackEnabled,e as matchedAgentToken,u as readSnapshot,k as referrerDomainFromReferer,w as renderPrePaintScript,b as sessionCookieName,p as toWireSlot,d as uaTokenMatch,v as writeSnapshot};
 //# sourceMappingURL=index.mjs.map

package/dist/session-meta-dN92q19_.d.cts

@@ -0,0 +1,378 @@
+import { SlotResult, SlotDecl } from '@sentientui/policy';
+
+/**
+ * Composition Blocks (spec: 2026-08-20-nocode-composition-variants-design.md §4).
+ *
+ * A bounded, TYPED component tree — never HTML — that a registry arm may carry
+ * (`published_config.arms[].blocks`). The vocabulary is the whitelist: every
+ * prop value is an enumerated token, validated server-side before publish
+ * (apps/api/src/domain/composition-blocks.ts) and rendered client-side through
+ * document.createElement + property assignment only. No innerHTML/outerHTML/
+ * insertAdjacentHTML exists anywhere on this path — the security property is
+ * preserved by never accepting HTML, not by sanitizing it, which is why there
+ * is no sanitizer to keep honest.
+ *
+ * Token lists live here (not in the API domain like SlotOps' mirrors) because
+ * three parties must agree byte-for-byte: the server validator, the snippet
+ * renderer, and eventually the React renderer (§11) — a drifted copy would let
+ * a published arm fail to render, which the fail-safe turns into an invisibly
+ * missing section, not an error.
+ */
+declare const BLOCK_GAPS: readonly ["none", "sm", "md", "lg"];
+declare const BLOCK_ALIGNS: readonly ["start", "center", "end", "stretch"];
+declare const BLOCK_JUSTIFIES: readonly ["start", "center", "end", "between"];
+declare const BLOCK_SIZES: readonly ["sm", "md", "lg"];
+declare const BLOCK_WEIGHTS: readonly ["normal", "medium", "bold"];
+declare const BLOCK_TONES: readonly ["default", "muted", "accent"];
+declare const BLOCK_EMPHASES: readonly ["primary", "secondary", "ghost"];
+declare const BLOCK_TEXT_ALIGNS: readonly ["left", "center", "right"];
+declare const BLOCK_RATIOS: readonly ["auto", "square", "landscape", "wide"];
+declare const BLOCK_FITS: readonly ["cover", "contain"];
+declare const BLOCK_GRID_COLUMNS: readonly [2, 3, 4];
+declare const BLOCK_HEADING_LEVELS: readonly [2, 3, 4];
+type BlockGap = (typeof BLOCK_GAPS)[number];
+type BlockAlign = (typeof BLOCK_ALIGNS)[number];
+type BlockJustify = (typeof BLOCK_JUSTIFIES)[number];
+type BlockSize = (typeof BLOCK_SIZES)[number];
+type BlockWeight = (typeof BLOCK_WEIGHTS)[number];
+type BlockTone = (typeof BLOCK_TONES)[number];
+type BlockEmphasis = (typeof BLOCK_EMPHASES)[number];
+type BlockTextAlign = (typeof BLOCK_TEXT_ALIGNS)[number];
+type BlockRatio = (typeof BLOCK_RATIOS)[number];
+type BlockFit = (typeof BLOCK_FITS)[number];
+/** Flex row/column container. */
+type StackBlock = {
+    type: 'stack';
+    direction: 'row' | 'column';
+    children: BlockNode[];
+    gap?: BlockGap;
+    align?: BlockAlign;
+    justify?: BlockJustify;
+    wrap?: boolean;
+};
+/** 2–4 equal-column grid container. */
+type GridBlock = {
+    type: 'grid';
+    columns: (typeof BLOCK_GRID_COLUMNS)[number];
+    children: BlockNode[];
+    gap?: BlockGap;
+    align?: BlockAlign;
+};
+/** Paragraph / label. */
+type TextBlock = {
+    type: 'text';
+    value: string;
+    size?: BlockSize;
+    weight?: BlockWeight;
+    tone?: BlockTone;
+    align?: BlockTextAlign;
+};
+/** h2–h4 — never h1 (the page owns its h1). */
+type HeadingBlock = {
+    type: 'heading';
+    value: string;
+    level: (typeof BLOCK_HEADING_LEVELS)[number];
+    size?: BlockSize;
+    align?: BlockTextAlign;
+};
+/** Link styled as a button. `tag` feeds agent legibility (agentDataByVariant). */
+type ButtonBlock = {
+    type: 'button';
+    label: string;
+    href: string;
+    emphasis?: BlockEmphasis;
+    size?: BlockSize;
+    tag?: string;
+};
+/** Inline text link. */
+type LinkBlock = {
+    type: 'link';
+    label: string;
+    href: string;
+    tag?: string;
+};
+/** Image. `alt` is required; empty only with an explicit `decorative: true`. */
+type ImageBlock = {
+    type: 'image';
+    src: string;
+    alt: string;
+    decorative?: boolean;
+    ratio?: BlockRatio;
+    fit?: BlockFit;
+};
+/** Eyebrow / pill. */
+type BadgeBlock = {
+    type: 'badge';
+    value: string;
+    tone?: BlockTone;
+};
+/** Vertical rhythm. */
+type SpacerBlock = {
+    type: 'spacer';
+    size: BlockSize;
+};
+declare const FORM_FIELD_KINDS: readonly ["input", "textarea", "select"];
+declare const FORM_INPUT_TYPES: readonly ["text", "email", "number", "tel"];
+declare const MAX_FORM_FIELDS = 5;
+declare const MAX_FORM_SELECT_OPTIONS = 8;
+/** One field of a form block. Fields are props, not child blocks, so an input
+ *  can never appear outside a form — the constraint is structural, no
+ *  validator has to chase it. */
+type FormField = {
+    kind: (typeof FORM_FIELD_KINDS)[number];
+    /** Slug key for the values object handed to onFormSubmit. */
+    name: string;
+    /** Visible label — required, a11y is not optional. */
+    label: string;
+    /** input fields only. Never password/file/hidden — the closed list is the guarantee. */
+    inputType?: (typeof FORM_INPUT_TYPES)[number];
+    required?: boolean;
+    placeholder?: string;
+    /** select fields only: 2–MAX_FORM_SELECT_OPTIONS plain-text options. */
+    options?: string[];
+};
+/** Lead/contact form. Submit fires `submitGoal` (a project goal) and hands the
+ *  values to the developer's onFormSubmit — field values never reach Sentient.
+ *  At most one form per tree; a form is a leaf (no children). */
+type FormBlock = {
+    type: 'form';
+    submitGoal: string;
+    submitLabel: string;
+    fields: FormField[];
+    emphasis?: BlockEmphasis;
+};
+type BlockNode = StackBlock | GridBlock | TextBlock | HeadingBlock | ButtonBlock | LinkBlock | ImageBlock | BadgeBlock | SpacerBlock | FormBlock;
+/** The derived site palette (spec §4 "Colour and type: derived, not chosen").
+ *  Sampled by the on-site editor from the live page's own buttons — computed
+ *  styles, so values are plain colors (rgb/hex), never var()/url() — validated
+ *  server-side, stored per project, and served with the decision so injected
+ *  blocks render in the merchant's own primary color and corner radius.
+ *  Absent → the renderer's neutral inherit-first defaults. */
+type SitePalette = {
+    primaryBg: string;
+    primaryText: string;
+    radius: string;
+};
+declare const MAX_BLOCK_NODES = 64;
+declare const MAX_BLOCK_DEPTH = 5;
+declare const MAX_BLOCK_CHILDREN = 12;
+declare const MAX_BLOCK_ARMS = 4;
+declare const MAX_BLOCK_TEXT_LEN = 500;
+/** True when the tree contains a form node at any depth. Surfaces that cannot
+ *  render forms (snippet today, React without an onFormSubmit handler) must
+ *  refuse the WHOLE tree — skipping just the form node would render a section
+ *  minus its call-to-action, which looks live while converting nothing. */
+declare function containsFormBlock(node: unknown): boolean;
+
+/**
+ * Slot declaration helpers shared by the browser client (decide) and the
+ * server preload path. Pure wrappers over @sentientui/policy.
+ */
+
+/** SDK-facing slot declaration. `dims` accepts readonly arrays (`as const`). */
+type SlotDeclInput = {
+    id: string;
+    arms?: string[];
+    dims?: Record<string, readonly string[]>;
+    baseline?: string | Record<string, string>;
+};
+
+/**
+ * Whitelists the wire fields of a slot declaration. Anything an SDK layer
+ * attached (goal configs, refs, …) is stripped so it never reaches the zod
+ * schema on the API. Also normalizes readonly arrays to mutable ones.
+ */
+declare function toWireSlot(d: SlotDeclInput): SlotDecl;
+/** The declared (or default first-declared) baseline result for a slot. */
+declare function baselineResultFor(d: SlotDeclInput): SlotResult;
+/** Baseline results for a whole declaration list, keyed by slot id. */
+declare function baselineSlots(decls: SlotDeclInput[]): Record<string, SlotResult>;
+/**
+ * Canonical arm string of a slot result: dims results encode as sorted
+ * `dim=value` pairs joined with '|'; arms results are the arm id verbatim.
+ */
+declare function armOfResult(result: SlotResult): string;
+
+/**
+ * Decision snapshot: the SPA / return-visit pre-paint source. Written after
+ * every successful decide; read by the inline pre-paint script (before any
+ * framework code runs) and by init() to seed slot/persona state.
+ */
+
+declare const SNAPSHOT_STORAGE_KEY_PREFIX = "_snt_snap:";
+/** Versioned compound locator: resolve id → dataAttr → selector, then verify
+ *  against fingerprint. Lets a slot survive DOM/markup drift. */
+type CompoundLocator = {
+    v?: number;
+    id?: string;
+    dataAttr?: {
+        name: string;
+        value: string;
+    };
+    selector?: string;
+    urlMatch?: string;
+    fingerprint?: {
+        tag?: string;
+        text?: string;
+    };
+    semanticId?: string;
+};
+/** Bounded, declarative operations a registry arm may apply to its element.
+ *  The style set is a fixed whitelist (validated server-side); no arbitrary CSS,
+ *  HTML, or JS ever. `text` is applied via textContent; https-only URLs.
+ *  moveBefore/moveAfter (exactly one) reposition the element relative to a
+ *  uniquely-resolving sibling anchor — post-decide only, never pre-paint. */
+type SlotOps = {
+    text?: string;
+    style?: Record<string, string>;
+    hidden?: boolean;
+    href?: string;
+    imageSrc?: string;
+    imageAlt?: string;
+    moveBefore?: CompoundLocator;
+    moveAfter?: CompoundLocator;
+};
+/** Registry-mode apply info per slot: where to apply and what to set. Stored so
+ *  a returning visitor's pre-paint can reapply it. `target` is the Phase-2 bare
+ *  selector; `locator` (Phase 3) is the compound locator, preferred when present. */
+type SlotConfigEntry = {
+    kind: 'tokens' | 'arms';
+    target?: string;
+    locator?: CompoundLocator;
+    content?: string;
+    ops?: SlotOps;
+    /** Composition Blocks per arm — ALL arms, not just the served one, because
+     *  Option-B rendering pre-paints every arm hidden and reveals the served one
+     *  (spec §6). Holdout sessions receive the baseline arm's tree only, so the
+     *  control group's DOM stays meaningful. Absent for non-composition slots. */
+    blocks?: Record<string, BlockNode>;
+};
+type DecisionSnapshot = {
+    v: 1;
+    persona: string;
+    band: 'low' | 'medium' | 'high';
+    slots: Record<string, SlotResult>;
+    layoutOrder: string[] | null;
+    savedAt: number;
+    slotConfig?: Record<string, SlotConfigEntry>;
+    /** Derived site palette for Composition Block rendering — cached so the
+     *  pre-paint render already looks native (a palette that pops in post-decide
+     *  would be its own flash). */
+    palette?: SitePalette;
+};
+/** Returns null on missing, corrupt, or wrong-version data — never throws. */
+declare function readSnapshot(apiKey: string): DecisionSnapshot | null;
+/** Best-effort persist — storage failures are swallowed. */
+declare function writeSnapshot(apiKey: string, snap: DecisionSnapshot): void;
+/**
+ * Inline pre-paint script (Rung 1a): reads the snapshot and sets
+ * `data-sentient-persona` / `data-sentient-confidence` on <html> before
+ * first paint. Single-writer: it never overwrites attributes already set.
+ *
+ * Safety properties (pinned by tests):
+ * - apiKey goes through JSON.stringify, then '<' is escaped to <, so a
+ *   hostile key can neither break the JS string nor terminate the <script>.
+ * - Built by string concatenation and contains no backticks, so the output
+ *   survives being embedded in template-literal-based renderers.
+ */
+declare function renderPrePaintScript(apiKey: string): string;
+
+/** Session metadata helpers (browser + Node). No DOM APIs. */
+/**
+ * Known AI-agent / crawler user-agent tokens. Matched case-insensitively as
+ * substrings. This is maintained data — bot lists move monthly. Used both to
+ * flag automation on sessions (agentic browsers that leak a token) and by the
+ * server middleware / agent-feed route to identify crawler HTTP reads.
+ */
+declare const agentUaList: readonly string[];
+/** True when the user-agent contains a known AI-agent / crawler token. */
+declare function uaTokenMatch(userAgent: string): boolean;
+/** The first known agent token found in the user-agent, or null. */
+declare function matchedAgentToken(userAgent: string): string | null;
+/**
+ * Purpose category for an agent fetch, inferred from its published user-agent:
+ *  - `user`     — a person asked an assistant to read the page, live (…-User UAs)
+ *  - `search`   — indexing for an AI answer engine (…-SearchBot / SearchBot)
+ *  - `training` — model-training crawl (GPTBot, ClaudeBot, CCBot, …)
+ *  - `other`    — not clearly AI, or an unknown/new token
+ */
+type AgentIntent = 'user' | 'search' | 'training' | 'other';
+/** Intent per agent token. Maintained beside `agentUaList` — when you add or
+ *  rename a token above, set its intent here (a unit test enforces coverage). */
+declare const AGENT_INTENTS: Record<string, AgentIntent>;
+/** Intent for a matched bot token (case-insensitive); `other` for null/unknown. */
+declare function agentIntent(botName: string | null): AgentIntent;
+/** `agentUaList` grouped by intent — the "which crawlers do you classify?" reference. */
+declare function classifiedAgents(): Record<AgentIntent, string[]>;
+declare function detectDeviceClass(userAgent: string): string;
+declare function detectTrafficSource(referrer: string, appOrigin?: string): string;
+declare function referrerDomainFromReferer(referrer: string): string | null;
+/**
+ * Ad-platform click-ID query params worth keeping. An ALLOWLIST, unlike the
+ * `utm_` prefix match: unknown query keys here are unbounded-cardinality junk
+ * (session tokens, cache busters) that would bloat the sessions table, so only
+ * the IDs the major ad platforms actually append survive.
+ *
+ *   gclid / gbraid / wbraid — Google Ads auto-tagging (search, YouTube, Display;
+ *     gbraid/wbraid are the iOS-14 privacy variants)
+ *   fbclid  — Meta (Facebook + Instagram). Appended to EVERY outbound Meta
+ *     click, paid and organic alike — it identifies the platform, never spend.
+ *   ttclid  — TikTok Ads
+ *   msclkid — Microsoft Ads (Bing)
+ *   twclid  — X/Twitter Ads
+ *   li_fat_id — LinkedIn Ads
+ */
+declare const CLICK_ID_KEYS: readonly string[];
+/**
+ * Splits a URL query into the attribution params the session upsert carries:
+ * every `utm_`-prefixed key, plus allowlisted ad click IDs (CLICK_ID_KEYS).
+ * Accepts a raw search string ("?a=b" or "a=b"), a URLSearchParams, or a
+ * Next.js `searchParams` object (whose values may be string arrays — the
+ * first occurrence wins, matching URLSearchParams iteration order).
+ * Node-safe: no DOM APIs.
+ */
+declare function extractTrackedParams(search: string | URLSearchParams | Record<string, string | string[] | undefined>): {
+    utmParams: Record<string, string>;
+    clickIds: Record<string, string>;
+};
+declare function detectTimeOfDay(d: Date): string;
+type SessionUpsertPayload = {
+    sessionId: string;
+    ephemeral: boolean;
+    utmParams: Record<string, string>;
+    /** Allowlisted ad-platform click IDs from the landing URL (CLICK_ID_KEYS). */
+    clickIds: Record<string, string>;
+    deviceClass: string;
+    trafficSource: string;
+    referrerDomain: string | null;
+    timeOfDay: string;
+    dayOfWeek: string;
+    /**
+     * True when this session is likely driven by automation — either
+     * `navigator.webdriver` was set, or the user-agent carried a known agent
+     * token. Probabilistic: a flag for metrics + bandit exclusion, never a gate.
+     */
+    automation: boolean;
+};
+/** Bandit segment key: `<device_class>:<traffic_source>`. */
+declare function deriveSessionSegment(opts?: {
+    userAgent?: string;
+    referer?: string;
+    appOrigin?: string;
+}): string;
+/**
+ * Builds a session upsert body aligned with the browser SDK so SSR assign uses
+ * the same segment key (`device:source`) as the client after hydration.
+ */
+declare function buildSessionUpsertPayload(sessionId: string, opts?: {
+    userAgent?: string;
+    referer?: string;
+    appOrigin?: string;
+    utmParams?: Record<string, string>;
+    clickIds?: Record<string, string>;
+    now?: Date;
+    /** `navigator.webdriver` value from the browser, when available. */
+    webdriver?: boolean;
+}): SessionUpsertPayload;
+
+export { type TextBlock as $, AGENT_INTENTS as A, BLOCK_ALIGNS as B, CLICK_ID_KEYS as C, type DecisionSnapshot as D, FORM_INPUT_TYPES as E, FORM_FIELD_KINDS as F, type FormBlock as G, type FormField as H, type GridBlock as I, type HeadingBlock as J, type ImageBlock as K, type LinkBlock as L, MAX_BLOCK_ARMS as M, MAX_BLOCK_CHILDREN as N, MAX_BLOCK_DEPTH as O, MAX_BLOCK_NODES as P, MAX_BLOCK_TEXT_LEN as Q, MAX_FORM_FIELDS as R, MAX_FORM_SELECT_OPTIONS as S, SNAPSHOT_STORAGE_KEY_PREFIX as T, type SessionUpsertPayload as U, type SitePalette as V, type SlotConfigEntry as W, type SlotDeclInput as X, type SlotOps as Y, type SpacerBlock as Z, type StackBlock as _, type AgentIntent as a, agentIntent as a0, agentUaList as a1, armOfResult as a2, baselineResultFor as a3, baselineSlots as a4, buildSessionUpsertPayload as a5, classifiedAgents as a6, containsFormBlock as a7, deriveSessionSegment as a8, detectDeviceClass as a9, detectTimeOfDay as aa, detectTrafficSource as ab, extractTrackedParams as ac, matchedAgentToken as ad, readSnapshot as ae, referrerDomainFromReferer as af, renderPrePaintScript as ag, toWireSlot as ah, uaTokenMatch as ai, writeSnapshot as aj, 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_RATIOS as h, BLOCK_SIZES as i, BLOCK_TEXT_ALIGNS as j, BLOCK_TONES as k, BLOCK_WEIGHTS as l, type BadgeBlock as m, type BlockAlign as n, type BlockEmphasis as o, type BlockFit as p, type BlockGap as q, type BlockJustify as r, type BlockNode as s, type BlockRatio as t, type BlockSize as u, type BlockTextAlign as v, type BlockTone as w, type BlockWeight as x, type ButtonBlock as y, type CompoundLocator as z };