@genn-inc/cluebase-frontend-sdk 0.0.1

package/dist/exporter/span-to-source-signal.js

@@ -0,0 +1,174 @@
+// 相関のために残す属性名は、正本から生成した部品を読みます。ここには手で書かれて
+// おり、もう 1 か所の写しと 15 語食い違い、`cluebase.session_id` `mcp.session.id` が
+// 欠けていて**落ちていました**（`session` を含むため落とす側に当たる）。
+import { CLUEBASE_CORRELATION_ATTRIBUTE_KEYS } from "../_generated/correlation-attribute-keys.js";
+import { attrString, hrTimeToUnixNano, nanosToIso, parentSpanId, } from "../_generated/otel-span-conversion.js";
+import { EVENT_SOURCE, EVENT_VERSION, SOURCE_SCHEMA_VERSION, } from "../provider/constants.js";
+import { generateEventId, generateInteractionId, generateRequestId, generateRequestSpanId, generateTraceId, } from "./event-id.js";
+import { isDeniedKey } from "./sanitize.js";
+import { toFrontendSourceResource } from "./frontend-resource.js";
+import { SDK_SOURCE_SIGNAL_EVENT_NAME, SDK_SOURCE_SIGNAL_EVENT_TYPE, } from "./source-event.js";
+const isDynamicJsonObject = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+function toJsonValue(value) {
+    if (value === null)
+        return null;
+    if (typeof value === "string" ||
+        typeof value === "number" ||
+        typeof value === "boolean") {
+        return typeof value === "number" && !Number.isFinite(value) ? null : value;
+    }
+    if (Array.isArray(value))
+        return value.map((entry) => toJsonValue(entry));
+    if (isDynamicJsonObject(value)) {
+        const record = {};
+        for (const [key, entry] of Object.entries(value)) {
+            record[key] = toJsonValue(entry);
+        }
+        return record;
+    }
+    if (typeof value === "bigint")
+        return value.toString();
+    return null;
+}
+function toJsonRecord(value, deniedKeys = []) {
+    const record = {};
+    for (const [key, entry] of Object.entries(value ?? {})) {
+        if (!CLUEBASE_CORRELATION_ATTRIBUTE_KEYS.has(key) &&
+            isDeniedKey(key, deniedKeys)) {
+            continue;
+        }
+        record[key] = toJsonValue(entry);
+    }
+    return record;
+}
+function instrumentationScopeName(span) {
+    const instrumentation = span;
+    return (instrumentation.instrumentationScope?.name ??
+        instrumentation.instrumentationLibrary?.name ??
+        null);
+}
+function contextRecord(context, overrides) {
+    return {
+        producer_id: context.producer_id,
+        anonymous_id: context.anonymous_id,
+        user_id: context.user_id,
+        organization_id: context.organization_id ?? null,
+        user_profile: context.user_profile,
+        session_id: context.session_id,
+        tab_id: context.tab_id,
+        trace_id: overrides.trace_id,
+        request_id: overrides.request_id,
+        request_span_id: overrides.request_span_id,
+        interaction_id: overrides.interaction_id,
+        correlation_id: context.correlation_id,
+        sdk_collection_mode: context.sdk_collection_mode,
+        frontend_release: context.frontend_release,
+        locale: context.locale,
+        country: context.country,
+        device_type: context.device_type,
+        browser: context.browser,
+        os: context.os,
+        referrer: context.referrer,
+        browser_family: context.browser_family ?? null,
+        browser_major_version: context.browser_major_version ?? null,
+        browser_engine: context.browser_engine ?? null,
+        os_family: context.os_family ?? null,
+        os_major_version: context.os_major_version ?? null,
+        timezone: context.timezone ?? null,
+        pointer_type_candidate: context.pointer_type_candidate ?? null,
+        touch_capable: context.touch_capable ?? null,
+        cookies_enabled: context.cookies_enabled ?? null,
+        local_storage_available: context.local_storage_available ?? null,
+        session_storage_available: context.session_storage_available ?? null,
+        service_worker_supported: context.service_worker_supported ?? null,
+        webgl_supported: context.webgl_supported ?? null,
+        reduced_motion: context.reduced_motion ?? null,
+        color_scheme: context.color_scheme ?? null,
+        subject_traits: context.subject_traits,
+        organization_traits: context.organization_traits,
+        context_traits: context.context_traits,
+    };
+}
+export function spanToSourceSignalEvent(span, options) {
+    const context = options.context;
+    const attributes = toJsonRecord(span.attributes, options.deniedKeys);
+    const spanContext = span.spanContext();
+    const traceId = attrString(attributes, "cluebase.trace_id") ??
+        spanContext.traceId ??
+        generateTraceId();
+    const spanId = spanContext.spanId || null;
+    const parentId = parentSpanId(span, attributes);
+    const startTimeUnixNano = hrTimeToUnixNano(span.startTime);
+    const endTimeUnixNano = hrTimeToUnixNano(span.endTime);
+    const eventId = generateEventId();
+    const requestSpanId = attrString(attributes, "cluebase.request_span_id") ??
+        spanId ??
+        context.request_span_id ??
+        generateRequestSpanId();
+    const requestId = attrString(attributes, "cluebase.request.id") ??
+        attrString(attributes, "cluebase.request_id") ??
+        context.request_id ??
+        generateRequestId();
+    const interactionId = attrString(attributes, "cluebase.interaction.id") ??
+        attrString(attributes, "cluebase.interaction_id") ??
+        context.interaction_id ??
+        generateInteractionId();
+    return {
+        event_id: eventId,
+        source_event_id: eventId,
+        source_schema_version: SOURCE_SCHEMA_VERSION,
+        source_event_type: SDK_SOURCE_SIGNAL_EVENT_TYPE,
+        source_event_kind: SDK_SOURCE_SIGNAL_EVENT_TYPE,
+        producer_id: context.producer_id,
+        service_name: EVENT_SOURCE,
+        event_name: SDK_SOURCE_SIGNAL_EVENT_NAME,
+        event_category: "context",
+        event_source: EVENT_SOURCE,
+        event_version: EVENT_VERSION,
+        occurred_at: nanosToIso(startTimeUnixNano),
+        ingested_at: new Date().toISOString(),
+        status: "observed",
+        sdk_collection_mode: context.sdk_collection_mode,
+        privacy_state: "masked",
+        privacy_level: "default_masked",
+        masking_state: "masked",
+        allowed_value_keys: [],
+        privacy_summary: context.privacy_summary,
+        trace_id: traceId,
+        span_id: spanId,
+        parent_span_id: parentId,
+        request_id: requestId,
+        request_span_id: requestSpanId,
+        interaction_id: interactionId,
+        frontend_release: context.frontend_release,
+        backend_release: null,
+        properties: {},
+        metrics: {},
+        sdk_signal: {
+            surface: "frontend",
+            kind: "span",
+            name: span.name,
+            span_kind: span.kind ?? null,
+            trace_id: traceId,
+            span_id: spanId,
+            parent_span_id: parentId,
+            start_time_unix_nano: startTimeUnixNano,
+            end_time_unix_nano: endTimeUnixNano,
+            status_code: span.status?.code ?? null,
+            status_message: span.status?.message ?? null,
+            instrumentation_scope_name: instrumentationScopeName(span),
+            attributes,
+            events: (span.events ?? []).map((event) => ({
+                name: event.name,
+                attributes: toJsonRecord(event.attributes, options.deniedKeys),
+            })),
+            resource: toFrontendSourceResource(span.resource, options.deniedKeys),
+            context: contextRecord(context, {
+                trace_id: traceId,
+                request_id: requestId,
+                request_span_id: requestSpanId,
+                interaction_id: interactionId,
+            }),
+        },
+    };
+}

package/dist/exporter/text-fingerprint.d.ts

@@ -0,0 +1,9 @@
+/**
+ * 文字列を短い印にたたむ。
+ *
+ * 中身そのものは残さない（項目の並びや入力欄の値は、そのままでは送れない）。
+ * 同じ入力なら必ず同じ印になり、印から元へは戻らない。
+ * FNV-1a の 32 bit 版。**衝突しない保証は無い**ので、突合の鍵ではなく
+ * 「同じか違うか」を見るための印としてのみ使う。
+ */
+export declare const fingerprintText: (value: string) => string;

package/dist/exporter/text-fingerprint.js

@@ -0,0 +1,16 @@
+/**
+ * 文字列を短い印にたたむ。
+ *
+ * 中身そのものは残さない（項目の並びや入力欄の値は、そのままでは送れない）。
+ * 同じ入力なら必ず同じ印になり、印から元へは戻らない。
+ * FNV-1a の 32 bit 版。**衝突しない保証は無い**ので、突合の鍵ではなく
+ * 「同じか違うか」を見るための印としてのみ使う。
+ */
+export const fingerprintText = (value) => {
+    let hash = 0x811c9dc5;
+    for (let index = 0; index < value.length; index += 1) {
+        hash ^= value.charCodeAt(index);
+        hash = Math.imul(hash, 0x01000193);
+    }
+    return `fnv1a:${(hash >>> 0).toString(16).padStart(8, "0")}`;
+};

package/dist/index.d.ts

@@ -0,0 +1,25 @@
+import type { InternalMetricsSnapshot } from "./internal/metrics.js";
+import { createCluebaseBrowserSdk } from "./provider/sdk.js";
+import type { CluebaseBrowserSdk, CluebaseConsentState, CluebaseGroupTraits, CluebaseGroupType, CluebaseInitOptions, CluebaseSubjectTraits, CluebaseTrackMetrics, CluebaseTrackProperties } from "./provider/types.js";
+declare const cluebase: {
+    /**
+     * SDK を初期化する。 `endpoint` / `projectKey` は必須で、 欠けていれば送信を
+     * 黙って捨てずに throw する。
+     */
+    init(options: CluebaseInitOptions): void;
+    identify(userId: string, traits?: CluebaseSubjectTraits): void;
+    group(groupType: CluebaseGroupType, groupKey: string, traits?: CluebaseGroupTraits): void;
+    reset(): void;
+    track(eventName: string, properties?: CluebaseTrackProperties, metrics?: CluebaseTrackMetrics): void;
+    setConsent(consent: CluebaseConsentState): void;
+    flush(): Promise<void>;
+    close(): Promise<void>;
+    getInternalMetrics(): InternalMetricsSnapshot;
+    getDiagnostics(): import("./exporter/diagnostics.js").DiagnosticsSnapshot;
+};
+export { EXPORT_RESULT_FAILED, EXPORT_RESULT_SUCCESS, ObservationSourceEventExporter, type ObservationSourceEventExporterOptions, } from "./exporter/observation-source-event-exporter.js";
+export { attachNextRouterIntegration } from "./integrations/next-router.js";
+export { attachReactRouterIntegration } from "./integrations/react-router.js";
+export type { CluebaseBrowserSdk, CluebaseConsentState, CluebaseGroupTraits, CluebaseGroupType, CluebaseInitOptions, CluebaseSubjectTraits, CluebaseTrackMetrics, CluebaseTrackProperties, InternalMetricsSnapshot, };
+export { createCluebaseBrowserSdk };
+export default cluebase;

package/dist/index.js

@@ -0,0 +1,158 @@
+import { parseSendableUrl } from "./provider/config.js";
+import { createCluebaseBrowserSdk } from "./provider/sdk.js";
+// SDK は host application 内で singleton として動く。
+// 同じ tab で複数回 import されても 1 instance に統合する。
+const GLOBAL_SDK_KEY = "__cluebase_frontend_sdk_singleton__";
+const globalWithCluebaseSdk = globalThis;
+const existingSdk = globalWithCluebaseSdk[GLOBAL_SDK_KEY];
+const internalSdk = existingSdk ?? createCluebaseBrowserSdk();
+if (!existingSdk) {
+    globalWithCluebaseSdk[GLOBAL_SDK_KEY] = internalSdk;
+}
+const reportPublicSdkError = (operation) => {
+    try {
+        if (typeof console !== "undefined" && typeof console.warn === "function") {
+            console.warn(`[cluebase] ${operation} failed`, {
+                error_code: "sdk_operation_failed",
+            });
+        }
+    }
+    catch {
+        // Cluebase は host application を絶対に失敗させない。
+    }
+};
+const safeCall = (operation, callback) => {
+    try {
+        callback();
+    }
+    catch {
+        reportPublicSdkError(operation);
+    }
+};
+const safeAsyncCall = async (operation, callback) => {
+    try {
+        await callback();
+    }
+    catch {
+        reportPublicSdkError(operation);
+    }
+};
+// `privacy.allowedValuePaths` used to let the caller name the request/response
+// fields that may leave the browser in clear text. That choice now belongs to
+// the Cluebase privacy screen and reaches the SDK through the delivered privacy
+// policy, so the option has nothing left to apply to.
+const REMOVED_PRIVACY_OPTIONS = {
+    allowedValuePaths: "cluebase.init: 'privacy.allowedValuePaths' was removed in " +
+        "@genn-inc/cluebase-frontend-sdk 0.0.1. The fields allowed to leave the browser in " +
+        "clear text are now chosen in the Cluebase privacy screen and delivered to the " +
+        "SDK automatically. Remove 'privacy.allowedValuePaths' from cluebase.init(...) " +
+        "and select those fields in the Cluebase privacy screen instead. Until then " +
+        "every value stays masked.",
+};
+const REQUIRED_INIT_OPTIONS = [
+    "endpoint",
+    "projectKey",
+];
+/**
+ * Raise on a setup mistake instead of collecting nothing and warning once.
+ *
+ * This is the one place `cluebase.init` is allowed to throw. The `cluebase.*`
+ * never-propagate contract exists so a telemetry fault cannot break a page the
+ * visitor is using; it is not there to hide a setting that quietly stopped
+ * applying, nor a key the caller forgot. Both mistakes come from the build's
+ * own configuration, so they surface on the developer's first page load rather
+ * than on a visitor's — and left silent they are invisible afterwards: the page
+ * renders, `getDiagnostics()` reports an open lifecycle with no errors, and not
+ * one event is ever delivered.
+ */
+const validateInitOptions = (options) => {
+    const privacy = options.privacy ?? {};
+    for (const [name, message] of Object.entries(REMOVED_PRIVACY_OPTIONS)) {
+        if (name in privacy) {
+            throw new Error(message);
+        }
+    }
+    // Anything that is not a string reads as absent, so a stray `undefined` from
+    // the bundler's env replacement cannot become the literal "undefined" endpoint.
+    const missing = REQUIRED_INIT_OPTIONS.filter((name) => {
+        const value = options[name];
+        return typeof value !== "string" || value.trim() === "";
+    });
+    if (missing.length > 0) {
+        throw new Error(`cluebase.init: ${missing.map((name) => `'${name}'`).join(", ")} ` +
+            `${missing.length === 1 ? "is" : "are"} required and must be a non-empty ` +
+            "string. Cluebase collects nothing until every required option is set. Pass " +
+            "them from your environment, for example " +
+            "endpoint=NEXT_PUBLIC_CLUEBASE_API_BASE_URL and " +
+            "projectKey=NEXT_PUBLIC_CLUEBASE_PROJECT_KEY.");
+    }
+    // Reporting a typo against the setting that caused it, rather than letting
+    // it surface later as delivery that never arrives.
+    if (parseSendableUrl(options.endpoint) === null) {
+        throw new Error(`cluebase.init: 'endpoint' must be an absolute http:// or https:// URL, but ` +
+            `received ${JSON.stringify(options.endpoint)}. An endpoint the SDK cannot ` +
+            "send to loses every event just as silently as one that was never passed. " +
+            "Pass the Cluebase API base URL from your environment, for example " +
+            "endpoint=NEXT_PUBLIC_CLUEBASE_API_BASE_URL.");
+    }
+};
+// Public API — namespace `cluebase` の 8 method
+const cluebase = {
+    /**
+     * SDK を初期化する。 `endpoint` / `projectKey` は必須で、 欠けていれば送信を
+     * 黙って捨てずに throw する。
+     */
+    init(options) {
+        // Thrown before `safeCall` so the caller actually sees it; see
+        // `validateInitOptions`.
+        validateInitOptions(options);
+        safeCall("init", () => {
+            internalSdk.init(options);
+        });
+    },
+    identify(userId, traits) {
+        safeCall("identify", () => {
+            internalSdk.identify(userId, traits);
+        });
+    },
+    group(groupType, groupKey, traits) {
+        safeCall("group", () => {
+            if (groupType !== "organization") {
+                throw new Error(`unsupported group type: ${String(groupType)}`);
+            }
+            internalSdk.setOrganization(groupKey, traits);
+        });
+    },
+    reset() {
+        safeCall("reset", () => internalSdk.reset());
+    },
+    track(eventName, properties, metrics) {
+        safeCall("track", () => {
+            internalSdk.track(eventName, properties, metrics);
+        });
+    },
+    setConsent(consent) {
+        safeCall("setConsent", () => {
+            internalSdk.setConsent(consent);
+        });
+    },
+    async flush() {
+        await safeAsyncCall("flush", () => internalSdk.flush());
+    },
+    async close() {
+        await safeAsyncCall("close", () => internalSdk.close());
+    },
+    // 内部 metrics 取得 (= 顧客 debug 用、 production では通常不要)
+    getInternalMetrics() {
+        return internalSdk.getInternalMetrics();
+    },
+    getDiagnostics() {
+        return internalSdk.getDiagnostics();
+    },
+};
+// OTel-core exporter surface for advanced host integrations.
+export { EXPORT_RESULT_FAILED, EXPORT_RESULT_SUCCESS, ObservationSourceEventExporter, } from "./exporter/observation-source-event-exporter.js";
+export { attachNextRouterIntegration } from "./integrations/next-router.js";
+export { attachReactRouterIntegration } from "./integrations/react-router.js";
+export { createCluebaseBrowserSdk };
+export default cluebase;

package/dist/instrumentation/action.d.ts

@@ -0,0 +1,2 @@
+import type { CaptureModuleContext, CaptureStopHandle } from "../provider/types.js";
+export declare const startActionCapture: (context: CaptureModuleContext) => CaptureStopHandle;

package/dist/instrumentation/action.js

@@ -0,0 +1,171 @@
+import { buildLocalTextDescriptor, buildLocalValueDescriptor, } from "../exporter/local-minimization.js";
+import { extractFieldName, extractFieldType, getElementAriaLabel, getElementClassList, getElementLabel, getElementPlaceholder, getElementRole, getElementSectionHeading, isEditableElement, resolveClickDisplayTarget, resolveInteractionScopeDescriptor, resolveStableKeyDescriptor, shouldCaptureClickTarget, } from "./dom.js";
+import { buildPrimaryActionKey } from "./common.js";
+import { getCurrentPageSnapshot } from "./location.js";
+import { buildScreenActionNamingEvidence } from "./naming-evidence.js";
+const ariaToggleRoles = new Set([
+    "checkbox",
+    "menuitemcheckbox",
+    "menuitemradio",
+    "radio",
+    "switch",
+]);
+const parseAriaChecked = (value) => {
+    if (value === "true")
+        return true;
+    if (value === "false")
+        return false;
+    return null;
+};
+const isNativeToggleInput = (element) => element instanceof HTMLInputElement &&
+    (element.type === "checkbox" || element.type === "radio");
+const fallbackCssEscape = (value) => value
+    .replace(/^\d/, (match) => `\\3${match} `)
+    .replace(/[^a-zA-Z0-9_-]/g, (match) => `\\${match}`);
+const ensureCssEscape = () => {
+    const globalWithCss = globalThis;
+    if (typeof globalWithCss.CSS?.escape === "function") {
+        return;
+    }
+    Object.defineProperty(globalWithCss, "CSS", {
+        configurable: true,
+        value: {
+            ...(globalWithCss.CSS ?? {}),
+            escape: fallbackCssEscape,
+        },
+    });
+};
+const emitElementClicked = (context, target, occurredAtMs) => {
+    const displayTarget = resolveClickDisplayTarget(target);
+    if (context.shouldIgnoreElement?.(displayTarget)) {
+        return;
+    }
+    if (!shouldCaptureClickTarget(displayTarget)) {
+        return;
+    }
+    const stableKey = resolveStableKeyDescriptor(displayTarget);
+    const interactionScope = resolveInteractionScopeDescriptor(displayTarget);
+    const interactionId = context.startInteraction?.({
+        nowMs: occurredAtMs,
+        interactionInitiator: "click",
+        interactionStartEventKind: "click",
+        targetStableKey: stableKey.stableKey,
+        formKey: stableKey.formKey,
+        interactionScopeKind: interactionScope?.interactionScopeKind,
+        interactionScopeKey: interactionScope?.interactionScopeKey,
+    }) ?? null;
+    context.onEvent({
+        type: "element_clicked",
+        occurredAtMs,
+        payload: {
+            viewId: context.getViewId(),
+            ...(interactionId
+                ? {
+                    interactionId,
+                    interactionInitiator: "click",
+                    interactionStartEventKind: "click",
+                }
+                : {}),
+            elementTag: displayTarget.tagName.toLowerCase(),
+            elementRole: getElementRole(displayTarget),
+            primaryActionKey: buildPrimaryActionKey(getCurrentPageSnapshot().screenKey, stableKey.stableKey),
+            stableKey: stableKey.stableKey,
+            stableKeyQuality: stableKey.stableKeyQuality,
+            formKey: stableKey.formKey,
+            interactionScopeKind: interactionScope?.interactionScopeKind ?? null,
+            interactionScopeKey: interactionScope?.interactionScopeKey ?? null,
+            elementId: displayTarget.id || null,
+            elementClass: getElementClassList(displayTarget),
+            elementLabelMeta: buildLocalTextDescriptor(getElementLabel(displayTarget)),
+            ariaLabelMeta: buildLocalTextDescriptor(getElementAriaLabel(displayTarget)),
+            placeholderMeta: buildLocalTextDescriptor(getElementPlaceholder(displayTarget)),
+            clickTargetText: getElementLabel(displayTarget),
+            clickTargetAriaLabel: getElementAriaLabel(displayTarget),
+            clickTargetTitle: displayTarget.getAttribute("title") || null,
+            fieldName: extractFieldName(displayTarget),
+            fieldType: extractFieldType(displayTarget),
+            fieldDisplayLabel: getElementLabel(displayTarget),
+            fieldAriaLabel: getElementAriaLabel(displayTarget),
+            fieldPlaceholder: getElementPlaceholder(displayTarget),
+            isEditable: isEditableElement(displayTarget),
+            sectionHeading: getElementSectionHeading(displayTarget),
+            ...buildScreenActionNamingEvidence(displayTarget),
+        },
+    });
+    maybeEmitAriaToggleChanged(context, displayTarget);
+};
+const maybeEmitAriaToggleChanged = (context, element) => {
+    if (isNativeToggleInput(element)) {
+        return;
+    }
+    const role = getElementRole(element);
+    if (!ariaToggleRoles.has(role ?? "")) {
+        return;
+    }
+    window.setTimeout(() => {
+        try {
+            if (!element.isConnected || context.shouldIgnoreElement?.(element)) {
+                return;
+            }
+            const stableKey = resolveStableKeyDescriptor(element);
+            const interactionScope = resolveInteractionScopeDescriptor(element);
+            const checked = parseAriaChecked(element.getAttribute("aria-checked"));
+            context.onEvent({
+                type: "toggle_changed",
+                occurredAtMs: Date.now(),
+                payload: {
+                    viewId: context.getViewId(),
+                    elementTag: element.tagName.toLowerCase(),
+                    elementRole: role,
+                    stableKey: stableKey.stableKey,
+                    stableKeyQuality: stableKey.stableKeyQuality,
+                    formKey: stableKey.formKey,
+                    interactionScopeKind: interactionScope?.interactionScopeKind ?? null,
+                    interactionScopeKey: interactionScope?.interactionScopeKey ?? null,
+                    fieldNameMeta: buildLocalTextDescriptor(extractFieldName(element)),
+                    elementLabelMeta: buildLocalTextDescriptor(getElementLabel(element)),
+                    ariaLabelMeta: buildLocalTextDescriptor(getElementAriaLabel(element)),
+                    placeholderMeta: buildLocalTextDescriptor(getElementPlaceholder(element)),
+                    fieldName: extractFieldName(element),
+                    fieldType: extractFieldType(element),
+                    fieldDisplayLabel: getElementLabel(element),
+                    fieldAriaLabel: getElementAriaLabel(element),
+                    fieldPlaceholder: getElementPlaceholder(element),
+                    checked,
+                    inputValueMeta: buildLocalValueDescriptor(checked),
+                    sectionHeading: getElementSectionHeading(element),
+                    ...buildScreenActionNamingEvidence(element),
+                },
+            });
+        }
+        catch (error) {
+            context.onInternalError("capture/action:toggle", error);
+        }
+    }, 0);
+};
+export const startActionCapture = (context) => {
+    if (typeof document === "undefined") {
+        return { stop: () => undefined };
+    }
+    ensureCssEscape();
+    const clickHandler = (event) => {
+        if (context.getConsent() === "denied") {
+            return;
+        }
+        if (!(event.target instanceof Element)) {
+            return;
+        }
+        try {
+            emitElementClicked(context, event.target, Date.now());
+        }
+        catch (error) {
+            context.onInternalError("capture/action:click", error);
+        }
+    };
+    document.addEventListener("click", clickHandler, true);
+    return {
+        stop: () => {
+            document.removeEventListener("click", clickHandler, true);
+        },
+    };
+};

package/dist/instrumentation/cluebase-authored-attributes.d.ts

@@ -0,0 +1,4 @@
+/** 部品自身が測った値（文字列など）の属性名。 */
+export declare function cluebaseAuthoredPropertyAttribute(name: string): string;
+/** 部品自身が測った値（数値）の属性名。 */
+export declare function cluebaseAuthoredMetricAttribute(name: string): string;

package/dist/instrumentation/cluebase-authored-attributes.js

@@ -0,0 +1,32 @@
+/**
+ * 配る部品**自身が測った値**を封筒に載せる時の、属性の名前。
+ *
+ * 顧客が `track` で付けた項目は `cluebase.properties.<綴り>` /
+ * `cluebase.metrics.<綴り>` という封筒で運ばれます。**配る部品も同じ封筒を使う**
+ * ため、封筒を開けた受け口から見ると、顧客が名付けた業務項目と、部品が測った
+ * 値の区別が付きません。
+ *
+ * 実際にそれが起きました。分析が `duration_ms` を顧客の業務項目だと解釈し、
+ * 利用者へ**「duration_ms を測りました」**と答えました（実測 2026-08-15）。
+ *
+ * そこで、部品が測った値は封筒の中で**予約された名前**（`cluebase.` で始まる）を
+ * 名乗ります。顧客の項目がこの接頭辞を持つことはないため、封筒を開けた時点で
+ * 混ざりません。**顧客が偶然 `request_kind` という業務項目を送ってきても、
+ * それは顧客のものとして扱われます。**
+ *
+ * **受け口側で名前を付け替えていません。** 付け替える形にすると、受け口が
+ * 「部品が送る綴り」の一覧を持つことになり、その一覧が古くなります
+ * （`CLAUDE.md` §0.2）。**名乗るのは名付けた側の責任です。**
+ */
+const RESERVED_FIELD_KEY_PREFIX = "cluebase.";
+/** 顧客の項目が運ばれる封筒。部品が測った値も同じ封筒を使う。 */
+const PROPERTY_ENVELOPE_PREFIX = "cluebase.properties.";
+const METRIC_ENVELOPE_PREFIX = "cluebase.metrics.";
+/** 部品自身が測った値（文字列など）の属性名。 */
+export function cluebaseAuthoredPropertyAttribute(name) {
+    return `${PROPERTY_ENVELOPE_PREFIX}${RESERVED_FIELD_KEY_PREFIX}${name}`;
+}
+/** 部品自身が測った値（数値）の属性名。 */
+export function cluebaseAuthoredMetricAttribute(name) {
+    return `${METRIC_ENVELOPE_PREFIX}${RESERVED_FIELD_KEY_PREFIX}${name}`;
+}

package/dist/instrumentation/common.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Shared instrumentation helpers used across multiple capture modules
+ * (network, performance, navigation, etc.).
+ *
+ * The most important contract here is URL sanitization for any payload
+ * that may carry the user's current browsing URL. The page URL must never
+ * be emitted with query string intact, because OAuth callback /
+ * password-reset / magic-link flows place secret tokens in the query
+ * string. Any instrumentation module that needs a "page URL" field on
+ * its outgoing event payload MUST go through `currentPageUrl()` here.
+ *
+ * Previously `instrumentation/performance.ts` emitted
+ * `pageUrl: window.location.href` directly while
+ * `instrumentation/network.ts` had its own internal stripping helper.
+ * This module unifies the behavior so all callers share a single
+ * implementation and a single test surface.
+ */
+/**
+ * Resolves `value` to a URL, falling back to the current document
+ * location for relative URLs. Returns `null` if neither parsing succeeds.
+ */
+export declare const resolveUrlAgainstCurrentLocation: (value: string) => URL | null;
+/**
+ * Strips the query string and hash from the given URL, returning
+ * `origin + pathname` only. Falls back to a `split("?")` form if URL
+ * parsing fails so callers never receive a query-bearing string.
+ *
+ * The query string is the primary leak surface for OAuth callbacks
+ * (`?code=...&state=...`) and password reset links (`?token=...`).
+ */
+export declare const stripQueryFromUrl: (url: string) => string;
+/**
+ * Returns the current page URL with all query parameters and hash
+ * fragments stripped. Returns `null` if `globalThis.location` is not
+ * available (e.g., non-browser environments).
+ *
+ * THIS IS THE ONLY APPROVED WAY TO POPULATE A `pageUrl` FIELD ON ANY
+ * INSTRUMENTATION EVENT PAYLOAD. Do not use `window.location.href`
+ * directly.
+ */
+export declare const currentPageUrl: () => string | null;
+/**
+ * Single sentinel marker used by Cluebase-owned History API wrappers. OTel-owned
+ * navigation instrumentation may patch history independently and must remain
+ * the primary navigation source.
+ */
+export declare const HISTORY_WRAPPED_MARKER: "__cluebaseHistoryWrapped";
+/**
+ * Type guard for a history.pushState / replaceState function that
+ * carries the unified Cluebase sentinel marker. Use this in any module
+ * that monkey-patches the History API.
+ */
+export type HistoryWrappedFn<T extends History["pushState"] | History["replaceState"] = History["pushState"] | History["replaceState"]> = T & {
+    [HISTORY_WRAPPED_MARKER]?: true;
+};
+/**
+ * Returns true if either history.pushState or history.replaceState
+ * is already Cluebase-wrapped.
+ */
+/**
+ * 差し替え済みかを見る側が、履歴の口に実際に求めるもの。
+ *
+ * **`History` 全体を求めていました。** ここで読むのは 2 つだけなので、試験の
+ * 作り物は `as unknown as History` で嘘をつくしかない状態でした（`tests/README.md` §10）。
+ */
+export type WrappableHistory = Pick<History, "pushState" | "replaceState">;
+export declare const isHistoryAlreadyCluebaseWrapped: (historyApi: WrappableHistory) => boolean;
+/**
+ * 画面操作 1 種類を指す安定キー。意味層は操作の identity 単位で行動名を付けるため、
+ * 通信経路 (method / path) を持たない画面操作にも同じ粒度の識別子が要る。
+ * 画面と操作対象の安定キーの組で「どの画面のどの操作か」を表す。
+ */
+export declare const buildPrimaryActionKey: (screenKey: string | null | undefined, targetStableKey: string | null | undefined) => string | null;