Skip to content

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.

feat(tracking): add opt-in shared MCP and Studio event reporting

罗高0eacccd5ca27
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index d8a9d77f..a1602995 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -69,6 +69,8 @@ jobs:
npm run check
npm run typecheck:studio
npm run build:studio
+ npm run build:tracking
+ node --experimental-strip-types --test tests/tracking.test.ts
- name: Validate standalone installation and packaging
run: 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 regression
diff --git a/docs/product/architecture.md b/docs/product/architecture.md
index 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.ts
index f47beca3..54dbcbd1 100644
--- a/mcp.ts
+++ b/mcp.ts
@@ -9,13 +9,43 @@ import { workflowResources, readWorkflowResource, workflowEntryGuide } from './s
import { 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.json
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.env
const 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.env
const 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.ts
new file mode 100644
index 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.tsx
index 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.tsx
index 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.tsx
index 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.tsx
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.json
index 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.ts
index 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.ts
new file mode 100644
index 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.md
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.json
new file mode 100644
index 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.json
new file mode 100644
index 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"]
+}