@kharon-labs/browser 0.0.0-stage → 0.2.0

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,99 @@
-# Temporary Holding Version
+# @kharon-labs/browser
 
-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.
+Personalize parts of any website with Kharon Labs. Mark the regions you want to personalize, keep
+your own copy as the defaults, and the package swaps in the variant Kharon picks for each visitor,
+then measures it against a holdout.
+
+```sh
+npm install @kharon-labs/browser
+```
+
+On a site without a bundler, use the script-tag build at `https://kharonlabs.com/sdk/v1.js`. On a
+React site (including Next.js and React Native Web), use
+[`@kharon-labs/react`](https://www.npmjs.com/package/@kharon-labs/react), which is built on this package.
+
+## Plain HTML
+
+```html
+<head>
+  <!-- Optional: hides slots (never the page) until the swap, for at most 500 ms. -->
+  <style id="kharon-af">[data-ge-slot]{visibility:hidden!important}</style>
+  <script>window.__kharonAf=Date.now();setTimeout(function(){var s=document.getElementById("kharon-af");s&&s.parentNode.removeChild(s)},500)</script>
+  <script src="https://kharonlabs.com/sdk/v1.js" data-key="ge_pk_…" async></script>
+</head>
+<body>
+  <section data-ge-slot="hero">
+    <h1 data-ge-field="headline">Grow faster</h1>
+    <a data-ge-field="ctaLabel" data-ge-attr="href:ctaUrl" href="/demo">Book a demo</a>
+  </section>
+</body>
+```
+
+The anti-flicker snippet is also exported as `ANTI_FLICKER_SNIPPET`.
+
+## Bundlers
+
+```ts
+import { init, setConsent, conversion } from "@kharon-labs/browser";
+
+init({ key: "ge_pk_…" });
+myCmp.onChange((ok) => setConsent(ok ? "granted" : "denied"));
+conversion("demo_booked");
+```
+
+| Function | What it does |
+| --- | --- |
+| `init({ key, apiBase?, consent?, timeoutMs?, pageId?, cookieDomain? })` | Resolves the page's slots once the DOM is ready and starts measuring if allowed. |
+| `setConsent("granted" \| "denied" \| "unknown")` | Forward your consent tool's answer. Safe to call before `init`. |
+| `conversion(goal, value?)` | Records a goal. Forms with `data-ge-goal="…"` record theirs on submit. |
+| `signup()` | Records a `signup` conversion. Prefer `recordSignup` in `@kharon-labs/server`, which counts only signups that succeeded. |
+| `refresh()` | Re-scans and re-resolves, e.g. after a client-side route change. |
+
+## Slots
+
+- `data-ge-slot="id"` marks a slot; the id matches a slot in the console. Repeat an id to show the
+  same decision in several places.
+- `data-ge-field="name"` writes a content field as text (`textContent`), never as HTML.
+- `data-ge-attr="href:ctaUrl, title:ctaTitle"` writes fields into attributes. URL attributes accept
+  only `http(s)` and relative links; event handlers and `style` are never written.
+- The markup's own text is the default. A field the variant doesn't set keeps it, and a slot the
+  console doesn't know yet keeps all of it.
+
+## Single-page apps
+
+The package scans the page once, when the DOM is ready. After a client-side route change that mounts
+new slots, call `refresh()`. On React Native Web, a `dataSet={{ geSlot: "hero" }}` prop renders
+`data-ge-slot="hero"`; React Native's types don't declare `dataSet`, so add it with a module
+augmentation (or use `@kharon-labs/react`, which needs no DOM attributes).
+
+## Guarantees
+
+- **Defaults always render.** If we answer late (after `timeoutMs`, 500 ms), fail or are down, the
+  page keeps its defaults and slots are revealed. The package never retries.
+- **Consent is decided by our server**, by the visitor's country and choice (opt-in in the EEA, UK
+  and Switzerland, GPC honored). Until it allows storing the visitor, the package writes no cookie
+  or storage and sends no analytics.
+- **Holdouts.** Held-out visitors see the defaults; their impressions record the variant withheld.
+- **Acquisition.** A session's first page view records how it arrived: `utm_*` tags, which ad
+  network's click id was present (never the id), a Kharon campaign link, and the referring site's
+  host. Never the URL's path or other parameters.
+
+The visitor id is a first-party `ge_vid` cookie on your domain (one year; Safari caps script-set
+cookies at seven days, `@kharon-labs/server` avoids that). A denial deletes it.
+
+## Size and support
+
+About 4 KB gzip, no dependencies. ES2020 browsers; without `fetch` the page keeps its defaults, and
+without `IntersectionObserver` impressions aren't recorded.
+
+## Your privacy policy
+
+Adding Kharon Labs sets a first-party cookie and sends visit data to us, so your
+privacy policy should say so. A paragraph to adapt (not legal advice):
+
+> We use Kharon Labs to tailor parts of this website to the organization a visit comes from and to
+> measure whether that helps. Kharon Labs processes your IP address, browser details, the page you
+> visit and how you arrived, and infers your organization (not you personally). With your consent
+> where required, it stores a random visitor ID in a first-party cookie (`ge_vid`) and records page
+> views and interactions. See https://kharonlabs.com/privacy for what Kharon Labs collects and how
+> long it keeps it.