@syntrologie/runtime-sdk 2.2.0-canary.9 → 2.2.0

package/dist/telemetry/adapters/posthog.d.ts

@@ -5,6 +5,7 @@
  * and use the TelemetryClient interface.
  */
 import type { PostHog, Properties } from 'posthog-js';
+import type { ConsentGate } from '../consent';
 import type { CanvasSurface, TelemetryClient } from '../types';
 export interface PostHogAdapterOptions {
     /**
@@ -58,6 +59,18 @@ export interface PostHogAdapterOptions {
      * Used to feed events into the EventBus for runtime decisions.
      */
     onCapture?: (eventName: string, properties?: Record<string, unknown>) => void;
+    /**
+     * Consent gate for GDPR compliance.
+     * When provided with requireExplicitConsent, PostHog initialization is
+     * deferred until consent is granted.
+     */
+    consent?: ConsentGate;
+    /**
+     * Require explicit consent before initializing PostHog.
+     * When true, PostHog will not init until consent.grant() is called.
+     * @default false
+     */
+    requireExplicitConsent?: boolean;
 }
 interface CanvasAnalyticsPayload extends Properties {
     rectangleId?: string;
@@ -71,7 +84,13 @@ export declare class PostHogAdapter implements TelemetryClient {
     private client?;
     private featureFlagsCallback?;
     private captureCallback?;
+    private consentUnsub?;
     constructor(options?: PostHogAdapterOptions);
+    /**
+     * Initialize the PostHog client. Called immediately (no consent gate)
+     * or deferred (when consent gate grants).
+     */
+    private initPostHog;
     /**
      * Get all feature flags from PostHog.
      * Used to extract segment membership flags (in_segment_*).

package/dist/telemetry/consent.d.ts

@@ -0,0 +1,62 @@
+/**
+ * ConsentGate - GDPR-compliant consent management for telemetry.
+ *
+ * Gates PostHog (and any future telemetry provider) initialization on
+ * user consent status. Supports:
+ * - Explicit consent requirement (opt-in model)
+ * - GTM Consent Mode v2 integration (reads analytics_storage from dataLayer)
+ * - Programmatic grant/deny API for host page consent banners
+ *
+ * The ConsentGate lives in the runtime (not the PostHog adapter) because
+ * consent is provider-agnostic — if we switch from PostHog to Segment or
+ * another provider, consent logic should not change.
+ */
+export type ConsentStatus = 'granted' | 'denied' | 'pending';
+export interface ConsentConfig {
+    /** Initial consent status. Default: 'pending' */
+    initialStatus?: ConsentStatus;
+    /** If true, telemetry is blocked until grant() is called. Default: false */
+    requireExplicitConsent?: boolean;
+    /** Read consent state from GTM's window.dataLayer consent events. Default: false */
+    readFromGtmConsentMode?: boolean;
+    /** Called whenever consent status changes. */
+    onConsentChange?: (status: ConsentStatus) => void;
+}
+type ConsentListener = (status: ConsentStatus) => void;
+export declare class ConsentGate {
+    private status;
+    private listeners;
+    private configCallback?;
+    private gtmEnabled;
+    private destroyed;
+    constructor(config?: ConsentConfig);
+    /**
+     * Grant consent — enables telemetry collection.
+     */
+    grant(): void;
+    /**
+     * Deny consent — disables telemetry collection.
+     */
+    deny(): void;
+    /**
+     * Get the current consent status.
+     */
+    getStatus(): ConsentStatus;
+    /**
+     * Subscribe to consent status changes.
+     * Returns an unsubscribe function.
+     */
+    subscribe(listener: ConsentListener): () => void;
+    /**
+     * Poll GTM's dataLayer for consent state.
+     * Scans for the most recent consent update event with analytics_storage.
+     */
+    pollGtmConsent(): void;
+    /**
+     * Clean up listeners and stop responding to changes.
+     */
+    destroy(): void;
+    private setStatus;
+    private notify;
+}
+export {};

package/dist/version.d.ts

@@ -10,4 +10,4 @@
  *
  * @since 2.0.0
  */
-export declare const SDK_VERSION = "2.2.0-canary.9";
+export declare const SDK_VERSION = "2.2.0";

package/dist/widgets/WidgetRegistry.d.ts

@@ -68,11 +68,16 @@ export interface MountedWidgetHandle {
  * Allows apps to register custom widgets that can be rendered via
  * mountWidget actions or directly through the Surfaces system.
  */
+export type WidgetRegistryListener = (event: {
+    type: 'registered' | 'unregistered';
+    widgetId: string;
+}) => void;
 export declare class WidgetRegistry {
     private widgets;
     private mountedWidgets;
     private mountIdCounter;
     private runtimeRef?;
+    private listeners;
     /**
      * Bind a runtime reference so it can be injected into widget mount() calls.
      * Uses `unknown` to avoid circular imports (WidgetRegistry ← runtime.ts).
@@ -133,6 +138,11 @@ export declare class WidgetRegistry {
      * Get all widgets from a specific source.
      */
     getBySource(source: string): WidgetRegistration[];
+    /**
+     * Subscribe to widget registration changes.
+     */
+    subscribe(callback: WidgetRegistryListener): () => void;
+    private notify;
     /**
      * Clean up all mounted widgets.
      */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syntrologie/runtime-sdk",
-  "version": "2.2.0-canary.9",
+  "version": "2.2.0",
   "description": "Syntrologie Runtime SDK for web experimentation and analytics",
   "license": "Proprietary",
   "private": false,
@@ -35,12 +35,16 @@
     "./cdn": {
       "import": "./dist/smart-canvas.esm.js",
       "require": "./dist/smart-canvas.js"
+    },
+    "./build-plugin": {
+      "import": "./scripts/syntroReactPlugin.mjs"
     }
   },
   "files": [
     "dist",
     "schema",
     "scripts/validate-config.mjs",
+    "scripts/syntroReactPlugin.mjs",
     "CAPABILITIES.md"
   ],
   "scripts": {
@@ -63,12 +67,12 @@
     "@floating-ui/dom": "^1.7.5",
     "@growthbook/growthbook": "~1.6.2",
     "@growthbook/growthbook-react": "^1.6.4",
-    "@syntrologie/adapt-chatbot": "2.2.0-canary.9",
-    "@syntrologie/adapt-content": "2.2.0-canary.9",
-    "@syntrologie/adapt-faq": "2.2.0-canary.9",
-    "@syntrologie/adapt-gamification": "2.2.0-canary.9",
-    "@syntrologie/adapt-nav": "2.2.0-canary.9",
-    "@syntrologie/adapt-overlays": "2.2.0-canary.9",
+    "@syntrologie/adapt-chatbot": "2.2.0",
+    "@syntrologie/adapt-content": "2.2.0",
+    "@syntrologie/adapt-faq": "2.2.0",
+    "@syntrologie/adapt-gamification": "2.2.0",
+    "@syntrologie/adapt-nav": "2.2.0",
+    "@syntrologie/adapt-overlays": "2.2.0",
     "posthog-js": "~1.302.2",
     "zod": "^3.25.76"
   },

package/scripts/syntroReactPlugin.mjs

@@ -0,0 +1,113 @@
+/**
+ * syntroReactPlugin — esbuild plugin for shared React via SynOS
+ *
+ * Replaces `import { useState } from 'react'` (and react-dom, jsx-runtime)
+ * with lazy wrappers that resolve to SynOS.React / SynOS.ReactDOM at call
+ * time. This means:
+ *   - Adaptive modules load and self-register without React being available
+ *   - React resolves when components actually render
+ *   - The runtime SDK sets SynOS.React at module scope before any render
+ *
+ * Used by: build-cdn.js, build-adaptives-only.js, editor-sdk/build.js
+ */
+export const syntroReactPlugin = {
+  name: 'syntro-react',
+  setup(build) {
+    build.onResolve({ filter: /^react(-dom)?(\/.*)?$/ }, (args) => ({
+      path: args.path,
+      namespace: 'syntro-react',
+    }));
+
+    build.onLoad({ filter: /.*/, namespace: 'syntro-react' }, (args) => {
+      if (args.path === 'react/jsx-runtime' || args.path === 'react/jsx-dev-runtime') {
+        return {
+          contents: `
+            function _R() {
+              return (typeof SynOS !== 'undefined' && SynOS.React) || {};
+            }
+            function _jsx(type, props, key) {
+              var R = _R();
+              var p = props || {};
+              var c = p.children;
+              delete p.children;
+              if (key !== undefined) p.key = key;
+              return Array.isArray(c)
+                ? R.createElement.apply(null, [type, p].concat(c))
+                : c !== undefined
+                  ? R.createElement(type, p, c)
+                  : R.createElement(type, p);
+            }
+            export var jsx = _jsx;
+            export var jsxs = _jsx;
+            export var Fragment = _R().Fragment;
+          `,
+          loader: 'js',
+        };
+      }
+      if (args.path === 'react') {
+        // Hooks and creation APIs are lazy function wrappers — they resolve
+        // SynOS.React at call time (during render), not at module load.
+        //
+        // Component types (Fragment, Suspense, etc.) are resolved at module
+        // evaluation via _R(). This is fine because the runtime SDK always
+        // loads before adaptive modules evaluate, so SynOS.React is set.
+        // ES module named exports can't be truly lazy (no getter support).
+        return {
+          contents: `
+            function _R() {
+              return (typeof SynOS !== 'undefined' && SynOS.React) || {};
+            }
+
+            // Default export — lazy proxy for React.* access
+            export default new Proxy({}, { get: function(_, k) { return _R()[k]; } });
+
+            // Hooks — lazy function wrappers (resolve at call time)
+            export function useState() { return _R().useState.apply(null, arguments); }
+            export function useEffect() { return _R().useEffect.apply(null, arguments); }
+            export function useMemo() { return _R().useMemo.apply(null, arguments); }
+            export function useCallback() { return _R().useCallback.apply(null, arguments); }
+            export function useRef() { return _R().useRef.apply(null, arguments); }
+            export function useContext() { return _R().useContext.apply(null, arguments); }
+            export function useReducer() { return _R().useReducer.apply(null, arguments); }
+            export function useLayoutEffect() { return _R().useLayoutEffect.apply(null, arguments); }
+            export function useId() { return _R().useId.apply(null, arguments); }
+
+            // Creation APIs — lazy function wrappers
+            export function createElement() { return _R().createElement.apply(null, arguments); }
+            export function createContext() { return _R().createContext.apply(null, arguments); }
+            export function forwardRef() { return _R().forwardRef.apply(null, arguments); }
+            export function memo() { return _R().memo.apply(null, arguments); }
+            export function lazy() { return _R().lazy.apply(null, arguments); }
+            export function isValidElement() { return _R().isValidElement.apply(null, arguments); }
+            export function cloneElement() { return _R().cloneElement.apply(null, arguments); }
+
+            // Component types — resolved at module eval (runtime loads first)
+            var _r = _R();
+            export var Fragment      = _r.Fragment;
+            export var Suspense      = _r.Suspense;
+            export var Children      = _r.Children;
+            export var Component     = _r.Component;
+            export var PureComponent = _r.PureComponent;
+          `,
+          loader: 'js',
+        };
+      }
+      if (args.path === 'react-dom' || args.path.startsWith('react-dom/')) {
+        return {
+          contents: `
+            function _RD() {
+              return (typeof SynOS !== 'undefined' && SynOS.ReactDOM) || {};
+            }
+            export default new Proxy({}, { get: function(_, k) { return _RD()[k]; } });
+            export function createRoot() { return _RD().createRoot.apply(null, arguments); }
+            export function hydrateRoot() { return _RD().hydrateRoot.apply(null, arguments); }
+            export function createPortal() { return _RD().createPortal.apply(null, arguments); }
+            export function flushSync() { return _RD().flushSync.apply(null, arguments); }
+          `,
+          loader: 'js',
+        };
+      }
+      return { contents: 'export default {};', loader: 'js' };
+    });
+  },
+};