@hexclave/shared 1.0.13 → 1.0.15

package/src/interface/admin-metrics.ts

@@ -140,9 +140,9 @@ export const MetricsAnalyticsOverviewSchema = yupObject({
   daily_bounce_rate: yupArray(MetricsDataPointSchema).optional().default([]),
   daily_avg_session_seconds: yupArray(MetricsDataPointSchema).optional().default([]),
   // User-Agent-derived breakdowns for the analytics overview. Computed from the
-  // `data.user_agent` blob on `$page-view` events (captured client-side only,
-  // no server-side fallback). Optional + default-[] for one release cycle
-  // so older clients / servers without UA capture don't fail validation.
+  // `data.user_agent` blob on `$page-view` events, captured client-side.
+  // Optional + default-[] for one release cycle so older clients / servers
+  // without UA capture don't fail validation.
   top_browsers: yupArray(MetricsNamedCountSchema).optional().default([]),
   top_operating_systems: yupArray(MetricsNamedCountSchema).optional().default([]),
   top_devices: yupArray(MetricsNamedCountSchema).optional().default([]),
@@ -172,13 +172,77 @@ export const MetricsRecentUserSchema = yupObject({
   last_active_at_millis: yupNumber().nullable().defined(),
 }).noUnknown(false).defined();
 
-// Per-user activity heatmap — a simple list of daily event counts for a single
+// Per-user activity clickmap — a simple list of daily event counts for a single
 // user. Backed by ClickHouse `analytics_internal.events` filtered by user_id,
 // project_id, and branch_id. See `/internal/user-activity` on the backend.
 export const UserActivityResponseBodySchema = yupObject({
   data_points: MetricsDataPointsSchema,
 }).defined();
 
+export const AnalyticsClickmapKindSchema = yupString().oneOf(["team_user_hour_of_week", "session_replay_clicks"]).defined();
+export const AnalyticsClickmapDeviceSchema = yupString().oneOf(["tv", "widescreen", "desktop", "laptop", "tablet", "mobile"]).defined();
+
+export const AnalyticsClickmapTokenResponseBodySchema = yupObject({
+  token: yupString().defined(),
+  origin: yupString().defined(),
+  expires_at_millis: yupNumber().integer().defined(),
+}).defined();
+
+export const AnalyticsClickmapCellSchema = yupObject({
+  weekday: yupNumber().integer().min(1).max(7).defined(),
+  hour: yupNumber().integer().min(0).max(23).defined(),
+  value: yupNumber().integer().defined(),
+}).defined();
+
+export const AnalyticsClickmapResponseBodySchema = yupObject({
+  kind: AnalyticsClickmapKindSchema,
+  cells: yupArray(AnalyticsClickmapCellSchema).defined(),
+  // Fraction of source rows the result was computed from (1 = full scan).
+  // Returned counts are pre-scaled by 1/sampling.
+  sampling: yupNumber().min(0).max(1).optional().default(1),
+  routes: yupArray(yupObject({
+    path: yupString().defined(),
+    clicks: yupNumber().integer().defined(),
+    users: yupNumber().integer().defined(),
+    replays: yupNumber().integer().defined(),
+  }).defined()).optional().default([]),
+  users: yupArray(yupObject({
+    id: yupString().defined(),
+    display_name: yupString().nullable().defined(),
+    primary_email: yupString().nullable().defined(),
+    profile_image_url: yupString().nullable().defined(),
+    clicks: yupNumber().integer().defined(),
+    replays: yupNumber().integer().defined(),
+    last_event_at_millis: yupNumber().defined(),
+  }).defined()).optional().default([]),
+  replays: yupArray(yupObject({
+    id: yupString().defined(),
+    user_id: yupString().nullable().defined(),
+    route_path: yupString().nullable().defined(),
+    viewport_width: yupNumber().integer().nullable().defined(),
+    viewport_height: yupNumber().integer().nullable().defined(),
+    clicks: yupNumber().integer().defined(),
+    last_event_at_millis: yupNumber().defined(),
+  }).defined()).optional().default([]),
+  selectors: yupArray(yupObject({
+    selector: yupString().defined(),
+    clicks: yupNumber().integer().defined(),
+  }).defined()).optional().default([]),
+  // PostHog-style aggregated element identities. Resilient to DOM drift
+  // because the chain encodes ancestor tags/classes/attrs/text rather than
+  // a positional CSS selector.
+  elements: yupArray(yupObject({
+    elements_chain: yupString().defined(),
+    elements_text: yupString().defined(),
+    tag_name: yupString().defined(),
+    href: yupString().nullable().defined(),
+    clicks: yupNumber().integer().defined(),
+    // Optional for one release cycle so new overlay clients can validate
+    // responses from older servers that only returned aggregate click counts.
+    dead_clicks: yupNumber().integer().optional().default(0),
+  }).defined()).optional().default([]),
+}).defined();
+
 // Recent "currently live" users keyed by ISO country code. Populated by
 // joining a bounded ClickHouse selection from the live `$token-refresh` window
 // with the corresponding Prisma profile rows, so the overview globe can render
@@ -243,3 +307,27 @@ export type MetricsRecentUser = yup.InferType<typeof MetricsRecentUserSchema>;
 export type MetricsResponse = yup.InferType<typeof MetricsResponseBodySchema>;
 export type MetricsUserCounts = yup.InferType<typeof MetricsUserCountsSchema>;
 export type UserActivityResponse = yup.InferType<typeof UserActivityResponseBodySchema>;
+export type AnalyticsClickmapKind = yup.InferType<typeof AnalyticsClickmapKindSchema>;
+export type AnalyticsClickmapDevice = yup.InferType<typeof AnalyticsClickmapDeviceSchema>;
+export type AnalyticsClickmapCell = yup.InferType<typeof AnalyticsClickmapCellSchema>;
+export type AnalyticsClickmapResponse = yup.InferType<typeof AnalyticsClickmapResponseBodySchema>;
+export type AnalyticsClickmapTokenResponse = yup.InferType<typeof AnalyticsClickmapTokenResponseBodySchema>;
+
+// Single (camelCase) options shape for the clickmap SDK surface — shared by the
+// StackAdminApp interface and its implementation so the two can't drift. The
+// HexclaveAdminInterface transport layer maps these to the snake_case request body.
+export type AnalyticsClickmapOptions = {
+  kind: AnalyticsClickmapKind,
+  memberUserIds?: string[],
+  routePath?: string,
+  routeRegex?: string,
+  urlPattern?: string,
+  userId?: string,
+  replayId?: string,
+  device?: AnalyticsClickmapDevice,
+  viewportWidthMin?: number,
+  viewportWidthMax?: number,
+  sampling?: number,
+  since: string,
+  until: string,
+};

package/src/utils/analytics-clickmap-overlay.tsx

@@ -0,0 +1,15 @@
+/**
+ * Wire protocol for handing a clickmap overlay token from the dashboard to the
+ * in-page dev tool via `sessionStorage` + a window event.
+ *
+ * The token is a self-describing JWT: its payload already carries the
+ * `project_id` and `origin` it was minted for, so the reader derives both from
+ * the token itself and the writer only has to hand over a single value. The
+ * dashboard (writer) and the dev tool (reader) live in different packages but
+ * must agree on these exact names — this module is the single source of truth so
+ * they can never silently desync.
+ */
+
+export const CLICKMAP_OVERLAY_TOKEN_STORAGE_KEY = "hexclave-clickmap-token";
+export const CLICKMAP_OVERLAY_RESUME_STORAGE_KEY = "hexclave-clickmap-resume";
+export const CLICKMAP_OVERLAY_TOKEN_UPDATED_EVENT = "hexclave:clickmap-token-updated";

package/src/utils/dev-tool.tsx

@@ -0,0 +1,30 @@
+/**
+ * Shared identity of the Hexclave in-page dev tool / clickmap overlay.
+ *
+ * These constants are the single source of truth for "is this DOM / event /
+ * stored click part of the dev tool itself?". They are consumed across package
+ * boundaries:
+ *  - the dev tool mounts its root element with {@link DEV_TOOL_ROOT_ID} and
+ *    prefixes every generated class with {@link DEV_TOOL_CLASS_PREFIX};
+ *  - the event tracker uses them to skip self-clicks at ingest;
+ *  - the backend clickmap query uses them to filter dev-tool clicks out of
+ *    aggregate clickmaps server-side.
+ *
+ * Keep them here so a rename can never silently desync the SQL filter from the
+ * actual DOM identity.
+ */
+export const DEV_TOOL_ROOT_ID = "__hexclave-dev-tool-root";
+
+/**
+ * Root element id of the standalone clickmap overlay. The clickmap is an
+ * independent feature with its own mount (it must survive the dev tool being
+ * removed), so it gets its own root — but its self-clicks need the exact same
+ * ingest/query exclusions as the dev tool's.
+ */
+export const CLICKMAP_ROOT_ID = "__hexclave-clickmap-root";
+
+/** Prefix applied to every class/generated id the dev tool renders. */
+export const DEV_TOOL_CLASS_PREFIX = "sdt-";
+
+/** Legacy class marker still present on older dev-tool builds. */
+export const DEV_TOOL_LEGACY_CLASS = "stack-devtool";

package/src/utils/dom.tsx

@@ -5,3 +5,45 @@ export function hasClickableParent(element: HTMLElement): boolean {
 
   return hasClickableParent(element.parentElement);
 }
+
+/**
+ * Escape a string so it is safe to use as a CSS identifier (id/class) inside a selector.
+ * Prefers the native `CSS.escape` when available, falling back to a conservative
+ * backslash-escape for non-DOM environments (SSR, tests, older runtimes).
+ */
+export function cssEscapeIdent(value: string): string {
+  if (typeof CSS !== "undefined" && typeof CSS.escape === "function") {
+    return CSS.escape(value);
+  }
+
+  let escaped = "";
+  for (let i = 0; i < value.length; i += 1) {
+    const char = value.charAt(i);
+    const codeUnit = value.charCodeAt(i);
+
+    if (codeUnit === 0x0000) {
+      escaped += "\uFFFD";
+    } else if (
+      (codeUnit >= 0x0001 && codeUnit <= 0x001f) ||
+      codeUnit === 0x007f ||
+      (i === 0 && codeUnit >= 0x0030 && codeUnit <= 0x0039) ||
+      (i === 1 && codeUnit >= 0x0030 && codeUnit <= 0x0039 && value.charCodeAt(0) === 0x002d)
+    ) {
+      escaped += `\\${codeUnit.toString(16)} `;
+    } else if (i === 0 && codeUnit === 0x002d && value.length === 1) {
+      escaped += "\\-";
+    } else if (
+      codeUnit >= 0x0080 ||
+      codeUnit === 0x002d ||
+      codeUnit === 0x005f ||
+      (codeUnit >= 0x0030 && codeUnit <= 0x0039) ||
+      (codeUnit >= 0x0041 && codeUnit <= 0x005a) ||
+      (codeUnit >= 0x0061 && codeUnit <= 0x007a)
+    ) {
+      escaped += char;
+    } else {
+      escaped += `\\${char}`;
+    }
+  }
+  return escaped;
+}

package/src/utils/elements-chain.tsx

@@ -0,0 +1,349 @@
+/**
+ * PostHog-style `elements_chain` format — the single owner of both halves of the
+ * contract. The event tracker {@link buildElementsChain serializes} a clicked
+ * element (and its ancestors) into a string; the clickmap overlay
+ * {@link parseElementsChain parses} that string back into structured segments so
+ * it can re-locate the element in a live DOM.
+ *
+ * Encode and decode MUST round-trip exactly, which is why they live together:
+ * the escaping applied here on the write side is reversed by the parser below,
+ * and a single round-trip test in `elements-chain.test.tsx` guards the pair.
+ *
+ * Segment shape (leaf-first, joined by `;`):
+ *   tag.class1.class2:nth-child="2":nth-of-type="1":text="Save":attr__id="x":href="..."
+ */
+
+export type ElementsChainSegment = {
+  tag: string,
+  classes: string[],
+  attrs: Record<string, string>,
+  text: string | null,
+  nthChild: number | null,
+  nthOfType: number | null,
+  href: string | null,
+};
+
+export const ELEMENTS_CHAIN_MAX_DEPTH = 8;
+export const ELEMENTS_CHAIN_TEXT_MAX = 80;
+export const ELEMENTS_CHAIN_ATTR_MAX = 200;
+
+// Attributes we serialise into elements_chain. Mirrors the set PostHog persists:
+// stable identifiers (id, data-testid), semantics (role, type, name, aria-label),
+// and a few we expect downstream tooling to want to match against.
+export const ELEMENTS_CHAIN_ATTRS = [
+  "id",
+  "data-testid",
+  "data-test-id",
+  "data-hexclave-id",
+  "name",
+  "type",
+  "role",
+  "aria-label",
+  "placeholder",
+  "title",
+] as const;
+
+// ---------------------------------------------------------------------------
+// Serialization (DOM element -> elements_chain string)
+// ---------------------------------------------------------------------------
+
+function escapeElementsChainValue(value: string): string {
+  return value.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+}
+
+// Class tokens are written into the unquoted, dot-joined prefix of a segment, so
+// any "." or ":" inside a class (e.g. Tailwind variants like `md:hover:bg-blue-500`
+// or arbitrary values like `w-[1.5rem]`) must be escaped to round-trip through the
+// parser, which splits the prefix on unescaped "." and the segment on unescaped ":".
+function escapeElementsChainClass(value: string): string {
+  return value.replace(/\\/g, "\\\\").replace(/\./g, "\\.").replace(/:/g, "\\:");
+}
+
+function getElementClasses(element: Element): string[] {
+  const className = (element as HTMLElement).className;
+  if (typeof className !== "string" || className.trim() === "") {
+    return [];
+  }
+  return className.trim().split(/\s+/).filter(Boolean).slice(0, 4);
+}
+
+function getNthChildIndex(element: Element): number | null {
+  const parent = element.parentElement;
+  if (parent == null) return null;
+  const index = Array.prototype.indexOf.call(parent.children, element);
+  return index >= 0 ? index + 1 : null;
+}
+
+function getNthOfTypeIndex(element: Element): number | null {
+  const parent = element.parentElement;
+  if (parent == null) return null;
+  const tagName = element.tagName;
+  const siblings = Array.from(parent.children).filter((child) => child.tagName === tagName);
+  if (siblings.length <= 1) return null;
+  const index = siblings.indexOf(element);
+  return index >= 0 ? index + 1 : null;
+}
+
+function serializeElementsChainSegment(element: Element): string {
+  const parts: string[] = [];
+  parts.push(element.tagName.toLowerCase());
+  const classes = getElementClasses(element);
+  if (classes.length > 0) {
+    parts.push(`.${classes.map(escapeElementsChainClass).join(".")}`);
+  }
+  const text = element.textContent.trim().replace(/\s+/g, " ").slice(0, ELEMENTS_CHAIN_TEXT_MAX);
+  const nthChild = getNthChildIndex(element);
+  const nthOfType = getNthOfTypeIndex(element);
+  const attrPairs: string[] = [];
+  if (nthChild != null) attrPairs.push(`nth-child="${nthChild}"`);
+  if (nthOfType != null) attrPairs.push(`nth-of-type="${nthOfType}"`);
+  if (text !== "") attrPairs.push(`text="${escapeElementsChainValue(text)}"`);
+  for (const attrName of ELEMENTS_CHAIN_ATTRS) {
+    const value = element.getAttribute(attrName);
+    if (value == null || value === "") continue;
+    attrPairs.push(`attr__${attrName}="${escapeElementsChainValue(value.slice(0, ELEMENTS_CHAIN_ATTR_MAX))}"`);
+  }
+  if (element.tagName === "A") {
+    const href = element.getAttribute("href");
+    if (href != null && href !== "") {
+      attrPairs.push(`href="${escapeElementsChainValue(href.slice(0, ELEMENTS_CHAIN_ATTR_MAX))}"`);
+    }
+  }
+  if (attrPairs.length > 0) {
+    parts.push(`:${attrPairs.join(":")}`);
+  }
+  return parts.join("");
+}
+
+/**
+ * Serialise a clicked element and up to {@link ELEMENTS_CHAIN_MAX_DEPTH}
+ * ancestors (leaf-first) into an `elements_chain` string.
+ */
+export function buildElementsChain(element: Element): string {
+  const segments: string[] = [];
+  let current: Element | null = element;
+  let depth = 0;
+  while (current != null && depth < ELEMENTS_CHAIN_MAX_DEPTH && current !== document.documentElement) {
+    segments.push(serializeElementsChainSegment(current));
+    current = current.parentElement;
+    depth += 1;
+  }
+  return segments.join(";");
+}
+
+// ---------------------------------------------------------------------------
+// Parsing (elements_chain string -> structured segments)
+// ---------------------------------------------------------------------------
+
+// Split a string on unescaped occurrences of `.`, unescaping `\.`, `\:` and `\\`
+// back to their literal characters. Reverses `escapeElementsChainClass`.
+function splitEscapedDots(input: string): string[] {
+  const out: string[] = [];
+  let cur = '';
+  for (let i = 0; i < input.length; i++) {
+    const ch = input[i];
+    if (ch === '\\' && i + 1 < input.length) {
+      cur += input[i + 1];
+      i += 1;
+      continue;
+    }
+    if (ch === '.') {
+      out.push(cur);
+      cur = '';
+      continue;
+    }
+    cur += ch;
+  }
+  out.push(cur);
+  return out;
+}
+
+type ElementsChainAttrResult = {
+  nthChild?: number,
+  nthOfType?: number,
+  text?: string,
+  href?: string,
+  attrKey?: string,
+  attrValue?: string,
+};
+
+function applyElementsChainAttr(key: string, value: string): ElementsChainAttrResult {
+  if (key === 'nth-child') {
+    const n = Number.parseInt(value, 10);
+    return Number.isFinite(n) ? { nthChild: n } : {};
+  }
+  if (key === 'nth-of-type') {
+    const n = Number.parseInt(value, 10);
+    return Number.isFinite(n) ? { nthOfType: n } : {};
+  }
+  if (key === 'text') {
+    return { text: value };
+  }
+  if (key === 'href') {
+    return { href: value, attrKey: key, attrValue: value };
+  }
+  if (key.startsWith('attr__')) {
+    return { attrKey: key.slice('attr__'.length), attrValue: value };
+  }
+  return { attrKey: key, attrValue: value };
+}
+
+function parseElementsChainSegment(segment: string): ElementsChainSegment | null {
+  const trimmed = segment.trim();
+  if (trimmed === '') return null;
+
+  // Find first ':' at top level — separates tag/classes prefix from attribute pairs.
+  let prefixEnd = trimmed.length;
+  let inQuotes = false;
+  for (let i = 0; i < trimmed.length; i++) {
+    const ch = trimmed[i];
+    if (ch === '\\' && i + 1 < trimmed.length) {
+      i += 1;
+      continue;
+    }
+    if (ch === '"') {
+      inQuotes = !inQuotes;
+      continue;
+    }
+    if (ch === ':' && !inQuotes) {
+      prefixEnd = i;
+      break;
+    }
+  }
+
+  const prefix = trimmed.slice(0, prefixEnd);
+  const rest = trimmed.slice(prefixEnd);
+  const prefixParts = splitEscapedDots(prefix);
+  const tag = prefixParts[0].trim().toLowerCase();
+  if (tag === '') return null;
+  const classes = prefixParts.slice(1).map((c) => c.trim()).filter((c) => c !== '');
+
+  const attrs: Record<string, string> = {};
+  let nthChild: number | null = null;
+  let nthOfType: number | null = null;
+  let text: string | null = null;
+  let href: string | null = null;
+
+  // Parse :key="value" pairs from rest.
+  let i = 0;
+  while (i < rest.length) {
+    if (rest[i] !== ':') {
+      i += 1;
+      continue;
+    }
+    i += 1; // skip ':'
+    // read key up to '='
+    let keyEnd = i;
+    while (keyEnd < rest.length && rest[keyEnd] !== '=' && rest[keyEnd] !== ':') keyEnd += 1;
+    const key = rest.slice(i, keyEnd).trim();
+    if (keyEnd >= rest.length || rest[keyEnd] !== '=') {
+      i = keyEnd;
+      continue;
+    }
+    let valStart = keyEnd + 1;
+    if (rest[valStart] !== '"') {
+      // unquoted — read until next ':' at top level
+      let end = valStart;
+      while (end < rest.length && rest[end] !== ':') end += 1;
+      const value = rest.slice(valStart, end);
+      const result = applyElementsChainAttr(key, value);
+      if (result.nthChild != null) nthChild = result.nthChild;
+      if (result.nthOfType != null) nthOfType = result.nthOfType;
+      if (result.text != null) text = result.text;
+      if (result.href != null) href = result.href;
+      if (result.attrKey != null) attrs[result.attrKey] = result.attrValue ?? '';
+      i = end;
+      continue;
+    }
+    // quoted value — find unescaped closing quote
+    valStart += 1;
+    let end = valStart;
+    let value = '';
+    while (end < rest.length) {
+      const ch = rest[end];
+      if (ch === '\\' && end + 1 < rest.length) {
+        const next = rest[end + 1];
+        if (next === '"' || next === '\\') {
+          value += next;
+          end += 2;
+          continue;
+        }
+        value += ch;
+        end += 1;
+        continue;
+      }
+      if (ch === '"') break;
+      value += ch;
+      end += 1;
+    }
+    const result = applyElementsChainAttr(key, value);
+    if (result.nthChild != null) nthChild = result.nthChild;
+    if (result.nthOfType != null) nthOfType = result.nthOfType;
+    if (result.text != null) text = result.text;
+    if (result.href != null) href = result.href;
+    if (result.attrKey != null) attrs[result.attrKey] = result.attrValue ?? '';
+    i = end + 1; // skip closing quote
+  }
+
+  return { tag, classes, attrs, text, nthChild, nthOfType, href };
+}
+
+/** Parse an `elements_chain` string into structured, leaf-first segments. */
+export function parseElementsChain(chain: string): ElementsChainSegment[] {
+  // Split top-level by ';' respecting quoted strings.
+  const segments: string[] = [];
+  let current = '';
+  let inQuotes = false;
+  for (let i = 0; i < chain.length; i++) {
+    const ch = chain[i];
+    if (ch === '\\' && i + 1 < chain.length) {
+      current += ch + chain[i + 1];
+      i += 1;
+      continue;
+    }
+    if (ch === '"') {
+      inQuotes = !inQuotes;
+      current += ch;
+      continue;
+    }
+    if (ch === ';' && !inQuotes) {
+      segments.push(current);
+      current = '';
+      continue;
+    }
+    current += ch;
+  }
+  if (current.length > 0) {
+    segments.push(current);
+  }
+  return segments.map(parseElementsChainSegment).filter((segment): segment is ElementsChainSegment => segment != null);
+}
+
+import.meta.vitest?.test("parseElementsChain parses a simple leaf+ancestor chain", ({ expect }) => {
+  const parsed = parseElementsChain('button.btn.btn-primary:nth-of-type="1":text="Save":attr__id="save-btn";div.container');
+  expect(parsed).toEqual([
+    { tag: "button", classes: ["btn", "btn-primary"], attrs: { id: "save-btn" }, text: "Save", nthChild: null, nthOfType: 1, href: null },
+    { tag: "div", classes: ["container"], attrs: {}, text: null, nthChild: null, nthOfType: null, href: null },
+  ]);
+});
+
+import.meta.vitest?.test("parseElementsChain reverses class escaping for Tailwind-style tokens", ({ expect }) => {
+  // `md:hover:bg-blue-500` and `w-[1.5rem]` contain the prefix delimiters `:`/`.`,
+  // so the serializer escapes them; the parser must recover the literal classes.
+  const parsed = parseElementsChain('a.md\\:hover\\:bg-blue-500.w-\\[1\\.5rem\\]:href="/p?a=1"');
+  expect(parsed).toEqual([
+    { tag: "a", classes: ["md:hover:bg-blue-500", "w-[1.5rem]"], attrs: { href: "/p?a=1" }, text: null, nthChild: null, nthOfType: null, href: "/p?a=1" },
+  ]);
+});
+
+import.meta.vitest?.test("parseElementsChain unescapes quotes/backslashes and ignores ';' inside quoted values", ({ expect }) => {
+  const parsed = parseElementsChain('span:text="a \\"b\\"; c \\\\ d"');
+  expect(parsed).toEqual([
+    { tag: "span", classes: [], attrs: {}, text: 'a "b"; c \\ d', nthChild: null, nthOfType: null, href: null },
+  ]);
+});
+
+import.meta.vitest?.test("parseElementsChain drops empty/tagless segments", ({ expect }) => {
+  expect(parseElementsChain("")).toEqual([]);
+  expect(parseElementsChain(";;")).toEqual([]);
+});