v10/internal/design/spf/features/engine-adapter-integration.md

status, date, definition

status	date	definition
implemented	2026-05-20	sketched

Engine-adapter integration

Adapters drive an SPF engine through shared signal references rather than reaching into its behavior graph.

Implemented decisions

• shareSignals publishes writable and readonly references after composition setup, creating a small framework-level adapter boundary.
• The HLS DOM adapter maps an HTMLMediaElement-shaped contract onto those references; other platforms may build different adapters on the same boundary.
• Engine lifetime is independent of media-element attachment. Attach/detach does not destroy the engine, and assigning another source recycles it.
• Programmatic play activates loading before delegating to native playback so preload gating cannot deadlock the request.
• The adapter owns platform semantics; behaviors remain reusable and unaware of wrapper classes.

Deferred scope

Curated notifications, a public error-state contract, multiple simultaneous engines, and non-HTML adapters are separate API decisions.

Current sources of truth

• Signal-sharing primitive and tests: packages/spf/src/core/composition/share-signals.ts and packages/spf/src/core/composition/tests/share-signals.test.ts
• HLS adapters and tests: packages/spf/src/playback/engines/hls/
• Public wrapper behavior: packages/core/src/dom/media/simple-hls/