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.

16.8 KB
Raw Blame

Adding OpenMotion tracking events

Use this guide to ask a coding agent to add an event, implement it through the existing MCP/Studio tracking path, and verify its meaning and delivery. It describes the implementation in PR #189, not a released npm API. Check the current checkout before applying examples. @openmotion/tracking is private; application callers currently import repository sources rather than installing it from npm.

Give the agent a business question

The requester supplies the question, interaction and observable completion. The agent finds the existing implementation and chooses the smallest change. For example: “Can users successfully save changes in Studio? Measure one result for each actual save attempt; do not count every keystroke or treat a button click as a completed save.” Event names below are illustrative, not already implemented.

Copy this task template and replace the bracketed lines:

Read tracking/INTEGRATION.md, tracking/README.md and AGENTS.md first.
Add tracking for this OpenMotion behavior:
- Question: [what decision will this data support?]
- Entry: [Studio / MCP / worker]
- Trigger: [the exact interaction or completed operation]
- Success/failure: [observable conditions; include partial/no-op if relevant]
- Dimensions: [only the categories/counts needed for the question]

Inspect the existing event registry, all callers and the actual completion path.
Reuse an existing event if its meaning matches. Otherwise add its closed property
schema and producers in tracking/events.ts. Studio types and server admission are
derived from producers; do not maintain a separate browser event list.
Use the existing trackMotion wrapper or injected OmTracking instance. Keep one
owner for each business result; do not duplicate MCP wrapper events.
Do not add an SDK, direct browser-to-PostHog calls, a new identity or a capture key.
Do not send prompts, content, paths, URLs, raw errors or credentials.

Add focused tests for actual success/failure, rejected/private fields and the
relevant replay/no-op or duplicate-render cases. Verify opt-out still prevents
reporting while the feature continues working. Run the repository-required checks.
If live ingestion is checked, use isolated data and env=test with a new UUID
test_run_id. Read back those exact events from PostHog; an HTTP 200 is not proof.
If readback is unavailable, report it as unverified rather than passed.
Update the event definition/documentation. Report trigger, fields, files, checks,
actual indexed-event evidence and limits. Prepare the change for review; do not
merge or publish without authorization.

Before implementation, record the event's meaning, trigger, owner, allowed fields, required fields and deduplication unit. Missing business meaning needs clarification; the agent can determine file paths and existing helpers from code.

Find the correct owner

Signal Existing location Extension rule
Accepted MCP start and observed finish mcp.ts, toolNames in tracking/events.ts All eleven tools already use the wrapper. Do not add another start/finish pair inside a handler. Reconcile the tool contract and this list if adding a tool.
Committed phase-one business result phase1.ts and trackPhase1Result in shared/tracking.ts Use the shared domain completion. Replayed operations skip new domain completions. A successful call need not have made a useful edit.
Render/export terminal state renderNext in server.ts Emit from the worker's observed terminal state. A queued job is not a completed video.
Studio interaction or readiness Components under studio/src/motion/, using tracking.ts there Track an intentional handler or a guarded readiness/completion callback. Avoid unguarded render/effect reporting.
Browser admission producers in tracking/events.ts; derived studioEvents; ingress in server.ts Declare producers: ['studio'] on the event. The wrapper's types and server validator use the derived registry. Preserve server-side rejection of identity, source, worker and credential overrides.

ui_click already describes a fixed page/area/element tuple. Reuse it for matching intent and extend only its necessary enum values. Use a result event for persisted effects; do not infer success from intent. If MCP and Studio reach the same operation, choose one domain owner. Two calls to track() create two UUIDs and are not automatically recognized as the same business action.

Register and call an event

This proposed Studio-save example demonstrates the API; it does not add save coverage. Decide what constitutes one save attempt and attach it to the real save completion callback before using it. Count one committed save batch, not individual keystrokes. Define no-op and retry behavior explicitly.

Add the entry inside omEvents in tracking/events.ts:

studio_save_result: {
  producers: ['studio'],
  fields: {
    outcome: ['success', 'failure'],
    changed_file_count: 'integer',
    error_code: ['SAVE_FAILED', 'VERSION_CONFLICT'],
  },
  required: ['outcome'],
},

Keep the registry's existing as const satisfies declaration. Register the actual producer (studio, mcp or worker) on the event; only include studio for an event that browsers may submit. The registry supplies both TypeScript types and runtime validation; unknown properties are rejected, not silently removed. A new Studio event automatically enters studioEvents without another list edit. This metadata controls Studio exposure and admission; Node's tracker still owns the domain/worker call sites and entrypoint mapping.

In the owning Studio component, import the existing wrapper using the correct relative path. For a component directly in studio/src/motion/:

import { trackMotion } from './tracking';

// Call after the save operation confirms a committed change.
function reportSaveSuccess(changedFileCount: number) {
  void trackMotion('studio_save_result', {
    outcome: 'success', changed_file_count: changedFileCount,
  });
}

// Invoke from the failure path; map known conflicts separately if available.
function reportSaveFailure() {
  void trackMotion('studio_save_result', {
    outcome: 'failure', error_code: 'SAVE_FAILED',
  });
}

Preserve the feature's existing error handling. Map errors to explicit safe codes; never pass error.message, String(error), a stack or the whole result object. These helper names are examples; place calls in existing completion handlers instead of introducing wrappers solely for tracking.

Server/domain code uses its injected tracker:

import type { OmTracking } from './shared/tracking.ts';

// Example only: an additional restore hook is unnecessary where Phase1Service
// already emits version_restore_result. Adjust the import for the owning file.
function reportRestore(tracking: OmTracking | undefined, projectId: string) {
  tracking?.track('version_restore_result', {
    outcome: 'success', project_id: projectId,
  });
}

Reuse an existing tracker; do not create an identity/tracker per interaction. In a new process only, follow createAppTracking/closeTracking lifecycle wiring. Do not await delivery in a business operation. track() returning queued means local acceptance; trackMotion() resolves with a local queue/configuration status. Neither proves that the event is queryable in PostHog. Normal calls do not need an explicit flush.

Current field rules are closed enums, booleans, UUIDv4 values, safe-code strings or nonnegative safe integers up to 86,400,000. Do not invent arbitrary string fields or use the safe-code rule to tunnel user content. Omit unknown optional counts; missing is not zero. If the measurement needs a new type, review the validator and its tests rather than bypassing it. Do not silently change an existing event's meaning; use a distinct event or an explicit schema migration for breaking changes.

Leave common context to the tracking path

Business callers provide only registered semantic properties. The package/server adds event UUID/time, schema and app version, environment, entrypoint/runtime, installation/device identity, saved attribution, platform, locale and timezone. Do not place common fields inside an event's properties or copy a browser identity into Node. device_id, installation_id and distinct_id currently share one random installation UUID; they are not a hardware fingerprint or a unique-person count.

The current installation identity may retain utm_source; landing-to-installer --source propagation is separate work and an unknown source remains null. An event addition must not claim that acquisition plumbing is already implemented.

Events go to the existing OpenDesign project (420348), with product=openmotion. Filter OM queries by that property and exclude OM from unrelated shared reports. An OM-only receiver transformation preserves coarse GeoIP and removes raw IP and precise location after the existing GeoIP transformation; non-OM events are unchanged. Do not add client IP lookups or collect IP in callers. Device timezone is separate from GeoIP timezone; VPN/proxy egress may differ. See configuration, privacy and limits and coarse GeoIP.

Tracking is on by default in every application environment and version, including stable, test/prerelease and local builds. Studio Privacy settings → Share usage data disables collection for the installation, including MCP and Studio across restarts. Re-enabling resumes new reports without replaying discarded events. Application version and environment are event properties, not collection gates. DEV packages retain their separate installation/data directories and template routing. OPENMOTION_TELEMETRY=0 or DO_NOT_TRACK=1 forces it off; browser Do Not Track also suppresses browser collection. An added event must respect those controls.

Diagnose without logging event contents

Normal component calls remain void trackMotion(...). Tests or a local debugger can inspect the returned status without changing feature behavior:

const status = await trackMotion('ui_click', {
  page_name: 'home', area: 'workspace', element: 'new_creation',
});
// queued | invalid | full | duplicate | disabled | config_unavailable

queued means browser-local acceptance, not service or PostHog ingestion. invalid means schema rejection; full means the bounded browser queue is full. disabled covers policy/preference controls and a service opt-out response. config_unavailable means configuration could not be confirmed; the event is not queued. Do not retry a business operation because its tracking failed.

Studio shares one in-flight configuration load across callers. Each request has a one-second timeout. Transient HTTP/network/JSON/shape failures get at most three attempts, with one- and two-second delays. Collection stays off until a valid boolean configuration arrives. After exhaustion, calls return config_unavailable for 30 seconds; the next call after that cooldown starts a new attempt group. Events rejected during the cooldown are not replayed. There is no permanent background polling. A valid enabled: false is not a transient failure and does not trigger retries. Opt-out aborts pending configuration work, cancels retry delays and clears queued events; a late response cannot re-enable it. setMotionTrackingEnabled(true) is for the existing control after the service confirms the preference change, not a bypass around initialization or policy.

For a snapshot, import getMotionTrackingStatus from the same Studio wrapper. It exposes only configuration (uninitialized, loading, ready, disabled or unavailable), effective enabled, pending count and retryAfterMs. Browser Do Not Track can keep effective enabled false even with a ready configuration. No event properties, identity, tokens or raw errors are exposed.

flushMotionTracking() returns accepted, retry, drop, disabled or empty. This describes the browser-to-local-service boundary; accepted does not prove downstream PostHog ingestion. The existing core/Node tracker similarly returns local queue statuses from track() and transport receipts from flush(). Use fake senders/fetch in tests and assert these results; do not enable raw payload logging or build assertions around production data.

Verify meaning before checking ingestion

Extend the existing tests nearest the changed boundary:

  • tests/tracking.test.ts: schema/privacy, local ingress, domain completion, replay, export terminal state and installation-wide opt-out. It also compiles tests/tracking-types.ts to check Studio-only event exposure and field types.
  • studio/src/motion/tracking.test.ts: browser sender, common-field isolation and browser opt-out, bounded configuration recovery and safe diagnostic statuses. Also test the owning component's real completion/handler so a missing call site cannot pass on schema tests alone.
  • tests/source-install.test.ts, tests/package.test.ts and tests/npm-package.test.ts: public boundary and distributed content when affected. The npm tests also execute extracted test and stable application archives with fake senders, checking the version lock and repeated disable/re-enable cycles.

Check a valid event and required/unknown-field rejection, real success and failure, and the relevant no-op/retry/replay or rerender case. Prove there is one event per defined unit and zero reports after opt-out. A collector outage must leave the feature's normal success/failure behavior intact. Use an injected fake sender for deterministic checks. Normal Node/Vitest runs suppress external reporting.

Use the CI-pinned Node version and repository rules. These existing commands cover the shared boundary and browser wrapper; add the owning feature's tests as needed:

npm run check
npm run typecheck:studio
npm run build:studio
npm run build:tracking
node --experimental-strip-types --test tests/tracking.test.ts
npm run test:studio -- studio/src/motion/tracking.test.ts

Before branch publication, follow the local validation guidance, including affected install and packaging checks. The list above covers tracking changes, not every documentation edit. Documentation-only edits need link/content checks and applicable repository gates, not invented product events.

Read back a marked live run

Use an application of any version, an owned temporary data directory and fresh runtime processes. Apply the same test environment to every participating MCP/local service process, including ones launched by a host. An already-running shared service will not inherit new variables. For a POSIX shell, prepare the environment before starting the normal test runner or application entry:

export OPENMOTION_TRACKING_ENV=test
export OPENMOTION_TRACKING_TEST_RUN_ID="$(node -e 'console.log(crypto.randomUUID())')"
export MOTION_DATA_DIR="$(mktemp -d "${TMPDIR:-/tmp}/openmotion-tracking.XXXXXX")"

These lines only prepare a test; they do not run the feature or prove delivery. Keep test-run UUIDs stable for one run and start a fresh UUID for another. Do not override a user's saved preference or remove their force-off variables to make a test pass. Use a separately owned test launch; record an intentional opt-out case.

Exercise the actual action, then query the exact test_run_id and product=openmotion in the OpenDesign PostHog project. A read-authorized connector/account is needed; the distributed public capture token cannot query events. For example, replace the UUID below:

SELECT event, count() AS rows, uniqExact(uuid) AS unique_events
FROM events
WHERE properties.product = 'openmotion'
  AND properties.env = 'test'
  AND properties.test_run_id = 'REPLACE_WITH_TEST_RUN_UUID'
GROUP BY event
ORDER BY event

Compare counts and properties with the action's declared contract, excluding any known baseline page/tool events. Check entrypoint, allowed dimensions and common identity. Check raw IP/private fields are absent; GeoIP may be unknown on lookup failure. Disable through the actual control, repeat the successful action, and confirm no extra indexed events. Include timestamps and allow bounded ingestion latency; unavailable readback or unsettled indexing is an explicit verification gap. Product dashboards must filter out env=test and test-run records.

Review handoff

Provide event name/meaning, exact trigger, fields/enums, one reporting owner, deduplication behavior, changed paths and checks. Separate local tests, actual indexed evidence, current CI, installation/platform checks and release status. Link the marked live run when performed; never attach credentials or user content. No report is guaranteed: the bounded queue is process-local and can lose data on crash, overflow or permanent rejection. Do not use its counts as guaranteed billing or unique-person evidence. Adding an event does not authorize changing receiver settings, publishing the private tracking package or merging the feature PR.