extract internal audio engine boundary

Author: hising

docs/API_CONTRACT.md

@@ -232,3 +232,10 @@ Explicitly not required for `Issue 001`:
 - persistence implementation
 - React adapter implementation
 - React Native engine abstraction
+
+## Internal Engine Note
+
+- The public contract remains `AudioPlayer`, not an exported engine interface
+- The current implementation isolates browser audio behavior behind an internal engine boundary
+- That boundary exists to keep future non-DOM exploration, such as React Native, from changing the public player API too early
+- `beta.1` still ships only the browser engine

docs/BETA_1_ISSUES.md

@@ -158,9 +158,9 @@ Priority is based on one question only: does this unblock replacing the current
 
 - Goal: explore whether the same high-level API can sit above a non-DOM engine.
 - Done when:
-  - an engine interface is extracted
-  - feasibility is documented
-  - browser core remains the default path
+  - a minimal internal audio engine interface is extracted from direct `HTMLAudioElement` usage
+  - browser playback remains the default shipped engine
+  - feasibility is documented without promising React Native support in `beta.1`
 
 ### Issue 015: Nice-to-have playback features
 

docs/ROADMAP.md

@@ -38,6 +38,13 @@ Ship `1.0.0-beta.1` only when the library can replace the current `podcast-app`
 - Angular and Web Components should consume the same core instance
 - React Native is a stretch goal and likely needs a custom engine contract
 
+### Internal Engine Boundary
+
+- the public `AudioPlayer` API stays browser-first for `beta.1`
+- browser playback now sits behind a small internal audio engine boundary
+- the browser engine remains the only shipped runtime engine today
+- any future React Native work should implement the same internal engine contract instead of forking the public API
+
 ## Beta Definition
 
 `1.0.0-beta.1` should include:

src/index.test.ts

@@ -172,4 +172,15 @@ describe("createAudioPlayer", () => {
     expect(player.getState().currentSourceId).toBe("episode-1");
     expect(player.getState().status).not.toBe("ended");
   });
+
+  it("surfaces unsupported environments through the typed error state", async () => {
+    vi.stubGlobal("Audio", undefined);
+
+    const player = createAudioPlayer();
+
+    await player.load(episodeOne);
+
+    expect(player.getState().status).toBe("error");
+    expect(player.getState().error?.code).toBe("UNSUPPORTED_ENVIRONMENT");
+  });
 });