OpenParable
Skip to content
← Back to skills

Add Event

Development
add-event

Add 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.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
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?

EmitterClassificationWhere the type goes
Core, StateManager, surfaces, DefaultMediaEngine, track plumbingKernel eventPlayerEventPayloadMap interface in packages/core/src/core/events.ts
Any other package (ads, player UI, hls, youtube, external plugins)Package eventThat 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.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).

Step 4 — Test

Minimum tests for a new event (in the owning package's __tests__/):

  1. Emission: drive the real trigger (not the emit itself) and assert the callback got the exact payload shape — assert every property, not just truthiness.
  2. 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).
  3. 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:

  1. Change type + all emit sites + all subscribe sites in one commit.
  2. grep -rn "'old:name'" packages/ until it returns nothing. If .claude/CLAUDE.local.md lists other local consumer repos, grep and type-check those per its instructions.
  3. Run pnpm run type-check.
  4. Commit as feat(<scope>)!: or include a BREAKING CHANGE: footer so the release orchestrator bumps major.

Removing an event

Never trust "no typed listener" as proof of death — tests subscribe by string.

  1. grep -rn "'the:event'" packages/ — check src, __tests__/, e2e/, examples/.
  2. Same grep in any local consumer repos listed in .claude/CLAUDE.local.md, if present.
  3. Only when all hits are the emit itself: delete the emit, the type entry, and the union entry together. If the package's events.ts becomes empty, delete the file AND its import './events' line.
  4. 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's index.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 test green
  • Breaking change? → user approved + both monorepos type-check + !/footer in commit