feat(angular-web-sdk): implement Angular Web SDK reference implementation

implementations/angular-web-sdk/.gitignore

@@ -0,0 +1,23 @@
+# dependencies
+node_modules/
+
+# build output
+dist/
+
+# Angular cache
+.angular/
+
+# env files (copy from .env.example to set up locally)
+.env
+.env*.local
+
+# logs produced by launch-reference-app.sh
+logs/
+
+# debug
+*.log
+.pnpm-debug.log*
+
+# misc
+.DS_Store
+*.tsbuildinfo

implementations/angular-web-sdk/AGENTS.md

@@ -0,0 +1,41 @@
+# AGENTS.md
+
+Angular SPA reference implementation of `@contentful/optimization-web`. Serves the app on
+`http://localhost:4200` via the Angular CLI dev server alongside the shared mock API server.
+
+## Rules
+
+- Read [`REQUIREMENTS.md`](./REQUIREMENTS.md) before making any changes — it is the source of truth
+  for what this implementation must do and how it must behave.
+- Do not add local adapter shims; import SDK behaviour directly from the published package surface
+  when it exists.
+- This implementation uses Angular CLI (`@angular/build`) and PM2-managed mock server processes.
+- Use standalone components (no NgModule).
+- Use modern Angular patterns: signals and `computed()` for state, `inject()` for dependency
+  injection (not constructor injection), `input()` / `output()` for component I/O, `toSignal()` to
+  bridge RxJS observables to templates, and `@if` / `@for` control flow syntax.
+- Name files and classes after the concept only — no Angular-role suffixes anywhere. File: `home.ts`
+  not `home.component.ts`. Class: `Home` not `HomeComponent`, `Optimization` not
+  `OptimizationService`, `MergeTag` not `MergeTagPipe`, etc.
+- Avoid unsafe type assertions (`as SomeType`). Use `isRecord()` and typed type-guard functions
+  instead. The `no-unsafe-type-assertion` ESLint rule is enforced and blocks commits.
+- Follow the Angular style guide class member ordering: inputs → injected dependencies → private
+  state → constructor (effects/setup) → protected state (template-facing computed/signals) →
+  lifecycle hooks → public methods → private methods.
+
+## Commands
+
+```sh
+pnpm implementation:run -- angular-web-sdk implementation:install
+pnpm implementation:run -- angular-web-sdk serve:mocks
+pnpm implementation:run -- angular-web-sdk dev
+pnpm implementation:run -- angular-web-sdk build
+pnpm implementation:run -- angular-web-sdk typecheck
+```
+
+## Validate
+
+- Run `typecheck` for TypeScript changes.
+- Run `build` for production bundling changes.
+- Run lint via `npx eslint <file>` from the implementation directory for source file changes.
+- The pre-commit hook runs lint and Prettier automatically — fix any errors before committing.

implementations/angular-web-sdk/README.md

@@ -0,0 +1,96 @@
+<p align="center">
+  <a href="https://www.contentful.com/developers/docs/personalization/">
+    <img alt="Contentful Logo" title="Contentful" src="../../contentful-icon.png" width="150">
+  </a>
+</p>
+
+<h1 align="center">Contentful Personalization & Analytics</h1>
+
+<h3 align="center">Angular Web SDK Reference Implementation</h3>
+
+<div align="center">
+
+[Readme](./README.md) ·
+[Guides](https://contentful.github.io/optimization/documents/Documentation.Guides.html) ·
+[Reference](https://contentful.github.io/optimization) · [Contributing](../../CONTRIBUTING.md)
+
+</div>
+
+> [!WARNING]
+>
+> The Optimization SDK Suite is pre-release (alpha). Breaking changes can be published at any time.
+
+Reference implementation of `@contentful/optimization-web` for Angular applications. Demonstrates
+all SDK integration patterns — entry resolution, auto and manual tracking, consent, identify/reset,
+live updates, nested entries, rich text with merge tags, feature flags, analytics event display, and
+the preview panel.
+
+## What this demonstrates
+
+- SDK initialisation as a singleton Angular service
+- Page tracking on every route change via the Angular router
+- Entry resolution with variant/baseline display
+- Auto-tracking via `data-ctfl-*` DOM attributes
+- Manual tracking via `sdk.tracking.enableElement`
+- Click scenarios: direct, descendant, ancestor
+- Consent gating
+- Identify and reset with session persistence
+- Live updates: global toggle and per-entry override
+- Preview panel forced-live mode
+- Nested entries with recursive resolution
+- Rich text rendering with inline merge tags
+- Feature flag subscription with auto-emitted view events
+- Analytics event display with heartbeat deduplication
+- Multi-route navigation with conversion tracking
+
+See [`REQUIREMENTS.md`](./REQUIREMENTS.md) for full feature specs and visual verification steps.
+
+## Prerequisites
+
+- Node.js >= 20.19.0 (24.13.0 recommended to match `.nvmrc`)
+- pnpm 10.x
+
+## Quick start
+
+From the **repository root**:
+
+```sh
+pnpm build:pkgs
+pnpm implementation:run -- angular-web-sdk implementation:install
+pnpm implementation:run -- angular-web-sdk serve:mocks
+pnpm implementation:run -- angular-web-sdk dev
+```
+
+The app is available at `http://localhost:4200`. The mock server must be running for entry data and
+variant resolution to work.
+
+## Running locally
+
+From the **repository root**:
+
+```sh
+pnpm implementation:run -- angular-web-sdk dev
+pnpm implementation:run -- angular-web-sdk build
+pnpm implementation:run -- angular-web-sdk typecheck
+```
+
+Or from the **implementation directory**:
+
+```sh
+pnpm dev
+pnpm build
+pnpm typecheck
+```
+
+## Environment variables
+
+Copy `.env.example` to `.env`:
+
+```sh
+cp .env.example .env
+```
+
+## Related
+
+- [web-sdk_react](../web-sdk_react/README.md) — React Web SDK reference implementation
+- [@contentful/optimization-web](../../packages/web/web-sdk/README.md) — Web SDK

implementations/angular-web-sdk/REQUIREMENTS.md

@@ -0,0 +1,170 @@
+# Web SDK Reference Implementation — Requirements
+
+Implement and validate a client-side SPA reference implementation demonstrating the full Angular
+adapter SDK integration path using public APIs only, against shared mocks and fixtures. All behavior
+runs entirely on the client — no SSR, no server-side rendering, no hydration.
+
+**Constraint (REFREQ-20):** No local shims, casts, or adapter logic may mask a missing SDK
+capability. All SDK interaction must go through public package APIs.
+
+---
+
+## Core setup
+
+### SDK initialisation
+
+- Initialises once per page load from environment config; enforced by a module-level singleton.
+- Falls back to baseline rendering on init failure — no crash or blank screen.
+- On teardown: unsubscribes the router subscription, calls `sdk.destroy()` to flush queues and stop
+  entry interaction tracking, and resets the singleton so the SDK can be recreated cleanly.
+- Confirm: load — entry cards render and control panel shows **Active optimizations: 0**; on
+  failure, entries show baseline with no crash; navigate away and confirm no subscription leaks in
+  DevTools.
+
+### Multi-route navigation
+
+- Two routes: **Home** (`/`) and **Page Two** (`/page-two`).
+- SDK is not re-initialised on route changes; event history is preserved.
+- Arriving on Page Two auto-fires `component — page-two-conversion`; the **Track conversion** button
+  fires an additional one.
+- A `page` event fires on every SPA route change, regardless of consent.
+- Confirm: navigate to Page Two — sidebar shows `page — /page-two` and
+  `component — page-two-conversion` automatically; navigating back and forth produces no repeated
+  SDK init entries.
+
+### Consent
+
+- App exposes a consent toggle; granting enables tracking, withdrawing disables it immediately.
+- Page events are unaffected by consent state and always fire.
+- Confirm: clean session — no `component` events regardless of scrolling; grant consent — view
+  events appear on scroll; withdraw — no new `component` events but `page` events still fire on
+  navigation.
+
+### Identify and reset
+
+- `identify()` associates the session with a fixed user ID; `reset()` returns to anonymous.
+- Both states persist across page reloads via SDK-managed storage — no app-level code required.
+- Confirm: clean session shows **Identified: No**; after **Identify** with live updates ON, variant
+  cards update; after **Reset**, cards revert to baseline; after reload, **Identified: Yes**
+  immediately.
+
+### Preview panel
+
+- Panel code is lazy-loaded on first open — no bundle loads when the feature is disabled (network
+  tab).
+- Opening forces live re-resolution for all entries, overriding per-entry lock settings.
+- Closing restores each entry's configured live-update behaviour.
+- Supports audience activation/deactivation and variant override/reset — all handled by the panel
+  itself; no app code required.
+- Confirm: global OFF, **Always locked** — identify does not change the entry; open panel then reset
+  — it updates; close and identify again — it does not change. Inside the panel: activate an
+  audience override — entry updates; deactivate — reverts; apply a variant override then reset —
+  entry returns to SDK-resolved variant.
+
+### Locale consistency
+
+- All CDA entry fetches use the SDK-resolved locale.
+- Structural: Contentful client is wrapped with `sdk.withOptimizationLocale()` before entries are
+  fetched.
+
+### Feature flags
+
+- App subscribes to a `'boolean'` flag via the SDK flag state API; value shown in the control panel.
+- Accessing the flag emits a flag-view event automatically — no explicit tracking call in app code.
+- Returns `undefined` for anonymous sessions; resolves to configured value after `identify()`.
+- Confirm: clean session — **Flag "boolean": undefined**; after **Identify**, resolves to `true` and
+  a `component` event appears in the sidebar automatically; after **Reset**, returns to `undefined`.
+
+---
+
+## Tracking
+
+### Analytics
+
+- App renders the SDK event stream in real time; every tracking event (page, view, click, hover)
+  appears in the sidebar as it occurs.
+- View and hover rows update in place (duration); **Raw count** increases faster than the
+  deduplicated list.
+- Events blocked by consent do not appear — the SDK's `eventStream` only emits delivered events;
+  blocked events are routed to `blockedEventStream` and never reach the log.
+- History persists across route changes.
+- Confirm: clean session — sidebar shows `page — /`; without consent, scroll produces no `component`
+  events; grant consent, hover an entry — `component_hover` row appears and duration updates in
+  place while Raw count rises; navigate routes — prior events remain and `page` events append.
+
+### Page tracking
+
+- A `page` event fires on first load and on every route change, regardless of consent.
+- Confirm: clean session — `page — /` appears immediately; navigating between routes produces a
+  `page` event each time, with or without consent.
+
+### Entry tracking _(which events are emitted)_
+
+- **Attribute-based (auto)** — `data-ctfl-*` attributes on DOM elements are observed by the SDK;
+  view, click, and hover events fire automatically after consent; none before; all stop immediately
+  if consent is withdrawn.
+  - **Click scenarios** — all three must emit `component_click`:
+    - **Direct** — the tracked element itself is clicked.
+    - **Descendant** — a button inside the tracked element is clicked.
+    - **Ancestor** — click listener is on a wrapper element containing the tracked entry.
+  - Confirm: clean session — scroll **Auto-observed**, no `component` events; grant consent, scroll
+    — view events appear; click a card → `component_click`; hover → `component_hover`; click each of
+    `direct`, `descendant`, `ancestor` — a `component_click` appears for each.
+- **Code-based (manual)** — entries registered via explicit `enableElement` calls instead of
+  `data-ctfl-*` attributes; emits view events only; no click or hover events.
+  - Confirm: grant consent, scroll **Manually-observed** — view events appear; click or hover a card
+    — no `component_click` or `component_hover`.
+
+---
+
+## Live updates
+
+### Global toggle
+
+- **OFF (default):** entry resolves once then freezes; `identify()`/`reset()` does not change what
+  is displayed.
+- **ON:** entry re-resolves immediately on every profile change.
+- Confirm: global OFF, **Identify** — Default card does not change; toggle ON — label updates;
+  **Reset** — Default card updates immediately.
+
+### Per-entry overrides
+
+- **Always live** — re-resolves on profile change even when global is OFF.
+- **Always locked** — never re-resolves regardless of global toggle; does re-resolve when preview
+  panel is open.
+- **Default** — no override; follows the global toggle.
+- Confirm: global OFF, **Identify** — only **Always live** updates; **Default** and **Always
+  locked** stay frozen; toggle ON, **Reset** — **Default** and **Always live** update; **Always
+  locked** stays frozen.
+
+---
+
+## Content
+
+### Entry resolution
+
+- SDK resolves the correct variant for each entry; always falls back to baseline on invalid data; no
+  variant selection logic in app code.
+- Confirm: load — all cards show `baseline` badge; live updates ON, **Identify** — active experience
+  cards switch to `variant` with `var`/`exp` IDs; **Reset** — cards revert to `baseline`.
+
+### Nested entries
+
+- Each level resolves to its own variant independently; arbitrary nesting depth is handled by the
+  SDK without app-level recursion.
+- Confirm: first Auto-observed card shows `nested` badge with indented child entries, each with
+  their own ID rows; live updates ON, **Identify** — each nested level updates independently.
+
+### Merge tags
+
+- Profile-resolved values rendered inline; shows `[Merge Tag]` fallback when no profile is active.
+- Updates on `identify()` and reverts on `reset()`.
+- Confirm: clean session — merge tag cards (yellow badge) show `[Merge Tag]`; live updates ON,
+  **Identify** — replaced with resolved value; **Reset** — reverts to `[Merge Tag]`.
+
+### Rich text
+
+- Renders as formatted HTML (paragraphs, headings, lists, blockquotes, hyperlinks).
+- Merge tag nodes embedded in rich text are resolved inline with the same fallback behaviour.
+- Confirm: rich text cards (blue badge) render formatted HTML — not raw JSON; merge tag nodes show
+  resolved value or `[Merge Tag]` fallback inline.

implementations/angular-web-sdk/angular.json

@@ -0,0 +1,62 @@
+{
+  "$schema": "./node_modules/@angular/cli/lib/config/schema.json",
+  "version": 1,
+  "newProjectRoot": "projects",
+  "projects": {
+    "angular-web-sdk": {
+      "projectType": "application",
+      "root": "",
+      "sourceRoot": "src",
+      "prefix": "app",
+      "architect": {
+        "build": {
+          "builder": "@angular/build:application",
+          "options": {
+            "outputPath": "dist/angular-web-sdk",
+            "index": "src/index.html",
+            "browser": "src/main.ts",
+            "tsConfig": "tsconfig.json",
+            "assets": [],
+            "styles": ["src/styles.css"]
+          },
+          "configurations": {
+            "production": {
+              "budgets": [
+                {
+                  "type": "initial",
+                  "maximumWarning": "500kB",
+                  "maximumError": "1MB"
+                }
+              ],
+              "outputHashing": "all"
+            },
+            "development": {
+              "optimization": false,
+              "sourceMap": true
+            }
+          },
+          "defaultConfiguration": "production"
+        },
+        "serve": {
+          "builder": "@angular/build:dev-server",
+          "configurations": {
+            "production": {
+              "buildTarget": "angular-web-sdk:build:production"
+            },
+            "development": {
+              "buildTarget": "angular-web-sdk:build:development"
+            }
+          },
+          "defaultConfiguration": "development",
+          "options": {
+            "port": 4200
+          }
+        }
+      }
+    }
+  },
+  "cli": {
+    "analytics": false,
+    "packageManager": "pnpm"
+  }
+}