The open-source full-stack studio for Opus 5.5 motion video. Reverse engineering for any video. Code video with HTML: recreate, edit and render. BYOA + BYOK · Motion.md · Images, Video, Music & Voice.
TypeScript agent-skillsagentic-aiai-agentsai-videobyokclaude-codecodexdeepseek-harnessdsh-plugingenerative-ailocal-firstmcpmotionmotion-graphicsmultimodalopenmotionreverse-engineeringvideo-editingvideo-generationworkbuddy
feat(tracking): add opt-in shared MCP and Studio event reporting
罗高0eacccd5ca27
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.ymlindex d8a9d77f..a1602995 100644--- a/.github/workflows/ci.yml+++ b/.github/workflows/ci.yml@@ -69,6 +69,8 @@ jobs:npm run checknpm run typecheck:studionpm run build:studio+ npm run build:tracking+ node --experimental-strip-types --test tests/tracking.test.ts- name: Validate standalone installation and packagingrun: node --experimental-strip-types --test tests/install.test.ts tests/npm-installer.test.ts tests/npm-package.test.ts tests/test-package.test.ts tests/source-install.test.ts tests/bootstrap.test.ts tests/mcp-registry.test.ts tests/phase1.test.ts tests/adapters.test.ts tests/package.test.ts tests/recreate-measure.test.ts tests/workflow.test.ts tests/catalog.test.ts tests/prism-templates.test.ts tests/extension-boundary.test.ts tests/connections.test.ts- name: Studio regressiondiff --git a/docs/product/architecture.md b/docs/product/architecture.mdindex 5fdf5549..198da0f5 100644--- a/docs/product/architecture.md+++ b/docs/product/architecture.md@@ -163,7 +163,9 @@ flowchart LR当前交付标准:连接可验证、模板可定位、工程可继续编辑、预览与源文件一致、导出存在真实文件、检查结果有证据。相关实现由 `tests/`、`npm run test:studio` 的原生单元/DOM 与宿主回归、类型检查、设计检查和按需浏览器验证覆盖;没有执行的检查不能记为通过。-以下是待建立的产品衡量口径,尚无仓库内用户分析系统或统计基线:+The runtime now includes an opt-in, explicit-event tracking package shared by MCP and Studio. Studio submits allowlisted events to the local service; Node enriches them with a persisted random installation identity before asynchronous PostHog ingestion. The implementation covers tool results, selected domain operations and selected Studio interactions. It does not establish a product analytics baseline or implement every proposed event. See [tracking configuration, privacy and coverage](../../tracking/README.md).++The following product measures still require agreed observation windows and validated evidence:| 指标 | 建议定义 | 用途 || --- | --- | --- |diff --git a/mcp.ts b/mcp.tsindex f47beca3..54dbcbd1 100644--- a/mcp.ts+++ b/mcp.ts@@ -9,13 +9,43 @@ import { workflowResources, readWorkflowResource, workflowEntryGuide } from './simport { ensureEditor, editorRequest, editorHeaders, sharedEditorEnabled } from './editor-runtime.ts';import { isMain } from './shared/entry.ts';import type { Selection } from './editor-runtime.ts';+import { createAppTracking, closeTracking, trackingError, type OmTracking } from './shared/tracking.ts';+import { uuid } from './tracking/core.ts';+import { toolNames } from './tracking/events.ts';export function mcpRegistry(profile = releaseProfile) { return createToolRegistry(profile === 'phase1' ? phase1Tools : tools, profile); }export const releaseRegistry = mcpRegistry();export const publicTools = releaseRegistry.tools;const selections = new WeakMap<WorkspaceStore, { sessionId: string; projectId: string }>();+const trackingByStore = new WeakMap<WorkspaceStore, Promise<OmTracking>>();++function trackingFor(store: WorkspaceStore) {+ let tracking = trackingByStore.get(store);+ if (!tracking) { tracking = createAppTracking(store.directory, 'mcp'); trackingByStore.set(store, tracking); }+ return tracking;+}export async function rpc(message: any, store = new WorkspaceStore(), registry = releaseRegistry, connection?: { selection: Selection }) {+ const name = message?.params?.name;+ if (message?.jsonrpc !== '2.0' || message.id === undefined || message.method !== 'tools/call'+ || registry.profile !== 'phase1' || !(toolNames as readonly unknown[]).includes(name)) return invokeRpc(message, store, registry, connection);+ const tracking = await trackingFor(store), started = performance.now(), callId = crypto.randomUUID();+ let accepted = false;+ try { validateInput(phase1Tools.find(tool => tool.name === name)!.inputSchema, message.params.arguments ?? {}); accepted = true; } catch {}+ const fields = { tool_name: name as typeof toolNames[number], call_id: callId, accepted,+ ...(uuid.test(message.params.arguments?.requestId) ? { operation_id: message.params.arguments.requestId } : {}) };+ if (accepted) tracking.track('mcp_tool_started', fields);+ const response = await invokeRpc(message, store, registry, connection);+ const value = (response as any)?.result;+ const content = value?.structuredContent;+ const outcome = value?.isError || content?.status === 'failed' ? 'failure' : content?.status === 'partial' ? 'partial' : value ? 'success' : 'unknown';+ tracking.track('mcp_tool_finished', { ...fields, outcome, duration_ms: Math.min(86_400_000, Math.round(performance.now() - started)),+ ...(value?.isError ? { error_code: trackingError(new Error(String(content?.error?.code ?? 'TOOL_FAILED'))) } : {}),+ ...(typeof content?.replayed === 'boolean' ? { replayed: content.replayed } : {}) });+ return response;+}++async function invokeRpc(message: any, store: WorkspaceStore, registry: ReturnType<typeof mcpRegistry>, connection?: { selection: Selection }) {if (!message || message.jsonrpc !== '2.0' || typeof message.method !== 'string') return { jsonrpc: '2.0', id: message?.id ?? null, error: { code: -32600, message: 'Invalid request' } };if (message.id === undefined) return null;const result = (value: unknown) => ({ jsonrpc: '2.0', id: message.id, result: value });@@ -72,4 +102,5 @@ if (isMain(import.meta.url)) {catch { response = { jsonrpc: '2.0', id: null, error: { code: -32700, message: 'Parse error' } }; }if (response) process.stdout.write(JSON.stringify(response) + '\n');}+ await closeTracking(await trackingByStore.get(store));}diff --git a/package.json b/package.jsonindex 4a166a32..6c69b87e 100644--- a/package.json+++ b/package.json@@ -17,6 +17,7 @@"package:test": "node scripts/test-package.mjs","package:npm": "npm run build:studio && node scripts/package-npm.mjs","build:studio": "vite build --config studio/vite.config.ts",+ "build:tracking": "tsc -p tracking/tsconfig.json","typecheck:studio": "tsc -p studio/tsconfig.json","design:tokens": "node --experimental-strip-types scripts/design-tokens.ts","design:check": "node --experimental-strip-types scripts/design-check.ts",diff --git a/phase1.ts b/phase1.tsindex 25e94020..79a75b7b 100644--- a/phase1.ts+++ b/phase1.ts@@ -13,6 +13,7 @@ import { sessionPath } from './shared/workspace-url.ts';import { phase1Tools, validateInput } from './shared/phase1-tools.ts';import { atomicJson, cloneFile, fileHash, jsonFile, ProjectVersions, recoverProjectTransactions } from './phase1-versions.ts';import type { ContentVersion } from './phase1-versions.ts';+import { trackPhase1Result, type OmTracking } from './shared/tracking.ts';const metadataPath = 'motion-project.json', assetIndexPath = 'motion-assets.json';const textExtensions = new Set(['.html', '.css', '.js', '.mjs', '.json', '.svg', '.txt', '.md', '.vtt', '.srt', '.glsl', '.vert', '.frag']);@@ -31,6 +32,7 @@ export type Phase1Context = {openProject: (projectId: string) => Promise<void>;mutation: <T>(task: () => Promise<T>) => Promise<T>;cancel: (projectId: string, jobId: string) => Promise<unknown>;+ tracking?: OmTracking;};/** Thin public contract over the existing workspace, Studio history, probes and export engine. */@@ -44,6 +46,16 @@ export class Phase1Service {constructor(store: WorkspaceStore, runtimeRoot: string, context: Phase1Context) { this.store = store; this.runtimeRoot = runtimeRoot; this.context = context; }versions(projectId: string) { return new ProjectVersions(this.store.forProject(projectId), this.runtimeRoot, this.context.nativeUrl(projectId)); }async call(name: string, args: any) {+ try {+ const result = await this.invoke(name, args);+ trackPhase1Result(this.context.tracking, name, args, result);+ return result;+ } catch (error) {+ trackPhase1Result(this.context.tracking, name, args, undefined, error);+ throw error;+ }+ }+ private async invoke(name: string, args: any) {const definition = phase1Tools.find(tool => tool.name === name);if (!definition) throw new Error('MCP_TOOL_NOT_EXPOSED: ' + name);validateInput(definition.inputSchema, args);diff --git a/scripts/check.ts b/scripts/check.tsindex 80fddd33..f5350d0d 100644--- a/scripts/check.ts+++ b/scripts/check.ts@@ -42,7 +42,7 @@ export async function check() {assert.equal(mcp.mcpServers.motion.cwd, '.');assert.ok(!JSON.stringify(mcp).includes('${'), 'MCP launch paths cannot depend on placeholder expansion');assert.equal(marketplace.plugins[0].source.path, './');- for (const folder of ['web', 'shared', 'scripts', 'tests', 'gateway']) {+ for (const folder of ['web', 'shared', 'scripts', 'tests', 'gateway', 'tracking']) {for (const file of await readdir(path.join(root, folder))) {if (file.endsWith('.ts')) stripTypeScriptTypes(await readFile(path.join(root, folder, file), 'utf8'), { mode: 'strip' });}diff --git a/scripts/distribution.ts b/scripts/distribution.tsindex 7e2485fc..b092c700 100644--- a/scripts/distribution.ts+++ b/scripts/distribution.ts@@ -8,7 +8,7 @@ const root = fileURLToPath(new URL('../', import.meta.url));// New documentation and developer scripts require an explicit distribution decision.export const distributionDocuments = ['README.md', 'README.zh-CN.md', 'CONTRIBUTING.md', 'CONTRIBUTING.zh-CN.md', 'AGENTS.md', 'CLAUDE.md', 'docs/README.md',- 'docs/product/architecture.md', 'docs/product/media-generation-design.md',+ 'docs/product/architecture.md', 'docs/product/media-generation-design.md', 'tracking/README.md','docs/agent-adapters.md', 'docs/browser-runtime.md', 'docs/design-system.md', 'docs/editor-fork.md','docs/hyperframes.md', 'docs/mcp-phase1-tools.md', 'docs/model-gateway.md', 'docs/motion-director.md','docs/motion-extension-scope.md', 'docs/npm-installation.md', 'docs/project-workspace.md',@@ -32,6 +32,7 @@ export async function distributionFiles(profile: string): Promise<string[]> {'scripts/runtime-assets.mjs', 'scripts/npm-runtime.mjs', 'scripts/runtime-lock.json','scripts/verify-export.ts', 'scripts/export-adapters.ts', 'scripts/package.ts', 'scripts/distribution.ts','shared/workflow-entry.js', 'studio/LICENSE', 'studio/README.md', 'template-library/LICENSE', 'shared/editor-launch.pl',+ 'tracking/core.ts', 'tracking/node.ts', 'tracking/browser.ts', 'tracking/events.ts',];async function walk(directory: string, extensions: RegExp) {for (const entry of await readdir(path.join(root, directory), { withFileTypes: true })) {diff --git a/server.ts b/server.tsindex f7d5c2f3..7764953f 100644--- a/server.ts+++ b/server.ts@@ -24,9 +24,13 @@ import { WorkspaceBrowser } from './browser.ts';import { Phase1Service } from './phase1.ts';import { recoverProjectTransactions } from './phase1-versions.ts';import { verifyExport } from './scripts/verify-export.ts';+import { createAppTracking, closeTracking, type OmTracking } from './shared/tracking.ts';+import { browserEvents } from './tracking/events.ts';+import { validPending } from './tracking/core.ts';+import { omEvents } from './tracking/events.ts';const sharedStore = new WorkspaceStore();-export type Service = { studio?: Studio; runtimeRoot?: string; ffmpeg?: boolean; switching?: boolean; studioPort?: number; browser?: WorkspaceBrowser; editorToken?: string; ensureStudio?: (projectId?: string) => Promise<Studio>; launchStudio?: (directory: string, port: number) => Promise<Studio>; phase1?: Phase1Service; phase1Mutation?: Promise<void> };+export type Service = { studio?: Studio; runtimeRoot?: string; ffmpeg?: boolean; switching?: boolean; studioPort?: number; browser?: WorkspaceBrowser; editorToken?: string; ensureStudio?: (projectId?: string) => Promise<Studio>; launchStudio?: (directory: string, port: number) => Promise<Studio>; phase1?: Phase1Service; phase1Mutation?: Promise<void>; tracking?: OmTracking };const service: Service = {};const working = new Set<string>();const runningExports = new Map<string, AbortController>();@@ -44,7 +48,7 @@ export async function cancelExport(store: WorkspaceStore, projectId: string, job});}-export async function renderNext(store: WorkspaceStore, runtimeRoot: string) {+export async function renderNext(store: WorkspaceStore, runtimeRoot: string, tracking?: OmTracking) {const pending = await store.job();if (pending?.projectId) store = store.forProject(pending.projectId);const key = store.directory;@@ -93,6 +97,15 @@ export async function renderNext(store: WorkspaceStore, runtimeRoot: string) {const current = await store.job(job.id);if (current && ['running', 'cancelling'].includes(current.state)) await store.finishExport(job.id, job.token!, error instanceof Error ? error.message : '渲染失败');} finally {+ if (job && tracking) {+ const final = await store.job(job.id).catch(() => null);+ if (final && ['completed', 'failed', 'cancelled'].includes(final.state)) tracking.track('export_result', {+ job_id: final.id, job_state: final.state as 'completed' | 'failed' | 'cancelled',+ duration_ms: Math.min(86_400_000, Math.max(0, Date.now() - final.createdAt)),+ technical_check: (final.verification as any)?.status === 'passed' ? 'passed'+ : (final.verification as any)?.status === 'failed' ? 'failed' : 'unknown',+ }, undefined, 'worker');+ }if (job) runningExports.delete(job.id);if (job) await rm(store.snapshotDirectory(job.id), { recursive: true, force: true });working.delete(key);@@ -102,12 +115,12 @@ export async function renderNext(store: WorkspaceStore, runtimeRoot: string) {function json(res: ServerResponse, status: number, data: unknown) {res.writeHead(status, { 'Content-Type': 'application/json; charset=utf-8' }); res.end(JSON.stringify(data));}-async function input(req: IncomingMessage) {+async function input(req: IncomingMessage, maxBytes = 9 * 1024 * 1024) {if (!req.headers['content-type']?.startsWith('application/json')) throw new Error('需要 application/json');let size = 0; const chunks: Buffer[] = [];for await (const chunk of req) {size += chunk.length;- if (size > 9 * 1024 * 1024) throw new Error('提交内容超过大小限制');+ if (size > maxBytes) throw new Error('提交内容超过大小限制');chunks.push(chunk);}return JSON.parse(Buffer.concat(chunks).toString());@@ -238,6 +251,16 @@ export async function handler(req: IncomingMessage, res: ServerResponse, store =}if (motionRequest) url.pathname = url.pathname.replace(/^\/(?:motion|design)-api\//, '/api/');const editorUrl = `http://${host || 'localhost'}/#project/${store.projectId}`;+ if (motionRequest && url.pathname === '/api/tracking' && req.method === 'GET') return json(res, 200, { enabled: context.tracking?.enabled() ?? false });+ if (motionRequest && url.pathname === '/api/tracking' && req.method === 'POST') {+ if (!context.tracking?.enabled()) return json(res, 200, { accepted: 0 });+ const data = await input(req, 64 * 1024);+ if (!data || Object.keys(data).length !== 1 || !Array.isArray(data.events) || data.events.length > 16+ || !data.events.every((event: unknown) => validPending(omEvents, event) && event.entrypoint === 'studio'+ && (browserEvents as readonly string[]).includes(event.event))) return json(res, 400, { error: 'INVALID_TRACKING_BATCH' });+ const statuses = data.events.map((event: unknown) => context.tracking!.ingest(event));+ return json(res, statuses.includes('full') ? 429 : 200, { accepted: statuses.filter((status: string) => status === 'queued').length });+ }if (motionRequest && url.pathname === '/api/phase1/call' && req.method === 'POST') {if (!context.runtimeRoot) throw new Error('RUNTIME_NOT_READY');const authority = store.workspaceStore ?? store;@@ -251,6 +274,7 @@ export async function handler(req: IncomingMessage, res: ServerResponse, store =try { return await task(); } finally { release(); context.phase1Mutation = undefined; }},cancel: (projectId, jobId) => cancelExport(authority, projectId, jobId),+ tracking: context.tracking,});const data = await input(req);try { return json(res, 200, await context.phase1.call(data.name, data.arguments ?? {})); }@@ -441,7 +465,8 @@ export async function startServer(store = sharedStore, port = Number(process.envconst runtimeRoot = await ensureRuntime(store.directory);await recoverProjectTransactions(store, runtimeRoot);const ffmpeg = await execute(process.env.HYPERFRAMES_FFMPEG_PATH || process.env.FFMPEG_PATH || 'ffmpeg', ['-version'], pluginRoot, 5000).then(r => r.code === 0, () => false);- const context: Service = { runtimeRoot, ffmpeg, studioPort: !port || port === 65535 ? 4174 : port + 1, editorToken: options.editorToken };+ const context: Service = { runtimeRoot, ffmpeg, studioPort: !port || port === 65535 ? 4174 : port + 1, editorToken: options.editorToken,+ tracking: await createAppTracking(store.directory, 'mcp') };context.launchStudio = async (directory, chosenPort) => {if (!process.env.OPENMOTION_EDITOR_LOCK_FD) return startStudio(runtimeRoot, directory, path.join(store.directory, 'studio.log'), chosenPort, store.directory);const probe = createServer();@@ -470,16 +495,16 @@ export async function startServer(store = sharedStore, port = Number(process.envconst server = createServer((req, res) => { void (async () => { if (!options.privateHandler || !await options.privateHandler(req, res)) await handler(req, res, store, context); })().catch(error => { if (!res.headersSent) json(res, 500, { error: (error as Error).message }); else res.destroy(); }); });try {await new Promise<void>((resolve, reject) => { server.once('error', reject); server.listen(port, '127.0.0.1', resolve); });- } catch (error) { await context.studio?.close(); throw error; }+ } catch (error) { context.tracking?.close(); await context.studio?.close(); throw error; }const gateway = gatewayFor(store);const tick = () => {- void renderNext(store, runtimeRoot).catch(error => console.error(error.message));+ void renderNext(store, runtimeRoot, context.tracking).catch(error => console.error(error.message));void gateway.tick().catch(() => console.error('Model gateway queue could not be processed'));};const timer = setInterval(tick, 500); tick();return { server, get activeToolCalls() { return context.phase1?.pending ?? 0; }, openProject: async (projectId: string) => openProject(store, context, (await store.get()).revision, { projectId }, store.projectId), get studio() { return context.studio!; }, ensureStudio: context.ensureStudio,info: async () => ({ previewUrl: `http://127.0.0.1:${(server.address() as any).port}`, studioUrl: context.studio?.url, engine: 'hyperframes', ready: true, editorReady: Boolean(context.studio?.alive()), ffmpeg, revision: (await store.get()).revision, dataDirectory: store.directory, browserOpened: false, authoringGuide: path.join(runtimeRoot, 'node_modules/hyperframes/dist/skills/hyperframes/SKILL.md'), hyperframesCli: cliPath(runtimeRoot) }),- close: async () => { clearInterval(timer); await context.browser?.close(); await gateway.close(); server.closeAllConnections(); server.close(); await context.studio?.close(); } };+ close: async () => { clearInterval(timer); await context.browser?.close(); await gateway.close(); server.closeAllConnections(); server.close(); await context.studio?.close(); await closeTracking(context.tracking); } };}if (isMain(import.meta.url)) {try {diff --git a/shared/tracking.ts b/shared/tracking.tsnew file mode 100644index 00000000..f34ff31c--- /dev/null+++ b/shared/tracking.ts@@ -0,0 +1,61 @@+import path from 'node:path';+import { createTracker, uuid } from '../tracking/core.ts';+import type { Entry } from '../tracking/core.ts';+import { createNodeTracking, loadIdentity } from '../tracking/node.ts';+import { omEvents } from '../tracking/events.ts';+import { VERSION } from '../preview.ts';++export type OmTracking = ReturnType<typeof createTracker<typeof omEvents>>;++export async function createAppTracking(directory: string, entrypoint: Entry): Promise<OmTracking> {+ const disabled = () => createTracker({ registry: omEvents, entrypoint, enabled: false, send: async () => 'drop' });+ if (process.env.OPENMOTION_TELEMETRY !== '1' || process.env.DO_NOT_TRACK === '1'+ || !process.env.OPENMOTION_POSTHOG_KEY || !process.env.OPENMOTION_POSTHOG_HOST) return disabled();+ try {+ const env = process.env.OPENMOTION_TRACKING_ENV ?? 'production';+ if (!['development', 'test', 'production'].includes(env)) return disabled();+ return createNodeTracking({ registry: omEvents, entrypoint, enabled: true,+ identity: await loadIdentity(path.join(directory, 'tracking')), appVersion: VERSION,+ host: process.env.OPENMOTION_POSTHOG_HOST, token: process.env.OPENMOTION_POSTHOG_KEY,+ env: env as 'development' | 'test' | 'production', testRunId: process.env.OPENMOTION_TRACKING_TEST_RUN_ID });+ } catch { return disabled(); }+}++export async function closeTracking(tracking?: OmTracking) {+ if (!tracking) return;+ let timer: ReturnType<typeof setTimeout> | undefined;+ try {+ await Promise.race([+ (async () => { while (tracking.pending()) { if (await tracking.flush() !== 'accepted') break; } })(),+ new Promise<void>(resolve => { timer = setTimeout(resolve, 2000); }),+ ]);+ } finally { if (timer) clearTimeout(timer); tracking.close(); }+}++const errorCodes = new Set(['INVALID_ARGUMENT', 'VERSION_CONFLICT', 'PROJECT_NOT_BOUND', 'PROJECT_NOT_FOUND',+ 'PROJECT_SESSION_MISMATCH', 'REQUEST_ID_CONFLICT', 'REQUEST_STATE_UNKNOWN', 'MCP_TOOL_NOT_EXPOSED',+ 'EXPORT_BUSY', 'EXPORT_NOT_FOUND', 'EXPORT_NOT_COMPLETED', 'TEMPLATE_NOT_FOUND', 'TEMPLATE_NOT_EDITABLE',+ 'SOURCE_BATCH_TOO_LARGE', 'INVALID_FILE_TYPE_OR_RESERVED_PATH', 'PROJECT_VALIDATION_FAILED', 'VERSION_NOT_FOUND']);+export function trackingError(error: unknown) {+ const code = error instanceof Error ? /^([A-Z_]+)(?::|$)/.exec(error.message)?.[1] : undefined;+ return code && errorCodes.has(code) ? code : 'TOOL_FAILED';+}++/** Business results follow committed domain operations, separately from transport results. */+export function trackPhase1Result(tracking: OmTracking | undefined, name: string, args: any, result: any, error?: unknown) {+ if (!tracking || args?.action === 'record_review' || result?.replayed) return;+ const outcome = error ? 'failure' : result?.status === 'partial' ? 'partial' : result?.status === 'failed' ? 'failure' : 'success';+ const fields = { outcome, ...(uuid.test(result?.projectId) ? { project_id: result.projectId } : {}),+ ...(uuid.test(args?.requestId) ? { operation_id: args.requestId } : {}), ...(error ? { error_code: trackingError(error) } : {}) } as const;+ if (name === 'motion_create_project') tracking.track('project_create_result', { ...fields, effect_status: error ? 'unknown' : 'applied' });+ if (name === 'motion_open_preview') tracking.track('project_open_result', { ...fields, opened_by_host_status: 'unknown' });+ if (name === 'motion_edit_project') tracking.track('project_edit_result', { ...fields,+ ...(!error && Array.isArray(result?.changedFiles) ? { changed_file_count: result.changedFiles.length } : {}) });+ if (name === 'motion_restore_version') tracking.track('version_restore_result', fields);+ if (name === 'motion_import_assets') tracking.track('asset_import_result', { ...fields,+ ...(Array.isArray(args?.items) ? { requested_count: args.items.length } : {}) });+ if (name === 'motion_export_request') tracking.track('export_request_result', { ...fields,+ ...(uuid.test(result?.job?.id) ? { job_id: result.job.id, queue_state: result.job.state } : {}) });+ if (name === 'motion_export_cancel') tracking.track('export_cancel_result', { ...fields,+ ...(uuid.test(result?.job?.id) ? { job_id: result.job.id, state_after: result.job.state } : {}) });+}diff --git a/studio/src/motion/HomeTemplates.tsx b/studio/src/motion/HomeTemplates.tsxindex f120b0a6..df9445ac 100644--- a/studio/src/motion/HomeTemplates.tsx+++ b/studio/src/motion/HomeTemplates.tsx@@ -5,6 +5,7 @@ import { useI18n } from '../i18n/I18n';import { MotionIcon } from './icons';import { motionApi } from './useWorkspace';import { useWorkspaceChrome } from './WorkspaceFrame';+import { trackMotion } from './tracking';const categories = [['builtin', 'Ready to edit'], ['featured', 'Featured references'], ['ads', 'Product promos'],@@ -63,17 +64,23 @@ export function HomeTemplates({ onSelect }: { onSelect?: (template: GalleryTempl}async function copy(template: GalleryTemplate) {setFeedback(''); setManualCopy('');+ void trackMotion('ui_click', { page_name: 'studio', area: 'templates', element: 'copy_template' });try {const connection = info ?? await motionApi<IntegrationInfo>('/integration');setInfo(connection);const prompt = templatePrompt(connection, host, template);try {await navigator.clipboard.writeText(prompt);+ void trackMotion('template_instruction_copy_result', { host_product: host, copy_status: 'clipboard_written' });setFeedback(t('Copied. Send it to {agent} to recreate this template.', { agent: hostNames[host] }));} catch {+ void trackMotion('template_instruction_copy_result', { host_product: host, copy_status: 'manual_fallback_shown' });setManualCopy(prompt); setFeedback(t('Copy the instruction below and send it to your Agent.'));}- } catch (err) { setFeedback((err as Error).message); }+ } catch (err) {+ void trackMotion('template_instruction_copy_result', { host_product: host, copy_status: 'failed' });+ setFeedback((err as Error).message);+ }}function action(template: GalleryTemplate) {if (onSelect) { if (!switchingDisabled) { setPreview(null); onSelect(template); } return; }diff --git a/studio/src/motion/MotionApp.tsx b/studio/src/motion/MotionApp.tsxindex f1722598..81a94cb2 100644--- a/studio/src/motion/MotionApp.tsx+++ b/studio/src/motion/MotionApp.tsx@@ -1,4 +1,4 @@-import { useEffect, useState } from 'react';+import { useEffect, useRef, useState } from 'react';import { useI18n } from '../i18n/I18n';import { WorkspaceFrame } from './WorkspaceFrame';import { MotionHome } from './MotionHome';@@ -7,6 +7,7 @@ import { requestedProject, validWorkspaceProject } from './workspaceRouting';import { MotionSessionFrame } from './MotionSessionFrame';import type { SessionDetail, SessionArtifact } from '../../../shared/session';import { ArtifactViewer } from './ArtifactViewer';+import { trackMotion } from './tracking';const noPendingSaves = async () => {};@@ -26,6 +27,16 @@ export function MotionApp() {const [ready, setReady] = useState<{ sessionId: string; artifact?: SessionArtifact } | null>(null);const [error, setError] = useState('');const [attempt, retry] = useState(0);+ const view = useRef({ id: crypto.randomUUID(), started: performance.now(), sent: false });+ useEffect(() => {+ const home = projectId === null && sessionId === null;+ if (view.current.sent || (!home && !ready && !error)) return;+ view.current.sent = true;+ const embedded = new URLSearchParams(location.search).get('embed') === '1';+ if (home || ready) void trackMotion('page_view', { page_name: home ? 'home' : 'studio', view_id: view.current.id, embedded, has_project: Boolean(ready?.artifact) });+ if (!home && error) void trackMotion('studio_load_result', { load_id: view.current.id, outcome: 'failure', embedded,+ duration_ms: Math.min(86_400_000, Math.round(performance.now() - view.current.started)) });+ }, [projectId, sessionId, ready, error]);useEffect(() => {if (projectId === null && sessionId === null) return;const controller = new AbortController();diff --git a/studio/src/motion/MotionHome.tsx b/studio/src/motion/MotionHome.tsxindex 41b6d547..ac88ca1f 100644--- a/studio/src/motion/MotionHome.tsx+++ b/studio/src/motion/MotionHome.tsx@@ -5,6 +5,7 @@ import { MotionIcon } from './icons';import { useWorkspaceChrome, WorkspaceMenuButton } from './WorkspaceFrame';import { HomeComposer } from './ProjectConversation';import type { GalleryTemplate } from '../../../shared/catalog';+import { trackMotion, flushMotionTracking } from './tracking';export function MotionHome() {const { t, formatDate } = useI18n();@@ -15,7 +16,10 @@ export function MotionHome() {return <div className="motion-home"><div className="motion-home-navigation"><WorkspaceMenuButton /></div><main className="motion-home-scroll"><div className="motion-home-inner">- <button className="motion-create-project" disabled={switchingDisabled} onClick={() => void workspace.startSession()}>+ <button className="motion-create-project" disabled={switchingDisabled} onClick={() => {+ void trackMotion('ui_click', { page_name: 'home', area: 'workspace', element: 'new_creation' });+ void workspace.startSession();+ }}><span className="motion-create-plus"><MotionIcon name="plus" size={28} /></span><strong>{t(workspace.busy ? 'Preparing project…' : 'New creation')}</strong></button>@@ -24,13 +28,19 @@ export function MotionHome() {{sessions.length > 3 && <button className="motion-button motion-button-quiet" aria-expanded={showAll} onClick={() => setShowAll(all => !all)}>{t(showAll ? 'Show less' : 'View all')}<MotionIcon name="arrow-right" size={14} /></button>}</div><div className="motion-recent-grid">- {(showAll ? sessions : sessions.slice(0, 3)).map(project => <button className="motion-recent-project" key={project.id} disabled={switchingDisabled} onClick={() => void workspace.openSession(project.id)}>+ {(showAll ? sessions : sessions.slice(0, 3)).map(project => <button className="motion-recent-project" key={project.id} disabled={switchingDisabled} onClick={() => {+ void trackMotion('ui_click', { page_name: 'home', area: 'workspace', element: 'recent_session' }).then(() => flushMotionTracking());+ void workspace.openSession(project.id);+ }}><span className="motion-project-monogram"><MotionIcon name="film" size={24} /></span><span><strong>{project.title}</strong><small>{project.openedAt || project.createdAt ? formatDate((project.openedAt || project.createdAt)!, { month: 'short', day: 'numeric' }) : t('Local project')}</small></span><MotionIcon name="arrow-up-right" /></button>)}</div>{!sessions.length && <p className="motion-home-empty">{t(workspace.status ? 'Your conversations will appear here.' : 'Loading conversations…')}</p>}</section>- <HomeTemplates onSelect={selected => { setTemplate(selected); document.getElementById('home-creative-request')?.focus(); }} />+ <HomeTemplates onSelect={selected => {+ void trackMotion('ui_click', { page_name: 'home', area: 'templates', element: 'select_template' });+ setTemplate(selected); document.getElementById('home-creative-request')?.focus();+ }} /></div></main><HomeComposer template={template} onClear={() => setTemplate(undefined)} /></div>;diff --git a/studio/src/motion/MotionStudioHost.tsx b/studio/src/motion/MotionStudioHost.tsxindex 505c174f..8bba33b4 100644--- a/studio/src/motion/MotionStudioHost.tsx+++ b/studio/src/motion/MotionStudioHost.tsx@@ -1,6 +1,6 @@import { StudioErrorBoundary } from '../components/StudioErrorBoundary';import { I18nProvider, useI18n } from "../i18n/I18n";-import { useEffect, useState, type ReactNode } from 'react';+import { useEffect, useRef, useState, type ReactNode } from 'react';import { useStudioShellContext } from '../contexts/StudioContext';import { Dock } from '../components/dock/Dock';import { useDockLayoutStore } from '../components/dock/dockLayoutStore';@@ -14,6 +14,7 @@ import { MotionHistoryPanel } from './MotionHistoryPanel';import { MotionHistoryProvider, useMotionHistoryOperation } from './MotionHistoryState';import { MediaGatewayProvider, useMediaGateway } from './MediaGatewayContext';import { workspacePresentation } from '../../../shared/workspace-url';+import { trackMotion } from './tracking';export function MotionEditorFrame({ children }: { children: ReactNode }) {const { t } = useI18n();@@ -22,6 +23,13 @@ export function MotionEditorFrame({ children }: { children: ReactNode }) {const chrome = useOptionalWorkspaceChrome();const register = chrome?.registerEditor;const [saving, setSaving] = useState(isStudioEditSaving);+ const load = useRef({ id: crypto.randomUUID(), sent: false });+ useEffect(() => {+ if (load.current.sent) return;+ load.current.sent = true;+ void trackMotion('studio_load_result', { load_id: load.current.id, outcome: 'success',+ embedded: workspacePresentation(location.search).embedded, duration_ms: Math.min(86_400_000, Math.round(performance.now())) });+ }, []);useEffect(() => {const timer = window.setInterval(() => setSaving(isStudioEditSaving()), 250);return () => clearInterval(timer);diff --git a/studio/src/motion/tracking.test.ts b/studio/src/motion/tracking.test.tsnew file mode 100644index 00000000..c58d45ae--- /dev/null+++ b/studio/src/motion/tracking.test.ts@@ -0,0 +1,36 @@+// @vitest-environment happy-dom+import { afterEach, expect, it, vi } from 'vitest';++afterEach(() => { vi.unstubAllGlobals(); vi.restoreAllMocks(); vi.resetModules(); });++it('keeps the project token out of browser packets and sends only explicitly invoked events', async () => {+ const requests: Array<{ url: string; body?: string }> = [];+ vi.stubGlobal('fetch', vi.fn(async (url: string, init?: RequestInit) => {+ requests.push({ url, body: init?.body as string | undefined });+ return new Response(JSON.stringify({ enabled: true }));+ }));+ const tracking = await import('./tracking');+ await tracking.initializeTracking();+ expect(requests).toHaveLength(1);+ document.body.click(); await tracking.flushMotionTracking(); expect(requests).toHaveLength(1);+ await tracking.trackMotion('ui_click', { page_name: 'home', area: 'workspace', element: 'new_creation' });+ await tracking.flushMotionTracking();+ expect(requests).toHaveLength(2);+ const payload = JSON.parse(requests[1].body!);+ expect(payload.events[0].entrypoint).toBe('studio');+ expect(JSON.stringify(payload)).not.toMatch(/api_key|installation_id|distinct_id|utm_source|phc_/);+});++it('honors both local disablement and browser Do Not Track', async () => {+ for (const [enabled, dnt] of [[false, '0'], [true, '1']] as const) {+ vi.resetModules();+ Object.defineProperty(navigator, 'doNotTrack', { value: dnt, configurable: true });+ const fetcher = vi.fn(async () => new Response(JSON.stringify({ enabled })));+ vi.stubGlobal('fetch', fetcher);+ const tracking = await import('./tracking');+ await tracking.trackMotion('ui_click', { page_name: 'home', area: 'workspace', element: 'new_creation' });+ await tracking.flushMotionTracking();+ expect(fetcher).toHaveBeenCalledTimes(1);+ }+ Reflect.deleteProperty(navigator, 'doNotTrack');+});diff --git a/studio/src/motion/tracking.ts b/studio/src/motion/tracking.tsnew file mode 100644index 00000000..13da4350--- /dev/null+++ b/studio/src/motion/tracking.ts@@ -0,0 +1,22 @@+import { createBrowserTracking } from '../../../tracking/browser.ts';+import { omEvents } from '../../../tracking/events.ts';+import type { EventFields } from '../../../tracking/core.ts';++const tracking = createBrowserTracking({ registry: omEvents, endpoint: '/motion-api/tracking', enabled: false });+let initialization: Promise<void> | undefined;+export function initializeTracking() {+ initialization ??= fetch('/motion-api/tracking', { signal: AbortSignal.timeout(1000) }).then(async response => {+ if (!response.ok) return;+ const config = await response.json();+ tracking.setEnabled(config.enabled === true && navigator.doNotTrack !== '1');+ }).catch(() => {});+ return initialization;+}+export async function trackMotion<E extends keyof typeof omEvents>(event: E, properties: EventFields<typeof omEvents[E]>) {+ await initializeTracking();+ tracking.track(event, properties);+}+export function flushMotionTracking() { return tracking.flush(); }++window.addEventListener('pagehide', () => { void tracking.flush(); });+document.addEventListener('visibilitychange', () => { if (document.visibilityState === 'hidden') void tracking.flush(); });diff --git a/studio/tsconfig.json b/studio/tsconfig.jsonindex 4ddd1ecd..ac2e418f 100644--- a/studio/tsconfig.json+++ b/studio/tsconfig.json@@ -19,6 +19,7 @@],"allowJs": true,"noEmit": true,+ "allowImportingTsExtensions": true,"resolveJsonModule": true,"isolatedModules": true},diff --git a/tests/http.ts b/tests/http.tsindex 9a9d4f55..5c269582 100644--- a/tests/http.ts+++ b/tests/http.ts@@ -1,7 +1,7 @@import { Readable, Writable } from 'node:stream';import { finished } from 'node:stream/promises';import type { IncomingMessage, ServerResponse } from 'node:http';-import { handler } from '../server.ts';+import { handler, type Service } from '../server.ts';import type { WorkspaceStore } from '../workspace.ts';class Capture extends Writable {@@ -12,14 +12,14 @@ class Capture extends Writable {_write(chunk: Buffer, _: string, done: () => void) { this.chunks.push(Buffer.from(chunk)); done(); }}// Runs the real HTTP request handler with streams, without binding a socket.-export function transport(store: WorkspaceStore): (url: string, init?: RequestInit) => Promise<Response> {+export function transport(store: WorkspaceStore, context?: Service): (url: string, init?: RequestInit) => Promise<Response> {return async (url, init = {}) => {const headers = Object.fromEntries(new Headers(init.headers));headers.host = 'localhost:4173'; headers.origin = 'http://localhost:4173';const input = typeof init.body === 'string' ? Buffer.from(init.body) : init.body instanceof Blob ? Buffer.from(await init.body.arrayBuffer()) : Buffer.alloc(0);const req = Object.assign(Readable.from([input]), { url, method: init.method || 'GET', headers });const res = new Capture(); const complete = finished(res);- await handler(req as unknown as IncomingMessage, res as unknown as ServerResponse, store);+ await handler(req as unknown as IncomingMessage, res as unknown as ServerResponse, store, context);await complete;return new Response(Buffer.concat(res.chunks), { status: res.statusCode, headers: res.headers });};diff --git a/tests/tracking.test.ts b/tests/tracking.test.tsnew file mode 100644index 00000000..8870e822--- /dev/null+++ b/tests/tracking.test.ts@@ -0,0 +1,153 @@+import test from 'node:test';+import assert from 'node:assert/strict';+import { readFile, readdir, writeFile } from 'node:fs/promises';+import path from 'node:path';+import { createTracker, deviceContext } from '../tracking/core.ts';+import { createPosthogSender, loadIdentity } from '../tracking/node.ts';+import { omEvents } from '../tracking/events.ts';+import { closeTracking, createAppTracking, trackingError } from '../shared/tracking.ts';+import { Phase1Service } from '../phase1.ts';+import { renderNext } from '../server.ts';+import { pluginRoot } from '../hyperframes.ts';+import { fixture } from './fixtures.ts';+import { phase1Tools } from '../shared/phase1-tools.ts';+import { toolNames } from '../tracking/events.ts';+import { transport } from './http.ts';+import type { PendingEvent } from '../tracking/core.ts';++function packet(): PendingEvent {+ return { event: 'ui_click', event_id: crypto.randomUUID(), occurred_at: new Date().toISOString(), entrypoint: 'studio',+ ...deviceContext(), properties: { page_name: 'home', area: 'workspace', element: 'new_creation' } };+}+const core = (send: Parameters<typeof createTracker>[0]['send'], maxQueue = 64) =>+ createTracker({ registry: omEvents, entrypoint: 'mcp', enabled: true, flushIntervalMs: 0, maxQueue, send });++test('bounded queue rejects private properties, preserves UUID/time on retries and serializes flushes', async () => {+ const batches: PendingEvent[][] = []; let attempts = 0;+ const tracker = core(async events => { batches.push(structuredClone([...events])); return ++attempts === 1 ? 'retry' : 'accepted'; }, 2);+ const event = packet();+ assert.equal(tracker.ingest({ ...event, properties: { ...event.properties, prompt: 'private text' } }), 'invalid');+ assert.equal(tracker.ingest({ ...event, device_id: crypto.randomUUID() }), 'invalid');+ assert.equal(tracker.ingest({ ...event, occurred_at: 123 }), 'invalid');+ assert.equal(tracker.ingest({ ...event, device_timezone: 'not/a/timezone' }), 'invalid');+ assert.equal(tracker.ingest(event), 'queued');+ assert.equal(tracker.ingest(event), 'duplicate');+ assert.equal(tracker.ingest(packet()), 'queued');+ assert.equal(tracker.ingest(packet()), 'full');+ const first = tracker.flush(); assert.equal(tracker.flush(), first);+ assert.equal(await first, 'retry'); assert.equal(tracker.pending(), 2);+ assert.equal(await tracker.flush(), 'accepted'); assert.deepEqual(batches[0], batches[1]);+ assert.equal(tracker.pending(), 0); tracker.close();+});++test('opting out aborts the in-flight request, erases the queue and prevents later reports', async () => {+ let aborted = false, sends = 0;+ const tracker = core(async (_events, signal) => { sends++; return new Promise(resolve => {+ signal.addEventListener('abort', () => { aborted = true; resolve('retry'); }, { once: true });+ }); });+ tracker.ingest(packet()); const pending = tracker.flush(); tracker.setEnabled(false);+ assert.equal(await pending, 'disabled'); assert.equal(aborted, true); assert.equal(tracker.pending(), 0);+ assert.equal(tracker.ingest(packet()), 'disabled'); assert.equal(await tracker.flush(), 'disabled'); assert.equal(sends, 1);+});++test('concurrent identity creation has one winner, keeps its first source and fails closed on corruption', () => fixture(async store => {+ const directory = path.join(store.directory, 'tracking');+ const identities = await Promise.all(Array.from({ length: 20 }, () => loadIdentity(directory, 'alice')));+ assert.equal(new Set(identities.map(value => value.installation_id)).size, 1);+ assert.equal((await loadIdentity(directory, 'bob')).utm_source, 'alice');+ assert.deepEqual(await readdir(directory), ['identity.json']);+ await writeFile(path.join(directory, 'identity.json'), JSON.stringify({ installation_id: identities[0].installation_id, created_at: identities[0].created_at }));+ await assert.rejects(loadIdentity(directory), /INVALID_IDENTITY/);+ await writeFile(path.join(directory, 'identity.json'), '{}');+ await assert.rejects(loadIdentity(directory), /INVALID_IDENTITY/);+ await assert.rejects(loadIdentity(directory, 'https://private.example'), /INVALID_SOURCE/);+}, false));++test('PostHog adapter uses public ingest only, privacy fields and real receipt semantics', async () => {+ const identity = { installation_id: crypto.randomUUID(), utm_source: 'alice', created_at: new Date().toISOString() };+ const options = { identity, appVersion: '0.0.0-test', env: 'test' as const, host: 'https://us.i.posthog.com', token: 'phc_test' };+ assert.throws(() => createPosthogSender({ ...options, token: 'phx_private' }), /PUBLIC_PROJECT/);+ assert.throws(() => createPosthogSender({ ...options, host: 'http://example.com' }), /INVALID_INGEST/);+ assert.throws(() => createPosthogSender({ ...options, host: 'https://user:[email protected]' }), /INVALID_INGEST/);+ const event = packet(); const seen: any[] = []; let response = new Response('{"status":1}');+ const sender = createPosthogSender({ ...options, fetch: async (url, init) => {+ assert.equal(String(url), 'https://us.i.posthog.com/batch/'); seen.push(JSON.parse(String(init?.body))); return response;+ } });+ assert.equal(await sender([event], new AbortController().signal), 'accepted');+ const data = seen[0].batch[0];+ assert.equal(data.uuid, event.event_id); assert.equal(data.timestamp, event.occurred_at);+ assert.equal(data.properties.distinct_id, identity.installation_id); assert.equal(data.properties.device_id, identity.installation_id);+ assert.equal(data.properties.utm_source, 'alice'); assert.equal(data.properties.event_schema_version, 1);+ assert.equal(data.properties.$ip, '0.0.0.0'); assert.equal(data.properties.$geoip_disable, true);+ assert.equal(data.properties.$process_person_profile, false);+ response = new Response('{"status":"Ok"}'); assert.equal(await sender([event], new AbortController().signal), 'accepted');+ response = new Response('{"status":1,"quota_limited":["events"]}'); assert.equal(await sender([event], new AbortController().signal), 'retry');+ response = new Response('{}', { status: 429 }); assert.equal(await sender([event], new AbortController().signal), 'retry');+ response = new Response('{}', { status: 400 }); assert.equal(await sender([event], new AbortController().signal), 'drop');+ response = new Response('not json'); assert.equal(await sender([event], new AbortController().signal), 'retry');+ assert.equal(trackingError(new Error('private user prompt and /local/path')), 'TOOL_FAILED');+});++test('browser ingress rejects forged identity, worker events and oversized batches', () => fixture(async store => {+ const events: PendingEvent[] = [], tracking = core(async batch => { events.push(...batch); return 'accepted'; });+ const request = transport(store, { tracking });+ const config = await (await request('/motion-api/tracking')).json(); assert.deepEqual(config, { enabled: true });+ const send = (data: unknown) => request('/motion-api/tracking', { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(data) });+ const event = packet(); assert.equal((await send({ events: [event] })).status, 200);+ assert.equal((await send({ events: [event] })).status, 200);+ for (const data of [+ { events: [{ ...packet(), properties: { ...packet().properties, distinct_id: 'forged' } }] },+ { events: [{ ...packet(), utm_source: 'forged' }] },+ { events: [{ ...packet(), entrypoint: 'worker' }] },+ { events: Array.from({ length: 17 }, packet) },+ { events: [packet()], token: 'forged' },+ ]) assert.equal((await send(data)).status, 400);+ assert.equal((await send({ events: [packet()], padding: 'x'.repeat(65536) })).status, 400);+ await tracking.flush(); assert.equal(events.length, 1); tracking.close();+ assert.equal((await send({ events: [packet()] })).status, 200); assert.equal(tracking.pending(), 0);+}, false));++test('domain events follow real commits, skip replay and retain safe failure without source contents', () => fixture(async store => {+ assert.deepEqual([...toolNames].sort(), phase1Tools.map(tool => tool.name).sort());+ const events: PendingEvent[] = [], tracking = core(async batch => { events.push(...batch); return 'accepted'; });+ const service = new Phase1Service(store, pluginRoot, { tracking, origin: () => 'http://127.0.0.1:4173',+ nativeUrl: () => undefined, openProject: async () => {}, mutation: async task => task(), cancel: async () => {} });+ const args = { requestId: crypto.randomUUID(), projectType: 'natural_language', title: 'PRIVATE_TITLE', requirements: 'PRIVATE_PROMPT' };+ const created = await service.call('motion_create_project', args);+ assert.equal((await service.call('motion_create_project', args)).replayed, true);+ const edit = { projectId: created.projectId, requestId: crypto.randomUUID(), expectedRevision: created.revision,+ expectedVersionId: created.version.versionId, files: [{ path: 'private.txt', content: 'PRIVATE_SOURCE' }] };+ await service.call('motion_edit_project', edit);+ await assert.rejects(service.call('motion_edit_project', { ...edit, requestId: crypto.randomUUID() }), /VERSION_CONFLICT/);+ await tracking.flush();+ assert.deepEqual(events.map(event => [event.event, event.properties.outcome]), [+ ['project_create_result', 'success'], ['project_edit_result', 'success'], ['project_edit_result', 'failure'],+ ]);+ assert.equal(events[2].properties.error_code, 'VERSION_CONFLICT');+ assert.doesNotMatch(JSON.stringify(events), /PRIVATE_|private\.txt/); tracking.close();+}, false));++test('missing configuration and DO_NOT_TRACK create no identity and send nothing', () => fixture(async store => {+ const before = process.env.DO_NOT_TRACK; process.env.DO_NOT_TRACK = '1';+ try {+ const tracking = await createAppTracking(store.directory, 'mcp');+ assert.equal(tracking.enabled(), false); assert.equal(tracking.ingest(packet()), 'disabled');+ await closeTracking(tracking);+ await assert.rejects(readFile(path.join(store.directory, 'tracking', 'identity.json')), /ENOENT/);+ } finally { if (before === undefined) delete process.env.DO_NOT_TRACK; else process.env.DO_NOT_TRACK = before; }+}, false));++test('worker reports a real terminal render failure once, separately from queue acceptance', () => fixture(async store => {+ const events: PendingEvent[] = [], tracking = core(async batch => { events.push(...batch); return 'accepted'; });+ const current = await store.get(), job = await store.requestExport(current.revision);+ assert.equal(job.state, 'pending'); assert.equal(tracking.pending(), 0);+ await writeFile(path.join(store.snapshotDirectory(job.id), 'index.html'), '<html><body>Invalid composition for a failure test</body></html>');+ await renderNext(store, pluginRoot, tracking);+ assert.equal((await store.job(job.id))!.state, 'failed');+ await renderNext(store, pluginRoot, tracking);+ await tracking.flush();+ assert.equal(events.length, 1); assert.equal(events[0].event, 'export_result');+ assert.equal(events[0].entrypoint, 'worker'); assert.equal(events[0].properties.job_state, 'failed');+ assert.equal((await store.get()).revision, current.revision);+ assert.equal(events[0].properties.technical_check, 'unknown'); tracking.close();+}));diff --git a/tracking/README.md b/tracking/README.mdnew file mode 100644index 00000000..b1f6a9fd--- /dev/null+++ b/tracking/README.md@@ -0,0 +1,78 @@+# OpenMotion tracking++An explicit-event package shared by the standalone MCP runtime and Motion Studio.+It has no runtime dependencies. The application consumes its TypeScript sources;+`npm run build:tracking` emits JavaScript and declarations for a local `npm pack`+from this directory. The package remains private; this change does not publish it.++## Enable reporting++Reporting is **off by default**. Configure the process launching the MCP and local+service with `OPENMOTION_TELEMETRY=1`, `OPENMOTION_POSTHOG_HOST` (the project's HTTPS+ingestion origin) and `OPENMOTION_POSTHOG_KEY` (a public `phc_` project token).+`DO_NOT_TRACK=1` overrides enablement. Restart existing local services after changing+configuration. Missing/invalid configuration fails closed and never blocks creation.++Use `OPENMOTION_TRACKING_ENV=test` and a UUID in+`OPENMOTION_TRACKING_TEST_RUN_ID` for isolated ingestion checks; filter these records+out of product dashboards. Normal environments are `production` and `development`.+Do not commit deployment keys or put personal `phx_` API keys in this package.++Studio retrieves only an enabled flag and submits semantic events to the same-origin+`/motion-api/tracking` endpoint. The server validates the complete batch, rejects+identity/source/credential overrides, and adds trusted common fields before posting+to PostHog `/batch/`. Browser Do Not Track suppresses browser collection. Network+reporting is asynchronous, with a bounded timeout; local business results never wait+for PostHog. A collector receipt confirms acceptance, not queryable ingestion.++## Identity, properties and privacy++One random UUID is persisted atomically in `tracking/identity.json` under the owned+data directory, outside projects and versioned application caches. `device_id`,+`installation_id` and PostHog `distinct_id` share that UUID. Different data directories+are separate installations. No hardware ID or fingerprint is used. The package can+initialize an identity with a validated source label; existing identities retain+their first source. Landing-page attribution and installer `--source` plumbing are+a separate change. Unknown source remains null.++Common fields include schema/product/app version, environment, entrypoint/runtime,+platform/architecture, OS/version, runtime locale, device IANA timezone and UTC offset+(east of UTC is positive). GeoIP is disabled and `$ip` is the fixed value `0.0.0.0`;+null is insufficient because ingestion can replace it with the request's IP.+The fixed value suppresses real IP storage in event properties; network intermediaries+still see the connection address. Country/region and+GeoIP timezone remain unknown until ingress geolocation and IP-discard policy are+implemented together. Device timezone is not a country inference. Person profiles,+autocapture, session replay and upstream engine telemetry are not enabled.++Runtime and TypeScript event contracts whitelist required fields, enums, UUIDs and+bounded counts. No prompts, messages, source files, URLs, local paths, titles, raw+exceptions or credentials are accepted. Safe error categories are explicitly mapped.+All retries retain the original event UUID/timestamp and PostHog `$insert_id`.++## Implemented signals and limits++- All eleven phase-one stdio tools: accepted start and observed finish, including+ early-return catalog tools, input rejection, partial import and idempotent replay.+- Domain results: create/open/edit/import/restore and export request/cancel. Replayed+ operations do not manufacture additional domain completions. Preview returned by+ a tool does not imply the host opened it.+- Worker export terminal state, after render and available technical verification;+ it is distinct from queue acceptance and does not assert human content acceptance.+- Studio home/project page readiness, editor load outcome, new/recent-session and+ template-selection intent, plus actual instruction-copy/fallback results.++This first integration does not implement the entire tracking specification:+installer/integration/resource-read events, WebMCP execution, every editor save,+timeline/history/import gesture, review/adoption and optional media events remain+outside this change. Worker origin is `worker`; request-to-worker operation context+is not yet persisted. Pending export cancellation has a cancel result but no worker+completion because no worker claimed it.++The queue is process-local: 64 events, batches of 16, one in-flight request, a one-day+TTL and retry backoff capped at one minute. Disabling aborts and drops pending data;+shutdown drains for at most two seconds. Crashes, queue overflow, page termination+or permanent collector rejection may lose events. Add durable delivery if product+decisions require guaranteed counts. Public ingest tokens are not read/admin keys,+but forged events and quota abuse still require collector-side rate limiting and+monitoring; this package is not an anti-fraud boundary.diff --git a/tracking/browser.ts b/tracking/browser.tsnew file mode 100644index 00000000..00b58f56--- /dev/null+++ b/tracking/browser.ts@@ -0,0 +1,13 @@+import { createTracker } from './core.ts';+import type { Registry } from './core.ts';+export function createBrowserTracking<const R extends Registry>(options: { endpoint: string; registry: R; enabled: boolean; flushIntervalMs?: number }) {+ const endpoint = new URL(options.endpoint, window.location.href);+ if (endpoint.origin !== window.location.origin || endpoint.username || endpoint.password) throw new Error('SAME_ORIGIN_REQUIRED');+ return createTracker({ ...options, entrypoint: 'studio', send: async (events, signal) => {+ try {+ const response = await fetch(endpoint, { method: 'POST', redirect: 'error', headers: { 'content-type': 'application/json' },+ body: JSON.stringify({ events }), keepalive: true, signal: AbortSignal.any([signal, AbortSignal.timeout(1000)]) });+ return response.ok ? 'accepted' : response.status >= 500 || response.status === 429 ? 'retry' : 'drop';+ } catch { return 'retry'; }+ } });+}diff --git a/tracking/core.ts b/tracking/core.tsnew file mode 100644index 00000000..cbfd671d--- /dev/null+++ b/tracking/core.ts@@ -0,0 +1,102 @@+export type Rule = 'uuid' | 'code' | 'boolean' | 'integer' | readonly string[];+export type Registry = Record<string, { fields: Record<string, Rule>; required: readonly string[] }>;+export type Fields = Record<string, string | number | boolean>;+type RuleValue<R> = R extends readonly string[] ? R[number] : R extends 'boolean' ? boolean : R extends 'integer' ? number : string;+export type EventFields<S extends Registry[string]> =+ { [K in S['required'][number]]: K extends keyof S['fields'] ? RuleValue<S['fields'][K]> : never } &+ { [K in Exclude<keyof S['fields'], S['required'][number]>]?: RuleValue<S['fields'][K]> };+export type Entry = 'mcp' | 'studio' | 'webmcp' | 'installer' | 'worker';+export type PendingEvent = {+ event: string; event_id: string; occurred_at: string; entrypoint: Entry;+ device_timezone: string | null; utc_offset_minutes: number; properties: Fields;+};+export type Receipt = 'accepted' | 'retry' | 'drop';+export const uuid = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;+const code = /^[A-Za-z0-9_.-]{1,128}$/;+export function deviceContext() {+ return { device_timezone: Intl.DateTimeFormat().resolvedOptions().timeZone || null,+ utc_offset_minutes: -new Date().getTimezoneOffset() };+}+export function validProperties(registry: Registry, event: string, raw: unknown): raw is Fields {+ if (!Object.hasOwn(registry, event) || !raw || typeof raw !== 'object' || Array.isArray(raw)) return false;+ const spec = registry[event], values = raw as Fields;+ if (spec.required.some(key => !Object.hasOwn(values, key))) return false;+ return Object.entries(values).every(([key, value]) => {+ if (!Object.hasOwn(spec.fields, key)) return false;+ const rule = spec.fields[key];+ if (Array.isArray(rule)) return typeof value === 'string' && rule.includes(value);+ if (rule === 'boolean') return typeof value === 'boolean';+ if (rule === 'integer') return Number.isSafeInteger(value) && Number(value) >= 0 && Number(value) <= 86_400_000;+ return typeof value === 'string' && (rule === 'uuid' ? uuid : code).test(value);+ });+}+export function validPending(registry: Registry, value: unknown): value is PendingEvent {+ if (!value || typeof value !== 'object' || Array.isArray(value)) return false;+ const e = value as PendingEvent;+ if (Object.keys(e).some(k => !['event','event_id','occurred_at','entrypoint','device_timezone','utc_offset_minutes','properties'].includes(k))) return false;+ if (typeof e.occurred_at !== 'string' || !/^\d{4}-\d\d-\d\dT\d\d:\d\d:\d\d\.\d{3}Z$/.test(e.occurred_at)) return false;+ const time = Date.parse(e.occurred_at), age = Date.now() - time;+ if (!uuid.test(e.event_id) || !Number.isFinite(time) || age < -300_000 || age > 86_400_000) return false;+ if (!['mcp','studio','webmcp','installer','worker'].includes(e.entrypoint)) return false;+ if (!Number.isInteger(e.utc_offset_minutes) || Math.abs(e.utc_offset_minutes) > 840) return false;+ if (e.device_timezone !== null) {+ if (typeof e.device_timezone !== 'string' || e.device_timezone.length > 64) return false;+ try { new Intl.DateTimeFormat('en', { timeZone: e.device_timezone }); } catch { return false; }+ }+ return validProperties(registry, e.event, e.properties) && JSON.stringify(e).length <= 4096;+}++export function createTracker<const R extends Registry>(options: {+ registry: R; entrypoint: Entry; enabled: boolean;+ send: (events: readonly PendingEvent[], signal: AbortSignal) => Promise<Receipt>;+ maxQueue?: number; flushIntervalMs?: number;+}) {+ let enabled = options.enabled, queue: PendingEvent[] = [], timer: ReturnType<typeof setTimeout> | undefined;+ let inFlight: Promise<Receipt | 'disabled' | 'empty'> | undefined, controller: AbortController | undefined;+ const seen = new Set<string>(), maxQueue = options.maxQueue ?? 64;+ let failures = 0;+ function schedule() {+ if (!enabled || timer || options.flushIntervalMs === 0) return;+ timer = setTimeout(() => { timer = undefined; void flush(); }, Math.min(60_000, (options.flushIntervalMs ?? 1000) * 2 ** failures));+ (timer as unknown as { unref?: () => void }).unref?.();+ }+ function ingest(raw: unknown) {+ if (!enabled) return 'disabled';+ if (!validPending(options.registry, raw)) return 'invalid';+ if (seen.has(raw.event_id)) return 'duplicate';+ if (queue.length >= maxQueue) return 'full';+ queue.push(structuredClone(raw)); seen.add(raw.event_id);+ // shortcut: process-local queue and dedup; add durable storage only if crash recovery is required.+ if (seen.size > 2048) seen.delete(seen.values().next().value!);+ schedule(); return 'queued';+ }+ function track<E extends keyof R & string>(event: E, properties: EventFields<R[E]>, eventId: string = crypto.randomUUID(), entrypoint: Entry = options.entrypoint) {+ if (!enabled) return 'disabled';+ try { return ingest({ event, properties, event_id: eventId, occurred_at: new Date().toISOString(),+ entrypoint, ...deviceContext() }); } catch { return 'invalid'; }+ }+ function setEnabled(next: boolean) {+ enabled = next;+ if (!next) { queue = []; seen.clear(); if (timer) clearTimeout(timer); timer = undefined; controller?.abort(); }+ }+ function flush(): Promise<Receipt | 'disabled' | 'empty'> {+ if (inFlight) return inFlight;+ if (!enabled) return Promise.resolve('disabled');+ if (!queue.length) return Promise.resolve('empty');+ if (timer) clearTimeout(timer); timer = undefined;+ queue = queue.filter(event => Date.now() - Date.parse(event.occurred_at) <= 86_400_000);+ if (!queue.length) return Promise.resolve('empty');+ const snapshot = queue.slice(0, 16), request = new AbortController(); controller = request;+ inFlight = (async () => {+ let receipt: Receipt;+ try { receipt = await options.send(snapshot, request.signal); } catch { receipt = 'retry'; }+ if (!enabled) return 'disabled' as const;+ failures = receipt === 'retry' ? Math.min(6, failures + 1) : 0;+ if (receipt !== 'retry') { const ids = new Set(snapshot.map(e => e.event_id)); queue = queue.filter(e => !ids.has(e.event_id)); }+ return receipt;+ })().finally(() => { inFlight = undefined; controller = undefined; if (queue.length) schedule(); });+ return inFlight;+ }+ return { track, ingest, flush, setEnabled, enabled: () => enabled, pending: () => queue.length,+ close: () => { setEnabled(false); } };+}diff --git a/tracking/events.ts b/tracking/events.tsnew file mode 100644index 00000000..34cf74bb--- /dev/null+++ b/tracking/events.ts@@ -0,0 +1,28 @@+import type { Registry } from './core.ts';++export const toolNames = ['motion_list_templates', 'motion_get_template', 'motion_create_project', 'motion_open_preview',+ 'motion_import_assets', 'motion_get_project', 'motion_edit_project', 'motion_export_request', 'motion_list_versions',+ 'motion_restore_version', 'motion_export_cancel'] as const;+const outcome = ['success', 'failure', 'partial', 'cancelled', 'unknown'] as const;+const tool = { tool_name: toolNames, call_id: 'uuid', operation_id: 'uuid', accepted: 'boolean' } as const;+const business = { outcome, project_id: 'uuid', operation_id: 'uuid', replayed: 'boolean', error_code: 'code' } as const;++export const omEvents = {+ mcp_tool_started: { fields: tool, required: ['tool_name', 'call_id', 'accepted'] },+ mcp_tool_finished: { fields: { ...tool, outcome, duration_ms: 'integer', error_code: 'code', replayed: 'boolean' },+ required: ['tool_name', 'call_id', 'accepted', 'outcome', 'duration_ms'] },+ project_create_result: { fields: { ...business, creation_route: ['natural_language', 'template', 'existing_project'], effect_status: ['applied', 'not_applied', 'unknown'] }, required: ['outcome'] },+ project_open_result: { fields: { ...business, opened_by_host_status: ['unknown', 'opened', 'not_opened'] }, required: ['outcome'] },+ project_edit_result: { fields: { ...business, changed_file_count: 'integer' }, required: ['outcome'] },+ version_restore_result: { fields: business, required: ['outcome'] },+ asset_import_result: { fields: { ...business, requested_count: 'integer', added_count: 'integer', reused_count: 'integer', failed_count: 'integer' }, required: ['outcome'] },+ export_request_result: { fields: { ...business, job_id: 'uuid', queue_state: ['pending', 'running', 'cancelling', 'cancelled', 'completed', 'failed'] }, required: ['outcome'] },+ export_cancel_result: { fields: { ...business, job_id: 'uuid', state_after: ['pending', 'running', 'cancelling', 'cancelled', 'completed', 'failed'] }, required: ['outcome'] },+ export_result: { fields: { job_id: 'uuid', job_state: ['completed', 'failed', 'cancelled'], duration_ms: 'integer', technical_check: ['passed', 'failed', 'unknown'] }, required: ['job_id', 'job_state', 'duration_ms', 'technical_check'] },+ page_view: { fields: { page_name: ['home', 'studio'], view_id: 'uuid', embedded: 'boolean', has_project: 'boolean' }, required: ['page_name', 'view_id', 'embedded', 'has_project'] },+ studio_load_result: { fields: { load_id: 'uuid', outcome, duration_ms: 'integer', embedded: 'boolean' }, required: ['load_id', 'outcome', 'duration_ms', 'embedded'] },+ ui_click: { fields: { page_name: ['home', 'studio'], area: ['workspace', 'templates'], element: ['new_creation', 'recent_session', 'select_template', 'copy_template'], interaction_method: ['pointer', 'keyboard'] }, required: ['page_name', 'area', 'element'] },+ template_instruction_copy_result: { fields: { host_product: ['codex', 'claude', 'deepseek', 'chatgpt', 'mcp'], copy_status: ['clipboard_written', 'manual_fallback_shown', 'failed'] }, required: ['host_product', 'copy_status'] },+} as const satisfies Registry;++export const browserEvents = ['page_view', 'studio_load_result', 'ui_click', 'template_instruction_copy_result'] as const;diff --git a/tracking/node.ts b/tracking/node.tsnew file mode 100644index 00000000..f74c8860--- /dev/null+++ b/tracking/node.ts@@ -0,0 +1,81 @@+import { link, mkdir, readFile, rm, writeFile } from 'node:fs/promises';+import path from 'node:path';+import os from 'node:os';+import { createTracker, uuid } from './core.ts';+import type { Entry, Registry, PendingEvent, Receipt } from './core.ts';++export type Identity = { installation_id: string; utm_source: string | null; created_at: string };+const sourcePattern = /^[A-Za-z0-9_.-]{1,64}$/;++export async function loadIdentity(directory: string, source?: string): Promise<Identity> {+ if (source !== undefined && (typeof source !== 'string' || !sourcePattern.test(source))) throw new Error('INVALID_SOURCE');+ const file = path.join(directory, 'identity.json');+ async function read(): Promise<Identity> {+ const value = JSON.parse(await readFile(file, 'utf8'));+ if (typeof value.installation_id !== 'string' || !uuid.test(value.installation_id)+ || (value.utm_source !== null && (typeof value.utm_source !== 'string' || !sourcePattern.test(value.utm_source)))+ || !Number.isFinite(Date.parse(value.created_at))) throw new Error('INVALID_IDENTITY');+ return value;+ }+ try { return await read(); } catch (error) { if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error; }+ await mkdir(directory, { recursive: true, mode: 0o700 });+ const identity: Identity = { installation_id: crypto.randomUUID(), utm_source: source ?? null, created_at: new Date().toISOString() };+ const temporary = file + '.' + crypto.randomUUID();+ try {+ await writeFile(temporary, JSON.stringify(identity), { mode: 0o600, flag: 'wx' });+ // Publish a complete file exclusively; concurrent processes read the winning identity.+ try { await link(temporary, file); }+ catch (error) { if ((error as NodeJS.ErrnoException).code !== 'EEXIST') throw error; }+ return await read();+ } finally { await rm(temporary, { force: true }); }+}++export function createPosthogSender(options: {+ host: string; token: string; identity: Identity; appVersion: string;+ env: 'development' | 'test' | 'production'; testRunId?: string; timeoutMs?: number; fetch?: typeof fetch;+}) {+ const url = new URL(options.host);+ if (url.username || url.password || url.search || url.hash || url.pathname !== '/') throw new Error('INVALID_INGEST_HOST');+ if (url.protocol !== 'https:' && !(url.protocol === 'http:' && ['127.0.0.1', '[::1]'].includes(url.hostname))) throw new Error('INVALID_INGEST_HOST');+ if (!/^phc_[A-Za-z0-9_]+$/.test(options.token)) throw new Error('PUBLIC_PROJECT_TOKEN_REQUIRED');+ if (options.testRunId && (!uuid.test(options.testRunId) || options.env !== 'test')) throw new Error('INVALID_TEST_RUN');+ return async (events: readonly PendingEvent[], signal: AbortSignal): Promise<Receipt> => {+ const batch = events.map(event => ({ event: event.event, uuid: event.event_id, timestamp: event.occurred_at,+ properties: { ...event.properties, event_schema_version: 1, schema_version: 1, product: 'openmotion',+ app_version: options.appVersion, env: options.env, channel: 'standalone',+ ...(options.testRunId ? { test_run_id: options.testRunId } : {}),+ event_id: event.event_id, $insert_id: event.event_id, occurred_at: event.occurred_at,+ installation_id: options.identity.installation_id, device_id: options.identity.installation_id,+ distinct_id: options.identity.installation_id, utm_source: options.identity.utm_source,+ entrypoint: event.entrypoint, runtime: event.entrypoint === 'studio' ? 'browser' : 'node',+ capture_source: 'explicit', client_type: event.entrypoint === 'studio' ? 'web' : 'local',+ platform: os.platform(), arch: os.arch(), $os: os.type(), $os_version: os.release(),+ locale: Intl.DateTimeFormat().resolvedOptions().locale,+ device_timezone: event.device_timezone, utc_offset_minutes: event.utc_offset_minutes,+ // Null is replaced with the request IP by ingestion; a fixed zero address prevents that fallback.+ location_source: 'unknown', $geoip_disable: true, $ip: '0.0.0.0', $process_person_profile: false } }));+ const body = JSON.stringify({ api_key: options.token, batch });+ if (Buffer.byteLength(body) > 64 * 1024) return 'drop';+ try {+ const response = await (options.fetch ?? fetch)(new URL('/batch/', url), {+ method: 'POST', redirect: 'error', headers: { 'content-type': 'application/json' }, body,+ signal: AbortSignal.any([signal, AbortSignal.timeout(options.timeoutMs ?? 1500)]) });+ if (!response.ok) return response.status === 429 || response.status >= 500 ? 'retry' : 'drop';+ const receipt = await response.json() as { status?: number | string; quota_limited?: unknown };+ const limited = receipt.quota_limited;+ const quotaLimited = Array.isArray(limited) ? limited.length > 0+ : limited && typeof limited === 'object' ? Object.keys(limited).length > 0 : !!limited;+ return (receipt.status === 1 || receipt.status === 'Ok') && !quotaLimited ? 'accepted' : 'retry';+ } catch { return 'retry'; }+ };+}++export function createNodeTracking<const R extends Registry>(options: {+ registry: R; identity: Identity; host: string; token?: string; appVersion: string;+ env: 'development' | 'test' | 'production'; testRunId?: string; entrypoint: Entry;+ enabled: boolean; timeoutMs?: number; flushIntervalMs?: number; maxQueue?: number;+}) {+ const enabled = options.enabled && !!options.token;+ const send = enabled ? createPosthogSender({ ...options, token: options.token! }) : async () => 'drop' as const;+ return createTracker({ ...options, enabled, send });+}diff --git a/tracking/package.json b/tracking/package.jsonnew file mode 100644index 00000000..b7bade41--- /dev/null+++ b/tracking/package.json@@ -0,0 +1,14 @@+{+ "name": "@openmotion/tracking",+ "version": "0.1.0",+ "private": true,+ "type": "module",+ "files": ["dist", "README.md"],+ "exports": {+ "./core": { "types": "./dist/core.d.ts", "default": "./dist/core.js" },+ "./node": { "types": "./dist/node.d.ts", "default": "./dist/node.js" },+ "./browser": { "types": "./dist/browser.d.ts", "default": "./dist/browser.js" },+ "./events": { "types": "./dist/events.d.ts", "default": "./dist/events.js" }+ },+ "engines": { "node": ">=22.18.0" }+}diff --git a/tracking/tsconfig.json b/tracking/tsconfig.jsonnew file mode 100644index 00000000..068db69f--- /dev/null+++ b/tracking/tsconfig.json@@ -0,0 +1,8 @@+{+ "compilerOptions": {+ "target": "ES2022", "module": "NodeNext", "moduleResolution": "NodeNext",+ "strict": true, "skipLibCheck": true, "declaration": true,+ "rewriteRelativeImportExtensions": true, "outDir": "dist"+ },+ "include": ["*.ts"]+}