feat(share): slice 3 — play/remix counters + share_created/game_remixed funnel events

UNIT 1 (CEO ruling #4: aggregate integers only, zero PII):
- HostedExport.counts {plays, remixes}, init at host time
- getShareStats/incrementShareCount (never throws, integer-clamped)
- GET /api/share/:token/stats -> {plays, remixes} (404/410, ACAO:* + no-store)
- plays increment in shared serve handler (/share/:token + legacy view)
- remixes increment only on real payload delivery
- landing bar fetches stats post-render, subtle 'Played N times'

UNIT 2 (storage-only funnel):
- trackEvent('share_created', {hostedId}) on SharePopover success
- trackEvent('game_remixed', {hostedId, projectId}) after RemixPage fork

Tests: api +5 counter tests (incl. flatten-key PII sweep), web +3.
Status log entry same-commit (session-23).

Author: CompareAIHardware Builder

apps/api/src/routes/hostedRoutes.ts

@@ -64,6 +64,12 @@ export async function hostedRoutes(app: FastifyInstance) {
 
       const { content, mimeType } = await hostedServiceInstance!.getHostedFile(hostedId);
 
+      // Play counter (slice 3): every serve of the game counts as a play —
+      // both the canonical /share/:token link and the legacy view route come
+      // through this shared handler. Awaited (tiny local write) so the
+      // landing bar's own stats fetch sees its own view; never throws.
+      await hostedServiceInstance!.incrementShareCount(hostedId, 'plays');
+
       applyGameHtmlHeaders(reply);
       reply
         .header('Content-Type', mimeType)
@@ -207,6 +213,9 @@ export async function hostedRoutes(app: FastifyInstance) {
             code: 'remix_payload_missing',
           };
         }
+        // Remix counter (slice 3): only real payload deliveries count —
+        // unknown/expired/legacy-missing fetches are not remixes.
+        await hostedServiceInstance!.incrementShareCount(token, 'remixes');
         return payload;
       } catch (error: any) {
         reply.code(500);
@@ -215,6 +224,36 @@ export async function hostedRoutes(app: FastifyInstance) {
     }
   );
 
+  // Share stats (slice 3): aggregate integers only (CEO ruling #4 exception
+  // to the storage-only funnel — no PII). Consumed by the injected landing
+  // bar ("played N times"), which runs inside a CSP-sandboxed page with an
+  // opaque origin → its fetch is cross-origin, so ACAO:* is required.
+  app.get<{ Params: { token: string } }>(
+    '/api/share/:token/stats',
+    async (request, reply) => {
+      const { token } = request.params;
+      try {
+        const hostedExport = await hostedServiceInstance!.getHostedExport(token);
+        if (!hostedExport) {
+          reply.code(404);
+          return { error: 'Hosted game not found' };
+        }
+        if (hostedExport.expiresAt && new Date(hostedExport.expiresAt) < new Date()) {
+          reply.code(410);
+          return { error: 'Hosted game has expired' };
+        }
+        const stats = await hostedServiceInstance!.getShareStats(token);
+        reply
+          .header('Access-Control-Allow-Origin', '*')
+          .header('Cache-Control', 'no-store');
+        return stats;
+      } catch (error: any) {
+        reply.code(500);
+        return { error: error.message || 'Failed to load share stats' };
+      }
+    }
+  );
+
   // View hosted game in browser (serve HTML) — legacy route kept working;
   // new shares advertise /share/:token links instead.
   app.get<{ Params: { hostedId: string } }>(

apps/api/src/services/hostedService.ts

@@ -22,6 +22,8 @@ export interface HostedExport {
   downloadUrl: string;
   /** v1 ruling (CEO 2026-08-25): shares include full editable source by default. */
   sourceIncluded?: boolean;
+  /** Aggregate play/remix counters (slice 3). Integers only — zero PII by design. */
+  counts?: { plays: number; remixes: number };
 }
 
 export interface HostedOptions {
@@ -207,6 +209,7 @@ export class HostedService {
       expiresAt,
       downloadUrl: `/api/projects/${projectId}/exports/${exportFilename}`,
       sourceIncluded: true,
+      counts: { plays: 0, remixes: 0 },
     };
 
     // Save hosted metadata
@@ -404,7 +407,7 @@ window.addEventListener('DOMContentLoaded', () => {
   \`;
 
   nav.innerHTML = \`
-    <div>
+    <div id="clawgame-bar-left">
       <strong>🎮 ClawGame</strong>${expiresLine}
     </div>
     <div style="display:flex;align-items:center;gap:12px;">
@@ -422,6 +425,30 @@ window.addEventListener('DOMContentLoaded', () => {
     dismiss.addEventListener('click', () => nav.remove());
   }
 
+  // Play count (slice 3): subtle aggregate integer from the share-stats
+  // endpoint — rendered only after it arrives, so a slow/failed fetch never
+  // delays or breaks the game. The CSP sandbox gives this page an opaque
+  // origin, making the fetch cross-origin; /api/share/:token/stats answers
+  // with ACAO:*. Failure is silent by design.
+  try {
+    var meta = window.GAME_HOSTED_METADATA || {};
+    if (meta.hostedId) {
+      fetch('/api/share/' + encodeURIComponent(meta.hostedId) + '/stats')
+        .then(function (r) { return r.ok ? r.json() : null; })
+        .then(function (s) {
+          if (!s || typeof s.plays !== 'number' || s.plays < 1) return;
+          var left = document.getElementById('clawgame-bar-left');
+          if (!left || document.getElementById('clawgame-play-count')) return;
+          var span = document.createElement('span');
+          span.id = 'clawgame-play-count';
+          span.style.cssText = 'opacity:0.65;margin-left:8px;';
+          span.textContent = 'Played ' + s.plays + (s.plays === 1 ? ' time' : ' times');
+          left.appendChild(span);
+        })
+        .catch(function () {});
+    }
+  } catch (e) { /* counters must never break play */ }
+
   // Adjust game container for nav bar
   const container = document.getElementById('game-container');
   if (container) {
@@ -435,6 +462,46 @@ window.addEventListener('DOMContentLoaded', () => {
     return injectedHtml;
   }
 
+  /**
+   * Read the aggregate share counters for a token.
+   * Returns null when the token is unknown; zeros for legacy metas written
+   * before counters existed. Integers only — no PII is ever recorded here.
+   */
+  async getShareStats(hostedId: string): Promise<{ plays: number; remixes: number } | null> {
+    const hosted = await this.getHostedExport(hostedId);
+    if (!hosted) return null;
+    return {
+      plays: Math.max(0, Math.trunc(hosted.counts?.plays ?? 0)),
+      remixes: Math.max(0, Math.trunc(hosted.counts?.remixes ?? 0)),
+    };
+  }
+
+  /**
+   * Increment one aggregate counter in `<id>.meta.json` (read-modify-write).
+   *
+   * CEO ruling #4 exception to the storage-only funnel: these are bare
+   * integers on an already-public artifact's meta file — no IPs, no user
+   * agents, no fingerprints, nothing per-visitor. Never throws: a failed
+   * counter write must not break serving or remixing (callers rely on it).
+   */
+  async incrementShareCount(hostedId: string, key: 'plays' | 'remixes'): Promise<void> {
+    try {
+      const hostedDir = await this.ensureHostedDir();
+      const metaPath = join(hostedDir, `${hostedId}.meta.json`);
+      if (!existsSync(metaPath)) return;
+      const meta = JSON.parse(await readFile(metaPath, 'utf-8')) as HostedExport;
+      const counts = {
+        plays: Math.max(0, Math.trunc(meta.counts?.plays ?? 0)),
+        remixes: Math.max(0, Math.trunc(meta.counts?.remixes ?? 0)),
+      };
+      counts[key] += 1;
+      meta.counts = counts;
+      await writeFile(metaPath, JSON.stringify(meta, null, 2), 'utf-8');
+    } catch (err) {
+      this.logger.warn({ hostedId, key, err }, 'Failed to increment share counter');
+    }
+  }
+
   /**
    * Get hosted export by ID
    */

apps/api/src/test/share-remix.test.ts

@@ -52,6 +52,16 @@ async function createFixtureProject(name = 'Remix Fixture', sceneName = 'Remix M
   return { id, scenePath };
 }
 
+/** Recursively collect every object key path in a JSON value. */
+function flattenKeys(value: unknown, prefix = ''): string[] {
+  if (value === null || typeof value !== 'object') return [];
+  if (Array.isArray(value)) return value.flatMap((v) => flattenKeys(v, prefix));
+  return Object.entries(value as Record<string, unknown>).flatMap(([k, v]) => [
+    prefix ? `${prefix}.${k}` : k,
+    ...flattenKeys(v, prefix ? `${prefix}.${k}` : k),
+  ]);
+}
+
 async function shareProject(app: any, projectId: string) {
   const res = await app.inject({ method: 'POST', url: `/api/projects/${projectId}/share` });
   expect(res.statusCode).toBe(201);
@@ -204,3 +214,105 @@ describe('serialized payload size cap (design §4)', () => {
     expect(() => assertPayloadWithinSize(oversized)).toThrow(/too large/i);
   });
 });
+
+describe('share counters (slice 3, CEO ruling #4: aggregate integers only, zero PII)', () => {
+  it('fresh shares start at zero and GET /api/share/:token/stats returns exactly {plays, remixes}', async () => {
+    const app = await buildApp();
+    const { id: projectId } = await createFixtureProject('Stats Fresh');
+    const { hosted } = await shareProject(app, projectId);
+
+    const res = await app.inject({ method: 'GET', url: `/api/share/${hosted.id}/stats` });
+    expect(res.statusCode).toBe(200);
+    expect(res.json()).toEqual({ plays: 0, remixes: 0 });
+
+    // CORS header is mandatory: the injected landing bar fetches stats from a
+    // CSP-sandboxed page with an opaque origin (cross-origin request).
+    expect(res.headers['access-control-allow-origin']).toBe('*');
+    expect(res.headers['cache-control']).toBe('no-store');
+
+    await app.close();
+  });
+
+  it('serving the game increments plays — /share/:token and legacy view route both count', async () => {
+    const app = await buildApp();
+    const { id: projectId } = await createFixtureProject('Stats Plays');
+    const { hosted } = await shareProject(app, projectId);
+
+    await app.inject({ method: 'GET', url: `/share/${hosted.id}` });
+    await app.inject({ method: 'GET', url: `/api/hosted/${hosted.id}/view` });
+    await app.inject({ method: 'GET', url: `/share/${hosted.id}` });
+
+    const res = await app.inject({ method: 'GET', url: `/api/share/${hosted.id}/stats` });
+    expect(res.json()).toEqual({ plays: 3, remixes: 0 });
+
+    await app.close();
+  });
+
+  it('remix payload fetches increment remixes; failed/legacy remix attempts do not', async () => {
+    const app = await buildApp();
+    const { id: projectId } = await createFixtureProject('Stats Remixes');
+    const { hosted } = await shareProject(app, projectId);
+
+    await app.inject({ method: 'GET', url: `/api/share/${hosted.id}/remix` });
+    await app.inject({ method: 'GET', url: `/api/share/${hosted.id}/remix` });
+
+    // Legacy share without sidecar → typed 404 must NOT count as a remix.
+    const other = await createFixtureProject('Legacy Stats');
+    const legacyShare = await shareProject(app, other.id);
+    await unlink(join(HOSTED_DIR, `${legacyShare.hosted.id}.share.json`));
+    await app.inject({ method: 'GET', url: `/api/share/${legacyShare.hosted.id}/remix` });
+    expect(
+      (await app.inject({ method: 'GET', url: `/api/share/${legacyShare.hosted.id}/stats` })).json(),
+    ).toEqual({ plays: 0, remixes: 0 });
+
+    const res = await app.inject({ method: 'GET', url: `/api/share/${hosted.id}/stats` });
+    expect(res.json()).toEqual({ plays: 0, remixes: 2 });
+
+    await app.close();
+  });
+
+  it('404 unknown token, 410 expired token for stats', async () => {
+    const app = await buildApp();
+    const missing = await app.inject({ method: 'GET', url: '/api/share/no-such-token/stats' });
+    expect(missing.statusCode).toBe(404);
+
+    const service = new HostedService(mockLogger);
+    const { id: projectId } = await createFixtureProject('Expired Stats');
+    const { ExportService } = await import('../services/exportService');
+    const exportService = new ExportService(mockLogger);
+    const exported = await exportService.exportToPhaserHTML(projectId, { format: 'phaser-html' });
+    const hosted = await service.hostExport(projectId, exported.filename, { expiresInDays: 30 });
+    const metaPath = join(HOSTED_DIR, `${hosted.id}.meta.json`);
+    const meta = JSON.parse(await readFile(metaPath, 'utf-8'));
+    meta.expiresAt = new Date(Date.now() - 1000).toISOString();
+    await writeFile(metaPath, JSON.stringify(meta, null, 2), 'utf-8');
+
+    const expired = await app.inject({ method: 'GET', url: `/api/share/${hosted.id}/stats` });
+    expect(expired.statusCode).toBe(410);
+
+    await app.close();
+  });
+
+  it('meta file carries integers only — no PII keys ever written by counter paths', async () => {
+    const app = await buildApp();
+    const { id: projectId } = await createFixtureProject('Stats No PII');
+    const { hosted } = await shareProject(app, projectId);
+
+    await app.inject({ method: 'GET', url: `/share/${hosted.id}` });
+    await app.inject({ method: 'GET', url: `/api/share/${hosted.id}/remix` });
+
+    const raw = await readFile(join(HOSTED_DIR, `${hosted.id}.meta.json`), 'utf-8');
+    const meta = JSON.parse(raw);
+    expect(meta.counts).toEqual({ plays: 1, remixes: 1 });
+    expect(Number.isInteger(meta.counts.plays)).toBe(true);
+    expect(Number.isInteger(meta.counts.remixes)).toBe(true);
+
+    const FORBIDDEN = ['ip', 'ips', 'useragent', 'user-agent', 'ua', 'referer', 'referrer', 'fingerprint', 'sessionid'];
+    const keys = Object.keys(flattenKeys(meta)).map((k) => k.toLowerCase());
+    for (const forbidden of FORBIDDEN) {
+      expect(keys.some((k) => k === forbidden || k.endsWith(`.${forbidden}`))).toBe(false);
+    }
+
+    await app.close();
+  });
+});

apps/web/src/components/ShareButton.tsx

@@ -11,6 +11,7 @@ import React, { useCallback, useEffect, useRef, useState } from 'react';
 import { Link2, Copy, ExternalLink, Trash2, Loader2, X } from 'lucide-react';
 import { api, type HostedExport, type ShareResponse } from '../api/client';
 import { useToast } from './Toast';
+import { trackEvent } from '../utils/activationEvents';
 
 interface ShareButtonProps {
   projectId: string;
@@ -85,6 +86,8 @@ const SharePopover: React.FC<{ projectId: string; projectName?: string; onClose:
     try {
       const res = await api.shareProject(projectId);
       if (res.success && res.hosted && res.url) {
+        // Storage-only funnel (design §4): creator-side share event. Ids only.
+        trackEvent('share_created', { hostedId: res.hosted.id });
         setState({ phase: 'result', link: res.url, hosted: res.hosted });
         void loadExisting();
         return;

apps/web/src/pages/RemixPage.tsx

@@ -20,6 +20,7 @@ import React, { useEffect, useRef, useState } from 'react';
 import { useNavigate, useParams } from 'react-router-dom';
 import { api } from '../api/client';
 import { recordRecentProject } from '../utils/recentProjects';
+import { trackEvent } from '../utils/activationEvents';
 import './remix.css';
 
 /** API origin for the "back to game" link (the playable share lives there). */
@@ -82,6 +83,10 @@ export const RemixPage: React.FC = () => {
 
         recordRecentProject({ id: created.id, name, remixedFrom: token });
 
+        // Storage-only funnel (design §4): recipient-side remix event, fired
+        // only after the fork fully succeeded. Ids only — no payload text.
+        trackEvent('game_remixed', { hostedId: token, projectId: created.id });
+
         navigate(`/project/${created.id}/editor`, { replace: true });
       } catch (err) {
         const status = (err as any)?.status;

apps/web/src/test/remix-page.test.tsx

@@ -13,6 +13,7 @@ import { render, screen, waitFor } from '@testing-library/react';
 import { MemoryRouter, Routes, Route, useLocation } from 'react-router-dom';
 import { RemixPage } from '../pages/RemixPage';
 import { RECENT_PROJECTS_STORAGE_KEY } from '../utils/recentProjects';
+import { ACTIVATION_EVENTS_STORAGE_KEY } from '../utils/activationEvents';
 
 const TOKEN = '6f9619ff-8b86-d011-b42d-00cf4fc964ff';
 
@@ -136,6 +137,31 @@ describe('RemixPage — remix import flow (slice 2)', () => {
     expect(recent[0]).toMatchObject({ id: 'remixed-1', name: 'Remix of Space Shooter', remixedFrom: TOKEN });
   });
 
+  it('records a game_remixed funnel event (ids only) after the fork fully succeeds', async () => {
+    installFetch();
+    renderRemixPage();
+
+    await waitFor(() =>
+      expect(screen.getByTestId('location-probe').textContent).toBe('/project/remixed-1/editor'),
+    );
+
+    const events = JSON.parse(window.localStorage.getItem(ACTIVATION_EVENTS_STORAGE_KEY) || '[]');
+    const remixEvent = events.find((e: any) => e.name === 'game_remixed');
+    expect(remixEvent).toBeTruthy();
+    expect(remixEvent.props).toEqual({ hostedId: TOKEN, projectId: 'remixed-1' });
+    expect(typeof remixEvent.ts).toBe('string');
+  });
+
+  it('failed imports record no game_remixed event', async () => {
+    installFetch({ remixStatus: 404 });
+    renderRemixPage();
+
+    await waitFor(() => screen.getByText(/Remix unavailable/i));
+
+    const events = JSON.parse(window.localStorage.getItem(ACTIVATION_EVENTS_STORAGE_KEY) || '[]');
+    expect(events.filter((e: any) => e.name === 'game_remixed')).toHaveLength(0);
+  });
+
   it('invalid token (404): error card, no project created, back-to-game link offered', async () => {
     const { calls } = installFetch({ remixStatus: 404 });
     renderRemixPage();

apps/web/src/test/share-button.test.tsx

@@ -8,6 +8,7 @@ import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
 import { render, screen, fireEvent, waitFor } from '@testing-library/react';
 import { ToastProvider, ToastList } from '../components/Toast';
 import { ShareButton } from '../components/ShareButton';
+import { ACTIVATION_EVENTS_STORAGE_KEY } from '../utils/activationEvents';
 
 const SHARE_OK = {
   success: true,
@@ -107,6 +108,21 @@ describe('ShareButton/SharePopover — one-click share (slice 1)', () => {
     expect(screen.getByText(/Includes full editable source/i)).toBeTruthy();
   });
 
+  it('records a share_created funnel event (ids only) when the link is created', async () => {
+    installFetch(SHARE_OK);
+    renderShareButton();
+    await openPopover();
+
+    fireEvent.click(screen.getByText(/Create share link/i));
+    await waitFor(() => expect(screen.getByDisplayValue(SHARE_OK.url)).toBeTruthy());
+
+    const events = JSON.parse(window.localStorage.getItem(ACTIVATION_EVENTS_STORAGE_KEY) || '[]');
+    const shareEvent = events.find((e: any) => e.name === 'share_created');
+    expect(shareEvent).toBeTruthy();
+    expect(shareEvent.props).toEqual({ hostedId: SHARE_OK.hosted.id });
+    expect(typeof shareEvent.ts).toBe('string');
+  });
+
   it('shows the export-stage error toast when export fails', async () => {
     installFetch({ success: false, stage: 'export', error: 'Project not found' }, 400);
     renderShareButton();