From 8535d390128f082ffebf91856a8e272ca3ff5a77 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Fri, 6 Mar 2026 16:51:53 +0000
Subject: [PATCH] Refactor: untangle framework library from todo example
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The codebase is now split into two clear layers:

Framework library (src/):
- lib.rs — public API surface, re-exports all framework types
- signal.rs — SignalOpts, Signal, SignalStore, mangle/global/client_only helpers
- query.rs — Query trait, CacheKey, query_one!/query_all! macros
  (macro paths updated from $crate::framework::* to $crate::*)
- context.rs — RenderContext, ComponentTree, ComponentNode
- connection.rs — ConnectionManager, SubscriptionRegistry, ConnectionState
- sse.rs — format_patch_elements, format_patch_signals
- server.rs — AppState, SharedState, sse_handler (pure framework plumbing)

Todo example (examples/todo/):
- main.rs — SQLite setup, seeding, server bootstrap
- app.rs — router, document_shell, resolve_and_render, render_page,
  action_then_render, and all HTTP handlers
- queries.rs — Todo model, ListTodos/GetTodo queries, mutation helpers
- todo_list.rs — TodoList page component
- about.rs — About page component

Run the example independently with: cargo run --example todo

https://claude.ai/code/session_01JThiQbp3Bn9J1VhBpRuz4u
---
 Cargo.toml                              |   2 +
 {src/app => examples/todo}/about.rs     |   2 +-
 src/app/mod.rs => examples/todo/app.rs  | 102 +++---------------------
 {src => examples/todo}/main.rs          |  11 +--
 {src/app => examples/todo}/queries.rs   |   6 +-
 {src/app => examples/todo}/todo_list.rs |   5 +-
 src/{framework => }/connection.rs       |   2 +-
 src/{framework => }/context.rs          |   6 +-
 src/{framework/mod.rs => lib.rs}        |   2 +
 src/{framework => }/query.rs            |  10 +--
 src/server.rs                           |  85 ++++++++++++++++++++
 src/{framework => }/signal.rs           |   0
 src/{framework => }/sse.rs              |   0
 13 files changed, 122 insertions(+), 111 deletions(-)
 rename {src/app => examples/todo}/about.rs (97%)
 rename src/app/mod.rs => examples/todo/app.rs (78%)
 rename {src => examples/todo}/main.rs (87%)
 rename {src/app => examples/todo}/queries.rs (96%)
 rename {src/app => examples/todo}/todo_list.rs (96%)
 rename src/{framework => }/connection.rs (99%)
 rename src/{framework => }/context.rs (97%)
 rename src/{framework/mod.rs => lib.rs} (85%)
 rename src/{framework => }/query.rs (95%)
 create mode 100644 src/server.rs
 rename src/{framework => }/signal.rs (100%)
 rename src/{framework => }/sse.rs (100%)

diff --git a/Cargo.toml b/Cargo.toml
index e109ffc..242bf96 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -3,6 +3,8 @@ name = "livevue-rs"
 version = "0.1.0"
 edition = "2021"
 
+# Run the todo example with: cargo run --example todo
+
 [dependencies]
 axum = { version = "0.7", features = ["macros"] }
 tokio = { version = "1", features = ["full"] }
diff --git a/src/app/about.rs b/examples/todo/about.rs
similarity index 97%
rename from src/app/about.rs
rename to examples/todo/about.rs
index c696b5b..10edea8 100644
--- a/src/app/about.rs
+++ b/examples/todo/about.rs
@@ -1,4 +1,4 @@
-use crate::framework::context::RenderContext;
+use livevue_rs::RenderContext;
 use maud::{html, Markup};
 
 /// Second page component: a simple "About" page.
diff --git a/src/app/mod.rs b/examples/todo/app.rs
similarity index 78%
rename from src/app/mod.rs
rename to examples/todo/app.rs
index 20d8894..554fa0f 100644
--- a/src/app/mod.rs
+++ b/examples/todo/app.rs
@@ -1,37 +1,15 @@
-pub mod about;
-pub mod queries;
-pub mod todo_list;
-
-use crate::framework::connection::{ConnectionManager, SubscriptionRegistry};
-use crate::framework::context::{ComponentTree, RenderContext};
-use crate::framework::signal::SignalStore;
-use crate::framework::sse::{format_patch_elements, format_patch_signals};
+use livevue_rs::{
+    AppState, CacheKey, ComponentTree, RenderContext, SharedState, SignalStore,
+    format_patch_elements, format_patch_signals, sse_handler,
+};
 
 use axum::extract::{Query as AxumQuery, State};
 use axum::http::header;
-use axum::response::sse::{Event, KeepAlive, Sse};
 use axum::response::{Html, IntoResponse};
 use axum::routing::{get, post};
 use axum::{Json, Router};
-use std::convert::Infallible;
-use std::sync::Arc;
-use tokio::sync::mpsc;
-use tokio_stream::wrappers::ReceiverStream;
 use uuid::Uuid;
 
-// ---------------------------------------------------------------------------
-// Shared application state
-// ---------------------------------------------------------------------------
-
-/// All shared state, wrapped in Arc for axum's State extractor.
-pub struct AppState {
-    pub db: sqlx::SqlitePool,
-    pub connections: ConnectionManager,
-    pub subscriptions: SubscriptionRegistry,
-}
-
-pub type SharedState = Arc<AppState>;
-
 // ---------------------------------------------------------------------------
 // Router
 // ---------------------------------------------------------------------------
@@ -83,7 +61,7 @@ fn document_shell(conn_id: Uuid, initial_signals: &str, inner_html: &str) -> Str
 <head>
     <meta charset="utf-8">
     <meta name="viewport" content="width=device-width, initial-scale=1">
-    <title>LiveVue.rs Demo</title>
+    <title>LiveVue.rs — Todo</title>
     <script type="module" src="https://cdn.jsdelivr.net/gh/starfederation/datastar@v1.0.0-RC.8/bundles/datastar.js"></script>
     <style>
         {css}
@@ -105,7 +83,7 @@ fn document_shell(conn_id: Uuid, initial_signals: &str, inner_html: &str) -> Str
     )
 }
 
-/// Minimal CSS for the demo app. In a real app this would be a separate file.
+/// Minimal CSS for the todo app.
 const INLINE_CSS: &str = r#"
     body { font-family: system-ui, sans-serif; max-width: 600px; margin: 2rem auto; padding: 0 1rem; background: #fafafa; color: #333; }
     h1 { color: #2563eb; }
@@ -136,8 +114,8 @@ const INLINE_CSS: &str = r#"
 /// no async lifetime gymnastics. The right call for a v0 with two pages.
 async fn resolve_and_render(cx: &mut RenderContext) -> anyhow::Result<String> {
     let markup = match cx.tree.page.as_str() {
-        "TodoList" => todo_list::todo_list(cx).await?,
-        "About" => about::about(cx).await?,
+        "TodoList" => crate::todo_list::todo_list(cx).await?,
+        "About" => crate::about::about(cx).await?,
         other => maud::html! {
             div {
                 h1 { "404 — Unknown page" }
@@ -160,7 +138,7 @@ async fn render_page(
     conn_id: Uuid,
     signals: SignalStore,
     tree: ComponentTree,
-) -> anyhow::Result<(String, Vec<crate::framework::CacheKey>, String)> {
+) -> anyhow::Result<(String, Vec<CacheKey>, String)> {
     let signals_json = signals.to_json_string();
     let mut cx = RenderContext::new(conn_id, signals, tree, db.clone());
     let html = resolve_and_render(&mut cx).await?;
@@ -229,62 +207,6 @@ async fn initial_about_load(State(state): State<SharedState>) -> impl IntoRespon
     }
 }
 
-/// Query params for the SSE endpoint.
-#[derive(serde::Deserialize)]
-struct SseParams {
-    conn: Uuid,
-}
-
-/// `GET /sse?conn=<uuid>` — Long-lived SSE pipe for server-initiated push.
-///
-/// In v0, nothing actively pushes events through this pipe (no invalidation
-/// events yet). It exists to:
-/// 1. Register the connection in ConnectionManager.
-/// 2. Keep the SSE connection alive (DataStar expects it).
-/// 3. Provide the Phase 2 seam for server-initiated rerenders.
-///
-/// On drop, the connection is cleaned up from both the ConnectionManager
-/// and the SubscriptionRegistry.
-async fn sse_handler(
-    State(state): State<SharedState>,
-    AxumQuery(params): AxumQuery<SseParams>,
-) -> Sse<impl tokio_stream::Stream<Item = Result<Event, Infallible>>> {
-    let conn_id = params.conn;
-
-    // Create a channel for sending events to this connection
-    let (tx, rx) = mpsc::channel::<String>(32);
-
-    // Clone sender for the cleanup watcher. Sender::closed() resolves when
-    // the receiver is dropped (i.e. client disconnects and the SSE stream
-    // drops). This is the proper cleanup mechanism — no arbitrary sleep.
-    let tx_watch = tx.clone();
-
-    // Register the connection
-    state.connections.insert(conn_id, tx);
-
-    // Spawn cleanup task: waits for the receiver to drop (client disconnect),
-    // then removes the connection from all registries.
-    let state_cleanup = state.clone();
-    tokio::spawn(async move {
-        tx_watch.closed().await;
-        state_cleanup.connections.remove(&conn_id);
-        state_cleanup.subscriptions.remove_connection(&conn_id);
-    });
-
-    // Convert the receiver into an SSE stream.
-    // DESIGN NOTE: For v0, the SSE pipe is mostly idle — POST /render
-    // returns SSE directly in its response, not through this pipe. This
-    // channel exists for Phase 2 server-initiated pushes (data invalidation).
-    // Messages sent via the channel should be plain content strings (not
-    // pre-formatted SSE); axum's Sse wrapper handles the SSE framing.
-    let stream = ReceiverStream::new(rx);
-    let event_stream = tokio_stream::StreamExt::map(stream, |msg| {
-        Ok(Event::default().data(msg))
-    });
-
-    Sse::new(event_stream).keep_alive(KeepAlive::default())
-}
-
 /// `POST /render` — Signal-triggered rerender.
 ///
 /// DataStar sends all non-`_` signals as JSON body when any signal changes
@@ -426,7 +348,7 @@ async fn action_add_todo(
         body,
         async move {
             if !title.is_empty() {
-                queries::create_todo(&db, &title).await?;
+                crate::queries::create_todo(&db, &title).await?;
             }
             Ok(())
         },
@@ -446,7 +368,7 @@ async fn action_toggle_todo(
     action_then_render(
         &state,
         body,
-        async move { queries::toggle_todo(&db, id).await },
+        async move { crate::queries::toggle_todo(&db, id).await },
         None,
     )
     .await
@@ -463,7 +385,7 @@ async fn action_delete_todo(
     action_then_render(
         &state,
         body,
-        async move { queries::delete_todo(&db, id).await },
+        async move { crate::queries::delete_todo(&db, id).await },
         None,
     )
     .await
diff --git a/src/main.rs b/examples/todo/main.rs
similarity index 87%
rename from src/main.rs
rename to examples/todo/main.rs
index d6b47a7..d758d8c 100644
--- a/src/main.rs
+++ b/examples/todo/main.rs
@@ -1,8 +1,9 @@
-mod framework;
 mod app;
+mod queries;
+mod todo_list;
+mod about;
 
-use app::AppState;
-use framework::connection::{ConnectionManager, SubscriptionRegistry};
+use livevue_rs::{AppState, ConnectionManager, SubscriptionRegistry};
 use std::sync::Arc;
 
 #[tokio::main]
@@ -12,7 +13,7 @@ async fn main() -> anyhow::Result<()> {
     // -----------------------------------------------------------------------
 
     // SQLite with create-if-missing. In-memory `:memory:` also works for dev.
-    let db = sqlx::SqlitePool::connect("sqlite:livevue.db?mode=rwc").await?;
+    let db = sqlx::SqlitePool::connect("sqlite:todo.db?mode=rwc").await?;
 
     // Run migrations inline (no migration files needed for v0).
     sqlx::query(
@@ -55,7 +56,7 @@ async fn main() -> anyhow::Result<()> {
     let app = app::router(state);
 
     let listener = tokio::net::TcpListener::bind("0.0.0.0:3000").await?;
-    println!("LiveVue.rs v0.1 listening on http://localhost:3000");
+    println!("Todo example listening on http://localhost:3000");
 
     axum::serve(listener, app).await?;
 
diff --git a/src/app/queries.rs b/examples/todo/queries.rs
similarity index 96%
rename from src/app/queries.rs
rename to examples/todo/queries.rs
index 7f8a963..f692032 100644
--- a/src/app/queries.rs
+++ b/examples/todo/queries.rs
@@ -1,4 +1,4 @@
-use crate::framework::CacheKey;
+use livevue_rs::CacheKey;
 use serde::{Deserialize, Serialize};
 
 // ---------------------------------------------------------------------------
@@ -20,7 +20,7 @@ pub struct Todo {
 /// Fetch all todos, ordered by id.
 pub struct ListTodos;
 
-crate::query_all!(ListTodos {
+livevue_rs::query_all!(ListTodos {
     sql: "SELECT id, title, completed FROM todos ORDER BY id",
     params: [],
     output: Todo,
@@ -32,7 +32,7 @@ pub struct GetTodo {
     pub id: i64,
 }
 
-crate::query_one!(GetTodo {
+livevue_rs::query_one!(GetTodo {
     sql: "SELECT id, title, completed FROM todos WHERE id = ?",
     params: [|s: &GetTodo| s.id],
     output: Todo,
diff --git a/src/app/todo_list.rs b/examples/todo/todo_list.rs
similarity index 96%
rename from src/app/todo_list.rs
rename to examples/todo/todo_list.rs
index 53fc86e..0f8ceb8 100644
--- a/src/app/todo_list.rs
+++ b/examples/todo/todo_list.rs
@@ -1,6 +1,5 @@
-use crate::app::queries::{ListTodos, Todo};
-use crate::framework::context::RenderContext;
-use crate::framework::signal::{global, mangle};
+use crate::queries::{ListTodos, Todo};
+use livevue_rs::{RenderContext, global, mangle};
 use maud::{html, Markup};
 
 /// Root page component: renders the full todo list with add form.
diff --git a/src/framework/connection.rs b/src/connection.rs
similarity index 99%
rename from src/framework/connection.rs
rename to src/connection.rs
index 7186ee1..23f739e 100644
--- a/src/framework/connection.rs
+++ b/src/connection.rs
@@ -1,4 +1,4 @@
-use crate::framework::query::CacheKey;
+use crate::query::CacheKey;
 use dashmap::DashMap;
 use std::collections::HashSet;
 use tokio::sync::mpsc;
diff --git a/src/framework/context.rs b/src/context.rs
similarity index 97%
rename from src/framework/context.rs
rename to src/context.rs
index f2ff0dc..3c73976 100644
--- a/src/framework/context.rs
+++ b/src/context.rs
@@ -1,5 +1,5 @@
-use crate::framework::signal::{Signal, SignalOpts, SignalStore};
-use crate::framework::query::{CacheKey, Query};
+use crate::signal::{Signal, SignalOpts, SignalStore};
+use crate::query::{CacheKey, Query};
 use serde::{Deserialize, Serialize};
 use std::collections::HashMap;
 use uuid::Uuid;
@@ -34,7 +34,7 @@ pub struct ComponentNode {
 impl Default for ComponentTree {
     fn default() -> Self {
         Self {
-            page: "TodoList".into(),
+            page: String::new(),
             children: HashMap::new(),
         }
     }
diff --git a/src/framework/mod.rs b/src/lib.rs
similarity index 85%
rename from src/framework/mod.rs
rename to src/lib.rs
index 1e9046c..0fcf1bf 100644
--- a/src/framework/mod.rs
+++ b/src/lib.rs
@@ -3,9 +3,11 @@ pub mod query;
 pub mod context;
 pub mod connection;
 pub mod sse;
+pub mod server;
 
 pub use signal::{Signal, SignalStore, SignalOpts, mangle, client_only, global, data_signals};
 pub use query::{CacheKey, Query};
 pub use context::{RenderContext, ComponentTree, ComponentNode};
 pub use connection::{ConnectionManager, ConnectionState, SubscriptionRegistry};
 pub use sse::{format_patch_elements, format_patch_signals};
+pub use server::{AppState, SharedState, sse_handler};
diff --git a/src/framework/query.rs b/src/query.rs
similarity index 95%
rename from src/framework/query.rs
rename to src/query.rs
index d65d199..2060552 100644
--- a/src/framework/query.rs
+++ b/src/query.rs
@@ -79,10 +79,10 @@ macro_rules! query_one {
         output: $output:ty,
         cache: $cache:expr $(,)?
     }) => {
-        impl $crate::framework::Query for $name {
+        impl $crate::Query for $name {
             type Output = $output;
 
-            fn cache_key(&self) -> $crate::framework::CacheKey {
+            fn cache_key(&self) -> $crate::CacheKey {
                 ($cache)(self)
             }
 
@@ -134,10 +134,10 @@ macro_rules! query_all {
         output: $output:ty,
         cache: $cache:expr $(,)?
     }) => {
-        impl $crate::framework::Query for $name {
+        impl $crate::Query for $name {
             type Output = Vec<$output>;
 
-            fn cache_key(&self) -> $crate::framework::CacheKey {
+            fn cache_key(&self) -> $crate::CacheKey {
                 ($cache)(self)
             }
 
@@ -158,4 +158,4 @@ macro_rules! query_all {
             }
         }
     };
-}
\ No newline at end of file
+}
diff --git a/src/server.rs b/src/server.rs
new file mode 100644
index 0000000..0e14bae
--- /dev/null
+++ b/src/server.rs
@@ -0,0 +1,85 @@
+use crate::connection::{ConnectionManager, SubscriptionRegistry};
+
+use axum::extract::{Query as AxumQuery, State};
+use axum::response::sse::{Event, KeepAlive, Sse};
+use std::convert::Infallible;
+use std::sync::Arc;
+use tokio::sync::mpsc;
+use tokio_stream::wrappers::ReceiverStream;
+use uuid::Uuid;
+
+// ---------------------------------------------------------------------------
+// Shared application state
+// ---------------------------------------------------------------------------
+
+/// All shared state, wrapped in Arc for axum's State extractor.
+///
+/// Applications can use this directly or define their own state type.
+/// The framework's `sse_handler` is tied to this type.
+pub struct AppState {
+    pub db: sqlx::SqlitePool,
+    pub connections: ConnectionManager,
+    pub subscriptions: SubscriptionRegistry,
+}
+
+pub type SharedState = Arc<AppState>;
+
+// ---------------------------------------------------------------------------
+// SSE handler
+// ---------------------------------------------------------------------------
+
+/// Query params for the SSE endpoint.
+#[derive(serde::Deserialize)]
+pub struct SseParams {
+    conn: Uuid,
+}
+
+/// `GET /sse?conn=<uuid>` — Long-lived SSE pipe for server-initiated push.
+///
+/// In v0, nothing actively pushes events through this pipe (no invalidation
+/// events yet). It exists to:
+/// 1. Register the connection in ConnectionManager.
+/// 2. Keep the SSE connection alive (DataStar expects it).
+/// 3. Provide the Phase 2 seam for server-initiated rerenders.
+///
+/// On drop, the connection is cleaned up from both the ConnectionManager
+/// and the SubscriptionRegistry.
+pub async fn sse_handler(
+    State(state): State<SharedState>,
+    AxumQuery(params): AxumQuery<SseParams>,
+) -> Sse<impl tokio_stream::Stream<Item = Result<Event, Infallible>>> {
+    let conn_id = params.conn;
+
+    // Create a channel for sending events to this connection
+    let (tx, rx) = mpsc::channel::<String>(32);
+
+    // Clone sender for the cleanup watcher. Sender::closed() resolves when
+    // the receiver is dropped (i.e. client disconnects and the SSE stream
+    // drops). This is the proper cleanup mechanism — no arbitrary sleep.
+    let tx_watch = tx.clone();
+
+    // Register the connection
+    state.connections.insert(conn_id, tx);
+
+    // Spawn cleanup task: waits for the receiver to drop (client disconnect),
+    // then removes the connection from all registries.
+    let state_cleanup = state.clone();
+    tokio::spawn(async move {
+        tx_watch.closed().await;
+        state_cleanup.connections.remove(&conn_id);
+        state_cleanup.subscriptions.remove_connection(&conn_id);
+    });
+
+    // Convert the receiver into an SSE stream.
+    // DESIGN NOTE: For v0, the SSE pipe is mostly idle — POST /render
+    // returns SSE directly in its response, not through this pipe. This
+    // channel exists for Phase 2 server-initiated pushes (data invalidation).
+    // Messages sent via the channel should be plain content strings (not
+    // pre-formatted SSE); axum's Sse wrapper handles the SSE framing.
+    let stream = ReceiverStream::new(rx);
+    let event_stream = tokio_stream::StreamExt::map(stream, |msg| {
+        Ok(Event::default().data(msg))
+    });
+
+    Sse::new(event_stream).keep_alive(KeepAlive::default())
+}
diff --git a/src/framework/signal.rs b/src/signal.rs
similarity index 100%
rename from src/framework/signal.rs
rename to src/signal.rs
diff --git a/src/framework/sse.rs b/src/sse.rs
similarity index 100%
rename from src/framework/sse.rs
rename to src/sse.rs