@billdog.io/toolbar 0.0.0-stage → 1.0.2-beta.3

package/README.md

@@ -1,3 +1,36 @@
-# Temporary Holding Version
+# @billdog.io/toolbar
 
-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.
+In-page inspection overlay for your own site: see the selector autocapture will
+record for an element, override a feature flag locally, and read click data
+against the live page.
+
+## Launching
+
+The toolbar does not start on its own. A signed-in project member launches it
+from the dashboard, which mints a short-lived signed token and appends it to the
+page URL as a fragment. The toolbar reads that token once, strips it from the
+address bar, and exchanges it for a session.
+
+Two things gate it, and both are enforced server-side:
+
+- The token is HMAC-signed and expires in hours, so it cannot be forged or kept.
+- The page URL must appear on the project's **authorized URLs** list. An empty
+  list means the toolbar is off — an unconfigured project has not opted in, and
+  defaulting to "any origin" would expose flags and click data wherever the
+  snippet happens to load.
+
+Subdomain wildcards are deliberately unsupported: `*.example.com` is how a
+feature like this becomes "any subdomain an attacker can register".
+
+## Usage
+
+```ts
+import { startToolbar } from '@billdog.io/toolbar';
+
+// Returns null when there is no launch token in the URL, which is every
+// ordinary page load.
+await startToolbar({ apiHost: 'https://<project>.supabase.co/functions/v1' });
+```
+
+Everything renders inside a closed shadow root, so the host page's CSS cannot
+reach into the overlay and the overlay's cannot reach back out.

package/dist/index.d.mts

@@ -0,0 +1,161 @@
+/**
+ * @billdog.io/toolbar — the in-page inspection overlay.
+ *
+ * Renders on the customer's own site when a project member launches it from the
+ * dashboard: inspect an element to see the selector autocapture will record,
+ * view a click heatmap over the live page, and override a feature flag locally
+ * to check a variant without shipping a rollout.
+ *
+ * ## Launch
+ *
+ * The dashboard mints a short-lived signed token and puts it in the URL
+ * FRAGMENT. Fragments are not sent to servers on navigation, so the token does
+ * not land in the customer's access logs or in a Referer header on the way out.
+ * The toolbar reads it once and immediately strips it from the address bar, so
+ * a copied URL is not a working credential.
+ *
+ * ## Isolation
+ *
+ * Everything renders inside a shadow root. The toolbar is injected into a page
+ * whose CSS it has never seen: without a shadow root, the host's stylesheet
+ * reaches into the overlay and the overlay's reaches back out, and "the toolbar
+ * broke my site's layout" is not a defensible bug to ship.
+ */
+interface ToolbarOptions {
+    /** Where the toolbar API lives, e.g. https://<project>.supabase.co/functions/v1 */
+    apiHost: string;
+    /** Overrides the token read from the URL fragment. Mainly for tests. */
+    token?: string;
+}
+interface FeatureFlagSummary {
+    id: string;
+    key: string;
+    enabled: boolean;
+    rollout_percentage: number | null;
+}
+/** One aggregated click bin, as returned by the heatmap route. */
+interface HeatmapBin {
+    /** Fraction of viewport width, 0..1. */
+    relative_x: number;
+    /** Offset within the document, in pixels. */
+    page_y: number;
+    clicks: number;
+    users: number;
+    /** 0..1, normalised against the busiest bin on the page. */
+    intensity: number;
+}
+interface ToolbarSession {
+    project_id: string;
+    expires_at: number;
+    feature_flags: FeatureFlagSummary[];
+    event_definitions: Array<{
+        event_name: string;
+        display_name: string | null;
+    }>;
+}
+/** Fragment key the dashboard uses to hand over the launch token. */
+declare const TOOLBAR_FRAGMENT_KEY = "__billdog_toolbar__";
+/** localStorage key for flag overrides, read by the SDK's flag evaluation. */
+declare const FLAG_OVERRIDE_KEY = "billdog_flag_overrides";
+/**
+ * Read the launch token out of the URL fragment and remove it.
+ *
+ * Stripping matters: the toolbar is opened on a page a person is likely to
+ * screenshot, share or paste into a ticket, and a URL that still carries a live
+ * credential turns any of those into a leak. Exported so the removal is
+ * testable rather than a side effect buried in start-up.
+ */
+declare function consumeLaunchToken(location: {
+    hash: string;
+    href: string;
+}): {
+    token: string | null;
+    cleanedHref: string;
+};
+/**
+ * Build the selector autocapture would record for an element.
+ *
+ * Deliberately mirrors AutoCapture's `$elements_chain`: the point of the
+ * inspector is to show what the SDK will actually key on, so a selector that
+ * merely looks reasonable is worse than useless — someone would define an
+ * action against it and wonder why it never fires.
+ */
+declare function describeElement(el: Element): string;
+/**
+ * Place a bin on the CURRENT page.
+ *
+ * The stored coordinates are deliberately device-independent — a fraction of
+ * viewport width, and an offset within the document — because the clicks were
+ * aggregated across every screen size that visited the page. Turning them back
+ * into pixels is therefore a function of THIS viewport, which is what makes the
+ * overlay line up with what the person looking at it can see.
+ *
+ * `page_y` needs no conversion: it is already a document offset, so an absolutely
+ * positioned element at that y sits where the clicks were regardless of how far
+ * the reader has scrolled.
+ */
+declare function binToPageCoords(bin: Pick<HeatmapBin, 'relative_x' | 'page_y'>, viewportWidth: number): {
+    x: number;
+    y: number;
+};
+/**
+ * A match rule for the element someone just clicked.
+ *
+ * This is the whole "define an action by clicking" feature, and its single
+ * requirement is that the rule it proposes MATCHES WHAT AUTOCAPTURE RECORDED.
+ * A rule that merely looks plausible is worse than none: it saves cleanly,
+ * appears in every picker, and reports zero forever without erroring. So every
+ * field below is read exactly the way AutoCapture.buildElementProps reads it.
+ *
+ * Field choice, most stable first:
+ *   - `id`, when present. Unique and survives restyling.
+ *   - `href` for links, which is what the link MEANS rather than how it looks.
+ *   - visible text otherwise, because that is what the person clicking sees.
+ *
+ * Never CSS classes. Tailwind JIT and CSS-module hashes change them between
+ * builds, so an action keyed on one keeps matching until a deploy and then
+ * silently returns zero.
+ */
+interface ProposedStep {
+    event_type: 'click';
+    tag_name: string;
+    attr_id?: string;
+    href?: string;
+    text?: string;
+    text_match?: 'exact';
+    url?: string;
+    url_match?: 'exact';
+}
+declare function proposeActionStep(el: Element, pathname?: string): ProposedStep;
+/**
+ * Whether a proposed rule actually identifies anything.
+ *
+ * A step that is only a tag name means "every button on the site". That is a
+ * legal predicate and almost never what the author meant, so the toolbar warns
+ * rather than saving it silently.
+ */
+declare function isSpecificStep(step: ProposedStep): boolean;
+/**
+ * Colour for an intensity, 0..1.
+ *
+ * Blue through green to red, with opacity rising alongside it. Intensity is
+ * relative to the busiest bin on the page, so a quiet page still shows its
+ * hottest spot as hot rather than rendering uniformly cold.
+ */
+declare function intensityColor(intensity: number): string;
+/** Locally override a flag, for this browser only. */
+declare function setFlagOverride(key: string, value: boolean | string | null): void;
+declare function getFlagOverrides(): Record<string, unknown>;
+/**
+ * Start the toolbar.
+ *
+ * Returns a handle so a host can tear it down, and resolves to null when there
+ * is no launch token or the session is refused — the common case on a page load
+ * that has nothing to do with the toolbar. Failing silently is correct here:
+ * this runs on someone else's website.
+ */
+declare function startToolbar(options: ToolbarOptions): Promise<{
+    destroy(): void;
+} | null>;
+
+export { FLAG_OVERRIDE_KEY, type FeatureFlagSummary, type HeatmapBin, type ProposedStep, TOOLBAR_FRAGMENT_KEY, type ToolbarOptions, type ToolbarSession, binToPageCoords, consumeLaunchToken, describeElement, getFlagOverrides, intensityColor, isSpecificStep, proposeActionStep, setFlagOverride, startToolbar };

package/dist/index.d.ts

@@ -0,0 +1,161 @@
+/**
+ * @billdog.io/toolbar — the in-page inspection overlay.
+ *
+ * Renders on the customer's own site when a project member launches it from the
+ * dashboard: inspect an element to see the selector autocapture will record,
+ * view a click heatmap over the live page, and override a feature flag locally
+ * to check a variant without shipping a rollout.
+ *
+ * ## Launch
+ *
+ * The dashboard mints a short-lived signed token and puts it in the URL
+ * FRAGMENT. Fragments are not sent to servers on navigation, so the token does
+ * not land in the customer's access logs or in a Referer header on the way out.
+ * The toolbar reads it once and immediately strips it from the address bar, so
+ * a copied URL is not a working credential.
+ *
+ * ## Isolation
+ *
+ * Everything renders inside a shadow root. The toolbar is injected into a page
+ * whose CSS it has never seen: without a shadow root, the host's stylesheet
+ * reaches into the overlay and the overlay's reaches back out, and "the toolbar
+ * broke my site's layout" is not a defensible bug to ship.
+ */
+interface ToolbarOptions {
+    /** Where the toolbar API lives, e.g. https://<project>.supabase.co/functions/v1 */
+    apiHost: string;
+    /** Overrides the token read from the URL fragment. Mainly for tests. */
+    token?: string;
+}
+interface FeatureFlagSummary {
+    id: string;
+    key: string;
+    enabled: boolean;
+    rollout_percentage: number | null;
+}
+/** One aggregated click bin, as returned by the heatmap route. */
+interface HeatmapBin {
+    /** Fraction of viewport width, 0..1. */
+    relative_x: number;
+    /** Offset within the document, in pixels. */
+    page_y: number;
+    clicks: number;
+    users: number;
+    /** 0..1, normalised against the busiest bin on the page. */
+    intensity: number;
+}
+interface ToolbarSession {
+    project_id: string;
+    expires_at: number;
+    feature_flags: FeatureFlagSummary[];
+    event_definitions: Array<{
+        event_name: string;
+        display_name: string | null;
+    }>;
+}
+/** Fragment key the dashboard uses to hand over the launch token. */
+declare const TOOLBAR_FRAGMENT_KEY = "__billdog_toolbar__";
+/** localStorage key for flag overrides, read by the SDK's flag evaluation. */
+declare const FLAG_OVERRIDE_KEY = "billdog_flag_overrides";
+/**
+ * Read the launch token out of the URL fragment and remove it.
+ *
+ * Stripping matters: the toolbar is opened on a page a person is likely to
+ * screenshot, share or paste into a ticket, and a URL that still carries a live
+ * credential turns any of those into a leak. Exported so the removal is
+ * testable rather than a side effect buried in start-up.
+ */
+declare function consumeLaunchToken(location: {
+    hash: string;
+    href: string;
+}): {
+    token: string | null;
+    cleanedHref: string;
+};
+/**
+ * Build the selector autocapture would record for an element.
+ *
+ * Deliberately mirrors AutoCapture's `$elements_chain`: the point of the
+ * inspector is to show what the SDK will actually key on, so a selector that
+ * merely looks reasonable is worse than useless — someone would define an
+ * action against it and wonder why it never fires.
+ */
+declare function describeElement(el: Element): string;
+/**
+ * Place a bin on the CURRENT page.
+ *
+ * The stored coordinates are deliberately device-independent — a fraction of
+ * viewport width, and an offset within the document — because the clicks were
+ * aggregated across every screen size that visited the page. Turning them back
+ * into pixels is therefore a function of THIS viewport, which is what makes the
+ * overlay line up with what the person looking at it can see.
+ *
+ * `page_y` needs no conversion: it is already a document offset, so an absolutely
+ * positioned element at that y sits where the clicks were regardless of how far
+ * the reader has scrolled.
+ */
+declare function binToPageCoords(bin: Pick<HeatmapBin, 'relative_x' | 'page_y'>, viewportWidth: number): {
+    x: number;
+    y: number;
+};
+/**
+ * A match rule for the element someone just clicked.
+ *
+ * This is the whole "define an action by clicking" feature, and its single
+ * requirement is that the rule it proposes MATCHES WHAT AUTOCAPTURE RECORDED.
+ * A rule that merely looks plausible is worse than none: it saves cleanly,
+ * appears in every picker, and reports zero forever without erroring. So every
+ * field below is read exactly the way AutoCapture.buildElementProps reads it.
+ *
+ * Field choice, most stable first:
+ *   - `id`, when present. Unique and survives restyling.
+ *   - `href` for links, which is what the link MEANS rather than how it looks.
+ *   - visible text otherwise, because that is what the person clicking sees.
+ *
+ * Never CSS classes. Tailwind JIT and CSS-module hashes change them between
+ * builds, so an action keyed on one keeps matching until a deploy and then
+ * silently returns zero.
+ */
+interface ProposedStep {
+    event_type: 'click';
+    tag_name: string;
+    attr_id?: string;
+    href?: string;
+    text?: string;
+    text_match?: 'exact';
+    url?: string;
+    url_match?: 'exact';
+}
+declare function proposeActionStep(el: Element, pathname?: string): ProposedStep;
+/**
+ * Whether a proposed rule actually identifies anything.
+ *
+ * A step that is only a tag name means "every button on the site". That is a
+ * legal predicate and almost never what the author meant, so the toolbar warns
+ * rather than saving it silently.
+ */
+declare function isSpecificStep(step: ProposedStep): boolean;
+/**
+ * Colour for an intensity, 0..1.
+ *
+ * Blue through green to red, with opacity rising alongside it. Intensity is
+ * relative to the busiest bin on the page, so a quiet page still shows its
+ * hottest spot as hot rather than rendering uniformly cold.
+ */
+declare function intensityColor(intensity: number): string;
+/** Locally override a flag, for this browser only. */
+declare function setFlagOverride(key: string, value: boolean | string | null): void;
+declare function getFlagOverrides(): Record<string, unknown>;
+/**
+ * Start the toolbar.
+ *
+ * Returns a handle so a host can tear it down, and resolves to null when there
+ * is no launch token or the session is refused — the common case on a page load
+ * that has nothing to do with the toolbar. Failing silently is correct here:
+ * this runs on someone else's website.
+ */
+declare function startToolbar(options: ToolbarOptions): Promise<{
+    destroy(): void;
+} | null>;
+
+export { FLAG_OVERRIDE_KEY, type FeatureFlagSummary, type HeatmapBin, type ProposedStep, TOOLBAR_FRAGMENT_KEY, type ToolbarOptions, type ToolbarSession, binToPageCoords, consumeLaunchToken, describeElement, getFlagOverrides, intensityColor, isSpecificStep, proposeActionStep, setFlagOverride, startToolbar };

package/dist/index.js

@@ -0,0 +1,426 @@
+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);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  FLAG_OVERRIDE_KEY: () => FLAG_OVERRIDE_KEY,
+  TOOLBAR_FRAGMENT_KEY: () => TOOLBAR_FRAGMENT_KEY,
+  binToPageCoords: () => binToPageCoords,
+  consumeLaunchToken: () => consumeLaunchToken,
+  describeElement: () => describeElement,
+  getFlagOverrides: () => getFlagOverrides,
+  intensityColor: () => intensityColor,
+  isSpecificStep: () => isSpecificStep,
+  proposeActionStep: () => proposeActionStep,
+  setFlagOverride: () => setFlagOverride,
+  startToolbar: () => startToolbar
+});
+module.exports = __toCommonJS(index_exports);
+var TOOLBAR_FRAGMENT_KEY = "__billdog_toolbar__";
+var FLAG_OVERRIDE_KEY = "billdog_flag_overrides";
+function consumeLaunchToken(location2) {
+  const hash = location2.hash.startsWith("#") ? location2.hash.slice(1) : location2.hash;
+  if (!hash) return { token: null, cleanedHref: location2.href };
+  const params = new URLSearchParams(hash);
+  const token = params.get(TOOLBAR_FRAGMENT_KEY);
+  if (!token) return { token: null, cleanedHref: location2.href };
+  params.delete(TOOLBAR_FRAGMENT_KEY);
+  const rest = params.toString();
+  const base = location2.href.split("#")[0];
+  return { token, cleanedHref: rest ? `${base}#${rest}` : base };
+}
+function describeElement(el) {
+  const parts = [];
+  let current = el;
+  let depth = 0;
+  while (current && depth < 5) {
+    let part = current.tagName.toLowerCase();
+    if (current.id) {
+      parts.unshift(`${part}#${current.id}`);
+      break;
+    }
+    const classes = Array.from(current.classList).filter((c) => !["bd-mask", "bd-no-capture", "ph-no-capture", "ph-sensitive"].includes(c)).slice(0, 2);
+    if (classes.length > 0) part += `.${classes.join(".")}`;
+    parts.unshift(part);
+    current = current.parentElement;
+    depth++;
+  }
+  return parts.join(" > ");
+}
+function binToPageCoords(bin, viewportWidth) {
+  return {
+    x: Math.round(bin.relative_x * viewportWidth),
+    y: Math.round(bin.page_y)
+  };
+}
+var TOOLBAR_MASK_CLASSES = ["bd-mask", "ph-sensitive"];
+var VALUE_TAGS = ["INPUT", "TEXTAREA", "SELECT"];
+var MAX_PROPOSED_TEXT = 120;
+function isMaskedForToolbar(el) {
+  let node = el;
+  while (node) {
+    if (node.classList && TOOLBAR_MASK_CLASSES.some((c) => node.classList.contains(c))) return true;
+    node = node.parentElement;
+  }
+  return false;
+}
+function proposeActionStep(el, pathname) {
+  var _a, _b;
+  const step = {
+    // Autocapture stamps this on clicks. Without it the rule would also match
+    // `change` and `submit` on the same element.
+    event_type: "click",
+    tag_name: el.tagName ? el.tagName.toLowerCase() : ""
+  };
+  const id = (_a = el.getAttribute) == null ? void 0 : _a.call(el, "id");
+  const href = (_b = el.getAttribute) == null ? void 0 : _b.call(el, "href");
+  if (id) {
+    step.attr_id = id;
+  } else if (href) {
+    step.href = href;
+  } else if (!VALUE_TAGS.includes(el.tagName) && !isMaskedForToolbar(el)) {
+    const text = (el.textContent ?? "").trim().slice(0, 255);
+    if (text && text.length <= MAX_PROPOSED_TEXT) {
+      step.text = text;
+      step.text_match = "exact";
+    }
+  }
+  if (pathname) {
+    step.url = pathname;
+    step.url_match = "exact";
+  }
+  return step;
+}
+function isSpecificStep(step) {
+  return Boolean(step.attr_id || step.href || step.text);
+}
+function intensityColor(intensity) {
+  const t = Number.isFinite(intensity) ? Math.max(0, Math.min(1, intensity)) : 0;
+  const hue = Math.round(240 - t * 240);
+  const alpha = (0.25 + t * 0.45).toFixed(2);
+  return `hsla(${hue}, 90%, 50%, ${alpha})`;
+}
+function setFlagOverride(key, value) {
+  try {
+    const raw = localStorage.getItem(FLAG_OVERRIDE_KEY);
+    const overrides = raw ? JSON.parse(raw) : {};
+    if (value === null) delete overrides[key];
+    else overrides[key] = value;
+    localStorage.setItem(FLAG_OVERRIDE_KEY, JSON.stringify(overrides));
+  } catch {
+  }
+}
+function getFlagOverrides() {
+  try {
+    const raw = localStorage.getItem(FLAG_OVERRIDE_KEY);
+    return raw ? JSON.parse(raw) : {};
+  } catch {
+    return {};
+  }
+}
+async function startToolbar(options) {
+  if (typeof window === "undefined" || typeof document === "undefined") return null;
+  const { token, cleanedHref } = options.token ? { token: options.token, cleanedHref: window.location.href } : consumeLaunchToken(window.location);
+  if (!token) return null;
+  if (cleanedHref !== window.location.href) {
+    window.history.replaceState(null, "", cleanedHref);
+  }
+  let session;
+  try {
+    const res = await fetch(`${options.apiHost.replace(/\/$/, "")}/toolbar/session`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ token, url: window.location.href })
+    });
+    if (!res.ok) return null;
+    const json = await res.json();
+    session = (json == null ? void 0 : json.data) ?? json;
+  } catch {
+    return null;
+  }
+  return render(session, options.apiHost, token);
+}
+function render(session, apiHost, token) {
+  const host = document.createElement("div");
+  host.setAttribute("data-billdog-toolbar", "");
+  host.style.cssText = "position:fixed;z-index:2147483647;bottom:16px;right:16px;";
+  const shadow = host.attachShadow({ mode: "closed" });
+  const style = document.createElement("style");
+  style.textContent = `
+    :host { all: initial; }
+    .panel {
+      font: 13px/1.5 -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+      background: #12161C; color: #E7ECF1;
+      border-radius: 8px; box-shadow: 0 8px 32px rgba(0,0,0,.4);
+      width: 300px; overflow: hidden;
+    }
+    .head { display:flex; align-items:center; gap:8px; padding:10px 12px; background:#1D242D; }
+    .head b { font-weight:600; }
+    .body { padding: 10px 12px; max-height: 320px; overflow-y: auto; }
+    .row { display:flex; align-items:center; justify-content:space-between; gap:8px; padding:4px 0; }
+    button { font: inherit; background:#2F6F5E; color:#fff; border:0; border-radius:5px;
+             padding:4px 9px; cursor:pointer; }
+    button.ghost { background:#2A323C; }
+    .muted { color:#8A96A3; font-size:12px; }
+    .sel { font-family: ui-monospace, monospace; font-size:11px; word-break:break-all; color:#74C3A8; }
+  `;
+  const panel = document.createElement("div");
+  panel.className = "panel";
+  panel.innerHTML = `
+    <div class="head"><b>BillDog</b><span class="muted">toolbar</span></div>
+    <div class="body">
+      <div class="row">
+        <span>Inspect elements</span>
+        <button id="bd-inspect" class="ghost">Start</button>
+      </div>
+      <div class="row">
+        <span>Click heatmap</span>
+        <button id="bd-heatmap" class="ghost">Show</button>
+      </div>
+      <div class="row"><span class="muted" id="bd-heatmap-status"></span></div>
+      <div class="row"><span class="sel" id="bd-selected"></span></div>
+      <div id="bd-action" style="display:none">
+        <div class="row"><span class="muted" id="bd-action-rule"></span></div>
+        <div class="row">
+          <input id="bd-action-name" placeholder="Name this action" maxlength="120" />
+        </div>
+        <div class="row">
+          <label class="muted"><input type="checkbox" id="bd-action-scope" /> only on this page</label>
+          <button id="bd-action-save" class="ghost">Create action</button>
+        </div>
+        <div class="row"><span class="muted" id="bd-action-status"></span></div>
+      </div>
+      <div class="row muted">Feature flags</div>
+      <div id="bd-flags"></div>
+    </div>
+  `;
+  shadow.append(style, panel);
+  document.body.appendChild(host);
+  const overrides = getFlagOverrides();
+  const flagList = panel.querySelector("#bd-flags");
+  for (const flag of session.feature_flags.slice(0, 50)) {
+    const row = document.createElement("div");
+    row.className = "row";
+    const overridden = flag.key in overrides;
+    row.innerHTML = `<span>${escapeHtml(flag.key)}</span>`;
+    const btn = document.createElement("button");
+    btn.className = overridden ? "" : "ghost";
+    btn.textContent = overridden ? String(overrides[flag.key]) : flag.enabled ? "on" : "off";
+    btn.onclick = () => {
+      const current = getFlagOverrides()[flag.key];
+      const nextValue = current === void 0 ? true : current === true ? false : null;
+      setFlagOverride(flag.key, nextValue);
+      btn.textContent = nextValue === null ? flag.enabled ? "on" : "off" : String(nextValue);
+      btn.className = nextValue === null ? "ghost" : "";
+    };
+    row.appendChild(btn);
+    flagList.appendChild(row);
+  }
+  const selected = panel.querySelector("#bd-selected");
+  const inspectBtn = panel.querySelector("#bd-inspect");
+  let inspecting = false;
+  let lastOutlined = null;
+  const onOver = (e) => {
+    const target = e.target;
+    if (!target || host.contains(target)) return;
+    if (lastOutlined) lastOutlined.style.outline = "";
+    target.style.outline = "2px solid #74C3A8";
+    lastOutlined = target;
+  };
+  const actionBox = panel.querySelector("#bd-action");
+  const actionRule = panel.querySelector("#bd-action-rule");
+  const actionName = panel.querySelector("#bd-action-name");
+  const actionScope = panel.querySelector("#bd-action-scope");
+  const actionSave = panel.querySelector("#bd-action-save");
+  const actionStatus = panel.querySelector("#bd-action-status");
+  let pending = null;
+  const describeRule = (step) => {
+    if (step.attr_id) return `${step.tag_name}#${step.attr_id}`;
+    if (step.href) return `${step.tag_name}[href="${step.href}"]`;
+    if (step.text) return `${step.tag_name} labelled "${step.text}"`;
+    return `every <${step.tag_name}> on the site`;
+  };
+  const onClick = (e) => {
+    const target = e.target;
+    if (!target || host.contains(target)) return;
+    e.preventDefault();
+    e.stopPropagation();
+    selected.textContent = describeElement(target);
+    pending = proposeActionStep(target);
+    actionRule.textContent = isSpecificStep(pending) ? `Matches ${describeRule(pending)}` : `This would match ${describeRule(pending)} \u2014 pick something more specific.`;
+    actionStatus.textContent = "";
+    actionBox.style.display = "";
+  };
+  actionSave.onclick = async () => {
+    var _a;
+    if (!pending) return;
+    const name = actionName.value.trim();
+    if (!name) {
+      actionStatus.textContent = "Give it a name first.";
+      return;
+    }
+    const step = actionScope.checked ? { ...pending, url: location.pathname, url_match: "exact" } : pending;
+    actionSave.disabled = true;
+    actionStatus.textContent = "Saving...";
+    try {
+      const res = await fetch(`${apiHost.replace(/\/$/, "")}/toolbar/action`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          token,
+          url: location.href,
+          name,
+          steps: [step]
+        })
+      });
+      const json = await res.json().catch(() => null);
+      if (!res.ok) {
+        actionStatus.textContent = ((_a = json == null ? void 0 : json.error) == null ? void 0 : _a.message) ?? "Could not save the action.";
+        return;
+      }
+      actionStatus.textContent = `Created "${name}" \u2014 usable in funnels and trends, over history.`;
+      actionName.value = "";
+      pending = null;
+      actionBox.style.display = "none";
+    } catch {
+      actionStatus.textContent = "Could not reach BillDog.";
+    } finally {
+      actionSave.disabled = false;
+    }
+  };
+  const stopInspecting = () => {
+    inspecting = false;
+    inspectBtn.textContent = "Start";
+    document.removeEventListener("mouseover", onOver, true);
+    document.removeEventListener("click", onClick, true);
+    if (lastOutlined) {
+      lastOutlined.style.outline = "";
+      lastOutlined = null;
+    }
+  };
+  inspectBtn.onclick = () => {
+    if (inspecting) return stopInspecting();
+    inspecting = true;
+    inspectBtn.textContent = "Stop";
+    document.addEventListener("mouseover", onOver, true);
+    document.addEventListener("click", onClick, true);
+  };
+  const heatmapBtn = panel.querySelector("#bd-heatmap");
+  const heatmapStatus = panel.querySelector("#bd-heatmap-status");
+  let heatmapLayer = null;
+  let heatmapBins = null;
+  const paintHeatmap = (bins) => {
+    heatmapLayer == null ? void 0 : heatmapLayer.remove();
+    const layer = document.createElement("div");
+    layer.setAttribute("data-billdog-heatmap", "");
+    layer.style.cssText = [
+      "position:absolute",
+      "top:0",
+      "left:0",
+      "width:100%",
+      `height:${document.documentElement.scrollHeight}px`,
+      "z-index:2147483646",
+      // Clicks pass straight through: an overlay that swallowed them would stop
+      // the person exploring the page they came to look at.
+      "pointer-events:none"
+    ].join(";");
+    const width = document.documentElement.clientWidth;
+    for (const bin of bins) {
+      const { x, y } = binToPageCoords(bin, width);
+      const dot = document.createElement("div");
+      const size = 24 + Math.round(bin.intensity * 36);
+      dot.style.cssText = [
+        "position:absolute",
+        `left:${x - size / 2}px`,
+        `top:${y - size / 2}px`,
+        `width:${size}px`,
+        `height:${size}px`,
+        "border-radius:50%",
+        `background:radial-gradient(circle, ${intensityColor(bin.intensity)} 0%, transparent 70%)`
+      ].join(";");
+      dot.title = `${bin.clicks} clicks \xB7 ${bin.users} users`;
+      layer.appendChild(dot);
+    }
+    document.body.appendChild(layer);
+    heatmapLayer = layer;
+  };
+  const hideHeatmap = () => {
+    heatmapLayer == null ? void 0 : heatmapLayer.remove();
+    heatmapLayer = null;
+    heatmapBtn.textContent = "Show";
+    heatmapBtn.className = "ghost";
+  };
+  heatmapBtn.onclick = async () => {
+    if (heatmapLayer) return hideHeatmap();
+    if (!heatmapBins) {
+      heatmapStatus.textContent = "Loading\u2026";
+      try {
+        const res = await fetch(`${apiHost.replace(/\/$/, "")}/toolbar/heatmap`, {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({ token, url: window.location.href })
+        });
+        if (!res.ok) throw new Error(String(res.status));
+        const json = await res.json();
+        const payload = (json == null ? void 0 : json.data) ?? json;
+        heatmapBins = payload.bins ?? [];
+      } catch {
+        heatmapStatus.textContent = "Could not load heatmap data.";
+        return;
+      }
+    }
+    if (heatmapBins.length === 0) {
+      heatmapStatus.textContent = "No clicks recorded for this page. Heatmap capture is opt-in in project settings.";
+      return;
+    }
+    heatmapStatus.textContent = `${heatmapBins.length} hotspots`;
+    paintHeatmap(heatmapBins);
+    heatmapBtn.textContent = "Hide";
+    heatmapBtn.className = "";
+  };
+  const onResize = () => {
+    if (heatmapLayer && heatmapBins) paintHeatmap(heatmapBins);
+  };
+  window.addEventListener("resize", onResize);
+  return {
+    destroy() {
+      stopInspecting();
+      hideHeatmap();
+      window.removeEventListener("resize", onResize);
+      host.remove();
+    }
+  };
+}
+function escapeHtml(s) {
+  return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  FLAG_OVERRIDE_KEY,
+  TOOLBAR_FRAGMENT_KEY,
+  binToPageCoords,
+  consumeLaunchToken,
+  describeElement,
+  getFlagOverrides,
+  intensityColor,
+  isSpecificStep,
+  proposeActionStep,
+  setFlagOverride,
+  startToolbar
+});

package/dist/index.mjs

@@ -0,0 +1,392 @@
+// src/index.ts
+var TOOLBAR_FRAGMENT_KEY = "__billdog_toolbar__";
+var FLAG_OVERRIDE_KEY = "billdog_flag_overrides";
+function consumeLaunchToken(location2) {
+  const hash = location2.hash.startsWith("#") ? location2.hash.slice(1) : location2.hash;
+  if (!hash) return { token: null, cleanedHref: location2.href };
+  const params = new URLSearchParams(hash);
+  const token = params.get(TOOLBAR_FRAGMENT_KEY);
+  if (!token) return { token: null, cleanedHref: location2.href };
+  params.delete(TOOLBAR_FRAGMENT_KEY);
+  const rest = params.toString();
+  const base = location2.href.split("#")[0];
+  return { token, cleanedHref: rest ? `${base}#${rest}` : base };
+}
+function describeElement(el) {
+  const parts = [];
+  let current = el;
+  let depth = 0;
+  while (current && depth < 5) {
+    let part = current.tagName.toLowerCase();
+    if (current.id) {
+      parts.unshift(`${part}#${current.id}`);
+      break;
+    }
+    const classes = Array.from(current.classList).filter((c) => !["bd-mask", "bd-no-capture", "ph-no-capture", "ph-sensitive"].includes(c)).slice(0, 2);
+    if (classes.length > 0) part += `.${classes.join(".")}`;
+    parts.unshift(part);
+    current = current.parentElement;
+    depth++;
+  }
+  return parts.join(" > ");
+}
+function binToPageCoords(bin, viewportWidth) {
+  return {
+    x: Math.round(bin.relative_x * viewportWidth),
+    y: Math.round(bin.page_y)
+  };
+}
+var TOOLBAR_MASK_CLASSES = ["bd-mask", "ph-sensitive"];
+var VALUE_TAGS = ["INPUT", "TEXTAREA", "SELECT"];
+var MAX_PROPOSED_TEXT = 120;
+function isMaskedForToolbar(el) {
+  let node = el;
+  while (node) {
+    if (node.classList && TOOLBAR_MASK_CLASSES.some((c) => node.classList.contains(c))) return true;
+    node = node.parentElement;
+  }
+  return false;
+}
+function proposeActionStep(el, pathname) {
+  var _a, _b;
+  const step = {
+    // Autocapture stamps this on clicks. Without it the rule would also match
+    // `change` and `submit` on the same element.
+    event_type: "click",
+    tag_name: el.tagName ? el.tagName.toLowerCase() : ""
+  };
+  const id = (_a = el.getAttribute) == null ? void 0 : _a.call(el, "id");
+  const href = (_b = el.getAttribute) == null ? void 0 : _b.call(el, "href");
+  if (id) {
+    step.attr_id = id;
+  } else if (href) {
+    step.href = href;
+  } else if (!VALUE_TAGS.includes(el.tagName) && !isMaskedForToolbar(el)) {
+    const text = (el.textContent ?? "").trim().slice(0, 255);
+    if (text && text.length <= MAX_PROPOSED_TEXT) {
+      step.text = text;
+      step.text_match = "exact";
+    }
+  }
+  if (pathname) {
+    step.url = pathname;
+    step.url_match = "exact";
+  }
+  return step;
+}
+function isSpecificStep(step) {
+  return Boolean(step.attr_id || step.href || step.text);
+}
+function intensityColor(intensity) {
+  const t = Number.isFinite(intensity) ? Math.max(0, Math.min(1, intensity)) : 0;
+  const hue = Math.round(240 - t * 240);
+  const alpha = (0.25 + t * 0.45).toFixed(2);
+  return `hsla(${hue}, 90%, 50%, ${alpha})`;
+}
+function setFlagOverride(key, value) {
+  try {
+    const raw = localStorage.getItem(FLAG_OVERRIDE_KEY);
+    const overrides = raw ? JSON.parse(raw) : {};
+    if (value === null) delete overrides[key];
+    else overrides[key] = value;
+    localStorage.setItem(FLAG_OVERRIDE_KEY, JSON.stringify(overrides));
+  } catch {
+  }
+}
+function getFlagOverrides() {
+  try {
+    const raw = localStorage.getItem(FLAG_OVERRIDE_KEY);
+    return raw ? JSON.parse(raw) : {};
+  } catch {
+    return {};
+  }
+}
+async function startToolbar(options) {
+  if (typeof window === "undefined" || typeof document === "undefined") return null;
+  const { token, cleanedHref } = options.token ? { token: options.token, cleanedHref: window.location.href } : consumeLaunchToken(window.location);
+  if (!token) return null;
+  if (cleanedHref !== window.location.href) {
+    window.history.replaceState(null, "", cleanedHref);
+  }
+  let session;
+  try {
+    const res = await fetch(`${options.apiHost.replace(/\/$/, "")}/toolbar/session`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ token, url: window.location.href })
+    });
+    if (!res.ok) return null;
+    const json = await res.json();
+    session = (json == null ? void 0 : json.data) ?? json;
+  } catch {
+    return null;
+  }
+  return render(session, options.apiHost, token);
+}
+function render(session, apiHost, token) {
+  const host = document.createElement("div");
+  host.setAttribute("data-billdog-toolbar", "");
+  host.style.cssText = "position:fixed;z-index:2147483647;bottom:16px;right:16px;";
+  const shadow = host.attachShadow({ mode: "closed" });
+  const style = document.createElement("style");
+  style.textContent = `
+    :host { all: initial; }
+    .panel {
+      font: 13px/1.5 -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+      background: #12161C; color: #E7ECF1;
+      border-radius: 8px; box-shadow: 0 8px 32px rgba(0,0,0,.4);
+      width: 300px; overflow: hidden;
+    }
+    .head { display:flex; align-items:center; gap:8px; padding:10px 12px; background:#1D242D; }
+    .head b { font-weight:600; }
+    .body { padding: 10px 12px; max-height: 320px; overflow-y: auto; }
+    .row { display:flex; align-items:center; justify-content:space-between; gap:8px; padding:4px 0; }
+    button { font: inherit; background:#2F6F5E; color:#fff; border:0; border-radius:5px;
+             padding:4px 9px; cursor:pointer; }
+    button.ghost { background:#2A323C; }
+    .muted { color:#8A96A3; font-size:12px; }
+    .sel { font-family: ui-monospace, monospace; font-size:11px; word-break:break-all; color:#74C3A8; }
+  `;
+  const panel = document.createElement("div");
+  panel.className = "panel";
+  panel.innerHTML = `
+    <div class="head"><b>BillDog</b><span class="muted">toolbar</span></div>
+    <div class="body">
+      <div class="row">
+        <span>Inspect elements</span>
+        <button id="bd-inspect" class="ghost">Start</button>
+      </div>
+      <div class="row">
+        <span>Click heatmap</span>
+        <button id="bd-heatmap" class="ghost">Show</button>
+      </div>
+      <div class="row"><span class="muted" id="bd-heatmap-status"></span></div>
+      <div class="row"><span class="sel" id="bd-selected"></span></div>
+      <div id="bd-action" style="display:none">
+        <div class="row"><span class="muted" id="bd-action-rule"></span></div>
+        <div class="row">
+          <input id="bd-action-name" placeholder="Name this action" maxlength="120" />
+        </div>
+        <div class="row">
+          <label class="muted"><input type="checkbox" id="bd-action-scope" /> only on this page</label>
+          <button id="bd-action-save" class="ghost">Create action</button>
+        </div>
+        <div class="row"><span class="muted" id="bd-action-status"></span></div>
+      </div>
+      <div class="row muted">Feature flags</div>
+      <div id="bd-flags"></div>
+    </div>
+  `;
+  shadow.append(style, panel);
+  document.body.appendChild(host);
+  const overrides = getFlagOverrides();
+  const flagList = panel.querySelector("#bd-flags");
+  for (const flag of session.feature_flags.slice(0, 50)) {
+    const row = document.createElement("div");
+    row.className = "row";
+    const overridden = flag.key in overrides;
+    row.innerHTML = `<span>${escapeHtml(flag.key)}</span>`;
+    const btn = document.createElement("button");
+    btn.className = overridden ? "" : "ghost";
+    btn.textContent = overridden ? String(overrides[flag.key]) : flag.enabled ? "on" : "off";
+    btn.onclick = () => {
+      const current = getFlagOverrides()[flag.key];
+      const nextValue = current === void 0 ? true : current === true ? false : null;
+      setFlagOverride(flag.key, nextValue);
+      btn.textContent = nextValue === null ? flag.enabled ? "on" : "off" : String(nextValue);
+      btn.className = nextValue === null ? "ghost" : "";
+    };
+    row.appendChild(btn);
+    flagList.appendChild(row);
+  }
+  const selected = panel.querySelector("#bd-selected");
+  const inspectBtn = panel.querySelector("#bd-inspect");
+  let inspecting = false;
+  let lastOutlined = null;
+  const onOver = (e) => {
+    const target = e.target;
+    if (!target || host.contains(target)) return;
+    if (lastOutlined) lastOutlined.style.outline = "";
+    target.style.outline = "2px solid #74C3A8";
+    lastOutlined = target;
+  };
+  const actionBox = panel.querySelector("#bd-action");
+  const actionRule = panel.querySelector("#bd-action-rule");
+  const actionName = panel.querySelector("#bd-action-name");
+  const actionScope = panel.querySelector("#bd-action-scope");
+  const actionSave = panel.querySelector("#bd-action-save");
+  const actionStatus = panel.querySelector("#bd-action-status");
+  let pending = null;
+  const describeRule = (step) => {
+    if (step.attr_id) return `${step.tag_name}#${step.attr_id}`;
+    if (step.href) return `${step.tag_name}[href="${step.href}"]`;
+    if (step.text) return `${step.tag_name} labelled "${step.text}"`;
+    return `every <${step.tag_name}> on the site`;
+  };
+  const onClick = (e) => {
+    const target = e.target;
+    if (!target || host.contains(target)) return;
+    e.preventDefault();
+    e.stopPropagation();
+    selected.textContent = describeElement(target);
+    pending = proposeActionStep(target);
+    actionRule.textContent = isSpecificStep(pending) ? `Matches ${describeRule(pending)}` : `This would match ${describeRule(pending)} \u2014 pick something more specific.`;
+    actionStatus.textContent = "";
+    actionBox.style.display = "";
+  };
+  actionSave.onclick = async () => {
+    var _a;
+    if (!pending) return;
+    const name = actionName.value.trim();
+    if (!name) {
+      actionStatus.textContent = "Give it a name first.";
+      return;
+    }
+    const step = actionScope.checked ? { ...pending, url: location.pathname, url_match: "exact" } : pending;
+    actionSave.disabled = true;
+    actionStatus.textContent = "Saving...";
+    try {
+      const res = await fetch(`${apiHost.replace(/\/$/, "")}/toolbar/action`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          token,
+          url: location.href,
+          name,
+          steps: [step]
+        })
+      });
+      const json = await res.json().catch(() => null);
+      if (!res.ok) {
+        actionStatus.textContent = ((_a = json == null ? void 0 : json.error) == null ? void 0 : _a.message) ?? "Could not save the action.";
+        return;
+      }
+      actionStatus.textContent = `Created "${name}" \u2014 usable in funnels and trends, over history.`;
+      actionName.value = "";
+      pending = null;
+      actionBox.style.display = "none";
+    } catch {
+      actionStatus.textContent = "Could not reach BillDog.";
+    } finally {
+      actionSave.disabled = false;
+    }
+  };
+  const stopInspecting = () => {
+    inspecting = false;
+    inspectBtn.textContent = "Start";
+    document.removeEventListener("mouseover", onOver, true);
+    document.removeEventListener("click", onClick, true);
+    if (lastOutlined) {
+      lastOutlined.style.outline = "";
+      lastOutlined = null;
+    }
+  };
+  inspectBtn.onclick = () => {
+    if (inspecting) return stopInspecting();
+    inspecting = true;
+    inspectBtn.textContent = "Stop";
+    document.addEventListener("mouseover", onOver, true);
+    document.addEventListener("click", onClick, true);
+  };
+  const heatmapBtn = panel.querySelector("#bd-heatmap");
+  const heatmapStatus = panel.querySelector("#bd-heatmap-status");
+  let heatmapLayer = null;
+  let heatmapBins = null;
+  const paintHeatmap = (bins) => {
+    heatmapLayer == null ? void 0 : heatmapLayer.remove();
+    const layer = document.createElement("div");
+    layer.setAttribute("data-billdog-heatmap", "");
+    layer.style.cssText = [
+      "position:absolute",
+      "top:0",
+      "left:0",
+      "width:100%",
+      `height:${document.documentElement.scrollHeight}px`,
+      "z-index:2147483646",
+      // Clicks pass straight through: an overlay that swallowed them would stop
+      // the person exploring the page they came to look at.
+      "pointer-events:none"
+    ].join(";");
+    const width = document.documentElement.clientWidth;
+    for (const bin of bins) {
+      const { x, y } = binToPageCoords(bin, width);
+      const dot = document.createElement("div");
+      const size = 24 + Math.round(bin.intensity * 36);
+      dot.style.cssText = [
+        "position:absolute",
+        `left:${x - size / 2}px`,
+        `top:${y - size / 2}px`,
+        `width:${size}px`,
+        `height:${size}px`,
+        "border-radius:50%",
+        `background:radial-gradient(circle, ${intensityColor(bin.intensity)} 0%, transparent 70%)`
+      ].join(";");
+      dot.title = `${bin.clicks} clicks \xB7 ${bin.users} users`;
+      layer.appendChild(dot);
+    }
+    document.body.appendChild(layer);
+    heatmapLayer = layer;
+  };
+  const hideHeatmap = () => {
+    heatmapLayer == null ? void 0 : heatmapLayer.remove();
+    heatmapLayer = null;
+    heatmapBtn.textContent = "Show";
+    heatmapBtn.className = "ghost";
+  };
+  heatmapBtn.onclick = async () => {
+    if (heatmapLayer) return hideHeatmap();
+    if (!heatmapBins) {
+      heatmapStatus.textContent = "Loading\u2026";
+      try {
+        const res = await fetch(`${apiHost.replace(/\/$/, "")}/toolbar/heatmap`, {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({ token, url: window.location.href })
+        });
+        if (!res.ok) throw new Error(String(res.status));
+        const json = await res.json();
+        const payload = (json == null ? void 0 : json.data) ?? json;
+        heatmapBins = payload.bins ?? [];
+      } catch {
+        heatmapStatus.textContent = "Could not load heatmap data.";
+        return;
+      }
+    }
+    if (heatmapBins.length === 0) {
+      heatmapStatus.textContent = "No clicks recorded for this page. Heatmap capture is opt-in in project settings.";
+      return;
+    }
+    heatmapStatus.textContent = `${heatmapBins.length} hotspots`;
+    paintHeatmap(heatmapBins);
+    heatmapBtn.textContent = "Hide";
+    heatmapBtn.className = "";
+  };
+  const onResize = () => {
+    if (heatmapLayer && heatmapBins) paintHeatmap(heatmapBins);
+  };
+  window.addEventListener("resize", onResize);
+  return {
+    destroy() {
+      stopInspecting();
+      hideHeatmap();
+      window.removeEventListener("resize", onResize);
+      host.remove();
+    }
+  };
+}
+function escapeHtml(s) {
+  return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+export {
+  FLAG_OVERRIDE_KEY,
+  TOOLBAR_FRAGMENT_KEY,
+  binToPageCoords,
+  consumeLaunchToken,
+  describeElement,
+  getFlagOverrides,
+  intensityColor,
+  isSpecificStep,
+  proposeActionStep,
+  setFlagOverride,
+  startToolbar
+};

package/package.json

@@ -1,6 +1,28 @@
 {
   "name": "@billdog.io/toolbar",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.2-beta.3",
+  "description": "BillDog in-page toolbar — element inspector, feature-flag overrides and heatmaps on your own site",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts",
+    "dev": "tsup src/index.ts --format cjs,esm --dts --watch",
+    "clean": "rm -rf dist"
+  },
+  "keywords": [
+    "billdog",
+    "toolbar",
+    "heatmap",
+    "feature-flags"
+  ],
+  "author": "BillDog",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  }
+}