Add Event

Add / change / remove a player event

Events are the most rule-dense surface in this repo. Every step below exists because skipping it has broken something before. Work through the steps in order; do not improvise.

Step 0 — Classify the event

Answer one question: who emits it?

Hard rules:

• Core's map may contain ONLY: lifecycle, cmd:* commands, HTML5-native names (playing, pause, ended, loadedmetadata, …), track events, source:set, player:interacted.
• If you find yourself editing packages/core/src/core/events.ts for an ads:*, hls:*, ui:*, or zoom:* key — stop, you are in the wrong file.
• If the emitting package is unclear (e.g. core emits it but only ads consumes it), it is a kernel event only if core can describe the payload without importing any package concept. Otherwise redesign so the package emits it.

Step 1 — Name and shape the payload

Naming:

• cmd:<verb> — player→engine command (cmd:play, cmd:seek). Kernel only.
• <pkg-prefix>:<noun>[:<phase>] — package events (ads:break:start, ui:menu:open).
• Never a bare untyped string; never dot-notation (ads.foo was migrated away — colon only).

Payload conventions (follow existing shapes, don't invent parallel ones):

• A break descriptor is { id: string; kind: string } carried under a break property.
• Flat id references use breakId (e.g. ads:quartile: { breakId, quartile: 25|50|75|100 }).
• Paired events (X:open/X:close, X:start/X:end) must both exist and both be emitted — the player package relies on pairing (e.g. menu open/close gates the auto-hide timer).
• Error payloads: { reason?, error?, message?, owner? } (see ads:error).

Step 2 — Declare the type

Kernel event: add the key to the PlayerEventPayloadMap interface in packages/core/src/core/events.ts. Do not convert the interface to a type — it is the one sanctioned interface (declaration merging requires it).

Package event: edit (or create) packages/<pkg>/src/events.ts:

import '@openplayerjs/core';

declare module '@openplayerjs/core' {
  // eslint note: this augments core's sanctioned interface
  interface PlayerEventPayloadMap {
    'my:event': MyPayload;
  }
}

Then verify the side-effect import exists in packages/<pkg>/src/index.ts:

import './events';

If you created events.ts and forget this import, everything compiles locally but consumers of the published package silently lose the typing. Check it explicitly.

If the package keeps a union of its own events (ads has AdsEvent in src/types.ts), update it in the same commit — the augmentation and the union must stay in sync.

Special case — HLS: it deliberately has NO events.ts. It drives the player through standard core events only. Before adding an HLS event, confirm a real consumer exists (three HLS events were removed in Jun 2026 because nothing listened). Duration/live/ID3 metadata already flow through native channels — do not re-add events for them.

Step 3 — Emit and consume

• Emit: ctx.events.emit('my:event', payload) — payload type is enforced.
• Subscribe in a plugin: ctx.on('my:event', cb) (auto-disposed) — never a bare events.on without registering the unsubscriber in ctx.dispose.
• Subscribe in a control: this.onPlayer('my:event', cb).
• Timing rule: if the emit sits anywhere in the Core.play() → cmd:play path, it must not introduce an await/microtask before cmd:play fires (Safari user-gesture context).