@syntrologie/adapt-product 2.28.0 → 2.29.0

package/dist/native/nativeSlotWatcher.d.ts

@@ -0,0 +1,135 @@
+/**
+ * Native slot watcher — the quick-view-modal half of the native-takeover
+ * feature (FEAT-1784346204).
+ *
+ * On the vela SPA there is NO `<syntro-pdp>` element: the quick-view modal
+ * server-renders its OWN native FAQ / review sections (the Task 4 shape). This
+ * watcher observes those sections appearing, scores the visitor ONCE per product,
+ * swaps the personalized preset content into the host sections (via the Task 1
+ * `swapNativeSlot` engine), mounts a compact trending-news "extras" section, and
+ * speaks a small DOM-event protocol that the demo toggle (Task 7) drives:
+ *
+ *   listens (document): `syntro:demo-toggle`     — CustomEvent<{ on: boolean }>
+ *   emits   (document): `syntro:pdp-native-swap` — CustomEvent<{
+ *     state: 'swapped' | 'restored' | 'default-kept' | 'unavailable';
+ *     productId: string;
+ *     summary: string;      // "Tailored for: runner · fit_risk"; '' when not swapped
+ *     canToggle: boolean;   // true whenever flipping the toggle can visibly change
+ *                           // anything — a personalized overlap swap OR the cold
+ *                           // generic extras. false for `unavailable` and for a
+ *                           // cold visitor whose product has no `unknown`-row
+ *                           // trending-news to mount.
+ *     extrasMounted: boolean; // whether the compact trending-news extras section is
+ *                             // currently in the DOM. A cold-with-extras visitor
+ *                             // emits `default-kept` + extrasMounted:true.
+ *     archetype: string;      // raw scorer sport slug ('' unless swapped) — the
+ *                             // band maps it to HUMAN words and never prints it.
+ *     decision: string;       // raw scorer decision slug ('' unless swapped).
+ *   }>
+ *
+ * The four states are unchanged. A fully-unknown visitor on a product that HAS an
+ * `unknown` preset row with trending-news still keeps the overlap sections
+ * (qa/peer-feed) at their defaults, but mounts the generic extras — parity with
+ * `<syntro-pdp>`, which renders the unknown preset's extra sections. That case
+ * emits `default-kept` + canToggle:true + extrasMounted:true.
+ *
+ * It is INERT on pages owned by `<syntro-pdp>` (that element does its own native
+ * takeover): if one exists in the document when the watcher starts, it never
+ * observes. Single watcher per page; module-scoped state; never throws.
+ */
+import { type NativeItemFields, type NativeSlotKind } from './nativeSlotSwap';
+/** One config-set slot value: the widget kind, an optional header, and its content. */
+interface SlotPreset {
+    kind: string;
+    header?: unknown;
+    data: unknown;
+}
+/** `presets[product][archetype][slot] = SlotPreset` — the config's SET values. */
+type PdpPresetTable = Record<string, Record<string, Record<string, SlotPreset>>>;
+interface ScoreSpec {
+    model_id: string;
+    name: string;
+    type: string;
+    values?: string[];
+    value_descriptions?: Record<string, string>;
+    signals?: Record<string, unknown>;
+}
+interface SynOSGlobal {
+    score?: (spec: ScoreSpec) => Promise<string>;
+    scoreMulti?: (specs: ScoreSpec[]) => Promise<string[]>;
+}
+declare function readSynOS(): SynOSGlobal | undefined;
+declare function readPresets(): PdpPresetTable | undefined;
+declare function readArchetypeDescriptions(): Record<string, string>;
+declare function readDecisionDescriptions(): Record<string, string>;
+declare function readChatExcerpt(): string;
+interface ScorePair {
+    archetype: string;
+    decision: string;
+}
+declare function doScore(productPresets: Record<string, Record<string, SlotPreset>>): Promise<ScorePair>;
+/** Build the flat host-field items for one native slot from its scored preset. */
+declare function fieldsForSlot(row: Record<string, SlotPreset>, slotId: string, kind: NativeSlotKind, decision: string): NativeItemFields[];
+/** The preset slot's section-header shape (eyebrow/title/accent/subtitle). */
+interface ExtrasHeader {
+    eyebrow?: string | null;
+    title?: string | null;
+    accent?: string | null;
+    subtitle?: string | null;
+}
+/** Pool-selected trending-news payload + the slot's section header, so the
+ *  modal's extras carry the same heading the page's section wrapper renders
+ *  (a header-less article pile reads as a rendering glitch — Parker,
+ *  2026-07-18). */
+declare function extrasDataFor(row: Record<string, SlotPreset>, decision: string): {
+    payload: Record<string, unknown>;
+    header: ExtrasHeader | null;
+} | null;
+/** The native slot container for a product, ignoring any inside a `<syntro-pdp>`. */
+declare function slotContainer(productId: string, kind: NativeSlotKind): HTMLElement | null;
+type SwapEventState = 'swapped' | 'restored' | 'default-kept' | 'unavailable';
+declare function emit(state: SwapEventState, productId: string, summary: string, canToggle: boolean, extrasMounted: boolean, archetype?: string, decision?: string): void;
+declare function tearDownSwap(): void;
+/**
+ * Mount the compact trending-news extras section for a product, appended after the
+ * peer-feed section's PARENT block (falling back to the qa section). Shared by the
+ * personalized swap and the cold generic-extras path. Returns true when it mounted
+ * (a resolvable container existed) so the caller can decide whether anything
+ * visibly changed. Records the node on `session.extras`.
+ */
+declare function mountExtras(productId: string, extrasData: {
+    payload: Record<string, unknown>;
+    header: ExtrasHeader | null;
+}): boolean;
+/**
+ * Start the native slot watcher. Idempotent: a second call is a no-op that
+ * returns the SAME stop function (single watcher per page).
+ *
+ * No-ops (never observes) when a `<syntro-pdp>` element already owns the page —
+ * that element performs its own native takeover.
+ */
+export declare function startNativeSlotWatcher(): () => void;
+/**
+ * Test seam. Fully resets module state between tests (production code never calls
+ * this). `scanNow` synchronously scans the whole document for native containers
+ * and drives the SAME flush logic the observer uses — a deterministic stand-in
+ * for jsdom's async MutationObserver.
+ */
+export declare const _testing: {
+    scanNow(): Promise<void>;
+    readSynOSForTest: typeof readSynOS;
+    readPresetsForTest: typeof readPresets;
+    readArchetypeDescriptionsForTest: typeof readArchetypeDescriptions;
+    readDecisionDescriptionsForTest: typeof readDecisionDescriptions;
+    readChatExcerptForTest: typeof readChatExcerpt;
+    doScoreForTest: typeof doScore;
+    fieldsForSlotForTest: typeof fieldsForSlot;
+    extrasDataForTest: typeof extrasDataFor;
+    slotContainerForTest: typeof slotContainer;
+    mountExtrasForTest: typeof mountExtras;
+    emitForTest: typeof emit;
+    tearDownSwapForTest: typeof tearDownSwap;
+    reset(): void;
+};
+export {};
+//# sourceMappingURL=nativeSlotWatcher.d.ts.map

package/dist/native/nativeSlotWatcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nativeSlotWatcher.d.ts","sourceRoot":"","sources":["../../src/native/nativeSlotWatcher.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAIH,OAAO,EAIL,KAAK,gBAAgB,EACrB,KAAK,cAAc,EAKpB,MAAM,kBAAkB,CAAC;AAI1B,uFAAuF;AACvF,UAAU,UAAU;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,IAAI,EAAE,OAAO,CAAC;CACf;AACD,kFAAkF;AAClF,KAAK,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC,CAAC,CAAC;AAEjF,UAAU,SAAS;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,kBAAkB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5C,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AACD,UAAU,WAAW;IACnB,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,SAAS,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IAC7C,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,SAAS,EAAE,KAAK,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;CACxD;AAED,iBAAS,SAAS,IAAI,WAAW,GAAG,SAAS,CAG5C;AACD,iBAAS,WAAW,IAAI,cAAc,GAAG,SAAS,CAGjD;AACD,iBAAS,yBAAyB,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAM3D;AACD,iBAAS,wBAAwB,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAM1D;AAMD,iBAAS,eAAe,IAAI,MAAM,CAQjC;AAUD,UAAU,SAAS;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;CAClB;AA8DD,iBAAe,OAAO,CACpB,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC,GACzD,OAAO,CAAC,SAAS,CAAC,CAyCpB;AAsBD,kFAAkF;AAClF,iBAAS,aAAa,CACpB,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,EAC/B,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,cAAc,EACpB,QAAQ,EAAE,MAAM,GACf,gBAAgB,EAAE,CAMpB;AAED,8EAA8E;AAC9E,UAAU,YAAY;IACpB,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAED;;;mBAGmB;AACnB,iBAAS,aAAa,CACpB,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,EAC/B,QAAQ,EAAE,MAAM,GACf;IAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAAC,MAAM,EAAE,YAAY,GAAG,IAAI,CAAA;CAAE,GAAG,IAAI,CAW1E;AA4DD,qFAAqF;AACrF,iBAAS,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,cAAc,GAAG,WAAW,GAAG,IAAI,CAOlF;AAED,KAAK,cAAc,GAAG,SAAS,GAAG,UAAU,GAAG,cAAc,GAAG,aAAa,CAAC;AAE9E,iBAAS,IAAI,CACX,KAAK,EAAE,cAAc,EACrB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,OAAO,EAClB,aAAa,EAAE,OAAO,EACtB,SAAS,SAAK,EACd,QAAQ,SAAK,GACZ,IAAI,CAON;AAkBD,iBAAS,YAAY,IAAI,IAAI,CAI5B;AAED;;;;;;GAMG;AACH,iBAAS,WAAW,CAClB,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE;IAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAAC,MAAM,EAAE,YAAY,GAAG,IAAI,CAAA;CAAE,GAC5E,OAAO,CAkCT;AA+OD;;;;;;GAMG;AACH,wBAAgB,sBAAsB,IAAI,MAAM,IAAI,CA4CnD;AAED;;;;;GAKG;AACH,eAAO,MAAM,QAAQ;eACF,OAAO,CAAC,IAAI,CAAC;;;;;;;;;;;;;aAgBrB,IAAI;CAgBd,CAAC"}

package/dist/platformAdapter.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Platform-agnostic commerce interface the product-card widget reads to fetch
+ * variants, add to cart, and open the cart. The widget never branches on
+ * platform — it just reads whatever adapter the RUNTIME published for the
+ * detected platform.
+ *
+ * Implementations live in the platform packages and are wired in by the runtime
+ * (see runtime-sdk `_platforms-registered.ts` → `setProductCommerceGlobal`):
+ * - platform-shopify: /products/{handle}.js + /cart/add.js + navigate to /cart.
+ * - platform-woocommerce (future): Store API + ?wc-ajax=add_to_cart.
+ *
+ * This is NOT host-injected. The host page supplies nothing.
+ */
+export interface ProductPlatformAdapter {
+    /** Fetch normalized variant data for a product. */
+    fetchVariants(productId: string): Promise<VariantPayload>;
+    /** Perform the platform-specific add-to-cart POST. Returns success or
+     *  a structured error the widget can render. */
+    addToCart(input: AddToCartInput): Promise<AddToCartResult>;
+    /** Open the host's cart UI. Implementation is entirely platform-specific.
+     *  The widget calls this AFTER closing the chat canvas. */
+    openCart(): Promise<void>;
+}
+export interface AddToCartInput {
+    product_id: string;
+    /** null for single-SKU products (no variant to pick). */
+    variant_id: string | null;
+    quantity: number;
+}
+export interface AddToCartResult {
+    ok: boolean;
+    /** Set when ok=false. */
+    error?: {
+        code: 'oos' | 'network' | 'validation' | 'unknown';
+        message: string;
+    };
+}
+export interface VariantPayload {
+    product_id: string;
+    attributes: AttributeDef[];
+    variants: Variant[];
+}
+export interface AttributeDef {
+    /** Stable id: 'size', 'color', 'cadence'. */
+    key: string;
+    /** Display label: 'Size', 'Color', 'Delivery'. */
+    label: string;
+    /** Render mode. Extensible: future kinds may include 'dropdown'. */
+    kind: 'pill' | 'swatch';
+    values: AttributeValue[];
+}
+export interface AttributeValue {
+    /** Stable id: 'large', 'red', 'subscribe'. */
+    id: string;
+    /** Display label: 'Large', 'Red', 'Subscribe — save 15%'. */
+    label: string;
+    /** Present when the attribute's kind is 'swatch'; null for pill attributes. */
+    swatch: SwatchSpec | null;
+}
+export interface SwatchSpec {
+    kind: 'color' | 'image';
+    /** Hex color (#000000) for kind 'color'; URL for kind 'image'. */
+    value: string;
+}
+export interface Variant {
+    /** Platform-native SKU/variant id used as the cart-POST id. */
+    id: string;
+    /** Map of attribute key → value id, e.g. { size: 'large', color: 'red' }. */
+    selection: Record<string, string>;
+    price: number;
+    compare_at_price: number | null;
+    in_stock: boolean;
+    /** Optional per-variant hero image URL. When present the variant panel swaps
+     *  its image to this on selection; otherwise it keeps the product-level image.
+     *  Populated by platforms that carry variant-level media (Shopify
+     *  `variant.featured_image`); absent for products whose image never varies by
+     *  SKU (e.g. pack-size only). */
+    featured_image?: string;
+}
+/** Retrieve the runtime-published commerce adapter. Null if none was set. */
+export declare function getProductPlatformAdapter(): ProductPlatformAdapter | null;
+//# sourceMappingURL=platformAdapter.d.ts.map

package/dist/platformAdapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"platformAdapter.d.ts","sourceRoot":"","sources":["../src/platformAdapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,sBAAsB;IACrC,mDAAmD;IACnD,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;IAE1D;oDACgD;IAChD,SAAS,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;IAE3D;+DAC2D;IAC3D,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3B;AAED,MAAM,WAAW,cAAc;IAC7B,UAAU,EAAE,MAAM,CAAC;IACnB,yDAAyD;IACzD,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,OAAO,CAAC;IACZ,yBAAyB;IACzB,KAAK,CAAC,EAAE;QAAE,IAAI,EAAE,KAAK,GAAG,SAAS,GAAG,YAAY,GAAG,SAAS,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;CACjF;AAED,MAAM,WAAW,cAAc;IAC7B,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,YAAY,EAAE,CAAC;IAC3B,QAAQ,EAAE,OAAO,EAAE,CAAC;CACrB;AAED,MAAM,WAAW,YAAY;IAC3B,6CAA6C;IAC7C,GAAG,EAAE,MAAM,CAAC;IACZ,kDAAkD;IAClD,KAAK,EAAE,MAAM,CAAC;IACd,oEAAoE;IACpE,IAAI,EAAE,MAAM,GAAG,QAAQ,CAAC;IACxB,MAAM,EAAE,cAAc,EAAE,CAAC;CAC1B;AAED,MAAM,WAAW,cAAc;IAC7B,8CAA8C;IAC9C,EAAE,EAAE,MAAM,CAAC;IACX,6DAA6D;IAC7D,KAAK,EAAE,MAAM,CAAC;IACd,+EAA+E;IAC/E,MAAM,EAAE,UAAU,GAAG,IAAI,CAAC;CAC3B;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC;IACxB,kEAAkE;IAClE,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,OAAO;IACtB,+DAA+D;IAC/D,EAAE,EAAE,MAAM,CAAC;IACX,6EAA6E;IAC7E,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAClC,KAAK,EAAE,MAAM,CAAC;IACd,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,QAAQ,EAAE,OAAO,CAAC;IAClB;;;;qCAIiC;IACjC,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAaD,6EAA6E;AAC7E,wBAAgB,yBAAyB,IAAI,sBAAsB,GAAG,IAAI,CAKzE"}