Event reference

The event taxonomy, the JSON envelope shared by all events, and per-browser URL capture support.

Every event Zanei records — regardless of source — shares one OS-independent JSON envelope. The stable schema is the core asset of the project: capture backends may change per OS, but the shape your tools consume does not.

Event envelope

One event per line (NDJSON) in raw outputs (query --format jsonl, record, export):

{
  "v": 1,
  "id": "evt_01J...",
  "ts": "2026-08-16T12:34:56.789Z",
  "mono_ns": 128374651234,
  "source": "macos.ax",
  "type": "window.focus",
  "app":    { "name": "Safari", "bundle_id": "com.apple.Safari", "pid": 501 },
  "window": { "title": "Design doc", "id": 42 },
  "element":{ "role": "AXButton", "title": "Send", "value": null },
  "data":   { },
  "redaction": { "applied": true, "rules": ["email"] }
}

This envelope is also published as a machine-readable JSON Schema at /schema/event.schema.json — the single contract all surfaces share, and the file the Rust core’s types are tested against.

Event taxonomy

The current event types. The Permission column shows what must be granted for the type to be captured (see the permissions guide).

In --types filters, a trailing wildcard selects a whole family: browser.*, ui.*, and so on.

type is an open set, not a closed enum: future platforms and versions may add types without a version bump, and consumers must skip unknown types rather than error.

Per-type payloads

What each type carries in data, and whether the envelope’s window / element are present (✓) or null (—). The normative definitions live in the JSON Schema as per-type conditions.

field_kind classifies the focused input field: text / search / url / email / number / other, or null when focus is not on a text-like element. There is no password value — secure fields are excluded before an event exists.

ui.value in detail

For a free-text field, data.text contains only the newly added difference after an authorized input. Authorization requires a keystroke or paste from the same app, for the same focused-element generation, with the value-change notification timestamp no more than 3 seconds after that input. One authorization can permit at most one emission and is consumed when used. text_content must also be enabled. The field’s complete value is never stored in element.value.

A value change without valid authorization, including an app mismatch, focused-element generation mismatch, or expired authorization, is not recorded as text: data.text is null and only value_len describes the resulting value. Deletion likewise has text: null. Voice input has no keystroke trigger, so its text is not recorded.

input.key in detail

The exact shape of “fact of typing + field type by default, content opt-in”:

A shortcut is an action, not content — so combo is recorded without opt-in. It is a primary timeline ingredient (saves, commits, tab switches).

Coalescing guarantees

Events are coalesced before they reach the store, so consumers do not see raw key-repeat or scroll floods:

Shortcuts and ui.click do not coalesce (one action = one event). Core coalescing buffers are flushed on pause, stop, and batch flush. The collector-side ui.value buffer is flushed on focus change and collector stop.

What text_content changes

Only content (what you typed or copied) is opt-in. Facts of use (shortcuts, clicks, URLs, titles) are recorded by default:

Schema versioning

• Additive changes (new fields, new types, new sources) do not bump v. Consumers must ignore unknown fields and skip unknown types.
• Breaking changes (removal, rename, meaning change) bump v, with a store migration to match.

Browser URL capture

browser.navigate (URL capture) currently supports Chrome only. Chromium exposes each window’s mode (normal / incognito) deterministically via AppleScript, so Incognito windows can be excluded from URL capture without a configuration knob.

Safari/Firefox support may come later if a reliable private-mode detection mechanism exists.

Two layers of data

• Raw event layer — complete and machine-readable; what query, record, and export return.
• Timeline layer — human/LLM-readable; session splitting, dedup, coalescing, token-budgeted serialization. What timeline and get_timeline return.

Timeline sessions carry event_ids back-references to the underlying raw events. They are included only in the JSON format (--format json), and are dropped when the output must be coarsened to fit the token budget.