Phase 2: track() custom events and feature-flag annotation

[immanuel-peter]

Context

Phase 2 of the browser insights track: custom event tracking and feature-flag annotation, client side. Builds on @hostess/browser (#1) and the Next.js components (#2). Beacon schema v1 (howl-cloud/hostess#32) already reserves k: "ev", name/props, and a flags map so v1 ingests won't choke on early adopters.

Custom events

Vercel-style track():

import { track } from "@hostess/nextjs";   // re-export from @hostess/browser

track("signup_completed");
track("checkout", { plan: "pro", seats: 3 });

• k: "ev" beacon with name (≤ 64 chars, [a-zA-Z0-9_ .-]) and optional flat props (string | number | boolean values only; caps client-side: ≤ 8 keys, key ≤ 32, value ≤ 64 — server enforces the same, see platform issue).
• Same transport/queue as pageviews; same dev-mode silence and privacy rules (no PII in names/props is the user's responsibility — document loudly).
• Server-side track() (from route handlers/server actions, à la @vercel/analytics/server) is explicitly out of scope for this issue — needs an authenticated server path, not the public RUM endpoint; file separately when wanted.

Feature flags

Goal (Vercel parity): compare analytics by active flag values. Design:

• Optional flags map on pv/ev beacons: ≤ 16 flags, name ≤ 64, values stringified ≤ 32.
• Sourcing, in order of preference:
  1. Flags SDK adapter — Vercel's open-source Flags SDK (flags package) is framework-neutral; provide a helper that picks up resolved flag values it exposes to the client, so existing Flags SDK users get this for free.
  2. Manual API: reportFlags({ "new-checkout": "on" }) and/or a flags prop on <HostessAnalytics />.
• Flags are annotations, never identifiers: no per-user targeting keys, no variant payloads — name + value only.

Scope

• track() implementation in @hostess/browser + re-exports from adapters
• Client-side caps/validation + tests
• flags annotation plumbing (manual API first, Flags SDK adapter second)
• Docs: event naming guidance, PII warning, flag comparison examples

Depends on #1, #2, and the platform phase-2 issue howl-cloud/hostess#37 (events/flags ingest + rollups + Studio).