README improvements

* Compose scene states to slide advancements in other presentation
software. While these are similar in concept, states have a lot more
power. Where you might need multiple slides in other presentation
software, something similar could be created with a single scene and a
complex state class in Storyboard.

* Add notes about various Compose details and how Storyboard works from
that perspective. In particular, mention that a Transition is what
synchronizes all the animations between scene frames.

Author: bnorm

README.md

@@ -31,30 +31,60 @@ To see how publishing is achieved, see the [`pages.yml` workflow](.github/workfl
 
 This library is all about building _**storyboards**_.
 A storyboard is analogous to a slide show in other presentation software.
-While other software may have _**slides**_, Storyboard has two different terms it uses.
-
-When building a storyboard, you will create a sequence of _**scenes**_,
-and each scene may contain any number of _**states**_.
-The states of a scene is just a list of class instances, specified when creating the scene.
-This combination of _**scenes**_ and _**states**_ is analogous to _**slides**_ in other presentation software.
+While other software may have _**slides**_ with _**advancements**_,
+Storyboard uses the terms _**scenes**_ and _**states**_ respectively.
+Building on the _**state**_-driven nature of Compose UI,
+Storyboard provides a _**state**_-based way to build your presentation,
+and requires each scene to provide a list of states.
+When a storyboard advances, it simply moves to the next state specified for your scene,
+or the first state of the next scene.
 
 For the purpose of rendering, the states of a scene are converted into _**frames**_.
 If a scene comes after another scene, a _**start**_ frame will be added as the first frame.
 If a scene comes before another scene, an _**end**_ frame will be added as the last frame.
+Frames are used to control the transitions between scenes and states.
 
-For example, there is a storyboard of three scenes with one, three, and two states respectively.
-The frames of the storyboard could be displayed as the following:
+For example, imagine there is a storyboard with three scenes, each with one, three, and two states respectively.
+The frames of this storyboard could be displayed as follows:
 
 ```text
 1-1, 1-End, 2-Start, 2-1, 2-2, 2-3, 2-End, 3-Start, 3-1, 3-2
 ```
 
-A storyboard is rendered based on the current frame, but states determine when a storyboard pauses.
+This sequence of frames is what controls the advancement of a storyboard.
 Start and end frames are only used for intermediate rendering when transitioning between scenes.
 This enables start and end animations for a scene and smooth transitions between scenes.
 This also enables the use of scenes which do not have any states to create more complex transitions.
 
-### Libraries
+### Compose
+
+Along with defining a list of states, [a scene must also define a `@Composable` lambda][StoryboardBuilder],
+which takes a [`SceneScope`][SceneScope] as a receiver.
+The SceneScope providers a number of properties to the scene Composable,
+including a [`Transition`][Transition] instance that defines the current and target frames.
+This allows animating values between the states of the scene and synchronizing with the storyboard advancement.
+And because of the start and end frame, scene start and end animations are also easy to achieve.
+
+An [`AnimatedContentScope`][AnimatedContentScope] and [`SharedTransitionScope`][SharedTransitionScope] are also
+provided by the SceneScope.
+(These will eventually be context parameters)
+These scopes are provided for animating and sharing elements between scenes.
+
+Along with the Composable lambda and states, a scene is also able to define a enter and exit transition.
+These transitions determine how the scene transitions into view
+and can be based on the current advancement direction of the storyboard.
+For example, these transitions can be used to create a carousel like animation between scenes.
+
+[When building a storyboard][Storyboard], a custom `DpSize` may be provided; otherwise the default size is used.
+The `DpSize` of the storyboard determines the _**constant render size**_ of all scenes.
+This makes it so the scenes of the storyboard automatically scale according the available space,
+while maintaining a constant pixel space for defining the size and spacing of elements.
+
+A [SceneDecorator][SceneDecorator] may also be provided when building a storyboard.
+This decorator will be applied around all scenes
+and can be used to adjust theming, provide composition locals, or add a shared background.
+
+## Libraries
 
 There are two main libraries in Storyboard: Core and Easel.
 The Core library contains the building blocks for Storyboards,
@@ -106,5 +136,17 @@ Want to see Storyboard in action?
 * **Kotlin + Power-Assert = Love** _(KotlinConf 2024)_ - [YouTube](https://www.youtube.com/watch?v=N8u-6d0iCiE)
 * **Writing Your Third Kotlin Compiler Plugin** _(KotlinConf 2025)_ - [_Coming Soon!_](https://kotlinconf.com/schedule/?session=9df8d3fd-5dc8-5d72-a362-c83079285174)
 
-[//]: # (Links)
+[//]: # (Storyboard Links)
+
+[SceneScope]: /storyboard-core/src/commonMain/kotlin/dev/bnorm/storyboard/core/SceneScope.kt
+[SceneDecorator]: /storyboard-core/src/commonMain/kotlin/dev/bnorm/storyboard/core/SceneDecorator.kt
+[Storyboard]: storyboard-core/src/commonMain/kotlin/dev/bnorm/storyboard/core/Storyboard.kt
+[StoryboardBuilder]: storyboard-core/src/commonMain/kotlin/dev/bnorm/storyboard/core/StoryboardBuilder.kt
+
+[//]: # (Compose Links)
+
 [compose]: https://www.jetbrains.com/lp/compose-multiplatform
+
+[AnimatedContentScope]: https://developer.android.com/reference/kotlin/androidx/compose/animation/AnimatedContentScope
+[SharedTransitionScope]: https://developer.android.com/reference/kotlin/androidx/compose/animation/SharedTransitionScope
+[Transition]: https://developer.android.com/reference/kotlin/androidx/compose/animation/core/Transition