docs(audience): audit follow-up — README cohesion and runtime helper consumption

Follow-up to SDK-49's sample-app PR after a cross-product documentation
audit comparing the audience and pixel READMEs. Fixes a cluster of
correctness, cohesion, and DX gaps the audit flagged.

sdk/README.md:
- Add "Which Immutable event-tracking product is this?" near the top so
  studios landing on either @imtbl/audience or @imtbl/pixel can pick the
  right one. Cross-links to ../pixel/README.md without requiring any
  change to the pixel package itself.
- Swap "identity resolution" for "player identity" in the opening tagline
  so a game studio dev doesn't have to parse marketing-analytics jargon
  to understand what the SDK does.
- Expand the CDN quickstart to destructure the full runtime surface
  (Audience, AudienceError, AudienceEvents, IdentityType, canTrack,
  canIdentify, version) so no symbol reachable in ESM is quietly absent
  from the CDN snippet. Adds one short paragraph stating that the two
  paths have parity.
- Replace the relative markdown link to the sample-app package with an
  absolute GitHub blob URL. Relative links break on npmjs.com after
  publish; studios reading the package page would have seen a dead link.

sdk-sample-app/README.md:
- Add a "Why vanilla JavaScript?" paragraph so a reviewer browsing the
  monorepo understands why this sample app isn't React + Next.js + biom3
  like the four sibling sdk-sample-apps. The short answer: demonstrating
  <script>-tag loading is the point; a React wrapper would obscure it.
- Add a pre-release warning matching the one on sdk/README.md so the
  sample app's SDK dependency status is visible on either landing page.
- Remove the fabricated `pk_imapik-test-sample` fixture key; there is no
  shared fixture key. Point users at Immutable Hub to provision their
  own test key instead.
- Rewrite the AudienceEvents catalogue section: both ESM and CDN now
  expose the constant, so show the destructure-from-window pattern
  alongside the import pattern. Explain the drift-check the sample app
  runs at bootstrap.
- Rewrite the canTrack / canIdentify section the same way, and correct
  a load-bearing falsehood: the previous version claimed the sample app
  "gates its Identity and Alias buttons on this rule locally". It does
  not — the buttons stay enabled and the handlers call canIdentify
  before invoking the SDK, logging a "skipped" line when consent is
  lower. The README now matches the code.
- Walkthrough step 4 includes a positional hint ("5th row in the
  accordion") so readers don't hunt through 11 events.

sdk-sample-app/sample-app.js:
- Destructure AudienceEvents, canTrack, canIdentify off window.Immutable-
  Audience at the top of the IIFE. Previously these weren't on the CDN
  window surface and the sample app had to re-implement the consent
  rules as magic strings.
- Replace three `currentConsent !== 'full'` magic-string checks in
  onIdentify / onIdentifyTraits / onAlias with `!canIdentify(current-
  Consent)` calls to the SDK helper. Single source of truth, semantic
  log messages.
- Add a validateEventCatalogue() drift check that runs at bootstrap and
  compares the local AUDIENCE_EVENTS field-metadata array's event names
  against window.ImmutableAudience.AudienceEvents. Logs a `drift warn`
  entry when the two lists diverge so a new SDK event doesn't silently
  disappear from the Typed Events panel.

Refs SDK-49

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: ImmutableJeffrey

packages/audience/sdk-sample-app/README.md

@@ -5,6 +5,24 @@ typed `track()` event, and every reachable `AudienceErrorCode` has a
 dedicated UI control so you can sanity-check SDK changes end-to-end
 against the real sandbox backend and copy working call sites.
 
+> **Pre-release.** Depends on `@imtbl/audience@0.0.0`. The SDK API is
+> stabilising but breaking changes may still land before the first
+> published release.
+
+## Why vanilla JavaScript?
+
+Every other sample app in this monorepo (`packages/passport/sdk-sample-app`,
+`packages/checkout/sdk-sample-app`, `packages/internal/dex/sdk-sample-app`,
+`packages/internal/bridge/bridge-sample-app`) is React + Next.js with the
+`@biom3` design system. This one is plain ES2020 served by a ~90-line Node
+stdlib HTTP server. Intentional: the whole point is to demonstrate how
+`@imtbl/audience` loads via a plain `<script>` tag — the pattern real
+studios use when they drop the SDK into existing pages. A React wrapper
+would hide `window.ImmutableAudience` behind JSX abstractions and require
+a build step, obscuring the loading pattern we're demonstrating. The SDK
+itself is framework-agnostic — wrap these calls in your framework of
+choice when you ship.
+
 ## Run it
 
 ```sh
@@ -15,24 +33,24 @@ Open http://localhost:3456/. The `dev` script builds `@imtbl/audience`
 first (which produces `dist/cdn/imtbl-audience.global.js`), then serves
 this package's files plus the CDN bundle over a small Node server.
 
-## Test keys
-
-These are publishable-key fixtures safe for local use:
+## Publishable keys
 
-- **Sandbox (default):** `pk_imapik-test-sample` — talks to `api.sandbox.immutable.com`
-- **Prod:** any non-`pk_imapik-test-` key — talks to `api.immutable.com`
+You need a real publishable key from [Immutable Hub](https://hub.immutable.com/) —
+there is no shared fixture key. Test keys start with `pk_imapik-test-` and
+route to `api.sandbox.immutable.com`; any other prefix routes to
+`api.immutable.com` (prod).
 
 For dev-environment access, leave the key as a test key and set
-**Advanced → Base URL override** to `https://api.dev.immutable.com`.
-The SDK auto-derives sandbox vs prod from the key prefix; dev is not a
+**Advanced → Base URL override** to `https://api.dev.immutable.com`. The
+SDK auto-derives sandbox vs prod from the key prefix; dev is not a
 first-class environment and must be reached via explicit override.
 
 ## Ten-step walkthrough
 
 1. Paste a test key into **Setup**, leave Initial Consent at `none`, click **Init**.
 2. Open the **Consent** panel, click **anonymous**. Status bar updates.
 3. Click **Lifecycle → page()**. A page message is queued.
-4. Expand **Typed Events → purchase**, fill in `currency=USD`, `value=9.99`, click **Send**. Watch the live TS snippet mirror the form as you type.
+4. Expand **Typed Events → purchase** (5th row in the accordion), fill in `currency=USD`, `value=9.99`, click **Send**. Watch the live TS snippet mirror the form as you type.
 5. Set Consent to **full**.
 6. In **Identity → Named identify**, enter `user@example.com`, type `email`, traits `{"name":"Jane"}`, click.
 7. In **Identity → Traits-only identify**, enter `{"plan":"pro"}`, click.
@@ -43,13 +61,15 @@ first-class environment and must be reached via explicit override.
 ## `AudienceEvents` catalogue
 
 These are the 11 predefined event names and their typed property shapes.
-Because `AudienceEvents` is not attached to `window.ImmutableAudience` by
-the CDN bundle, the sample app hardcodes the names as a string array in
-`sample-app.js`. For TypeScript projects, import the constant instead:
+Both the CDN bundle and the ESM package expose them:
 
 ```ts
+// ESM
 import { AudienceEvents } from '@imtbl/audience';
 
+// CDN
+const { AudienceEvents } = window.ImmutableAudience;
+
 audience.track(AudienceEvents.PURCHASE, {
   currency: 'USD',
   value: 9.99,
@@ -58,6 +78,11 @@ audience.track(AudienceEvents.PURCHASE, {
 });
 ```
 
+The sample app reads event NAMES from `window.ImmutableAudience.AudienceEvents`
+at bootstrap and cross-checks them against the field-metadata array in
+`sample-app.js`. If the SDK grows a new event that the sample app hasn't
+picked up yet, the event log shows a `drift warn` entry.
+
 | Event | Required props | Optional props |
 |---|---|---|
 | `sign_up` | — | `method` |
@@ -80,13 +105,16 @@ audience.track('my_custom_event', { foo: 'bar' });
 
 ## Consent-aware UIs with `canTrack` / `canIdentify`
 
-The helpers `canTrack(level)` and `canIdentify(level)` are exported from
-`@imtbl/audience` but not attached to `window.ImmutableAudience`. TypeScript
-projects can import them:
+`canTrack(level)` and `canIdentify(level)` are the SDK's canonical consent
+predicates. Both the CDN bundle and the ESM package expose them:
 
 ```ts
+// ESM
 import { canTrack, canIdentify } from '@imtbl/audience';
 
+// CDN
+const { canTrack, canIdentify } = window.ImmutableAudience;
+
 if (canTrack(currentConsent)) {
   renderAnalyticsDashboard();
 }
@@ -95,12 +123,17 @@ if (canIdentify(currentConsent)) {
 }
 ```
 
-From a plain-JavaScript CDN-only context, the rules are:
-
-- `canTrack(level)` is true iff `level !== 'none'`
-- `canIdentify(level)` is true iff `level === 'full'`
-
-The sample app gates its Identity and Alias buttons on this rule locally.
+The rules themselves are simple:
+- `canTrack(level)` returns `true` iff `level !== 'none'`
+- `canIdentify(level)` returns `true` iff `level === 'full'`
+
+The sample app's Identity and Alias buttons stay enabled whenever the SDK
+is initialised, but the handlers call `canIdentify(currentConsent)` before
+invoking `identify()` / `alias()`. When it returns `false`, the handler
+logs a `skipped — canIdentify(...) is false` line and returns without
+calling the SDK. This mirrors how the SDK itself handles these calls at
+lower consent levels: it no-ops rather than throwing, so the sample app
+avoids a misleading "ok" log entry for a call that did nothing.
 
 ## Error codes
 

packages/audience/sdk-sample-app/sample-app.js

@@ -15,13 +15,16 @@
   var Audience = window.ImmutableAudience.Audience;
   var AudienceError = window.ImmutableAudience.AudienceError;
   var IdentityType = window.ImmutableAudience.IdentityType;
+  var SdkAudienceEvents = window.ImmutableAudience.AudienceEvents;
+  var canTrack = window.ImmutableAudience.canTrack;
+  var canIdentify = window.ImmutableAudience.canIdentify;
   var SDK_VERSION = window.ImmutableAudience.version || 'unknown';
 
-  // Hardcoded event catalogue. AudienceEvents is exported from @imtbl/audience
-  // but not attached to window.ImmutableAudience by the CDN bundle, so sample
-  // apps that load via <script> tag can't reach it at runtime. These strings
-  // are the canonical values from events.ts; see the README for the typed
-  // property shape of each one.
+  // Field metadata for the Typed Events accordion. The event NAMES come
+  // from window.ImmutableAudience.AudienceEvents (the SDK's canonical
+  // constant — cross-checked at bootstrap via validateEventCatalogue).
+  // The field shapes below are not exposed by the SDK at runtime, so they
+  // stay here as the sample app's own form-generation source of truth.
   var AUDIENCE_EVENTS = [
     { name: 'sign_up',          fields: [{ key: 'method', type: 'string', optional: true }] },
     { name: 'sign_in',          fields: [{ key: 'method', type: 'string', optional: true }] },
@@ -303,13 +306,43 @@
     text($('sdk-version'), 'SDK version: ' + SDK_VERSION);
   }
 
+  // --- Event catalogue drift check ---
+  //
+  // The sample app keeps field metadata locally because the SDK doesn't
+  // expose field shapes at runtime — but the event NAMES are authoritative
+  // on window.ImmutableAudience.AudienceEvents. Compare the two at bootstrap
+  // and log a warning if they diverge, so a new SDK event doesn't silently
+  // disappear from the Typed Events panel.
+
+  function validateEventCatalogue() {
+    if (!SdkAudienceEvents) return;
+    var sdkNames = Object.keys(SdkAudienceEvents).map(function (k) {
+      return SdkAudienceEvents[k];
+    });
+    var localNames = AUDIENCE_EVENTS.map(function (e) { return e.name; });
+    var missingLocally = sdkNames.filter(function (n) {
+      return localNames.indexOf(n) === -1;
+    });
+    var extraLocally = localNames.filter(function (n) {
+      return sdkNames.indexOf(n) === -1;
+    });
+    if (missingLocally.length > 0 || extraLocally.length > 0) {
+      log('drift', {
+        sdkHasButSampleAppMissing: missingLocally,
+        sampleAppHasButSdkMissing: extraLocally,
+      }, 'warn');
+    }
+  }
+
   // --- Bootstrap ---
 
   function bootstrap() {
     // Install the SDK console mirror before any SDK code runs so we don't
     // miss early debug output.
     installConsoleMirror();
 
+    validateEventCatalogue();
+
     // Populate IdentityType dropdowns
     var identityTypeOptions = Object.keys(IdentityType || {});
     ['id-type', 'alias-from-type', 'alias-to-type'].forEach(function (selectId) {
@@ -558,8 +591,8 @@
 
   function onIdentify() {
     if (!audience) return;
-    if (currentConsent !== 'full') {
-      log('identify()', 'skipped — requires consent: full (current: ' + currentConsent + ')', 'info');
+    if (!canIdentify(currentConsent)) {
+      log('identify()', 'skipped — canIdentify(' + currentConsent + ') is false; requires consent: full', 'info');
       return;
     }
     var id = $('id-id').value.trim();
@@ -581,8 +614,8 @@
 
   function onIdentifyTraits() {
     if (!audience) return;
-    if (currentConsent !== 'full') {
-      log('identify()', 'skipped — requires consent: full (current: ' + currentConsent + ')', 'info');
+    if (!canIdentify(currentConsent)) {
+      log('identify()', 'skipped — canIdentify(' + currentConsent + ') is false; requires consent: full', 'info');
       return;
     }
     var traits;
@@ -602,8 +635,8 @@
 
   function onAlias() {
     if (!audience) return;
-    if (currentConsent !== 'full') {
-      log('alias()', 'skipped — requires consent: full (current: ' + currentConsent + ')', 'info');
+    if (!canIdentify(currentConsent)) {
+      log('alias()', 'skipped — canIdentify(' + currentConsent + ') is false; requires consent: full', 'info');
       return;
     }
     var fromId = $('alias-from-id').value.trim();

packages/audience/sdk/README.md

@@ -1,13 +1,34 @@
 # @imtbl/audience
 
-Consent-aware event tracking and identity resolution for Immutable
-studios. Ships as an ESM/CJS package for bundled apps and as a single-file
-CDN IIFE for `<script>`-tag loading.
+Consent-aware event tracking and player identity for Immutable studios.
+Ships as an ESM/CJS package for bundled apps and as a single-file CDN
+IIFE for `<script>`-tag loading.
 
 > **Pre-release.** This package is at version `0.0.0`. The API is
 > stabilising but breaking changes may still land before the first
 > published release.
 
+## Which Immutable event-tracking product is this?
+
+Immutable ships two complementary event-tracking products in this
+monorepo. Pick based on your integration shape:
+
+- **`@imtbl/audience`** (this package) — the programmatic SDK. You call
+  `Audience.init()` from your app code and explicitly track events
+  (`track('purchase', {...})`, `identify()`, `setConsent()`, etc.).
+  Pick this when you need fine-grained control, typed events, player
+  identity, or explicit consent state machines.
+- **`@imtbl/pixel`** ([sibling package](../pixel/README.md)) — a drop-in
+  `<script>` snippet that captures page views, device signals, and
+  attribution data passively. Zero configuration beyond a publishable
+  key. Pick this for marketing sites, landing pages, and web shops
+  where you want to measure campaign performance without writing
+  tracking code.
+
+The two share the same backend pipeline, the same anonymous-id cookie
+(`imtbl_anon_id`), and the same publishable-key format — they're
+designed to coexist on a single site if you need both at once.
+
 ## Install
 
 ```sh
@@ -49,16 +70,25 @@ audience.shutdown();
 ```html
 <script src="https://cdn.jsdelivr.net/npm/@imtbl/audience@<version>/dist/cdn/imtbl-audience.global.js"></script>
 <script>
-  const { Audience, AudienceError, IdentityType } = window.ImmutableAudience;
+  const {
+    Audience, AudienceError, AudienceEvents,
+    IdentityType, canTrack, canIdentify,
+  } = window.ImmutableAudience;
   const audience = Audience.init({
     publishableKey: 'pk_imapik-test-...',
     consent: 'anonymous',
     onError: (err) => console.error(err.code, err.message),
   });
   audience.page();
+  audience.track(AudienceEvents.PURCHASE, { currency: 'USD', value: 9.99 });
 </script>
 ```
 
+The CDN bundle attaches the same runtime symbols that ESM consumers
+import — `Audience`, `AudienceError`, `AudienceEvents`, `IdentityType`,
+`canTrack`, `canIdentify`, and `version` — so no snippet is reachable
+on one path but not the other.
+
 ## Error handling
 
 `AudienceError.code` is a closed union — `'FLUSH_FAILED'`,
@@ -90,8 +120,8 @@ bad handler can't wedge the queue.
 
 For a live harness that exercises every public method, every typed
 `track()` event, and every reachable `AudienceErrorCode` against the
-real sandbox backend, see
-[`packages/audience/sdk-sample-app`](../sdk-sample-app/README.md).
+real sandbox backend, see [`packages/audience/sdk-sample-app`](https://github.com/immutable/ts-immutable-sdk/tree/main/packages/audience/sdk-sample-app)
+in the `ts-immutable-sdk` monorepo.
 
 ## License