trying to get new Bsp to work; update docs

engine/README.md

@@ -0,0 +1,65 @@
+# `tek_engine`
+
+this crate provides the `Engine` trait,
+which defines an application's lifecycle.
+
+currently, there is one kind of engine implemented, `Tui`.
+it uses `ratatui` to present an interactive user interface
+in text mode.
+
+at launch, the `Tui` engine spawns two threads,
+a **render thread** and an **input thread**. (the
+application may spawn further threads, such as a
+**jack thread**.)
+
+all threads communicate using shared ownership,
+`Arc<RwLock>` and `Arc<Atomic>`. the engine and
+application instances are expected to be wrapped
+in `Arc<RwLock>`; internally, those synchronization
+mechanisms may be used liberally.
+
+## rendering
+
+the **render thread** continually invokes the
+`Content::render` method of the application
+to redraw the display. it does this efficiently
+by using ratatui's double buffering.
+
+thus, for a type to be a valid application for engine `E`,
+it must implement the trait `Content<E>`, which allows
+it to display content to the engine's output.
+
+the most important thing about the `Content` trait is that
+it composes:
+* you can implement `Content::content` to build
+  `Content`s out of other `Content`s
+* and/or `Content::area` for custom positioning and sizing,
+* and/or `Content::render` for custom rendering
+  within the given `Content`'s area.
+
+the manner of output is determined by the
+`Engine::Output` type, a mutable pointer to which
+is passed to the render method, e.g. in the case of
+the `Tui` engine: `fn render(&self, output: &mut TuiOutput)`
+
+you can use `TuiOutput::blit` and `TuiOutput::place`
+to draw at specified coordinates of the display, and/or
+directly modify the underlying `ratatui::Buffer` at
+`output.buffer`
+
+rendering is intended to work with read-only access
+to the application state. if you really need to update
+values during rendering, use interior mutability.
+
+## input handling
+
+the **input thread** polls for keyboard events
+and passes them onto the application's `Handle::handle` method.
+
+thus, for a type to be a valid application for engine `E`,
+it must implement the trait `Handle<E>`, which allows it
+to respond to user input.
+
+this thread has write access to the application state,
+and is responsible for mutating it in response to
+user activity.

engine/src/engine.rs

@@ -78,7 +78,7 @@ impl<N: Coordinate> Size<N> for [N;2] {
     #[inline] fn y (&self) -> N { self[1] }
 }
 
-pub trait Area<N: Coordinate>: Copy {
+pub trait Area<N: Coordinate> {
     fn x (&self) -> N;
     fn y (&self) -> N;
     fn w (&self) -> N;
@@ -133,6 +133,10 @@ pub trait Area<N: Coordinate>: Copy {
         [self.x(), self.y(), self.w(), self.h().minus(y)]
     }
 
+    #[inline] fn center (&self) -> [N;2] {
+        [self.x() + self.w() / 2.into(), self.y() + self.h() / 2.into()]
+    }
+
     fn zero () -> [N;4] {
         [N::zero(), N::zero(), N::zero(), N::zero()]
     }

engine/src/output.rs

@@ -31,17 +31,39 @@ pub trait Content<E: Engine>: Send + Sync {
 }
 
 impl<E: Engine> Content<E> for () {
-    fn area (&self, area: E::Area) -> E::Area {
+    fn area (&self, _: E::Area) -> E::Area {
         [0.into(), 0.into(), 0.into(), 0.into()].into()
     }
-    fn render (&self, output: &mut E::Output) {}
+    fn render (&self, _: &mut E::Output) {}
 }
 
-impl<E: Engine, T: Content<E>> Content<E> for &T {}
+impl<E: Engine, T: Content<E>> Content<E> for &T {
+    fn content (&self) -> impl Content<E> {
+        (*self).content()
+    }
+    fn area (&self, area: E::Area) -> E::Area {
+        (*self).area(area)
+    }
+    fn render (&self, output: &mut E::Output) {
+        (*self).render(output)
+    }
+}
 
-impl<E: Engine, T: Content<E>> Content<E> for Option<T> {}
-
-impl<E: Engine, T: Content<E>> Content<E> for Vec<T> {}
+impl<E: Engine, T: Content<E>> Content<E> for Option<T> {
+    fn content (&self) -> impl Content<E> {
+        self.as_ref()
+            .map(|content|content.content())
+    }
+    fn area (&self, area: E::Area) -> E::Area {
+        self.as_ref()
+            .map(|content|content.area(area))
+            .unwrap_or([0.into(), 0.into(), 0.into(), 0.into(),].into())
+    }
+    fn render (&self, output: &mut E::Output) {
+        self.as_ref()
+            .map(|content|content.render(output));
+    }
+}
 
 pub struct Thunk<E: Engine, T: Content<E>, F: Fn()->T + Send + Sync>(F, PhantomData<E>);
 

engine/src/tui.rs

@@ -255,10 +255,14 @@ impl Output<Tui> for TuiOutput {
     #[inline] fn area (&self) -> [u16;4] { self.area }
     #[inline] fn area_mut (&mut self) -> &mut [u16;4] { &mut self.area }
     #[inline] fn place (&mut self, area: [u16;4], content: &impl Content<Tui>) {
-        let last = self.area();
-        *self.area_mut() = area;
+        let last = self.area().xywh().clone();
+        //panic!("a {last:?} {area:?} {:?}", self.area);
+        *self.area_mut() = area.xywh().clone();
+        //panic!("b {last:?} {area:?} {:?}", self.area);
         content.render(self);
+        //panic!("c {last:?} {area:?} {:?}", self.area);
         *self.area_mut() = last;
+        //panic!("placed");
     }
 }
 
@@ -330,12 +334,18 @@ pub fn half_block (lower: bool, upper: bool) -> Option<char> {
 //impl<T: Content<Tui>> Render<Tui> for T {}
 
 impl Content<Tui> for &str {
+    fn area (&self, to: [u16;4]) -> [u16;4] {
+        [to[0], to[1], self.chars().count() as u16, 1]
+    }
     fn render (&self, to: &mut TuiOutput) {
         to.blit(self, to.area.x(), to.area.y(), None)
     }
 }
 
 impl Content<Tui> for String {
+    fn area (&self, to: [u16;4]) -> [u16;4] {
+        [to[0], to[1], self.chars().count() as u16, 1]
+    }
     fn render (&self, to: &mut TuiOutput) {
         to.blit(self, to.area.x(), to.area.y(), None)
     }