fix: align media player playground with current APIs

Author: SandroMaglione

.changeset/clean-scenarios-plan.md

@@ -0,0 +1,5 @@
+---
+"@typeonce/effect-machine": patch
+---
+
+Keep `MachineTest.run` service-free for machines with invoked effects, matching the pure `Machine.planInitial` and `Machine.plan` APIs it uses internally.

examples/playground/README.md

@@ -35,7 +35,9 @@ React-to-machine adapter is left for the exercise.
 The media player is a complete browser integration. `schemas.ts` owns its typed
 protocol, `service.ts` exposes the audio element and Web Audio graph as an
 Effect service, `invocations.ts` defines its state-scoped processes, and the
-React page translates DOM events into machine events. Its compound
+React adapter registers the audio element through the shared service runtime
+before translating playback events into machine events. `view.ts` exhaustively
+projects the typed parallel snapshot into the React-facing view model. Its compound
 `Ready` state models the loaded playback lifecycle inside a parallel `Player`:
 the transport region owns loading, playback, buffering, and failures while the
 settings region independently owns `Audible` and `Muted`.

examples/playground/src/examples/media-player/MediaPlayerPage.tsx

@@ -1,10 +1,9 @@
 import { useAtomSet, useAtomValue } from "@effect/atom-react"
-import { Option } from "effect"
-import { AsyncResult } from "effect/unstable/reactivity"
+import { Match } from "effect"
 import { useCallback, useEffect, useState } from "react"
 import { ExamplePage } from "../../components/ExamplePage.tsx"
-import { mediaPlayerAtom } from "./atoms.ts"
-import { initialAudioSettings, initialPlaybackData, MediaPlayerEvent, MediaPlayerStates } from "./schemas.ts"
+import { mediaPlayerAtom, mediaPlayerViewAtom, registerMediaPlayerElement } from "./atoms.ts"
+import { MediaPlayerEvent } from "./schemas.ts"
 
 interface AudioSource {
   readonly name: string
@@ -20,17 +19,18 @@ const formatTime = (seconds: number): string => {
 }
 
 export function MediaPlayerPage() {
-  const snapshotResult = useAtomValue(mediaPlayerAtom.snapshot)
+  const viewResult = useAtomValue(mediaPlayerViewAtom)
   const send = useAtomSet(mediaPlayerAtom.send)
+  const register = useAtomSet(registerMediaPlayerElement)
   const [source, setSource] = useState<AudioSource>()
 
   const registerAudioElement = useCallback(
     (audioRef: HTMLAudioElement | null) => {
       if (audioRef !== null) {
-        send(MediaPlayerEvent.cases.AudioElementMounted.make({ audioRef }))
+        register(audioRef)
       }
     },
-    [send]
+    [register]
   )
 
   useEffect(
@@ -46,67 +46,13 @@ export function MediaPlayerPage() {
       summary="Coordinate a compound transport lifecycle and independent sound modes inside a parallel Effect statechart."
       machineFile="src/examples/media-player/machine.ts"
     >
-      {AsyncResult.isInitial(snapshotResult) ?
-        <div className="media-player-message">Starting the media player machine…</div> :
-        AsyncResult.isFailure(snapshotResult) ?
-        <div className="media-player-message is-error">The media player machine failed to start.</div> :
-        (
-          (() => {
-            const runtimeSnapshot = snapshotResult.value
-            const snapshot = runtimeSnapshot.state
-            const paused = Option.getOrUndefined(
-              MediaPlayerStates.get(snapshot, "Player.transport.Ready.Paused")
-            )
-            const playing = Option.getOrUndefined(
-              MediaPlayerStates.get(snapshot, "Player.transport.Ready.Playing")
-            )
-            const buffering = Option.getOrUndefined(
-              MediaPlayerStates.get(snapshot, "Player.transport.Ready.Buffering")
-            )
-            const restarting = Option.getOrUndefined(
-              MediaPlayerStates.get(snapshot, "Player.transport.Ready.Restarting")
-            )
-            const ended = Option.getOrUndefined(
-              MediaPlayerStates.get(snapshot, "Player.transport.Ready.Ended")
-            )
-            const failed = Option.getOrUndefined(
-              MediaPlayerStates.get(snapshot, "Player.transport.Failed")
-            )
-            const audible = Option.getOrUndefined(
-              MediaPlayerStates.get(snapshot, "Player.settings.Audible")
-            )
-            const muted = Option.getOrUndefined(
-              MediaPlayerStates.get(snapshot, "Player.settings.Muted")
-            )
-            const playback = paused ?? playing ?? buffering ?? restarting ?? ended
-            const playbackData = playback ?? initialPlaybackData
-            const settings = audible ?? muted ?? initialAudioSettings
-            const isMuted = muted !== undefined
-            const isPaused = paused !== undefined
-            const isPlaying = playing !== undefined
-            const isBuffering = buffering !== undefined
-            const isEnded = ended !== undefined
-            const canPlay = isPaused || isEnded
-            const canPause = isPlaying || isBuffering
-            const canRestart = canPlay || canPause
-            const transportPath = isPlaying ?
-              "Player.transport.Ready.Playing"
-              : isBuffering ?
-              "Player.transport.Ready.Buffering"
-              : restarting !== undefined ?
-              "Player.transport.Ready.Restarting"
-              : isEnded ?
-              "Player.transport.Ready.Ended"
-              : isPaused ?
-              "Player.transport.Ready.Paused"
-              : failed !== undefined ?
-              "Player.transport.Failed"
-              : MediaPlayerStates.matches(snapshot, "Player.transport.Loading") ?
-              "Player.transport.Loading"
-              : "Player.transport.Empty"
-            const stateName = transportPath.slice(transportPath.lastIndexOf(".") + 1)
-            const settingsPath = isMuted ? "Player.settings.Muted" : "Player.settings.Audible"
-            const loudness = playing?.loudness ?? null
+      {Match.value(viewResult).pipe(
+        Match.tagsExhaustive({
+          Initial: () => <div className="media-player-message">Starting the media player machine…</div>,
+          Failure: () => <div className="media-player-message is-error">The media player machine failed to start.</div>,
+          Success: ({ value: view }) => {
+            const { settings, status, transport } = view
+            const { canPause, canPlay, canRestart, isPlaying, loudness, playback } = transport
             const loudnessLevel = Math.min(100, Math.round((loudness?.rms ?? 0) * 220))
             const peakLevel = Math.min(100, Math.round((loudness?.peak ?? 0) * 100))
 
@@ -118,7 +64,7 @@ export function MediaPlayerPage() {
                     <h2>{source?.name ?? "Choose a local audio track"}</h2>
                   </div>
                   <div className="media-player-toolbar-actions">
-                    <span className={`media-state-chip is-${stateName.toLowerCase()}`}>{stateName}</span>
+                    <span className={`media-state-chip is-${transport.name.toLowerCase()}`}>{transport.name}</span>
                     <label className="media-file-button">
                       <span>{source === undefined ? "Choose audio" : "Replace audio"}</span>
                       <input
@@ -163,7 +109,7 @@ export function MediaPlayerPage() {
 
                     <div className="media-time-row">
                       <span>Current time</span>
-                      <strong>{formatTime(playbackData.currentTime)}</strong>
+                      <strong>{formatTime(playback.currentTime)}</strong>
                     </div>
 
                     <div className="media-controls">
@@ -207,7 +153,7 @@ export function MediaPlayerPage() {
                     <section className="media-settings">
                       <div className="media-panel-heading">
                         <span>Audio settings</span>
-                        <strong>{isMuted ? "Muted" : "Audible"} · {Math.round(settings.volume * 100)}%</strong>
+                        <strong>{settings.muted ? "Muted" : "Audible"} · {Math.round(settings.volume * 100)}%</strong>
                       </div>
                       <label>
                         <span>Volume</span>
@@ -227,7 +173,7 @@ export function MediaPlayerPage() {
                         <span>Muted</span>
                         <input
                           type="checkbox"
-                          checked={isMuted}
+                          checked={settings.muted}
                           onChange={({ currentTarget }) =>
                             send(
                               currentTarget.checked
@@ -257,30 +203,31 @@ export function MediaPlayerPage() {
                     <section className="media-state-preview">
                       <div className="media-panel-heading">
                         <span>Machine snapshot</span>
-                        <strong>{runtimeSnapshot.status}</strong>
+                        <strong>{status}</strong>
                       </div>
                       <pre>
                       {JSON.stringify({
-                        status: runtimeSnapshot.status,
+                        status,
                         states: {
-                          transport: transportPath,
-                          settings: settingsPath
+                          transport: transport.path,
+                          settings: settings.path
                         },
                         data: {
-                          transport: playback ?? failed ?? null,
-                          settings
+                          transport: transport.value,
+                          settings: settings.value
                         }
                       }, null, 2)}
                       </pre>
                     </section>
 
-                    {failed !== undefined && <p className="media-error-message" role="alert">{failed.message}</p>}
+                    {transport.error !== null && <p className="media-error-message" role="alert">{transport.error}</p>}
                   </aside>
                 </div>
               </div>
             )
-          })()
-        )}
+          }
+        })
+      )}
     </ExamplePage>
   )
 }

examples/playground/src/examples/media-player/atoms.ts

@@ -1,8 +1,22 @@
 import { AtomMachine } from "@typeonce/effect-machine/reactivity"
+import { Effect } from "effect"
 import { Atom } from "effect/unstable/reactivity"
 import { MediaPlayerMachine } from "./machine.ts"
 import { MediaPlayer } from "./service.ts"
+import { toMediaPlayerView } from "./view.ts"
 
 const mediaPlayerRuntime = Atom.runtime(MediaPlayer.layer)
 
 export const mediaPlayerAtom = AtomMachine.bind(mediaPlayerRuntime).make(MediaPlayerMachine)
+
+export const mediaPlayerViewAtom = Atom.mapResult(mediaPlayerAtom.snapshot, (snapshot) => ({
+  status: snapshot.status,
+  ...toMediaPlayerView(snapshot.state)
+}))
+
+export const registerMediaPlayerElement = mediaPlayerRuntime.fn((audioRef: HTMLAudioElement) =>
+  Effect.gen(function*() {
+    const mediaPlayer = yield* MediaPlayer
+    yield* mediaPlayer.register(audioRef)
+  })
+)

examples/playground/src/examples/media-player/invocations.ts

@@ -1,6 +1,6 @@
 import { Machine } from "@typeonce/effect-machine"
 import { Data, Effect, Stream } from "effect"
-import { type LoudnessSample, MediaPlayerInternalEvent } from "./schemas.ts"
+import { type LoudnessSample, MediaPlayerInternalEvent, type SoundSettings, toAudioSettings } from "./schemas.ts"
 import { MediaPlayer, MediaPlayerError } from "./service.ts"
 
 export const loadAudio = (url: string) =>
@@ -44,6 +44,16 @@ export const restartAudio = Machine.invokeEffect({
   onFailure: (failure) => MediaPlayerInternalEvent.cases.OperationFailed.make({ message: failure.message })
 })
 
+export const applyAudioSettings = (settings: SoundSettings, muted: boolean) =>
+  Machine.invokeEffect({
+    id: "apply-audio-settings",
+    effect: Effect.gen(function*() {
+      const mediaPlayer = yield* MediaPlayer
+      yield* mediaPlayer.applySettings(toAudioSettings(settings, muted))
+    }),
+    onSuccess: () => undefined
+  })
+
 type LoudnessProcessState = Data.TaggedEnum<{
   Waiting: {}
   Measured: { readonly sample: LoudnessSample }

examples/playground/src/examples/media-player/machine.test.ts

@@ -1,20 +1,23 @@
 import { assert, describe, it } from "@effect/vitest"
 import { MachineTest } from "@typeonce/effect-machine/testing"
 import { Effect, Graph } from "effect"
-import { MediaPlayerEvent, MediaPlayerMachine } from "./machine.ts"
+import { MediaPlayerMachine } from "./machine.ts"
+import { MediaPlayerEvent } from "./schemas.ts"
 
 const everyPublicEvent = [
   MediaPlayerEvent.cases.SourceSelected.make({ url: "https://example.com/audio.mp3" }),
   MediaPlayerEvent.cases.PlayRequested.make({}),
   MediaPlayerEvent.cases.PauseRequested.make({}),
-  MediaPlayerEvent.cases.MediaPlaying.make({}),
-  MediaPlayerEvent.cases.MediaPaused.make({}),
+  MediaPlayerEvent.cases.RestartRequested.make({}),
   MediaPlayerEvent.cases.MediaWaiting.make({}),
   MediaPlayerEvent.cases.MediaCanPlay.make({}),
-  MediaPlayerEvent.cases.MediaEnded.make({}),
+  MediaPlayerEvent.cases.PlaybackEnded.make({ currentTime: 42 }),
+  MediaPlayerEvent.cases.TimeUpdated.make({ currentTime: 21 }),
   MediaPlayerEvent.cases.MediaFailed.make({ message: "unsupported codec" }),
   MediaPlayerEvent.cases.VolumeChanged.make({ volume: 0.4 }),
-  MediaPlayerEvent.cases.MuteToggled.make({})
+  MediaPlayerEvent.cases.PlaybackRateChanged.make({ playbackRate: 1.5 }),
+  MediaPlayerEvent.cases.MuteRequested.make({}),
+  MediaPlayerEvent.cases.UnmuteRequested.make({})
 ]
 
 const generated = MachineTest.scenarios(MediaPlayerMachine, {
@@ -32,69 +35,45 @@ describe("media-player statechart model", () => {
         Effect.tap((trace) =>
           Effect.sync(() => {
             assert.strictEqual(trace.final.path, "Player")
-            assert.strictEqual(trace.final.states.playback.state.path, "Player.playback.Empty")
-            const volume = trace.final.states.volume.state
-            if (volume.path !== "Player.volume.Audible") {
-              throw new Error(`Expected Audible, received ${volume.path}`)
-            }
-            assert.strictEqual(volume.value.volume, 1)
+            assert.strictEqual(trace.final.states.transport.state.path.startsWith("Player.transport."), true)
+            assert.strictEqual(trace.final.states.settings.state.path.startsWith("Player.settings."), true)
           })
         ),
         Effect.asVoid
       ),
     { fastCheck: { numRuns: 100, seed: 24_061 } }
   )
 
-  it.effect("makes the current behavior gaps explicit through coverage", () =>
+  it.effect("covers the public protocol and its reachable states", () =>
     Effect.gen(function*() {
       const trace = yield* MachineTest.run(MediaPlayerMachine, { events: everyPublicEvent })
       yield* MachineTest.verify(MediaPlayerMachine, trace)
 
       const coverage = MachineTest.coverage(MediaPlayerMachine, trace)
 
-      assert.strictEqual(coverage.events.missing, 0)
       assert.strictEqual(coverage.events.hit, everyPublicEvent.length)
-      assert.strictEqual(coverage.transitions.total, 0)
-      assert.strictEqual(coverage.logicalConfigurations.hit, 1)
-      assert.deepStrictEqual(coverage.states.activation.hits.map(({ path }) => path), [
-        "Player",
-        "Player.playback",
-        "Player.playback.Empty",
-        "Player.volume",
-        "Player.volume.Audible"
-      ])
-      assert.deepStrictEqual(coverage.states.activation.misses.map(({ path }) => path), [
-        "Player.playback.Loading",
-        "Player.playback.Paused",
-        "Player.playback.Playing",
-        "Player.playback.Buffering",
-        "Player.playback.Ended",
-        "Player.playback.Failed",
-        "Player.volume.Muted"
-      ])
+      assert.strictEqual(coverage.events.missing, 0)
+      assert.strictEqual(coverage.transitions.hit > 0, true)
+
+      const activated = new Set(coverage.states.activation.hits.map(({ path }) => path))
+      assert.strictEqual(activated.has("Player.transport.Empty"), true)
+      assert.strictEqual(activated.has("Player.transport.Loading"), true)
+      assert.strictEqual(activated.has("Player.transport.Failed"), true)
+      assert.strictEqual(activated.has("Player.settings.Audible"), true)
+      assert.strictEqual(activated.has("Player.settings.Muted"), true)
     }))
 
-  it.effect("records ignored events without inventing new logical configurations", () =>
+  it.effect("records every planned event in the observed graph", () =>
     Effect.gen(function*() {
       const trace = yield* MachineTest.run(MediaPlayerMachine, { events: everyPublicEvent })
       const observed = yield* MachineTest.observedGraph(MediaPlayerMachine, trace)
       const eventEdges = Array.from(Graph.edges(observed.graph), ([, edge]) => edge).filter(
         ({ data }) => data._tag === "Event"
       )
 
-      assert.strictEqual(Graph.nodeCount(observed.graph), 1)
+      assert.strictEqual(Graph.nodeCount(observed.graph) > 1, true)
       assert.strictEqual(Graph.edgeCount(observed.graph), everyPublicEvent.length + 1)
       assert.strictEqual(eventEdges.length, everyPublicEvent.length)
-      assert.strictEqual(eventEdges.every(({ source, target }) => source === target), true)
       assert.strictEqual(observed.starts.length, 1)
-
-      const node = Array.from(observed.graph)[0]![1]
-      assert.deepStrictEqual(node.configuration, [
-        "Player",
-        "Player.playback",
-        "Player.playback.Empty",
-        "Player.volume",
-        "Player.volume.Audible"
-      ])
     }))
 })