Add Event
Developmentadd-eventAdd Event is an Agent Skill for development published in the openplayerjs/openplayerjs repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Add, rename, change the payload of, or remove a typed player event in OpenPlayerJS. Use whenever a task involves PlayerEventPayloadMap, EventBus events, cmd:* commands, ads:* events, or "emit/listen to X". Encodes the core-vs-package routing decision, declaration merging, payload conventions, and the safe-removal procedure.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/openplayerjs/openplayerjs/blob/HEAD/.claude/skills/add-event/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/add-event, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
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?
| Emitter | Classification | Where the type goes |
|---|---|---|
Core, StateManager, surfaces, DefaultMediaEngine, track plumbing | Kernel event | PlayerEventPayloadMap interface in packages/core/src/core/events.ts |
| Any other package (ads, player UI, hls, youtube, external plugins) | Package event | That package's src/events.ts declaration-merging augmentation |
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.tsfor anads:*,hls:*,ui:*, orzoom:*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.foowas migrated away — colon only).
Payload conventions (follow existing shapes, don't invent parallel ones):
- A break descriptor is
{ id: string; kind: string }carried under abreakproperty. - 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? }(seeads: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 bareevents.onwithout registering the unsubscriber inctx.dispose. - Subscribe in a control:
this.onPlayer('my:event', cb). - Timing rule: if the emit sits anywhere in the
Core.play()→cmd:playpath, it must not introduce anawait/microtask beforecmd:playfires (Safari user-gesture context).
Step 4 — Test
Minimum tests for a new event (in the owning package's __tests__/):
- Emission: drive the real trigger (not the emit itself) and assert the callback got the exact payload shape — assert every property, not just truthiness.
- Typing: subscribing through
core.on('my:event', (p) => …)compiles with the precise payload type (this is implicit if the test file uses the typed callback). - Pairing/cleanup, when applicable: the paired close/end event fires; unsubscribe on destroy.
Step 5 — Document
- Add the event to the owning package's README event table (payload shape included).
- If the event encodes a behavioral rule (ordering, pairing, sync requirement), add one line
to that package's
CLAUDE.md.
Renaming or changing a payload
This is a breaking change for downstream consumers. Stop and confirm with the user before doing it (manual §7 E1). Once approved:
- Change type + all emit sites + all subscribe sites in one commit.
grep -rn "'old:name'" packages/until it returns nothing. If.claude/CLAUDE.local.mdlists other local consumer repos, grep and type-check those per its instructions.- Run
pnpm run type-check. - Commit as
feat(<scope>)!:or include aBREAKING CHANGE:footer so the release orchestrator bumps major.
Removing an event
Never trust "no typed listener" as proof of death — tests subscribe by string.
grep -rn "'the:event'" packages/— check src,__tests__/,e2e/,examples/.- Same grep in any local consumer repos listed in
.claude/CLAUDE.local.md, if present. - Only when all hits are the emit itself: delete the emit, the type entry, and the union
entry together. If the package's
events.tsbecomes empty, delete the file AND itsimport './events'line. - Run the full test suite; a hanging/timing-out test means you missed a subscriber.
Final checklist
- Type declared in the correct home (kernel map vs package augmentation)
-
import './events'present in the package'sindex.ts(package events) - Package event-union (e.g.
AdsEvent) updated if one exists - Emission test asserts the full payload shape
- README event table updated
-
pnpm run type-check && pnpm run lint && pnpm run testgreen - Breaking change? → user approved + both monorepos type-check +
!/footer in commit