@createcms/core 0.1.1

package/dist/react/tracking.cjs

@@ -0,0 +1,243 @@
+'use client';
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var jsxRuntime = require('react/jsx-runtime');
+var React = require('react');
+
+function _interopNamespace(e) {
+  if (e && e.__esModule) return e;
+  var n = Object.create(null);
+  if (e) {
+    Object.keys(e).forEach(function (k) {
+      if (k !== 'default') {
+        var d = Object.getOwnPropertyDescriptor(e, k);
+        Object.defineProperty(n, k, d.get ? d : {
+          enumerable: true,
+          get: function () { return e[k]; }
+        });
+      }
+    });
+  }
+  n.default = e;
+  return n;
+}
+
+var React__namespace = /*#__PURE__*/_interopNamespace(React);
+
+/**
+ * Resolves the GA4/dataLayer wire name for a block event key: the author's
+ * `EventDeclaration.name` override, else the default `cms_<blockType>_<key>`
+ * (locked measurement decision #7). Pure + framework-free so BOTH the client
+ * tracker (react/tracking.tsx, where a fire happens) and the server goal-picker
+ * (ab-test listGoalEvents, which advertises the goal) resolve names identically
+ * — the stored event_type and the offered goal must be the same string.
+ */ function resolveWireName(key, blockType, events) {
+    return events?.[key]?.name ?? `cms_${blockType}_${key}`;
+}
+
+const TrackingRuntimeContext = /*#__PURE__*/ React.createContext(null);
+/**
+ * Mount once, high in the CLIENT tree, wrapping the rendered page. Supplies the
+ * dispatch + ambient ab-context every {@link BlockTracker} below it reads.
+ */ function TrackingRuntimeProvider({ runtime, children }) {
+    return /*#__PURE__*/ jsxRuntime.jsx(TrackingRuntimeContext.Provider, {
+        value: runtime,
+        children: children
+    });
+}
+const BlockTrackingContext = /*#__PURE__*/ React.createContext(null);
+/**
+ * Scopes the per-block tracking identity for its children. Rendered BY
+ * renderContentNode around a functional block (children-as-props — the wrapped
+ * subtree is server-rendered and just passed through). Itself renders nothing but
+ * the context provider, so it is safe during SSR and never blocks paint.
+ */ function BlockTracker({ blockType, blockId, trackingId, events, children }) {
+    const value = React.useMemo(()=>({
+            blockType,
+            blockId,
+            trackingId,
+            events
+        }), [
+        blockType,
+        blockId,
+        trackingId,
+        events
+    ]);
+    return /*#__PURE__*/ jsxRuntime.jsx(BlockTrackingContext.Provider, {
+        value: value,
+        children: children
+    });
+}
+/**
+ * Builds the {@link ClientCMSEvent} a fired block event dispatches. Pure +
+ * exported so it is unit-testable without a React renderer: stamps the ambient
+ * ab-context, maps the block identity to `source` (trackingId → handle, type →
+ * block type), and marks it anonymous (the consent-free aggregate path; the
+ * consent-gated legs live inside dispatch).
+ */ function buildBlockEvent(key, params, runtime, block, interactionId) {
+    return {
+        // The typed API fires the event KEY; the wire (GA4/dataLayer + the stored
+        // event_type) carries the resolved wire name. Outside a BlockTracker
+        // (block === null) there is nothing to resolve against, so the key passes.
+        name: block ? resolveWireName(key, block.blockType, block.events) : key,
+        anonymous: true,
+        ...runtime.ab ? {
+            ab: runtime.ab
+        } : {},
+        ...block ? {
+            source: {
+                handle: block.trackingId,
+                type: block.blockType
+            }
+        } : {},
+        ...interactionId ? {
+            interactionId
+        } : {},
+        ...params ? {
+            params
+        } : {}
+    };
+}
+/**
+ * The UNTYPED core hook. Reads the runtime + the per-block identity from context
+ * and returns a `fire` that builds a {@link ClientCMSEvent} and dispatches it
+ * (anonymous aggregate by design — the consent-gated legs are inside dispatch).
+ * If no {@link TrackingRuntimeProvider} is mounted, `fire` is a dev-warned no-op
+ * (degrade-safe). Prefer the typed {@link createTrackedBlocks} facade.
+ */ function useBlockTrackerRaw(expectedBlockType) {
+    const runtime = React.useContext(TrackingRuntimeContext);
+    const block = React.useContext(BlockTrackingContext);
+    const emit = React.useCallback((name, params, interactionId)=>{
+        if (!runtime) {
+            if (process.env.NODE_ENV !== 'production') {
+                console.warn(`[cms] useBlockTracker fire("${name}") called with no <TrackingRuntimeProvider> mounted — event dropped.`);
+            }
+            return;
+        }
+        if (process.env.NODE_ENV !== 'production') {
+            // Fired outside any <BlockTracker> (e.g. a <TrackedForm> not inside a
+            // functional block): the event name is NOT wire-resolved and carries no
+            // source, so it won't match a picked goal. Loud, not silent.
+            if (!block) {
+                console.warn(`[cms] fire("${name}") called outside a <BlockTracker> — the event name is unresolved (no wire name) and has no source; render the firing component inside a functional block.`);
+            }
+            // The block key is a TYPE-only selector; the dispatched source is the
+            // ENCLOSING <BlockTracker>. Warn when they disagree (wrong-key call, or
+            // a call from outside the block's own subtree) so a mis-stamped event
+            // is loud, not silent.
+            if (block && expectedBlockType && block.blockType !== expectedBlockType) {
+                console.warn(`[cms] useTrackedBlock("${expectedBlockType}").fire is running inside a "${block.blockType}" block — the event is stamped with "${block.blockType}". Call it from the block's own component.`);
+            }
+            if (block?.events && !(name in block.events)) {
+                console.warn(`[cms] fire("${name}") is not a declared event of block "${block.blockType}".`);
+            }
+        }
+        runtime.dispatch(buildBlockEvent(name, params, runtime, block, interactionId));
+    }, [
+        runtime,
+        block,
+        expectedBlockType
+    ]);
+    const fire = React.useCallback((name, params)=>emit(name, params, undefined), [
+        emit
+    ]);
+    const fireInteraction = React.useCallback((name, interactionId, params)=>emit(name, params, interactionId), [
+        emit
+    ]);
+    return {
+        fire,
+        fireInteraction
+    };
+}
+/**
+ * Builds the per-collection typed tracking facade. Pass the collection
+ * DEFINITION (single source of truth, same object as `createBlocksMap`).
+ * `useTrackedBlock('signupForm').fire` is narrowed to that block's declared
+ * events — `fire('typo')`, a missing required param, or a wrong-typed param are
+ * all compile errors; a non-functional block key is rejected too.
+ *
+ * The block key is a TYPE-level selector: the dispatched source is always the
+ * ENCLOSING <BlockTracker> (set by the renderer from the rendered node), so call
+ * `useTrackedBlock('x')` from block x's own component. A mismatch dev-warns.
+ *
+ * @example
+ * ```tsx
+ * // blocks/index.tsx
+ * export const trackedBlocks = createTrackedBlocks(pagesCollection);
+ *
+ * // signup-form.tsx ('use client')
+ * const { fire } = trackedBlocks.useTrackedBlock('signupForm');
+ * <form action={() => fire('submitSuccess', { plan: 'pro' })} />
+ * ```
+ */ function createTrackedBlocks(_collection) {
+    function useTrackedBlock(block) {
+        // The block-key literal selects the event union at the TYPE level; at
+        // runtime the BlockTracker has already scoped identity, so the raw hook's
+        // fire forwards the (compile-checked) name + params unchanged. The cast is
+        // the single controlled erasure point (mirrors BlocksMap._components: any).
+        // `block` is passed for the dev-mismatch warning, not for dispatch.
+        return useBlockTrackerRaw(block);
+    }
+    return {
+        useTrackedBlock
+    };
+}
+/**
+ * Wraps a `<form>` so one submit becomes a funnel: it mints an `interactionId`,
+ * fires the `attempt` event when the submit STARTS, runs `action`, and fires the
+ * `success` event only if `action` resolves — both legs share the interactionId
+ * so `completion_rate` (= successes / attempts) can pair them. A throw from
+ * `action` leaves the attempt unmatched (a started-but-not-completed interaction).
+ *
+ * Must be rendered inside a functional block (the renderer's <BlockTracker>), so
+ * the events stamp that block's source. Uses React 19 `useActionState` — render
+ * it only on React 19 (the rest of this module works on 18). `attempt`/`success`
+ * are the block's declared event keys (a typo dev-warns via the raw tracker).
+ *
+ * @example
+ * ```tsx
+ * <TrackedForm attempt="submitAttempt" success="submitSuccess" action={subscribe}>
+ *   <input name="email" /> <button>Join</button>
+ * </TrackedForm>
+ * ```
+ */ function TrackedForm({ attempt, success, action, children, ...formProps }) {
+    const { fireInteraction } = useBlockTrackerRaw();
+    const run = React.useCallback(async (_prev, formData)=>{
+        const interactionId = typeof crypto !== 'undefined' && 'randomUUID' in crypto ? crypto.randomUUID() : `ix_${Date.now()}_${Math.round(Math.random() * 1e9)}`;
+        fireInteraction(attempt, interactionId);
+        try {
+            await action(formData);
+            fireInteraction(success, interactionId);
+            return {
+                ok: true
+            };
+        } catch  {
+            return {
+                ok: false
+            }; // attempt stays unmatched (failed interaction)
+        }
+    }, [
+        attempt,
+        success,
+        action,
+        fireInteraction
+    ]);
+    // React 19. Namespaced so importing this module never breaks on React 18 —
+    // only rendering <TrackedForm> requires 19.
+    const [, formAction] = React__namespace.useActionState(run, {
+        ok: false
+    });
+    return /*#__PURE__*/ jsxRuntime.jsx("form", {
+        action: formAction,
+        ...formProps,
+        children: children
+    });
+}
+
+exports.BlockTracker = BlockTracker;
+exports.TrackedForm = TrackedForm;
+exports.TrackingRuntimeProvider = TrackingRuntimeProvider;
+exports.buildBlockEvent = buildBlockEvent;
+exports.createTrackedBlocks = createTrackedBlocks;
+exports.resolveWireName = resolveWireName;
+exports.useBlockTrackerRaw = useBlockTrackerRaw;

package/dist/react/tracking.d.cts

@@ -0,0 +1,364 @@
+import * as React from 'react';
+import { ReactNode, ComponentProps } from 'react';
+import { ConsentState } from '../plugins/consent/index.cjs';
+
+type BlockTreeNode = {
+    blockId: string;
+    type: string;
+    properties: Record<string, unknown>;
+    children: BlockTreeNode[];
+};
+
+/**
+ * One published branch of a root, as a snapshot. Shared by the page-level
+ * variant shape and the block-level A/B `variants` (below) so the two can't
+ * drift. `properties` mirrors the (depth-1 typed) reference `properties`.
+ */
+type PublishedBranchSnapshot<TProps = Record<string, unknown>> = {
+    branchId: string;
+    isControl: boolean;
+    properties: TProps;
+    tree: BlockTreeNode;
+};
+type ResolvedReference<TProps = Record<string, unknown>> = {
+    rootId: string;
+    collection: string;
+    properties: TProps;
+    tree: BlockTreeNode;
+    /**
+     * Present only when this referenced root has a RUNNING A/B test (AB_FANOUT
+     * F2 server fan-out). The server stays a pure, cacheable function: top-level
+     * `tree`/`properties` are the CONTROL branch (a no-JS / AB-disabled client
+     * renders it as-is), and the client pre-render pass (F3) picks the visitor's
+     * variant from `variants` and swaps it in. `variants` includes the control.
+     * An OPTIONAL field (not a discriminated union) so `isResolvedReference` —
+     * which narrows on `tree`/`properties` — keeps matching.
+     */
+    abTest?: {
+        testId: string;
+        trafficPercentage: number;
+        variants: PublishedBranchSnapshot<TProps>[];
+    };
+};
+type BlockTypes = {
+    string: string;
+    number: number;
+    boolean: boolean;
+    date: string;
+    richText: string;
+    image: string;
+    select: string;
+    reference: string;
+};
+/** Reference inference mode: `raw` (write input + getBlockTree editor read) keeps
+ *  a `reference` as its stored rootId string; `resolved` (getPublishedContent)
+ *  surfaces the inlined `ResolvedReference`. */
+type RefMode = 'raw' | 'resolved';
+type BlockPropertyType = keyof BlockTypes;
+type SelectOption = {
+    readonly label: string;
+    readonly value: string;
+};
+type BlockPropertySpec<T extends BlockPropertyType> = {
+    type: T;
+    required?: boolean;
+    defaultValue?: BlockTypes[T];
+    label: string;
+    description?: string;
+    placeholder?: string;
+} & (T extends 'select' ? {
+    options: readonly SelectOption[];
+} : {}) & (T extends 'reference' ? {
+    collection: string;
+} : {});
+/** Discriminated union over all concrete block-property specs. */
+type BlockProperty = {
+    [K in BlockPropertyType]: BlockPropertySpec<K>;
+}[BlockPropertyType];
+type Simplify<T> = {
+    [K in keyof T]: T[K];
+};
+/** Extracts the runtime value type for a block property.
+ *  For `select` properties with options, returns the union of option values.
+ *  A `reference` is a rootId string in `raw` mode (write input + editor read) and
+ *  a `ResolvedReference` in `resolved` mode (published read).
+ *  For all other types, returns the corresponding primitive type. */
+type InferPropertyValue<T extends BlockProperty, M extends RefMode = 'raw', TCol extends Record<string, AnyCollectionDefinition> = {}> = T extends {
+    type: 'select';
+    options: readonly {
+        readonly value: infer V extends string;
+    }[];
+} ? V : T extends {
+    type: 'reference';
+    collection: infer C extends string;
+} ? M extends 'resolved' ? C extends keyof TCol ? ResolvedReference<NonNullable<InferBlockProperties<TCol[C]['root']['properties'], 'resolved'>>> : ResolvedReference : string : BlockTypes[T['type']];
+type RequiredPart<T extends Record<string, BlockProperty>, M extends RefMode, TCol extends Record<string, AnyCollectionDefinition>> = {
+    [K in keyof T as T[K] extends {
+        required: true;
+    } ? K : never]: InferPropertyValue<T[K], M, TCol>;
+};
+type OptionalPart<T extends Record<string, BlockProperty>, M extends RefMode, TCol extends Record<string, AnyCollectionDefinition>> = {
+    [K in keyof T as T[K] extends {
+        required: true;
+    } ? never : K]?: InferPropertyValue<T[K], M, TCol>;
+};
+type HasRequiredKeys<T extends Record<string, BlockProperty>> = true extends {
+    [K in keyof T]: T[K] extends {
+        required: true;
+    } ? true : never;
+}[keyof T] ? true : false;
+/** Maps a properties record to its runtime value types, respecting `required`.
+ *  When all properties are optional, the entire input becomes optional (| undefined). */
+type InferBlockProperties<T extends Record<string, BlockProperty>, M extends RefMode = 'raw', TCol extends Record<string, AnyCollectionDefinition> = {}> = HasRequiredKeys<T> extends true ? Simplify<RequiredPart<T, M, TCol> & OptionalPart<T, M, TCol>> : Simplify<RequiredPart<T, M, TCol> & OptionalPart<T, M, TCol>> | undefined;
+/** Scalar property subset usable as an event parameter (no references/media). */
+type ScalarBlockProperty = Extract<BlockProperty, {
+    type: 'string' | 'number' | 'boolean' | 'select' | 'date';
+}>;
+/**
+ * Declares a meaningful event a functional block can emit (e.g. a form's
+ * `submitSuccess`). Living on the block DEFINITION makes it the single source of
+ * truth for the typed `fire(...)` union, the test-creation goal picker, and the
+ * analytics wire name. `name` overrides the GA4/dataLayer wire name (defaults to
+ * `cms_<blockType>_<eventKey>`, computed by the measurement layer). Whether an
+ * event counts as a conversion is decided per test in the UI, not here.
+ */
+type EventDeclaration = {
+    /** Analytics wire-name override (snake_case). Defaults to cms_<type>_<key>. */
+    name?: string;
+    /** Typed parameters carried with the event (scalar only). */
+    params?: Record<string, ScalarBlockProperty>;
+    /** Human label for the goal picker. */
+    label?: string;
+};
+/** Call-args tuple for `fire`: required iff the event declares a required param. */
+type EventFireArgs<E extends EventDeclaration> = E extends {
+    params: infer P extends Record<string, BlockProperty>;
+} ? HasRequiredKeys<P> extends true ? [params: InferBlockProperties<P>] : [params?: InferBlockProperties<P>] : [];
+/** Event keys a block declares. */
+type BlockEventNames<TEvents extends Record<string, EventDeclaration>> = keyof TEvents & string;
+/**
+ * The typed `fire` signature derived from a block's event declarations — the
+ * runtime tracker (M3) implements this. `fire('unknown')`, a missing required
+ * param, and a wrong-typed param are all compile errors.
+ */
+type BlockEventFire<TEvents extends Record<string, EventDeclaration>> = <K extends BlockEventNames<TEvents>>(name: K, ...args: EventFireArgs<TEvents[K]>) => void;
+type BlockDefinition<TProps extends Record<string, BlockProperty> = Record<string, BlockProperty>, TEvents extends Record<string, EventDeclaration> = Record<string, never>> = {
+    properties: TProps;
+    label: string;
+    description?: string;
+    previewImageUrl?: string;
+    /** Events this (functional) block can emit — see {@link EventDeclaration}. */
+    events?: TEvents;
+} & ({
+    allowChildren?: false;
+} | {
+    allowChildren: true;
+    allowedChildBlocks?: string[];
+});
+type AnyBlockDefinition = BlockDefinition<Record<string, BlockProperty>, Record<string, EventDeclaration>>;
+type RootDefinition<TProps extends Record<string, BlockProperty> = Record<string, BlockProperty>> = {
+    properties: TProps;
+};
+type SlugConfig = {
+    enabled: false;
+} | {
+    enabled: true;
+    root: string;
+    allowRoot?: boolean;
+    normalize?: boolean;
+    nested?: boolean;
+};
+type CollectionDefinition<TProps extends Record<string, BlockProperty> = Record<string, BlockProperty>, TBlocks extends Record<string, AnyBlockDefinition> = Record<string, AnyBlockDefinition>> = {
+    slug?: SlugConfig;
+    root: RootDefinition<TProps>;
+    blocks?: TBlocks;
+    label: string;
+    description?: string;
+    /**
+     * Marks this collection as one whose roots are meant to be EMBEDDED into other
+     * roots via a `reference` property (a "reusable block" library). Purely an
+     * ergonomic hint — it informs editor pickers and which endpoints to surface; it
+     * NEVER gates safety (the delete-in-use guard protects every referenced root
+     * regardless of this flag). Any collection can still be a reference target.
+     */
+    reusableBlock?: boolean;
+};
+type AnyCollectionDefinition = CollectionDefinition<Record<string, BlockProperty>, Record<string, AnyBlockDefinition>>;
+
+/**
+ * The client-side event a sink receives. Decoupled from the server `CMSEvent`
+ * (no `timestamp`/storage `id` — those are minted server-side): this is what the
+ * browser knows at fire time.
+ */
+type ClientCMSEvent = {
+    /** Canonical event name, e.g. `'impression' | 'conversion' | 'form_submit'`. */
+    name: string;
+    /**
+     * A/B attribution by the SERVER-served branch (Pattern A: the variant came
+     * from the URL). `branchId` is what the client has; the store leg resolves it
+     * to a `variantId` server-side. Absent for non-A/B analytics events.
+     */
+    ab?: {
+        testId: string;
+        branchId?: string;
+        variantId?: string;
+    };
+    /** Identity — only on the consent-gated unique-visitor path; never anonymous. */
+    visitorId?: string;
+    /** True when no identifier is attached (the consent-free aggregate path). */
+    anonymous: boolean;
+    /** Originating functional block instance (the `trackingId` + block type). */
+    source?: {
+        handle?: string;
+        type?: string;
+    };
+    /** Funnel grouping id (M4): shared by the attempt + success legs of one interaction. */
+    interactionId?: string;
+    /** GA4 stitching ids (M5): set only when consent is granted; the store leg
+     *  forwards them so the server-MP can attribute the hit. */
+    transport?: {
+        clientId?: string;
+        sessionId?: string;
+        engagementTimeMsec?: number;
+    };
+    /**
+     * Consent Mode v2 state at fire time (M5). Stamped ALONGSIDE `transport` (only
+     * when analytics_storage is granted), so the store leg can relay it to the
+     * server, where `buildGa4Payload` needs it to authorize the server-MP forward.
+     * Absent on the consent-free anonymous path — its absence is exactly what keeps
+     * the server's denied-consent guard from dropping the anonymous aggregate count.
+     */
+    consent?: ConsentState;
+    /** Scalar event params (GA4 wire params). */
+    params?: Record<string, string | number | boolean>;
+    metadata?: Record<string, unknown>;
+};
+
+/**
+ * Resolves the GA4/dataLayer wire name for a block event key: the author's
+ * `EventDeclaration.name` override, else the default `cms_<blockType>_<key>`
+ * (locked measurement decision #7). Pure + framework-free so BOTH the client
+ * tracker (react/tracking.tsx, where a fire happens) and the server goal-picker
+ * (ab-test listGoalEvents, which advertises the goal) resolve names identically
+ * — the stored event_type and the offered goal must be the same string.
+ */
+declare function resolveWireName(key: string, blockType: string, events: Record<string, EventDeclaration> | undefined): string;
+
+/**
+ * The tracking runtime the consumer supplies via {@link TrackingRuntimeProvider}.
+ * `dispatch` is the M3a sink fan-out (e.g. `cmsClient.abTest.dispatchEvent`); the
+ * package reaches it through context, never by importing the client instance.
+ * `ab` is the ambient, server-served A/B attribution for THIS page — single-valued
+ * per the XOR rule, so every block event on the page binds to the one running test.
+ */
+type TrackingRuntime = {
+    dispatch: (event: ClientCMSEvent) => void;
+    ab?: {
+        testId: string;
+        branchId: string;
+    };
+};
+/**
+ * Mount once, high in the CLIENT tree, wrapping the rendered page. Supplies the
+ * dispatch + ambient ab-context every {@link BlockTracker} below it reads.
+ */
+declare function TrackingRuntimeProvider({ runtime, children, }: {
+    runtime: TrackingRuntime;
+    children: ReactNode;
+}): React.JSX.Element;
+/** Per-block identity injected by the renderer from the RSC node (serializable). */
+type BlockTrackingCtx = {
+    blockType: string;
+    blockId: string;
+    /** The block's authored, branch-stable goal anchor (`trackingId` property). */
+    trackingId?: string;
+    /** The block's declared events — used to resolve wire names + dev-validate. */
+    events?: Record<string, EventDeclaration>;
+};
+/**
+ * Scopes the per-block tracking identity for its children. Rendered BY
+ * renderContentNode around a functional block (children-as-props — the wrapped
+ * subtree is server-rendered and just passed through). Itself renders nothing but
+ * the context provider, so it is safe during SSR and never blocks paint.
+ */
+declare function BlockTracker({ blockType, blockId, trackingId, events, children, }: BlockTrackingCtx & {
+    children: ReactNode;
+}): React.JSX.Element;
+/**
+ * Builds the {@link ClientCMSEvent} a fired block event dispatches. Pure +
+ * exported so it is unit-testable without a React renderer: stamps the ambient
+ * ab-context, maps the block identity to `source` (trackingId → handle, type →
+ * block type), and marks it anonymous (the consent-free aggregate path; the
+ * consent-gated legs live inside dispatch).
+ */
+declare function buildBlockEvent(key: string, params: Record<string, string | number | boolean> | undefined, runtime: TrackingRuntime, block: BlockTrackingCtx | null, interactionId?: string): ClientCMSEvent;
+/**
+ * The UNTYPED core hook. Reads the runtime + the per-block identity from context
+ * and returns a `fire` that builds a {@link ClientCMSEvent} and dispatches it
+ * (anonymous aggregate by design — the consent-gated legs are inside dispatch).
+ * If no {@link TrackingRuntimeProvider} is mounted, `fire` is a dev-warned no-op
+ * (degrade-safe). Prefer the typed {@link createTrackedBlocks} facade.
+ */
+declare function useBlockTrackerRaw(expectedBlockType?: string): {
+    fire: (name: string, params?: Record<string, string | number | boolean>) => void;
+    /** Like {@link fire} but stamps a funnel `interactionId` (M4 — <TrackedForm>). */
+    fireInteraction: (name: string, interactionId: string, params?: Record<string, string | number | boolean>) => void;
+};
+/** The functional blocks of a collection (those that declared a non-empty `events`). */
+type FunctionalBlocks<TBlocks extends Record<string, AnyBlockDefinition>> = {
+    [K in keyof TBlocks as TBlocks[K]['events'] extends Record<string, EventDeclaration> ? [keyof TBlocks[K]['events']] extends [never] ? never : K : never]: NonNullable<TBlocks[K]['events']>;
+};
+/**
+ * Builds the per-collection typed tracking facade. Pass the collection
+ * DEFINITION (single source of truth, same object as `createBlocksMap`).
+ * `useTrackedBlock('signupForm').fire` is narrowed to that block's declared
+ * events — `fire('typo')`, a missing required param, or a wrong-typed param are
+ * all compile errors; a non-functional block key is rejected too.
+ *
+ * The block key is a TYPE-level selector: the dispatched source is always the
+ * ENCLOSING <BlockTracker> (set by the renderer from the rendered node), so call
+ * `useTrackedBlock('x')` from block x's own component. A mismatch dev-warns.
+ *
+ * @example
+ * ```tsx
+ * // blocks/index.tsx
+ * export const trackedBlocks = createTrackedBlocks(pagesCollection);
+ *
+ * // signup-form.tsx ('use client')
+ * const { fire } = trackedBlocks.useTrackedBlock('signupForm');
+ * <form action={() => fire('submitSuccess', { plan: 'pro' })} />
+ * ```
+ */
+declare function createTrackedBlocks<TProps extends Record<string, BlockProperty>, TBlocks extends Record<string, AnyBlockDefinition>>(_collection: CollectionDefinition<TProps, TBlocks>): {
+    useTrackedBlock: <K extends keyof FunctionalBlocks<TBlocks> & string>(block: K) => {
+        fire: BlockEventFire<FunctionalBlocks<TBlocks>[K]>;
+    };
+};
+/**
+ * Wraps a `<form>` so one submit becomes a funnel: it mints an `interactionId`,
+ * fires the `attempt` event when the submit STARTS, runs `action`, and fires the
+ * `success` event only if `action` resolves — both legs share the interactionId
+ * so `completion_rate` (= successes / attempts) can pair them. A throw from
+ * `action` leaves the attempt unmatched (a started-but-not-completed interaction).
+ *
+ * Must be rendered inside a functional block (the renderer's <BlockTracker>), so
+ * the events stamp that block's source. Uses React 19 `useActionState` — render
+ * it only on React 19 (the rest of this module works on 18). `attempt`/`success`
+ * are the block's declared event keys (a typo dev-warns via the raw tracker).
+ *
+ * @example
+ * ```tsx
+ * <TrackedForm attempt="submitAttempt" success="submitSuccess" action={subscribe}>
+ *   <input name="email" /> <button>Join</button>
+ * </TrackedForm>
+ * ```
+ */
+declare function TrackedForm({ attempt, success, action, children, ...formProps }: {
+    attempt: string;
+    success: string;
+    action: (formData: FormData) => void | Promise<void>;
+    children: ReactNode;
+} & Omit<ComponentProps<'form'>, 'action' | 'children'>): React.JSX.Element;
+
+export { BlockTracker, TrackedForm, TrackingRuntimeProvider, buildBlockEvent, createTrackedBlocks, resolveWireName, useBlockTrackerRaw };
+export type { BlockTrackingCtx, TrackingRuntime };