@kharon-labs/react 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kharon Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,53 @@
-# Temporary Holding Version
+# @kharon-labs/react
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+React components for Kharon Labs personalization, on top of
+[`@kharon-labs/browser`](https://www.npmjs.com/package/@kharon-labs/browser):
+`npm install @kharon-labs/react`.
+
+```tsx
+import { useEffect } from "react";
+import { KharonProvider, Slot, useKharon } from "@kharon-labs/react";
+
+export function App() {
+  return (
+    <KharonProvider publishableKey="ge_pk_…">
+      <Slot id="hero" defaults={{ headline: "Grow faster", ctaLabel: "Book a demo" }}>
+        {(c) => (
+          <>
+            <h1>{c.headline}</h1>
+            <a href="/demo">{c.ctaLabel}</a>
+          </>
+        )}
+      </Slot>
+    </KharonProvider>
+  );
+}
+
+function ConsentBridge() {
+  const { setConsent } = useKharon();
+  useEffect(() => myCmp.onChange((ok) => setConsent(ok ? "granted" : "denied")), [setConsent]);
+  return null;
+}
+```
+
+- `<Slot id defaults>` has the same shape as the hosted site's `<Slot>`. It renders `defaults` until
+  a decision arrives and takes only the fields you declared from the variant; one the variant
+  doesn't set keeps its default. Text is rendered by React, so variant content can't inject markup.
+- `<KharonProvider>` takes the `@kharon-labs/browser` options (`apiBase`, `consent`, `timeoutMs`,
+  `pageId`, `cookieDomain`). Changing `consent` works like calling `setConsent`. After `timeoutMs`
+  (500 ms) an answer is dropped and the defaults stay.
+- `useKharon()` gives `setConsent`, `conversion(goal, value?)` and `refresh()` (call it after a
+  route change that mounts new slots).
+
+## Server decisions (no flash)
+
+Resolve on your server with `@kharon-labs/server` and pass the result as `decisions`. Slots render
+it on the first paint, the browser skips its own resolve, and measurement starts if the server
+allowed storing the visitor.
+
+```tsx
+<KharonProvider publishableKey="ge_pk_…" decisions={decisions}>…</KharonProvider>
+```
+
+The provider and slots are client components (`"use client"`), so they work in the Next.js App
+Router. React 18 or later; adds about 1 KB gzip to the browser core.

package/dist/index.cjs

@@ -0,0 +1,161 @@
+"use client";
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// packages/react/src/index.tsx
+var index_exports = {};
+__export(index_exports, {
+  KharonProvider: () => KharonProvider,
+  Slot: () => Slot,
+  useKharon: () => useKharon
+});
+module.exports = __toCommonJS(index_exports);
+var import_react = require("react");
+var import_browser = require("@kharon-labs/browser");
+
+// src/engine/analytics/touch.ts
+var CLICK_ID_PARAMS = {
+  gclid: "google",
+  gbraid: "google",
+  wbraid: "google",
+  msclkid: "microsoft",
+  fbclid: "meta",
+  li_fat_id: "linkedin",
+  ttclid: "tiktok",
+  twclid: "x"
+};
+var CLICK_ID_KINDS = new Set(Object.values(CLICK_ID_PARAMS));
+
+// src/engine/analytics/beacon.ts
+var SLOT_ATTRIBUTES = {
+  slot: "data-ge-slot",
+  variant: "data-ge-variant",
+  counterfactual: "data-ge-counterfactual",
+  /** Why the slot shows what it shows (matched, default, holdout). For debugging; not sent. */
+  reason: "data-ge-reason",
+  /** Which step of the fallback ladder chose the content (exact, near, segment, default). Sent on impressions. */
+  rung: "data-ge-rung"
+};
+
+// packages/react/src/index.tsx
+var import_jsx_runtime = require("react/jsx-runtime");
+var KharonContext = (0, import_react.createContext)(null);
+var noop = () => {
+};
+function KharonProvider({ publishableKey, decisions: serverDecisions, children, ...options }) {
+  const [response, setResponse] = (0, import_react.useState)(serverDecisions ?? null);
+  const slots = (0, import_react.useRef)(/* @__PURE__ */ new Map());
+  const client = (0, import_react.useRef)(null);
+  const timeoutMs = options.timeoutMs ?? import_browser.DEFAULT_TIMEOUT_MS;
+  const initial = (0, import_react.useRef)({ publishableKey, serverDecisions, options });
+  const pendingConsent = (0, import_react.useRef)(void 0);
+  const pending = (0, import_react.useRef)(Promise.resolve());
+  const resolve = (0, import_react.useCallback)((deadline) => {
+    pending.current = pending.current.then(async () => {
+      const current = client.current;
+      if (!current) return;
+      const result = await current.resolve(
+        [...slots.current].map(([id, defaults]) => ({ id, defaults })),
+        deadline
+      );
+      if (result && client.current === current) setResponse(result);
+      (0, import_browser.reveal)(document);
+    });
+    return pending.current;
+  }, []);
+  (0, import_react.useEffect)(() => {
+    const { publishableKey: key, serverDecisions: decided, options: opts } = initial.current;
+    const created = (0, import_browser.createClient)({ ...opts, key, consent: pendingConsent.current ?? opts.consent });
+    client.current = created;
+    if (decided) {
+      created.adopt(decided);
+      (0, import_browser.reveal)(document);
+    } else {
+      void resolve(((0, import_browser.antiFlickerStart)(document) ?? Date.now()) + (opts.timeoutMs ?? import_browser.DEFAULT_TIMEOUT_MS));
+    }
+    const unsubscribe = created.onConsentChange((consent) => {
+      if (consent === "granted") void resolve();
+    });
+    return () => {
+      unsubscribe();
+      created.stop();
+      client.current = null;
+    };
+  }, [resolve]);
+  (0, import_react.useEffect)(() => {
+    if (response) client.current?.track(response.configVersion);
+  }, [response]);
+  (0, import_react.useEffect)(() => {
+    if (options.consent) client.current?.setConsent(options.consent);
+  }, [options.consent]);
+  const register = (0, import_react.useCallback)((id, defaults) => {
+    slots.current.set(id, defaults);
+    return () => {
+      if (slots.current.get(id) === defaults) slots.current.delete(id);
+    };
+  }, []);
+  const setConsent = (0, import_react.useCallback)((consent) => {
+    if (client.current) client.current.setConsent(consent);
+    else pendingConsent.current = consent;
+  }, []);
+  const conversion = (0, import_react.useCallback)((goal, value2) => client.current?.conversion(goal, value2), []);
+  const refresh = (0, import_react.useCallback)(() => resolve(Date.now() + timeoutMs), [resolve, timeoutMs]);
+  const value = (0, import_react.useMemo)(
+    () => ({
+      decisions: response?.decisions ?? null,
+      register,
+      setConsent,
+      conversion,
+      refresh
+    }),
+    [response, register, setConsent, conversion, refresh]
+  );
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(KharonContext.Provider, { value, children });
+}
+function Slot({ id, defaults, children, as = "div", className }) {
+  const context = (0, import_react.useContext)(KharonContext);
+  const register = context?.register;
+  const key = JSON.stringify(defaults);
+  const stable = (0, import_react.useMemo)(() => JSON.parse(key), [key]);
+  (0, import_react.useEffect)(() => register?.(id, stable) ?? noop, [register, id, stable]);
+  const decision = context?.decisions?.[id];
+  const content = { ...defaults };
+  if (decision) {
+    for (const field of Object.keys(defaults)) if (typeof decision.content[field] === "string") content[field] = decision.content[field];
+  }
+  return (0, import_react.createElement)(
+    as,
+    {
+      className,
+      [SLOT_ATTRIBUTES.slot]: id,
+      ...decision && {
+        [SLOT_ATTRIBUTES.variant]: decision.variantId ?? "",
+        [SLOT_ATTRIBUTES.counterfactual]: decision.counterfactualVariantId ?? "",
+        [SLOT_ATTRIBUTES.reason]: decision.reason,
+        ...decision.rung && { [SLOT_ATTRIBUTES.rung]: decision.rung }
+      }
+    },
+    children(content)
+  );
+}
+function useKharon() {
+  const context = (0, import_react.useContext)(KharonContext);
+  if (!context) throw new Error("useKharon must be used inside <KharonProvider>");
+  return context;
+}

package/dist/index.d.ts

@@ -0,0 +1,54 @@
+import { Consent, KharonOptions, ResolveResponse } from '@kharon-labs/browser';
+import { ReactNode } from 'react';
+
+export interface KharonProviderProps extends Omit<KharonOptions, "key" | "root"> {
+	/** Publishable key (`pk_…`). */
+	publishableKey: string;
+	/**
+	 * Decisions resolved on your server with `@kharon-labs/server`. Slots render them on the first
+	 * paint and the browser skips its own resolve.
+	 */
+	decisions?: ResolveResponse | null;
+	children: ReactNode;
+}
+export interface KharonApi {
+	/** Forward your consent tool's answer. A grant re-resolves and starts measuring; a denial stops it. */
+	setConsent(consent: Consent): void;
+	conversion(goal: string, value?: number): void;
+	/** Re-resolves the mounted slots, e.g. after a route change. */
+	refresh(): Promise<void>;
+}
+/**
+ * Personalizes the `<Slot>`s below it. Without `decisions` the slots paint their defaults and swap
+ * once the browser's resolve answers (or keep them after `timeoutMs`, 500 ms).
+ */
+export declare function KharonProvider({ publishableKey, decisions: serverDecisions, children, ...options }: KharonProviderProps): import("react").JSX.Element;
+export interface SlotProps<F extends string> {
+	/** Slot id from the console. */
+	id: string;
+	/** Your copy, shown until (and unless) a variant replaces it. Also what the console imports. */
+	defaults: Record<F, string>;
+	/** Renders the slot's content: the variant's fields over the defaults. */
+	children: (content: Record<F, string>) => ReactNode;
+	/** Element to render. Default `div`. */
+	as?: "div" | "section" | "span" | "header" | "aside" | "article" | "li";
+	className?: string;
+}
+/** A personalizable region. Same shape as the hosted site's `<Slot>`, with defaults in code. */
+export declare function Slot<F extends string>({ id, defaults, children, as, className }: SlotProps<F>): import("react").DetailedReactHTMLElement<{
+	"data-ge-rung"?: ("default" | "exact" | "near" | "segment") | undefined;
+	"data-ge-variant"?: string | undefined;
+	"data-ge-counterfactual"?: string | undefined;
+	"data-ge-reason"?: ("matched" | "default" | "holdout") | undefined;
+	className: string | undefined;
+	"data-ge-slot": string;
+}, HTMLElement>;
+/** Consent, conversions and refresh for the nearest `<KharonProvider>`. */
+export declare function useKharon(): KharonApi;
+
+export {
+	Consent,
+	ResolveResponse,
+};
+
+export {};

package/dist/index.js

@@ -0,0 +1,146 @@
+"use client";
+
+// packages/react/src/index.tsx
+import { createContext, createElement, useCallback, useContext, useEffect, useMemo, useRef, useState } from "react";
+import {
+  DEFAULT_TIMEOUT_MS,
+  antiFlickerStart,
+  createClient,
+  reveal
+} from "@kharon-labs/browser";
+
+// src/engine/analytics/touch.ts
+var CLICK_ID_PARAMS = {
+  gclid: "google",
+  gbraid: "google",
+  wbraid: "google",
+  msclkid: "microsoft",
+  fbclid: "meta",
+  li_fat_id: "linkedin",
+  ttclid: "tiktok",
+  twclid: "x"
+};
+var CLICK_ID_KINDS = new Set(Object.values(CLICK_ID_PARAMS));
+
+// src/engine/analytics/beacon.ts
+var SLOT_ATTRIBUTES = {
+  slot: "data-ge-slot",
+  variant: "data-ge-variant",
+  counterfactual: "data-ge-counterfactual",
+  /** Why the slot shows what it shows (matched, default, holdout). For debugging; not sent. */
+  reason: "data-ge-reason",
+  /** Which step of the fallback ladder chose the content (exact, near, segment, default). Sent on impressions. */
+  rung: "data-ge-rung"
+};
+
+// packages/react/src/index.tsx
+import { jsx } from "react/jsx-runtime";
+var KharonContext = createContext(null);
+var noop = () => {
+};
+function KharonProvider({ publishableKey, decisions: serverDecisions, children, ...options }) {
+  const [response, setResponse] = useState(serverDecisions ?? null);
+  const slots = useRef(/* @__PURE__ */ new Map());
+  const client = useRef(null);
+  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const initial = useRef({ publishableKey, serverDecisions, options });
+  const pendingConsent = useRef(void 0);
+  const pending = useRef(Promise.resolve());
+  const resolve = useCallback((deadline) => {
+    pending.current = pending.current.then(async () => {
+      const current = client.current;
+      if (!current) return;
+      const result = await current.resolve(
+        [...slots.current].map(([id, defaults]) => ({ id, defaults })),
+        deadline
+      );
+      if (result && client.current === current) setResponse(result);
+      reveal(document);
+    });
+    return pending.current;
+  }, []);
+  useEffect(() => {
+    const { publishableKey: key, serverDecisions: decided, options: opts } = initial.current;
+    const created = createClient({ ...opts, key, consent: pendingConsent.current ?? opts.consent });
+    client.current = created;
+    if (decided) {
+      created.adopt(decided);
+      reveal(document);
+    } else {
+      void resolve((antiFlickerStart(document) ?? Date.now()) + (opts.timeoutMs ?? DEFAULT_TIMEOUT_MS));
+    }
+    const unsubscribe = created.onConsentChange((consent) => {
+      if (consent === "granted") void resolve();
+    });
+    return () => {
+      unsubscribe();
+      created.stop();
+      client.current = null;
+    };
+  }, [resolve]);
+  useEffect(() => {
+    if (response) client.current?.track(response.configVersion);
+  }, [response]);
+  useEffect(() => {
+    if (options.consent) client.current?.setConsent(options.consent);
+  }, [options.consent]);
+  const register = useCallback((id, defaults) => {
+    slots.current.set(id, defaults);
+    return () => {
+      if (slots.current.get(id) === defaults) slots.current.delete(id);
+    };
+  }, []);
+  const setConsent = useCallback((consent) => {
+    if (client.current) client.current.setConsent(consent);
+    else pendingConsent.current = consent;
+  }, []);
+  const conversion = useCallback((goal, value2) => client.current?.conversion(goal, value2), []);
+  const refresh = useCallback(() => resolve(Date.now() + timeoutMs), [resolve, timeoutMs]);
+  const value = useMemo(
+    () => ({
+      decisions: response?.decisions ?? null,
+      register,
+      setConsent,
+      conversion,
+      refresh
+    }),
+    [response, register, setConsent, conversion, refresh]
+  );
+  return /* @__PURE__ */ jsx(KharonContext.Provider, { value, children });
+}
+function Slot({ id, defaults, children, as = "div", className }) {
+  const context = useContext(KharonContext);
+  const register = context?.register;
+  const key = JSON.stringify(defaults);
+  const stable = useMemo(() => JSON.parse(key), [key]);
+  useEffect(() => register?.(id, stable) ?? noop, [register, id, stable]);
+  const decision = context?.decisions?.[id];
+  const content = { ...defaults };
+  if (decision) {
+    for (const field of Object.keys(defaults)) if (typeof decision.content[field] === "string") content[field] = decision.content[field];
+  }
+  return createElement(
+    as,
+    {
+      className,
+      [SLOT_ATTRIBUTES.slot]: id,
+      ...decision && {
+        [SLOT_ATTRIBUTES.variant]: decision.variantId ?? "",
+        [SLOT_ATTRIBUTES.counterfactual]: decision.counterfactualVariantId ?? "",
+        [SLOT_ATTRIBUTES.reason]: decision.reason,
+        ...decision.rung && { [SLOT_ATTRIBUTES.rung]: decision.rung }
+      }
+    },
+    children(content)
+  );
+}
+function useKharon() {
+  const context = useContext(KharonContext);
+  if (!context) throw new Error("useKharon must be used inside <KharonProvider>");
+  return context;
+}
+export {
+  KharonProvider,
+  Slot,
+  useKharon
+};

package/package.json

@@ -1,6 +1,29 @@
 {
   "name": "@kharon-labs/react",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "React components for Kharon Labs personalization: <KharonProvider> and <Slot>.",
+  "license": "MIT",
+  "homepage": "https://kharonlabs.com",
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": ["dist"],
+  "dependencies": {
+    "@kharon-labs/browser": "0.2.0"
+  },
+  "peerDependencies": {
+    "react": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}