docs(plugins): explain namespaced custom hooks

[gabek]

Related to owncast/owncast#5093, owncast/owncast#5119, and owncast/plugin-sdk#16.

What changes

This PR documents the runtime contract introduced by owncast/owncast#5119 across event, API, permission, testing, and language SDK pages:

• A receiver declares a local custom hook, such as announcement.broadcast.
• The host registers it as <recipient-slug>.announcement.broadcast.
• An emitter targets that fully qualified receiver hook with owncast.events.emit.
• The receiver's on_event handler receives the local hook name.
• Native WebAssembly modules declare local subscriptions.notify hooks in their manifest and follow the same rule.

How to use it

For a plugin whose slug is announcer:

// receiver
on: { "announcement.broadcast": handleAnnouncement }

// another plugin
owncast.events.emit("announcer.announcement.broadcast", payload)

A scenario event uses the same fully qualified target. An emitted-event assertion also expects that fully qualified target.

What this does not change

• This is hook ownership, not emitter authorization. A plugin with events.emit may target a known receiver hook.
• Built-in events, commands, and filter subscriptions keep their existing names.
• Receivers that previously included their own slug in a custom hook declaration must remove it. There is no compatibility alias.

Verification

npx docusaurus build --locale en compiled the updated MDX. It then reached the repository's known redirect-validation failure for /development-builds and /dev-docs/contributor-guide, generated by the skipped prebuild. No broken-link, anchor, MDX, or parse error was reported.

Merge order

Merge after owncast/owncast#5119 ships and owncast/plugin-sdk#16 updates host-runtime/go.mod to the released runtime. This PR targets owncast-docusaurus, where the plugin documentation lives.

[Copilot]

Pull request overview

Updates the Owncast plugin documentation to clarify that custom hooks are receiver-owned and namespaced by the receiving plugin slug, and that emitters must target the fully qualified <recipient-slug>.<hook> name across SDKs, permissions, APIs, events reference, and the scenario test harness.

Changes:

• Clarify custom-hook ownership and fully qualified emit targets (<recipient-slug>.<hook>) across permissions, APIs, and events reference docs.
• Update JavaScript/Python SDK docs to describe local hook declarations vs fully qualified names.
• Update scenario testing docs/examples to assert against fully qualified emitted event targets.

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
docs/plugins/testing.mdx	Clarifies scenario event dispatch semantics for custom hooks and updates emitted-event assertions/examples.
docs/plugins/sdks/python.md	Updates Python SDK mapping and decorator explanation to reflect receiver-owned custom hooks.
docs/plugins/sdks/native-wasm.mdx	Documents how native WASM modules receive local hook names while emitters use namespaced targets.
docs/plugins/sdks/javascript.md	Updates JS SDK mapping table to reflect receiver-owned custom hooks.
docs/plugins/permissions.md	Updates events.emit permission docs to reflect fully qualified recipient hook targets and no host rewriting.
docs/plugins/events.mdx	Reframes plugin-to-plugin “custom events” as receiver-owned hooks; updates examples and permission table wording.
docs/plugins/apis.mdx	Updates owncast.events.emit reference to require fully qualified <recipient-slug>.<hook> targets and refreshes examples.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.