feat(docs): cookieless PostHog analytics (SSR-safe)

- posthog-js service with isPlatformBrowser guards; init skipped without key
- events across hero/header/sidebar/playground/theme; install-copy = conversion
- key/host from VITE_POSTHOG_* (.env gitignored) + CI build via repo vars
- persistence: memory -> cookieless, no consent banner (RGPD); EU host

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: cdskill

.github/workflows/deploy.yml

@@ -79,6 +79,10 @@ jobs:
 
       - name: Build ${{ matrix.app }}
         run: pnpm nx build ${{ matrix.app }}
+        # PostHog (docs) reads VITE_* at build time. Public project key → repo variables, not secrets.
+        env:
+          VITE_POSTHOG_KEY: ${{ vars.POSTHOG_KEY }}
+          VITE_POSTHOG_HOST: ${{ vars.POSTHOG_HOST }}
 
       - name: Resolve deploy target
         id: cfg

.gitignore

@@ -44,3 +44,4 @@ Thumbs.db
 .claude/settings.local.json
 
 .angular
+.env

apps/docs/src/app/app.component.ts

@@ -1,10 +1,33 @@
-import { ChangeDetectionStrategy, Component } from '@angular/core';
+import {
+  ChangeDetectionStrategy,
+  Component,
+  OnInit,
+  inject,
+} from '@angular/core';
 import { RouterOutlet } from '@angular/router';
 
+import { PosthogService } from './services/posthog.service';
+import { environment } from '../environments/environment';
+
 @Component({
   selector: 'app-root',
   imports: [RouterOutlet],
-  template: ` <router-outlet/> `,
+  template: ` <router-outlet /> `,
   changeDetection: ChangeDetectionStrategy.OnPush,
 })
-export class AppComponent {}
+export class AppComponent implements OnInit {
+  private readonly posthogService = inject(PosthogService);
+
+  ngOnInit(): void {
+    if (!environment.posthogKey) {
+      return;
+    }
+
+    this.posthogService.init(environment.posthogKey, {
+      api_host: environment.posthogHost,
+      defaults: '2026-01-30',
+      capture_exceptions: true,
+      persistence: 'memory', // cookieless: no consent banner needed (RGPD)
+    });
+  }
+}

apps/docs/src/app/components/docs-header.ts

@@ -1,4 +1,9 @@
-import { ChangeDetectionStrategy, Component, signal } from '@angular/core';
+import {
+  ChangeDetectionStrategy,
+  Component,
+  inject,
+  signal,
+} from '@angular/core';
 import { RouterLink, RouterLinkActive } from '@angular/router';
 import { NgIcon, provideIcons } from '@ng-icons/core';
 import {
@@ -11,6 +16,7 @@ import {
 
 import { HlmButton } from '../ui/button';
 import { ThemeToggle } from './theme-toggle';
+import { PosthogService } from '../services/posthog.service';
 
 /**
  * Minimal top bar in the shadcn / plate spirit: short height, no dividing
@@ -21,11 +27,19 @@ import { ThemeToggle } from './theme-toggle';
   selector: 'app-docs-header',
   imports: [RouterLink, RouterLinkActive, NgIcon, HlmButton, ThemeToggle],
   providers: [
-    provideIcons({ lucideFeather, lucideGithub, lucideMenu, lucideSearch, lucideX }),
+    provideIcons({
+      lucideFeather,
+      lucideGithub,
+      lucideMenu,
+      lucideSearch,
+      lucideX,
+    }),
   ],
   template: `
     <header class="sticky top-0 z-40 w-full bg-background/70 backdrop-blur-md">
-      <div class="relative mx-auto flex h-14 max-w-6xl items-center gap-6 px-4 sm:px-6">
+      <div
+        class="relative mx-auto flex h-14 max-w-6xl items-center gap-6 px-4 sm:px-6"
+      >
         <a href="/" class="flex items-center gap-2" aria-label="Qalma home">
           <ng-icon
             name="lucideFeather"
@@ -40,7 +54,10 @@ import { ThemeToggle } from './theme-toggle';
         <nav
           class="hidden items-center gap-5 text-sm text-muted-foreground md:flex"
         >
-          <a class="transition-colors hover:text-foreground" href="/#playground">
+          <a
+            class="transition-colors hover:text-foreground"
+            href="/#playground"
+          >
             Playground
           </a>
           <a
@@ -75,6 +92,7 @@ import { ThemeToggle } from './theme-toggle';
             target="_blank"
             rel="noreferrer"
             aria-label="GitHub repository"
+            (click)="trackGithubClick()"
           >
             <ng-icon name="lucideGithub" aria-hidden="true" />
           </a>
@@ -89,7 +107,7 @@ import { ThemeToggle } from './theme-toggle';
             class="md:hidden"
             [attr.aria-label]="mobileNavOpen() ? 'Close menu' : 'Open menu'"
             [attr.aria-expanded]="mobileNavOpen()"
-            (click)="mobileNavOpen.set(!mobileNavOpen())"
+            (click)="toggleMobileNav()"
           >
             <ng-icon
               [name]="mobileNavOpen() ? 'lucideX' : 'lucideMenu'"
@@ -124,5 +142,19 @@ import { ThemeToggle } from './theme-toggle';
   `,
 })
 export class DocsHeader {
+  private readonly posthogService = inject(PosthogService);
+
   protected readonly mobileNavOpen = signal(false);
+
+  protected toggleMobileNav(): void {
+    const opening = !this.mobileNavOpen();
+    this.mobileNavOpen.set(opening);
+    if (opening) {
+      this.posthogService.posthog.capture('mobile_nav_opened');
+    }
+  }
+
+  protected trackGithubClick(): void {
+    this.posthogService.posthog.capture('github_link_clicked');
+  }
 }

apps/docs/src/app/components/hero.ts

@@ -1,6 +1,7 @@
 import {
   ChangeDetectionStrategy,
   Component,
+  inject,
   signal,
 } from '@angular/core';
 import { NgIcon, provideIcons } from '@ng-icons/core';
@@ -12,6 +13,7 @@ import {
 } from '@ng-icons/lucide';
 
 import { HlmButton } from '../ui/button';
+import { PosthogService } from '../services/posthog.service';
 
 const INSTALL_COMMAND = 'pnpm add @qalma/editor';
 
@@ -28,7 +30,9 @@ const INSTALL_COMMAND = 'pnpm add @qalma/editor';
     provideIcons({ lucideArrowRight, lucideCheck, lucideCopy, lucideSparkles }),
   ],
   template: `
-    <section class="mx-auto max-w-3xl px-4 pb-10 pt-12 text-center sm:pb-12 sm:pt-16">
+    <section
+      class="mx-auto max-w-3xl px-4 pb-10 pt-12 text-center sm:pb-12 sm:pt-16"
+    >
       <span
         class="mb-5 inline-flex items-center gap-1.5 rounded-full border border-border bg-card px-3 py-1 text-xs font-medium text-muted-foreground"
       >
@@ -60,13 +64,15 @@ const INSTALL_COMMAND = 'pnpm add @qalma/editor';
         crafted for Angular.
       </h1>
 
-      <p class="mx-auto mt-5 max-w-xl text-base leading-relaxed text-muted-foreground">
+      <p
+        class="mx-auto mt-5 max-w-xl text-base leading-relaxed text-muted-foreground"
+      >
         A headless, plugin-based editor built on ProseMirror. Composable
         primitives, Tailwind-first styling, and zero opinions about your design.
       </p>
 
       <div class="mt-7 flex flex-wrap items-center justify-center gap-3">
-        <a appBtn size="lg" href="#playground">
+        <a appBtn size="lg" href="#playground" (click)="trackGetStarted()">
           Get started
           <ng-icon name="lucideArrowRight" aria-hidden="true" />
         </a>
@@ -80,7 +86,11 @@ const INSTALL_COMMAND = 'pnpm add @qalma/editor';
         >
           {{ installCommand }}
           @if (copied()) {
-            <ng-icon name="lucideCheck" class="text-accent" aria-hidden="true" />
+            <ng-icon
+              name="lucideCheck"
+              class="text-accent"
+              aria-hidden="true"
+            />
           } @else {
             <ng-icon name="lucideCopy" aria-hidden="true" />
           }
@@ -90,6 +100,8 @@ const INSTALL_COMMAND = 'pnpm add @qalma/editor';
   `,
 })
 export class Hero {
+  private readonly posthogService = inject(PosthogService);
+
   protected readonly installCommand = INSTALL_COMMAND;
   protected readonly copied = signal(false);
 
@@ -98,5 +110,13 @@ export class Hero {
       this.copied.set(true);
       setTimeout(() => this.copied.set(false), 1400);
     });
+
+    this.posthogService.posthog.capture('install_command_copied', {
+      command: INSTALL_COMMAND,
+    });
+  }
+
+  protected trackGetStarted(): void {
+    this.posthogService.posthog.capture('get_started_clicked');
   }
 }

apps/docs/src/app/components/theme-toggle.ts

@@ -2,12 +2,14 @@ import {
   ChangeDetectionStrategy,
   Component,
   afterNextRender,
+  inject,
   signal,
 } from '@angular/core';
 import { NgIcon, provideIcons } from '@ng-icons/core';
 import { lucideMoon, lucideSun } from '@ng-icons/lucide';
 
 import { HlmButton } from '../ui/button';
+import { PosthogService } from '../services/posthog.service';
 
 @Component({
   changeDetection: ChangeDetectionStrategy.OnPush,
@@ -21,7 +23,9 @@ import { HlmButton } from '../ui/button';
       size="icon"
       type="button"
       (click)="toggle()"
-      [attr.aria-label]="isDark() ? 'Switch to light theme' : 'Switch to dark theme'"
+      [attr.aria-label]="
+        isDark() ? 'Switch to light theme' : 'Switch to dark theme'
+      "
       title="Toggle theme"
     >
       @if (isDark()) {
@@ -33,6 +37,8 @@ import { HlmButton } from '../ui/button';
   `,
 })
 export class ThemeToggle {
+  private readonly posthogService = inject(PosthogService);
+
   protected readonly isDark = signal(false);
 
   constructor() {
@@ -54,5 +60,9 @@ export class ThemeToggle {
     }
 
     this.isDark.set(next);
+
+    this.posthogService.posthog.capture('theme_toggled', {
+      theme: next ? 'dark' : 'light',
+    });
   }
 }

apps/docs/src/app/docs/docs-sidebar.ts

@@ -4,6 +4,7 @@ import {
   Component,
   ElementRef,
   HostListener,
+  inject,
   output,
   signal,
   viewChild,
@@ -13,6 +14,7 @@ import { NgIcon, provideIcons } from '@ng-icons/core';
 import { lucideMouse } from '@ng-icons/lucide';
 
 import { DOCS_NAV } from './docs-nav';
+import { PosthogService } from '../services/posthog.service';
 
 /**
  * Left-nav for the docs site. Plain grouped link list (no collapsible
@@ -47,7 +49,7 @@ import { DOCS_NAV } from './docs-nav';
                   [routerLink]="item.href"
                   routerLinkActive="bg-accent-subtle !text-accent font-medium"
                   [routerLinkActiveOptions]="{ exact: true }"
-                  (click)="linkClick.emit()"
+                  (click)="onLinkClick(item.title, item.href)"
                   class="block rounded-md px-2 py-1 text-xs text-muted-foreground transition-colors hover:bg-secondary hover:text-foreground"
                 >
                   {{ item.title }}
@@ -78,9 +80,12 @@ import { DOCS_NAV } from './docs-nav';
   `,
 })
 export class DocsSidebar implements AfterViewInit {
+  private readonly posthogService = inject(PosthogService);
+
   protected readonly groups = DOCS_NAV;
 
-  private readonly scrollEl = viewChild.required<ElementRef<HTMLElement>>('scrollEl');
+  private readonly scrollEl =
+    viewChild.required<ElementRef<HTMLElement>>('scrollEl');
 
   protected readonly showTopFade = signal(false);
   protected readonly showBottomFade = signal(false);
@@ -97,6 +102,16 @@ export class DocsSidebar implements AfterViewInit {
     const el = this.scrollEl().nativeElement;
 
     this.showTopFade.set(el.scrollTop > 4);
-    this.showBottomFade.set(el.scrollTop + el.clientHeight < el.scrollHeight - 4);
+    this.showBottomFade.set(
+      el.scrollTop + el.clientHeight < el.scrollHeight - 4,
+    );
+  }
+
+  protected onLinkClick(title: string, href: string): void {
+    this.linkClick.emit();
+    this.posthogService.posthog.capture('docs_sidebar_clicked', {
+      title,
+      href,
+    });
   }
 }

apps/docs/src/app/playground/playground.ts

@@ -45,12 +45,15 @@ import {
 } from './image';
 import { LinkPopoverController } from './link-popover-controller';
 import { PlaygroundLinkPopover } from './link-popover';
+import { LinkPopover } from './link-popover.model';
 import {
   PlaygroundMentionController,
+  PlaygroundMentionOption,
   createPlaygroundMentionSource,
 } from './mention';
 import { PlaygroundMentionMenu } from './mention-menu';
 import { PlaygroundToolbar } from './toolbar';
+import { PosthogService } from '../services/posthog.service';
 
 @Component({
   changeDetection: ChangeDetectionStrategy.OnPush,
@@ -103,7 +106,7 @@ import { PlaygroundToolbar } from './toolbar';
         [loading]="mentionController.loading()"
         [activeIndex]="mentionController.activeIndex()"
         (activate)="mentionController.setActiveIndex($event)"
-        (pick)="mentionController.insert($event)"
+        (pick)="onMentionPick($event)"
         (dismiss)="mentionController.hide()"
       />
     }
@@ -113,7 +116,7 @@ import { PlaygroundToolbar } from './toolbar';
       [href]="linkPopover.href()"
       (hrefChange)="linkPopover.href.set($event)"
       (edit)="linkPopover.edit($event)"
-      (save)="linkPopover.save($event)"
+      (save)="onLinkSave($event)"
       (remove)="linkPopover.remove($event)"
       (dismiss)="linkPopover.hide()"
       (keepOpen)="linkPopover.keepOpen()"
@@ -135,6 +138,7 @@ import { PlaygroundToolbar } from './toolbar';
 })
 export class Playground {
   private readonly destroyRef = inject(DestroyRef);
+  private readonly posthogService = inject(PosthogService);
   // `#mentionSurface` sits on the <qalma-content> component, so without an
   // explicit `read` the query resolves to the component instance (whose
   // `.nativeElement` is undefined). Read the host ElementRef instead.
@@ -238,6 +242,10 @@ export class Playground {
       currentImage ? 'updateImage' : 'insertImage',
       commandValue,
     );
+
+    this.posthogService.posthog.capture('playground_image_inserted', {
+      type: 'url',
+    });
   }
 
   protected chooseImageFile(): void {
@@ -269,6 +277,20 @@ export class Playground {
       title: file.name,
       previewSrc,
     });
+
+    this.posthogService.posthog.capture('playground_image_uploaded', {
+      mime_type: file.type,
+    });
+  }
+
+  protected onLinkSave(popover: LinkPopover): void {
+    this.linkPopover.save(popover);
+    this.posthogService.posthog.capture('playground_link_saved');
+  }
+
+  protected onMentionPick(option: PlaygroundMentionOption): void {
+    this.mentionController.insert(option);
+    this.posthogService.posthog.capture('playground_mention_inserted');
   }
 
   private revokeImagePreviewUrls(): void {